diff options
| author | Tom Hughes <tomhughes@chromium.org> | 2021-01-26 10:38:55 -0800 |
|---|---|---|
| committer | Commit Bot <commit-bot@chromium.org> | 2021-01-28 16:38:57 +0000 |
| commit | 2f40b71b625bcd826fd0cb4a005985abef0b8903 (patch) | |
| tree | 1f67563e6de1dc64fd4d40bb50ea70d2a17d18a7 /docs | |
| parent | 4e950b9fde9e5d7197d2558f7a36bc809e193a49 (diff) | |
| download | chrome-ec-2f40b71b625bcd826fd0cb4a005985abef0b8903.tar.gz | |
docs: Run mdformat on all .md files
BRANCH=none
BUG=b:178648877
TEST=view in gitiles
Signed-off-by: Tom Hughes <tomhughes@chromium.org>
Change-Id: I0ac5581ba7bc512234d40dbf34222422afa9c725
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/2650551
Reviewed-by: Jack Rosenthal <jrosenth@chromium.org>
Diffstat (limited to 'docs')
32 files changed, 1031 insertions, 989 deletions
diff --git a/docs/ap-ec-comm.md b/docs/ap-ec-comm.md index a65c419171..2fb72da67b 100644 --- a/docs/ap-ec-comm.md +++ b/docs/ap-ec-comm.md @@ -9,11 +9,12 @@ by issuing *host commands*, which are identified by a command ID and version number, and then reading a response. When a host command is issued through `ectool`, two or three software components are involved: -* `ectool`, the user-space binary, -* normally the `cros-ec` Kernel driver, and -* the code on the EC itself. This can be thought of as two parts: - * a chip-specific driver for the appropriate transport, and - * the generic host command handling code (mostly in the [host command task]). +* `ectool`, the user-space binary, +* normally the `cros-ec` Kernel driver, and +* the code on the EC itself. This can be thought of as two parts: + * a chip-specific driver for the appropriate transport, and + * the generic host command handling code (mostly in the + [host command task]). We'll go into detail of each of these, as well as the traffic on the wire, in the following sections. @@ -39,25 +40,25 @@ to the Linux [Industrial I/O] system. Now we come to the protocol itself. All transactions take this general form: -* Host writes the request packet, consisting of: - * a transport-specific header; - * a `struct ec_host_request` containing the command ID, data length, and a - checksum; and - * zero or more bytes of parameters for the command, the format of which - depends on the command. -* Host reads the response to its request, consisting of: - * a transport-specific header; - * a `struct ec_host_response` containing the result code, data length, and a - checksum; and - * zero or more bytes of response from the command, again with a - command-specific format. +* Host writes the request packet, consisting of: + * a transport-specific header; + * a `struct ec_host_request` containing the command ID, data length, and a + checksum; and + * zero or more bytes of parameters for the command, the format of which + depends on the command. +* Host reads the response to its request, consisting of: + * a transport-specific header; + * a `struct ec_host_response` containing the result code, data length, and + a checksum; and + * zero or more bytes of response from the command, again with a + command-specific format. ### On the EC The host packet is received on the EC by some chip-specific code which checks -its transport-specific header, then passes it on to the common host command code, -starting at `host_packet_receive`. The common code validates the packet and -then sends it on to the handler function (annotated with the +its transport-specific header, then passes it on to the common host command +code, starting at `host_packet_receive`. The common code validates the packet +and then sends it on to the handler function (annotated with the `DECLARE_HOST_COMMAND` macro), which runs in the `HOSTCMD` task. The handler can set a response by modifying its arguments struct, which is sent back to the host via the chip-specific code. @@ -74,8 +75,8 @@ of the overarching protocol, and versions of individual commands. ### Protocol versions There have been three protocol versions so far, and this document describes -version 3. Version 1 was superseded by 2 before it shipped, so no devices use -it anymore. Version 2 is generally deprecated, but you might still encounter it +version 3. Version 1 was superseded by 2 before it shipped, so no devices use it +anymore. Version 2 is generally deprecated, but you might still encounter it occasionally. Which version is in use can be determined using the `EC_CMD_GET_PROTOCOL_INFO` @@ -128,15 +129,14 @@ embedded controllers either aren't fast enough or don't have any support for hardware flow-control. It works like this: When the AP sends a byte to the EC, if the EC doesn't have a -response queued up in advance, a default byte is returned. The EC -preconfigures that default response byte to indicate its status (ready, busy, -waiting for more input, etc.). Once the AP has sent a complete command message, -it continues clocking bytes to the EC (which the EC ignores) and just looks at -the response byte that comes back. Once the EC has parsed the AP's command and -is ready to reply, it sends a "start of frame" byte, followed by the actual -response. The AP continues to read and ignore bytes from the EC until it sees -the start of frame byte, and then it knows that the EC's response is starting -with the next byte. +response queued up in advance, a default byte is returned. The EC preconfigures +that default response byte to indicate its status (ready, busy, waiting for more +input, etc.). Once the AP has sent a complete command message, it continues +clocking bytes to the EC (which the EC ignores) and just looks at the response +byte that comes back. Once the EC has parsed the AP's command and is ready to +reply, it sends a "start of frame" byte, followed by the actual response. The AP +continues to read and ignore bytes from the EC until it sees the start of frame +byte, and then it knows that the EC's response is starting with the next byte. Once the response packet has been read, any additional reads should return `EC_SPI_PAST_END`. @@ -146,7 +146,6 @@ Once the response packet has been read, any additional reads should return The EC should set `EC_LPC_STATUS_PROCESSING` in its command status register after receiving a host packet and before it has a response ready. - [`cros-ec` Kernel driver]: https://chromium.googlesource.com/chromiumos/third_party/kernel/+/refs/heads/chromeos-4.19/drivers/mfd/cros_ec_dev.c [Industrial I/O]: https://www.kernel.org/doc/html/v4.14/driver-api/iio/index.html [host command task]: https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/master/common/host_command.c diff --git a/docs/case_closed_debugging.md b/docs/case_closed_debugging.md index 05373f1de9..8310970652 100644 --- a/docs/case_closed_debugging.md +++ b/docs/case_closed_debugging.md @@ -1,2 +1,2 @@ -The has been moved into a [different -branch](https://chromium.googlesource.com/chromiumos/platform/ec/+/cr50_stab/docs/case_closed_debugging.md) +The has been moved into a +[different branch](https://chromium.googlesource.com/chromiumos/platform/ec/+/cr50_stab/docs/case_closed_debugging.md) diff --git a/docs/case_closed_debugging_cr50.md b/docs/case_closed_debugging_cr50.md index 6eb622cc37..ac518c0153 100644 --- a/docs/case_closed_debugging_cr50.md +++ b/docs/case_closed_debugging_cr50.md @@ -1,2 +1,2 @@ -The has been moved into a [different -branch](https://chromium.googlesource.com/chromiumos/platform/ec/+/cr50_stab/docs/case_closed_debugging_cr50.md) +The has been moved into a +[different branch](https://chromium.googlesource.com/chromiumos/platform/ec/+/cr50_stab/docs/case_closed_debugging_cr50.md) diff --git a/docs/ccd_howtos.md b/docs/ccd_howtos.md index 624253d22c..44deecd16d 100644 --- a/docs/ccd_howtos.md +++ b/docs/ccd_howtos.md @@ -1,2 +1,2 @@ -The has been moved into a [different -branch](https://chromium.googlesource.com/chromiumos/platform/ec/+/cr50_stab/docs/ccd_howtos.md) +The has been moved into a +[different branch](https://chromium.googlesource.com/chromiumos/platform/ec/+/cr50_stab/docs/ccd_howtos.md) diff --git a/docs/code_coverage.md b/docs/code_coverage.md index 458d87b7c5..4d9dbb6948 100644 --- a/docs/code_coverage.md +++ b/docs/code_coverage.md @@ -7,8 +7,8 @@ tests in the EC codebase. ## Availability -Code coverage is only available for host-based unit tests, as opposed to -manual tests that run on target hardware. +Code coverage is only available for host-based unit tests, as opposed to manual +tests that run on target hardware. ## Building for code coverage @@ -26,9 +26,10 @@ The coverage report top-level page is `build/coverage/coverage_rpt/index.html`. ### Noise in the build output When building for code coverage, you may see multiple warnings of the form -`geninfo: WARNING: no data found for /mnt/host/source/src/platform/ec/core/host/cpu.h` -and -`genhtml: WARNING: function data mismatch at /mnt/host/source/src/platform/ec/common/math_util.c:134` +`geninfo: WARNING: no data found for +/mnt/host/source/src/platform/ec/core/host/cpu.h` and `genhtml: WARNING: +function data mismatch at +/mnt/host/source/src/platform/ec/common/math_util.c:134` These warnings can be ignored. (FYI, the "function data mismatch" warnings appear to be caused in part by using relative paths instead of absolute paths.) diff --git a/docs/code_reviews.md b/docs/code_reviews.md index 8bda5fe31a..5a616ffdf0 100644 --- a/docs/code_reviews.md +++ b/docs/code_reviews.md @@ -44,9 +44,9 @@ Add your name to the [list of reviewers][1]. ## Reference -* [Chrome OS firmware review guidelines][2] -* [Coreboot Gerrit Guidelines][3] -* [Google small CL guidelines][5] +* [Chrome OS firmware review guidelines][2] +* [Coreboot Gerrit Guidelines][3] +* [Google small CL guidelines][5] [1]: http://google3/chrome/crosinfra/gwsq/ec_reviewers [2]: http://chromium.googlesource.com/chromiumos/docs/+/master/firmware_code_reviews.md diff --git a/docs/configuration/ap_power_sequencing.md b/docs/configuration/ap_power_sequencing.md index 2b78592e57..c5073d5809 100644 --- a/docs/configuration/ap_power_sequencing.md +++ b/docs/configuration/ap_power_sequencing.md @@ -3,13 +3,13 @@ This section details the configuration related to managing the system power states (G3, S5, S3, S0, S0iX, etc). This includes the following tasks: -- Selecting the AP chipset type. -- Configure output GPIOs that enable voltage rails. -- Configure input GPIOs that monitor the voltage rail status (power good - signals). -- Configure input GPIOs that monitor the AP sleep states. -- Pass through power sequencing signals from the board to the AP, often with - delays or other sequencing control. +- Selecting the AP chipset type. +- Configure output GPIOs that enable voltage rails. +- Configure input GPIOs that monitor the voltage rail status (power good + signals). +- Configure input GPIOs that monitor the AP sleep states. +- Pass through power sequencing signals from the board to the AP, often with + delays or other sequencing control. ## Config options @@ -28,8 +28,8 @@ particular, the `CONFIG_POWER_BUTTON`, and `CONFIG_POWER_COMMON` should be defined. The `CONFIG_BRINGUP` option is especially useful option during the initial power -up of a new board. This option is discussed in more detail in the [Testing and -Debugging](#Testing-and-Debugging) section. +up of a new board. This option is discussed in more detail in the +[Testing and Debugging](#Testing-and-Debugging) section. ## Feature Parameters @@ -54,15 +54,16 @@ GPIO(EN_PP5000, PIN(A, 4), GPIO_OUT_LOW) For boards with an x86 AP, the following signals can be connected between the EC and AP/PCH. Create `GPIO()` entries for any signals used on your board. -- `GPIO_PCH_PWRBTN_L` - Output from the EC that proxies the status of the EC - input `GPIO_POWER_BUTTON_L` (driven by the H1). Only used when - `CONFIG_POWER_BUTTON_X86` is defined. -- `GPIO_PCH_RSMRST_L` - Output from the EC that proxies the status of the EC - input `GPIO_RSMRST_L_PGOOD` (driven by the PMIC or voltage regulators on the - board). -- `GPIO_PCH_SYS_PWROK` - Output from the EC that indicates when the system power - is good and the AP can power up. -- `GPIO_PCH_WAKE_L` - Output from the EC, driven low when there is a wake event. +- `GPIO_PCH_PWRBTN_L` - Output from the EC that proxies the status of the EC + input `GPIO_POWER_BUTTON_L` (driven by the H1). Only used when + `CONFIG_POWER_BUTTON_X86` is defined. +- `GPIO_PCH_RSMRST_L` - Output from the EC that proxies the status of the EC + input `GPIO_RSMRST_L_PGOOD` (driven by the PMIC or voltage regulators on the + board). +- `GPIO_PCH_SYS_PWROK` - Output from the EC that indicates when the system + power is good and the AP can power up. +- `GPIO_PCH_WAKE_L` - Output from the EC, driven low when there is a wake + event. ### Power Signal Interrupts @@ -85,15 +86,15 @@ macros. ## Data structures -- `const struct power_signal_info power_signal_list[]` - This array defines the - signals from the AP and from the power subsystem on the board that control the - power state. For some Intel chipsets, including Apollo Lake and Ice Lake, this - power signal list is already defined by the corresponding chipset file under - the `./power` directory. +- `const struct power_signal_info power_signal_list[]` - This array defines + the signals from the AP and from the power subsystem on the board that + control the power state. For some Intel chipsets, including Apollo Lake and + Ice Lake, this power signal list is already defined by the corresponding + chipset file under the `./power` directory. ## Tasks -The `CHIPSET` task monitors and handles the power state changes. This task +The `CHIPSET` task monitors and handles the power state changes. This task should always be enabled with a priority higher than the `CHARGER` task, but lower than the `HOSTCMD` and `CONSOLE` tasks. @@ -178,8 +179,8 @@ RTC: 0x000067bf (26559.00 s) [9.128640 power state 7 = S3->S0, in 0x003f] ``` -This example shows successful power on of the AP as the AP transitions from the G3 -state all the way to the S0 state. +This example shows successful power on of the AP as the AP transitions from the +G3 state all the way to the S0 state. The console messages shown in brackets `[]` include a timestamp. This timestamp records when the corresponding console message was printed. @@ -192,7 +193,7 @@ signal changes shown on the console to be out of order with respect to the other EC messages. The power signal changes include a timestamp to help you correlate when the -actual power signal changed compared to other messages. From the example above, +actual power signal changed compared to other messages. From the example above, the first power signal change recorded is the `DSW_PWROK` signal transitioning from 0 to 1, and this is recorded at timestamp `6.807298`. Using the regular EC console timestamp, you can reconstruct the real power sequence to look like the @@ -246,7 +247,6 @@ RTC: 0x000067bf (26559.00 s) [9.128640 power state 7 = S3->S0, in 0x003f] ``` - *TODO ([b/147808790](http://issuetracker.google.com/147808790)) Add documentation specific to each x86 processor type.* diff --git a/docs/configuration/cbi.md b/docs/configuration/cbi.md index f285e8a8c2..d80d31dd13 100644 --- a/docs/configuration/cbi.md +++ b/docs/configuration/cbi.md @@ -8,13 +8,13 @@ before enabling CBI. Add the following config options to `baseboard.h` or `board.h`. -- `CONFIG_BOARD_VERSION_CBI` -- `CONFIG_CROS_BOARD_INFO` +- `CONFIG_BOARD_VERSION_CBI` +- `CONFIG_CROS_BOARD_INFO` ## Feature Parameters -- `I2C_ADDR_EEPROM_FLAGS <7-bit addr>` - Defines the 7-bit slave address for the - EEPROM containing CBI. +- `I2C_ADDR_EEPROM_FLAGS <7-bit addr>` - Defines the 7-bit slave address for + the EEPROM containing CBI. ## GPIOs and Alternate Pins @@ -31,8 +31,9 @@ None required by this feature. ## Testing and Debugging -Refer to the [I2C debugging information] to verify communication with the CBI EEPROM. +Refer to the [I2C debugging information] to verify communication with the CBI +EEPROM. [CBI]: https://chromium.googlesource.com/chromiumos/docs/+/master/design_docs/cros_board_info.md [I2C buses]: ./i2c.md -[I2C debugging information]: ./i2c.md#
\ No newline at end of file +[I2C debugging information]: ./i2c.md# diff --git a/docs/configuration/config_ap_to_ec_comm.md b/docs/configuration/config_ap_to_ec_comm.md index 2fdcc5a147..7110185bcb 100644 --- a/docs/configuration/config_ap_to_ec_comm.md +++ b/docs/configuration/config_ap_to_ec_comm.md @@ -1,7 +1,7 @@ # Configure AP to EC Communication This document provides details on how to configure the AP to EC communication -channel used on your board. The [AP to EC Communication] document provides +channel used on your board. The [AP to EC Communication] document provides details a system level of the operation of this feature. ## Config options @@ -9,13 +9,13 @@ details a system level of the operation of this feature. Configure the AP to EC communication channel, picking exactly one of the following options. -- `CONFIG_HOSTCMD_SPS` - [SPI slave](./ec_terms.md#spi) (SPS) interface -- `CONFIG_HOSTCMD_HECI` - HECI interface -- `CONFIG_HOSTCMD_LPC` - [LPC](./ec_terms.md#lpc) bus -- `CONFIG_HOSTCMD_ESPI` - [eSPI](./ec_terms.md#espi) bus +- `CONFIG_HOSTCMD_SPS` - [SPI slave](./ec_terms.md#spi) (SPS) interface +- `CONFIG_HOSTCMD_HECI` - HECI interface +- `CONFIG_HOSTCMD_LPC` - [LPC](./ec_terms.md#lpc) bus +- `CONFIG_HOSTCMD_ESPI` - [eSPI](./ec_terms.md#espi) bus In [config.h], search for options that start with the same name as your selected -communication interface. Override defaults as needed. +communication interface. Override defaults as needed. ## Feature Parameters @@ -26,26 +26,26 @@ None needed in this section. The EC code requires the following signals between the AP and the EC to be defined by each board variant. -- `GPIO_ENTERING_RW` - Output from the EC, active high signal indicates when the - EC code transitions from RO to RW code. +- `GPIO_ENTERING_RW` - Output from the EC, active high signal indicates when + the EC code transitions from RO to RW code. - ```c - GPIO(EC_ENTERING_RW, PIN(E, 3), GPIO_OUT_LOW) - ``` + ```c + GPIO(EC_ENTERING_RW, PIN(E, 3), GPIO_OUT_LOW) + ``` -- `GPIO_SYS_RESET_L` - Output from the EC, active low signal used to put the AP - into reset. +- `GPIO_SYS_RESET_L` - Output from the EC, active low signal used to put the + AP into reset. - ```c - GPIO(SYS_RST_ODL, PIN(C, 5), GPIO_ODR_HIGH) - ``` + ```c + GPIO(SYS_RST_ODL, PIN(C, 5), GPIO_ODR_HIGH) + ``` Create `ALTERNATE()` entries for all EC signals used for AP communication. This step can be skipped for any pins that default to communication channel functionality. -See the [GPIO](./gpio.md) documentation for additional details on -the GPIO macros. +See the [GPIO](./gpio.md) documentation for additional details on the GPIO +macros. ## Data structures @@ -58,15 +58,15 @@ always required. The typical priority is higher than the `CHIPSET` task, but lower than the `CONSOLE` task. ```c - TASK_ALWAYS(HOSTCMD, host_command_task, NULL, LARGER_TASK_STACK_SIZE, 0) \ + TASK_ALWAYS(HOSTCMD, host_command_task, NULL, LARGER_TASK_STACK_SIZE, 0) \ ``` ## Testing and Debugging For Nuvoton EC chipsets, the file [./chip/npcx/registers.h] provides a collection of `DEBUG_*` macros that can be used to enable extra console messages -related to a specific interface. For AP to EC communication, the `DEBUG_LPC` -and `DEBUG_ESPI` macros can help troubleshoot communication issues. +related to a specific interface. For AP to EC communication, the `DEBUG_LPC` and +`DEBUG_ESPI` macros can help troubleshoot communication issues. [./chip/npcx/registers.h]: ../../chip/npcx/registers.h [AP to EC Communication]: ../ap-ec-comm.md diff --git a/docs/configuration/ec_chipset.md b/docs/configuration/ec_chipset.md index b006736712..defc27eec8 100644 --- a/docs/configuration/ec_chipset.md +++ b/docs/configuration/ec_chipset.md @@ -6,20 +6,20 @@ The EC chipset is selected using board specific make file [build.mk]. The following configuration options specify the type and size of flash memory used by the EC. - - `CONFIG_SPI_FLASH_REGS` - Should always be defined when using internal or +- `CONFIG_SPI_FLASH_REGS` - Should always be defined when using internal or external SPI flash. - - `CONFIG_SPI_FLASH` - Define only if your board uses an external flash. - - `CONFIG_SPI_FLASH_<device_type>` - Select exactly one the supported flash +- `CONFIG_SPI_FLASH` - Define only if your board uses an external flash. +- `CONFIG_SPI_FLASH_<device_type>` - Select exactly one the supported flash devices to compile in the required driver. This is needed even when using the internal SPI flash of the EC chipset. - - Additional EC Chipset options are prefixed with `CONFIG_HIBERNATE*` and +- Additional EC Chipset options are prefixed with `CONFIG_HIBERNATE*` and should be evaluated for relevance on your board. ## Feature Parameters - - `CONFIG_FLASH_SIZE_BYTES <bytes>` - Set to the size of the internal flash of the - EC. Must be defined to link the final image. - - `CONFIG_SPI_FLASH_PORT <port>` - Only used if your board as an external +- `CONFIG_FLASH_SIZE_BYTES <bytes>` - Set to the size of the internal flash of + the EC. Must be defined to link the final image. +- `CONFIG_SPI_FLASH_PORT <port>` - Only used if your board as an external flash. ## GPIOs and Alternate Pins @@ -27,38 +27,39 @@ by the EC. Configure the signals which will wakeup the EC from hibernate or deep sleep. Typical wakeup sources include: -- `GPIO_LID_OPEN` - An active high signal that indicates the lid has been - opened. The source of the signal is typically from a [GMR](../ec_terms.md#gmr) - or Hall-Effect sensor. The `GPIO_INT()` entry for this signal should be - connected to the `lid_interrupt()` routine. -- `GPIO_AC_PRESENT` - A signal from the battery charger that indicates the - device is connected to AC power. This signal is connected to the - `power_interrupt()` routine. -- `GPIO_POWER_BUTTON_L` - An active low signal from the power switch. This signal is connected to the `power_button_interrupt()` routine. -- `GPIO_EC_RST_ODL` - On some Nuvoton EC chipsets, the reset signal is - dual-routed to both a dedicated reset pin and a GPIO. In this case, no - interrupt handler needs to be registered to the GPIO signal, but the GPIO pin - must still be configured to wake on both edge types. The GPIO pin should also - be locked prevent the pin configuration from changing after the EC read-only - code runs. +- `GPIO_LID_OPEN` - An active high signal that indicates the lid has been + opened. The source of the signal is typically from a + [GMR](../ec_terms.md#gmr) or Hall-Effect sensor. The `GPIO_INT()` entry for + this signal should be connected to the `lid_interrupt()` routine. +- `GPIO_AC_PRESENT` - A signal from the battery charger that indicates the + device is connected to AC power. This signal is connected to the + `power_interrupt()` routine. +- `GPIO_POWER_BUTTON_L` - An active low signal from the power switch. This + signal is connected to the `power_button_interrupt()` routine. +- `GPIO_EC_RST_ODL` - On some Nuvoton EC chipsets, the reset signal is + dual-routed to both a dedicated reset pin and a GPIO. In this case, no + interrupt handler needs to be registered to the GPIO signal, but the GPIO + pin must still be configured to wake on both edge types. The GPIO pin should + also be locked prevent the pin configuration from changing after the EC + read-only code runs. See the [GPIO](./gpio.md) documentation for additional details on the GPIO macros. ## Data structures -- `const enum gpio_signal hibernate_wake_pins[]` - add all GPIO signals that - should trigger a wakeup of the EC. -- `const int hibernate_wake_pins_used = ARRAY_SIZE(hibernate_wake_pins);` - - configures the number of wake signals used on the board. +- `const enum gpio_signal hibernate_wake_pins[]` - add all GPIO signals that + should trigger a wakeup of the EC. +- `const int hibernate_wake_pins_used = ARRAY_SIZE(hibernate_wake_pins);` - + configures the number of wake signals used on the board. All ChromeOS wake sources are documented on the ChromeOS partner site in the -[Wake Sources and Battery Life] section. The EC specific wake sources are found +[Wake Sources and Battery Life] section. The EC specific wake sources are found under the Deep Sleep and Shipping states and include: -- Power button -- AC insert -- Lid open +- Power button +- AC insert +- Lid open ## Tasks @@ -95,19 +96,21 @@ ALTERNATE(PIN_MASK(D, BIT(2)), 0, MODULE_PMU, 0) ALTERNATE(PIN_MASK(0, BIT(0) | BIT(1) | BIT(2)), 0, MODULE_PMU, 0) ``` -The final step is to add the hibernate signals array to Volteer [baseboard.c] file: +The final step is to add the hibernate signals array to Volteer [baseboard.c] +file: ```c /* Wake up pins */ const enum gpio_signal hibernate_wake_pins[] = { - GPIO_LID_OPEN, - GPIO_ACOK_OD, - GPIO_POWER_BUTTON_L, - GPIO_EC_RST_ODL, + GPIO_LID_OPEN, + GPIO_ACOK_OD, + GPIO_POWER_BUTTON_L, + GPIO_EC_RST_ODL, }; const int hibernate_wake_pins_used = ARRAY_SIZE(hibernate_wake_pins); ``` + [gpio.inc]: ../../board/volteer/gpio.inc [baseboard.c]: ../../baseboard/volteer/baseboard.c [build.mk]: ../new_board_checklist.md#board_build_mk -[Wake Sources and Battery Life]: https://chromeos.google.com/partner/dlm/docs/latest-requirements/chromebook.html#wake-sources-and-battery-life
\ No newline at end of file +[Wake Sources and Battery Life]: https://chromeos.google.com/partner/dlm/docs/latest-requirements/chromebook.html#wake-sources-and-battery-life diff --git a/docs/configuration/gpio.md b/docs/configuration/gpio.md index 4e13a7cb59..f4a5c4719a 100644 --- a/docs/configuration/gpio.md +++ b/docs/configuration/gpio.md @@ -4,18 +4,18 @@ GPIO setup is done for every board variant, but never for the baseboard, by configuring the file `./board/<board>/gpio.inc`. This file configures all the the pins on the EC chipset through the following macros. -- `GPIO(<name>, ...)` - Configures simple GPIO input and outputs -- `GPIO_INT(<name>, ...)` - Configures GPIO inputs that connect to an interrupt - service routine. Historically these entries are defined first, but this no - longer required. -- `ALTERNATE(...)` - Configures a pin for an alternate function (e.g I2C, ADC, - SPI, etc) -- `UNIMPLEMENTED(<name>, ...)` - Creates a fake GPIO entry +- `GPIO(<name>, ...)` - Configures simple GPIO input and outputs +- `GPIO_INT(<name>, ...)` - Configures GPIO inputs that connect to an + interrupt service routine. Historically these entries are defined first, but + this no longer required. +- `ALTERNATE(...)` - Configures a pin for an alternate function (e.g I2C, ADC, + SPI, etc) +- `UNIMPLEMENTED(<name>, ...)` - Creates a fake GPIO entry The `GPIO()`, `GPIO_INT()`, and `UNIMPLEMENTED()` macros create a C enumeration -of the form `GPIO_<name>` that can be used in the code. As noted in [GPIO -Naming](../new_board_checklist.md#GPIO-Naming), the `<name>` parameter should -always match the schematic net name. +of the form `GPIO_<name>` that can be used in the code. As noted in +[GPIO Naming](../new_board_checklist.md#GPIO-Naming), the `<name>` parameter +should always match the schematic net name. ## `GPIO()` macro @@ -23,13 +23,13 @@ always match the schematic net name. `GPIO(name, pin, flags)` -- `name` - Defines the schematic net name, which is expanded to the enumeration - `GPIO_name` by the macro. -- `pin` - Use the `PIN(group,pin)` macro to define the GPIO group and pin - number. Note that on a few EC chipsets, the PIN macro is just `PIN(pin)`. -- `flags` - Define attributes of the pin (direction, pullup/pulldown, open - drain, voltage level, etc). All supported flags are found following the - `GPIO_FLAG_NONE` definition in [./include/gpio.h](../../include/gpio.h). +- `name` - Defines the schematic net name, which is expanded to the + enumeration `GPIO_name` by the macro. +- `pin` - Use the `PIN(group,pin)` macro to define the GPIO group and pin + number. Note that on a few EC chipsets, the PIN macro is just `PIN(pin)`. +- `flags` - Define attributes of the pin (direction, pullup/pulldown, open + drain, voltage level, etc). All supported flags are found following the + `GPIO_FLAG_NONE` definition in [./include/gpio.h](../../include/gpio.h). ### Example @@ -49,15 +49,16 @@ should also map the net name to the EC name in the `board.h` file. ## `GPIO_INT()` macro ### Prototype + `GPIO_INT(name, pin, flags, signal)` -- `name` - Defines the schematic net name, which is expanded to the enumeration - `GPIO_name` by the macro. -- `pin` - Same definition as `GPIO()` macro. -- `flags` - Same definition as `GPIO()` macro. Should always have one of the - `GPIO_INT_*` flags set. -- `signal` - Interrupt service routine called when the pin asserts according to - the flags set. +- `name` - Defines the schematic net name, which is expanded to the + enumeration `GPIO_name` by the macro. +- `pin` - Same definition as `GPIO()` macro. +- `flags` - Same definition as `GPIO()` macro. Should always have one of the + `GPIO_INT_*` flags set. +- `signal` - Interrupt service routine called when the pin asserts according + to the flags set. ### Example @@ -77,42 +78,43 @@ need to map the net name to the EC name in the `board.h` file. ## `ALTERNATE()` macro ### Prototype + `ALTERNATE(pinmask, function, module, flags)` -- `pinmask` - Defines a set of pins in the same GPIO group to assign to a - different function. -- `function` - A chip-specific function number. Only used if the EC chipset - provides multiple alternate functions in addition to GPIO (e.g. pin can be - UART, I2C, SPI, or GPIO). The permitted values for this parameter vary based - on the EC chipset type. - - STM32 - 0 to 7 - - Maxim - 1 to 3 - - Microchip - 0 to 3 - - MediaTek - 0 to 7 - - All others (Nuvton, ITE, TI Stellaris, ) only support one alternate - function per pin, so this parameter should be set to 0. -- `module` - One of the enum module_id values defined in - [./include/module_id.h](../../include/module_id.h). -- `flags` - Same definition as `GPIO()` macro. +- `pinmask` - Defines a set of pins in the same GPIO group to assign to a + different function. +- `function` - A chip-specific function number. Only used if the EC chipset + provides multiple alternate functions in addition to GPIO (e.g. pin can be + UART, I2C, SPI, or GPIO). The permitted values for this parameter vary based + on the EC chipset type. + - STM32 - 0 to 7 + - Maxim - 1 to 3 + - Microchip - 0 to 3 + - MediaTek - 0 to 7 + - All others (Nuvton, ITE, TI Stellaris, ) only support one alternate + function per pin, so this parameter should be set to 0. +- `module` - One of the enum module_id values defined in + [./include/module_id.h](../../include/module_id.h). +- `flags` - Same definition as `GPIO()` macro. ### Notes At runtime there are two mechanisms for switching a pin between GPIO mode and alternate function mode. -- `gpio_config_module(enum module_id id, int enable)` - Configures all pins - matching the module enumeration `id`. -- `gpio_config_pin(enum module_id id, enum gpio_signal signal, int enable)` - - Configures a single pin matching the GPIO enumeration `signal`. +- `gpio_config_module(enum module_id id, int enable)` - Configures all pins + matching the module enumeration `id`. +- `gpio_config_pin(enum module_id id, enum gpio_signal signal, int enable)` - + Configures a single pin matching the GPIO enumeration `signal`. For both routines, if `enable` is 1, then the corresponding pins are configured -for alternate mode operation. If `enable` is 0, then the corresponding pins are +for alternate mode operation. If `enable` is 0, then the corresponding pins are configure for GPIO mode. `gpio_config_module()` is automatically called at runtime for all enabled interfaces (I2C, SPI, UART, etc). You can use `gpio_config_pin()` to temporarily configure a pin for GPIO operation, and to restore the original alternate -function. The I2C bus error recovery employs this mechanism to temporarily +function. The I2C bus error recovery employs this mechanism to temporarily driver the I2C SCL and SDA signals to known states, without interference by the I2C controller in the EC chipset. @@ -132,8 +134,6 @@ The general recipe for overriding alternate functions is shown below. gpio_config_pin(MODULE_I2C, GPIO_I2C1_SDA, 1); ``` - - ### Example ![ALTERNATE Example] @@ -148,8 +148,13 @@ ALTERNATE(PIN_MASK(B, BIT(4) | BIT(5)), 0, MODULE_I2C, (GPIO_INPUT | GPIO_SEL_1P appending "export/png" to the Google Drive link. --> <!-- https://docs.google.com/drawings/d/18cWTYQRRCpypYDOLlvKQJTObwcj6wOjUga02B0oZXBg --> + [GPIO Example]: ../images/gpio_example.png + <!-- https://docs.google.com/drawings/d/1X6p5XfB6BBmUUKCrwOg56Bz6LZj9P_WPQXsOdk-OIiI --> + [GPIO_INT Example]: ../images/gpio_int_example.png + <!-- https://docs.google.com/drawings/d/1-kroVezQuA_KdQLzqYPs8u94EBg37z3k6lKzkSLRv-0 --> + [ALTERNATE Example]: ../images/alternate_example.png diff --git a/docs/configuration/i2c.md b/docs/configuration/i2c.md index 7a6241e349..23406ad1e1 100644 --- a/docs/configuration/i2c.md +++ b/docs/configuration/i2c.md @@ -14,10 +14,10 @@ The following parameters control the behavior of the I2C library. [config.h] defines a reasonable default value, but you may need to change the default value for your board. -- `CONFIG_I2C_CHIP_MAX_TRANSFER_SIZE <bytes>` -- `CONFIG_I2C_NACK_RETRY_COUNT <count>` -- `CONFIG_I2C_EXTRA_PACKET_SIZE <bytes>` - Only used on STM32 EC's if - `CONFIG_HOSTCMD_I2C_ADDR_FLAGS` is defined. +- `CONFIG_I2C_CHIP_MAX_TRANSFER_SIZE <bytes>` +- `CONFIG_I2C_NACK_RETRY_COUNT <count>` +- `CONFIG_I2C_EXTRA_PACKET_SIZE <bytes>` - Only used on STM32 EC's if + `CONFIG_HOSTCMD_I2C_ADDR_FLAGS` is defined. ## GPIOs and Alternate Pins @@ -28,7 +28,7 @@ recovery actions using bit-banging without involvement by the EC-specific I2C device driver. You also need to define the alternate function assignment for all I2C pins using -the `ALTERNATE()` macro. This step can be skipped for any pins that default to +the `ALTERNATE()` macro. This step can be skipped for any pins that default to I2C functionality. Note that many I2C buses only support 1.8V operation. This is determined by I2C @@ -42,12 +42,12 @@ macros. ## Data Structures -- `const struct i2c_port_t i2c_ports[]` - This array should be defined in your - baseboard.c or board.c file. This array defines the mapping of internal I2C - port numbers used by the I2C library to the physical I2C ports connected to - the EC. -- `const unsigned int i2c_port_used = ARRAY_SIZE(i2c_ports)` - Defines the - number of internal I2C ports accessible by the I2C library. +- `const struct i2c_port_t i2c_ports[]` - This array should be defined in your + baseboard.c or board.c file. This array defines the mapping of internal I2C + port numbers used by the I2C library to the physical I2C ports connected to + the EC. +- `const unsigned int i2c_port_used = ARRAY_SIZE(i2c_ports)` - Defines the + number of internal I2C ports accessible by the I2C library. ## Tasks @@ -57,14 +57,14 @@ None required by this feature. ### Console Commands -- `i2cscan` - Provides a quick look of all I2C devices found on all configured - buses. -- `i2cxfer` - Allows you to read and write individual registers on an I2C - device. +- `i2cscan` - Provides a quick look of all I2C devices found on all configured + buses. +- `i2cxfer` - Allows you to read and write individual registers on an I2C + device. -For runtime troubleshooting of an I2C device, enable and the [I2C -tracing](../i2c-debugging.md) module to log all I2C transactions initiated by -the EC code. +For runtime troubleshooting of an I2C device, enable and the +[I2C tracing](../i2c-debugging.md) module to log all I2C transactions initiated +by the EC code. ## Example @@ -72,8 +72,8 @@ The image below shows the I2C bus assignment for the Volteer reference board. ![I2C Example] -The `gpio.inc` file for Volteer defines both `GPIO()` and `ALTERNATE()` entries for -all I2C buses used in the design. +The `gpio.inc` file for Volteer defines both `GPIO()` and `ALTERNATE()` entries +for all I2C buses used in the design. ```c /* I2C pins - Alternate function below configures I2C module on these pins */ @@ -101,17 +101,17 @@ ALTERNATE(PIN_MASK(B, BIT(3) | BIT(2)), 0, MODULE_I2C, 0) The `i2c_ports[]` array requires the `.port` field to be assigned to an EC chipset specific enumeration. For the NPCx7 I2C bus names are defined in -[./chip/npcx/registers.h]. The Volteer `baseboard.h` file creates a mapping -from the schematic net name to the NPCx7 I2C bus enumeration. +[./chip/npcx/registers.h]. The Volteer `baseboard.h` file creates a mapping from +the schematic net name to the NPCx7 I2C bus enumeration. ```c #define CONFIG_I2C -#define I2C_PORT_SENSOR NPCX_I2C_PORT0_0 -#define I2C_PORT_USB_C0 NPCX_I2C_PORT1_0 -#define I2C_PORT_USB_C1 NPCX_I2C_PORT2_0 -#define I2C_PORT_USB_1_MIX NPCX_I2C_PORT3_0 -#define I2C_PORT_POWER NPCX_I2C_PORT5_0 -#define I2C_PORT_EEPROM NPCX_I2C_PORT7_0 +#define I2C_PORT_SENSOR NPCX_I2C_PORT0_0 +#define I2C_PORT_USB_C0 NPCX_I2C_PORT1_0 +#define I2C_PORT_USB_C1 NPCX_I2C_PORT2_0 +#define I2C_PORT_USB_1_MIX NPCX_I2C_PORT3_0 +#define I2C_PORT_POWER NPCX_I2C_PORT5_0 +#define I2C_PORT_EEPROM NPCX_I2C_PORT7_0 ``` The last piece for I2C configuration is to create the `i2c_ports[]` array using @@ -120,56 +120,56 @@ the macros and enumerations added to `baseboard.h` and `gpio.inc`. ```c /* I2C port map configuration */ const struct i2c_port_t i2c_ports[] = { - { - .name = "sensor", - .port = I2C_PORT_SENSOR, - .kbps = 400, - .scl = GPIO_EC_I2C0_SENSOR_SCL, - .sda = GPIO_EC_I2C0_SENSOR_SDA, - .flags = 0, - }, - { - .name = "usb_c0", - .port = I2C_PORT_USB_C0, - /* - * I2C buses used for PD communication must be set for 400 kbps - * or greater. Set to the maximum speed supported by all devices. - */ - .kbps = 1000, - .scl = GPIO_EC_I2C1_USB_C0_SCL, - .sda = GPIO_EC_I2C1_USB_C0_SDA, - }, - { - .name = "usb_c1", - .port = I2C_PORT_USB_C1, - /* - * I2C buses used for PD communication must be set for 400 kbps - * or greater. Set to the maximum speed supported by all devices. - */ - .scl = GPIO_EC_I2C2_USB_C1_SCL, - .sda = GPIO_EC_I2C2_USB_C1_SDA, - }, - { - .name = "usb_1_mix", - .port = I2C_PORT_USB_1_MIX, - .kbps = 100, - .scl = GPIO_EC_I2C3_USB_1_MIX_SCL, - .sda = GPIO_EC_I2C3_USB_1_MIX_SDA, - }, - { - .name = "power", - .port = I2C_PORT_POWER, - .kbps = 100, - .scl = GPIO_EC_I2C5_POWER_SCL, - .sda = GPIO_EC_I2C5_POWER_SDA, - }, - { - .name = "eeprom", - .port = I2C_PORT_EEPROM, - .kbps = 400, - .scl = GPIO_EC_I2C7_EEPROM_SCL, - .sda = GPIO_EC_I2C7_EEPROM_SDA, - }, + { + .name = "sensor", + .port = I2C_PORT_SENSOR, + .kbps = 400, + .scl = GPIO_EC_I2C0_SENSOR_SCL, + .sda = GPIO_EC_I2C0_SENSOR_SDA, + .flags = 0, + }, + { + .name = "usb_c0", + .port = I2C_PORT_USB_C0, + /* + * I2C buses used for PD communication must be set for 400 kbps + * or greater. Set to the maximum speed supported by all devices. + */ + .kbps = 1000, + .scl = GPIO_EC_I2C1_USB_C0_SCL, + .sda = GPIO_EC_I2C1_USB_C0_SDA, + }, + { + .name = "usb_c1", + .port = I2C_PORT_USB_C1, + /* + * I2C buses used for PD communication must be set for 400 kbps + * or greater. Set to the maximum speed supported by all devices. + */ + .scl = GPIO_EC_I2C2_USB_C1_SCL, + .sda = GPIO_EC_I2C2_USB_C1_SDA, + }, + { + .name = "usb_1_mix", + .port = I2C_PORT_USB_1_MIX, + .kbps = 100, + .scl = GPIO_EC_I2C3_USB_1_MIX_SCL, + .sda = GPIO_EC_I2C3_USB_1_MIX_SDA, + }, + { + .name = "power", + .port = I2C_PORT_POWER, + .kbps = 100, + .scl = GPIO_EC_I2C5_POWER_SCL, + .sda = GPIO_EC_I2C5_POWER_SDA, + }, + { + .name = "eeprom", + .port = I2C_PORT_EEPROM, + .kbps = 400, + .scl = GPIO_EC_I2C7_EEPROM_SCL, + .sda = GPIO_EC_I2C7_EEPROM_SDA, + }, }; const unsigned int i2c_ports_used = ARRAY_SIZE(i2c_ports); ``` @@ -184,19 +184,18 @@ different speeds based on the BOARD_VERSION in [CBI]. For example board version operation. `I2C_PORT_FLAG_DYNAMIC_SPEED` is not used to change the I2C bus frequency on the fly depending on the addressed slave device. -An example of changing the I2C bus frequency from the [Kodama -board](../../board/kodama/board.c) is shown below. +An example of changing the I2C bus frequency from the +[Kodama board](../../board/kodama/board.c) is shown below. ```c static void board_i2c_init(void) { - if (board_get_version() < 2) - i2c_set_freq(1, I2C_FREQ_100KHZ); + if (board_get_version() < 2) + i2c_set_freq(1, I2C_FREQ_100KHZ); } DECLARE_HOOK(HOOK_INIT, board_i2c_init, HOOK_PRIO_INIT_I2C); ``` - [config.h]: ../new_board_checklist.md#config_h [./chip/npcx/registers.h]: ../../chip/npcx/registers.h [./include/i2c.h]: ../../include/i2c.h diff --git a/docs/configuration/keyboard.md b/docs/configuration/keyboard.md index f2dc585e1b..c04e8eddbd 100644 --- a/docs/configuration/keyboard.md +++ b/docs/configuration/keyboard.md @@ -8,23 +8,23 @@ appropriate to add to `baseboard.h` or `board.h`. Your board should select only one of these options to configure the protocol used to send keyboard events to the AP. -- `CONFIG_KEYBOARD_PROTOCOL_8042` - Systems with an x86 AP use the 8042 - protocol. -- `CONFIG_KEYBOARD_PROTOCOL_MKBP` - Systems without an x86 AP (e.g. ARM) - typically use the MKBP protocol. +- `CONFIG_KEYBOARD_PROTOCOL_8042` - Systems with an x86 AP use the 8042 + protocol. +- `CONFIG_KEYBOARD_PROTOCOL_MKBP` - Systems without an x86 AP (e.g. ARM) + typically use the MKBP protocol. ## Feature Parameters -- `CONFIG_KEYBOARD_KSO_BASE <pin>` - Evaluate whether this parameter is required - by your board. +- `CONFIG_KEYBOARD_KSO_BASE <pin>` - Evaluate whether this parameter is + required by your board. ## GPIOs and Alternate Pins Define `ALTERNATE()` pin entries for all keyboard matrix signals, to connect the signals to the keyboard controller of the EC chipset. -Note that KSO_02 is purposely not configured for for alternate mode. See the [H1 -Special Requirements](#H1-Special-Requirements) below for details. +Note that KSO_02 is purposely not configured for for alternate mode. See the +[H1 Special Requirements](#H1-Special-Requirements) below for details. ```c /* Example Keyboard pin setup */ @@ -42,8 +42,8 @@ macros. ## Data structures -- `struct keyboard_scan_config keyscan_config` - This must be defined if the - `CONFIG_KEYBOARD_BOARD_CONFIG` option is defined. +- `struct keyboard_scan_config keyscan_config` - This must be defined if the + `CONFIG_KEYBOARD_BOARD_CONFIG` option is defined. ## Tasks @@ -65,27 +65,23 @@ priority is lower than the `HOSTCMD` task. ## Additional Notes -- If you're including keyboard support, you should also define - `CONFIG_CMD_KEYBOARD` to enable keyboard debug commands from the EC console. -- `CONFIG_KEYBOARD_PROTOCOL_MKBP` automatically enables `CONFIG_MKBP_EVENT`. -- Boards that enable `CONFIG_KEYBOARD_PROTOCOL_8042` will often also define - `CONFIG_MKBP_EVENT` for sensor events. In this case only motion sensor data is - reported using the MKBP protocol, keyboard events are provided using the 8042 - protocol. Refer to [Configuring Sensors](./motion_sensors.md) for more - information. +- If you're including keyboard support, you should also define + `CONFIG_CMD_KEYBOARD` to enable keyboard debug commands from the EC console. +- `CONFIG_KEYBOARD_PROTOCOL_MKBP` automatically enables `CONFIG_MKBP_EVENT`. +- Boards that enable `CONFIG_KEYBOARD_PROTOCOL_8042` will often also define + `CONFIG_MKBP_EVENT` for sensor events. In this case only motion sensor data + is reported using the MKBP protocol, keyboard events are provided using the + 8042 protocol. Refer to [Configuring Sensors](./motion_sensors.md) for more + information. ### H1 Special Requirements + On Boards that use the H1 secure microcontroller, one KSI (keyboard scan input) signal and one KSO (keyboard scan output) signal are routed through the H1 microcontroller. There are additional GPIO and configuration options that must -be enabled in this case. -- The KSO_02/COL2 signal is always inverted. Explicitly configure the GPIO to - default low. - ```c - GPIO(KBD_KSO2, PIN(1, 7), GPIO_OUT_LOW) /* KSO_02 inverted */ - ``` -- Add the define `CONFIG_KEYBOARD_COL2_INVERTED` to `baseboard.h` or `board.h`. -- If required by the board, define one of the following options to configure the - KSI pin routed to the H1 microcontroller. - - `CONFIG_KEYBOARD_PWRBTN_ASSERTS_KSI2` - - `CONFIG_KEYBOARD_PWRBTN_ASSERTS_KSI3` +be enabled in this case. - The KSO_02/COL2 signal is always inverted. Explicitly +configure the GPIO to default low. `c GPIO(KBD_KSO2, PIN(1, 7), GPIO_OUT_LOW) /* +KSO_02 inverted */` - Add the define `CONFIG_KEYBOARD_COL2_INVERTED` to +`baseboard.h` or `board.h`. - If required by the board, define one of the +following options to configure the KSI pin routed to the H1 microcontroller. - +`CONFIG_KEYBOARD_PWRBTN_ASSERTS_KSI2` - `CONFIG_KEYBOARD_PWRBTN_ASSERTS_KSI3` diff --git a/docs/configuration/leds.md b/docs/configuration/leds.md index 72a548a306..c4fe7894af 100644 --- a/docs/configuration/leds.md +++ b/docs/configuration/leds.md @@ -2,13 +2,13 @@ LEDs provide status about the following: -- Dedicated battery state/charging state -- Chromebook power -- Adapter power -- Left side USB-C port (battery state/charging state) -- Right side USB-C port (battery state/charging state) -- Recovery mode -- Debug mode +- Dedicated battery state/charging state +- Chromebook power +- Adapter power +- Left side USB-C port (battery state/charging state) +- Right side USB-C port (battery state/charging state) +- Recovery mode +- Debug mode LEDs can be configured as simple GPIOs, with on/off control only, or as PWM with adjustment brightness and color. @@ -18,23 +18,21 @@ adjustment brightness and color. In [config.h], search for options that start with `CONFIG_LED*` and evaluate whether each option is appropriate to add to `baseboard.h` or `board.h`. -- `CONFIG_LED_COMMON` - Should be defined for both GPIO and PWM style LEDs. -- `CONFIG_LED_ONOFF_STATES` - used for GPIO controlled LEDs -- `CONFIG_LED_PWM` - used for PWM controlled LEDs. You must also define - `CONFIG_PWM` when using PWM controlled LEDs. +- `CONFIG_LED_COMMON` - Should be defined for both GPIO and PWM style LEDs. +- `CONFIG_LED_ONOFF_STATES` - used for GPIO controlled LEDs +- `CONFIG_LED_PWM` - used for PWM controlled LEDs. You must also define + `CONFIG_PWM` when using PWM controlled LEDs. ## Feature Parameters -- `CONFIG_LED_PWM_COUNT <count>` - Must be defined when using PWM LEDs +- `CONFIG_LED_PWM_COUNT <count>` - Must be defined when using PWM LEDs Override the following parameters when using PWM LEDs if you don't want to use -the recommended LED color settings. -- `CONFIG_LED_PWM_CHARGE_COLOR <ec_led_color>` -- `CONFIG_LED_PWM_NEAR_FULL_COLOR <ec_led_color>` -- `CONFIG_LED_PWM_CHARGE_ERROR_COLOR <ec_led_color>` -- `CONFIG_LED_PWM_SOC_ON_COLOR <ec_led_color>` -- `CONFIG_LED_PWM_SOC_SUSPEND_COLOR <ec_led_color>` -- `CONFIG_LED_PWM_LOW_BATT_COLOR <ec_led_color>` +the recommended LED color settings. - `CONFIG_LED_PWM_CHARGE_COLOR +<ec_led_color>` - `CONFIG_LED_PWM_NEAR_FULL_COLOR <ec_led_color>` - +`CONFIG_LED_PWM_CHARGE_ERROR_COLOR <ec_led_color>` - +`CONFIG_LED_PWM_SOC_ON_COLOR <ec_led_color>` - `CONFIG_LED_PWM_SOC_SUSPEND_COLOR +<ec_led_color>` - `CONFIG_LED_PWM_LOW_BATT_COLOR <ec_led_color>` ## GPIOs and Alternate Pins @@ -47,20 +45,18 @@ For PWM LEDs, configure the `ALTERNATE()` macro, setting the module type to ## Data structures -For GPIO based LEDs: -- `struct led_descriptor led_bat_state_table[LED_NUM_STATES][LED_NUM_PHASES]` - - Must be defined when `CONFIG_LED_ONOFF_STATES` is used. Defines the LED states - for the platform for various charging states. - -For PWM based LEDs: -- `const enum ec_led_id supported_led_ids[]` - Defines the LED type for all PWM - LEDs in the system. See [./include/ec_commands.h] for a description of the - supported LED types. -- `struct pwm_led led_color_map[]` - Defines the PWM intensity of the individual - LEDs to generate the corresponding color. This table allows for custom tuning - of the LED brightness and color. -- `const struct pwm_channels[]` - Configures the PWM module, refer to the - [Configuring PWM](./pwm.md) section for details. +For GPIO based LEDs: - `struct led_descriptor +led_bat_state_table[LED_NUM_STATES][LED_NUM_PHASES]` - Must be defined when +`CONFIG_LED_ONOFF_STATES` is used. Defines the LED states for the platform for +various charging states. + +For PWM based LEDs: - `const enum ec_led_id supported_led_ids[]` - Defines the +LED type for all PWM LEDs in the system. See [./include/ec_commands.h] for a +description of the supported LED types. - `struct pwm_led led_color_map[]` - +Defines the PWM intensity of the individual LEDs to generate the corresponding +color. This table allows for custom tuning of the LED brightness and color. - +`const struct pwm_channels[]` - Configures the PWM module, refer to the +[Configuring PWM](./pwm.md) section for details. See the [GPIO](./gpio.md) documentation for additional details on the GPIO macros. @@ -73,12 +69,12 @@ None required by this feature. ### Console Commands -- `pwmduty` - *TODO* add description. -- `gpioset` - For GPIO based LEDs, this command lets you directly change the - state of the LED. -- `gpioget` - For GPIO based LEDs, this reads current state of the pin. If the - current state does not track changes made with `gpioset`, check your board for - stuck at high or stuck at low condition. +- `pwmduty` - *TODO* add description. +- `gpioset` - For GPIO based LEDs, this command lets you directly change the + state of the LED. +- `gpioget` - For GPIO based LEDs, this reads current state of the pin. If the + current state does not track changes made with `gpioset`, check your board + for stuck at high or stuck at low condition. If you're having problems with a PWM LED, try reconfiguring the pin as a GPIO to verify the board operation independent of the PWM module. @@ -89,4 +85,4 @@ LED driver chips are used to control the LCD panel backlight. The backlight control is separate from the platform LEDs. [config.h]: ../new_board_checklist.md#config_h -[./include/ec_commands.h]: ../../include/ec_commands.h
\ No newline at end of file +[./include/ec_commands.h]: ../../include/ec_commands.h diff --git a/docs/configuration/motion_sensors.md b/docs/configuration/motion_sensors.md index 4dac939b10..6e84fc3307 100644 --- a/docs/configuration/motion_sensors.md +++ b/docs/configuration/motion_sensors.md @@ -2,12 +2,12 @@ EC sensors are used for the following capabilities: -- Accelerometers in base and lid measure lid angle to toggle between laptop and - tablet modes. -- Ambient light sensors control display backlight level. -- All sensor types, including gyroscope, e-compass, and pressure, are used by - Android apps. -- Special sync sensor type, synchronizes sensor events with AP. +- Accelerometers in base and lid measure lid angle to toggle between laptop + and tablet modes. +- Ambient light sensors control display backlight level. +- All sensor types, including gyroscope, e-compass, and pressure, are used by + Android apps. +- Special sync sensor type, synchronizes sensor events with AP. *TODO* - there is good content available in the most recent [Chrome EC] overview presentation that can be added here. @@ -20,13 +20,12 @@ presentation that can be added here. *TODO* - ## GPIOs and Alternate Pins *TODO* -- `GPIO_EC_INT_L` - Output from the EC, driven low to indicate an event on the - EC is ready for servicing by the AP. +- `GPIO_EC_INT_L` - Output from the EC, driven low to indicate an event on the + EC is ready for servicing by the AP. ## Data Structures @@ -49,4 +48,3 @@ presentation that can be added here. *TODO* [Chrome EC]: https://docs.google.com/presentation/d/1Y3PwNSnCQoCqDfL5rYqfaBP_ZqbMOTw_x83_ry4cro8/view#slide=id.g63bdbcea4b_0_27 - diff --git a/docs/core_runtime.md b/docs/core_runtime.md index f2eb17f069..4a45136234 100644 --- a/docs/core_runtime.md +++ b/docs/core_runtime.md @@ -67,8 +67,8 @@ exceptions should ultimately lead to a reboot. Each task has a *pending* events bitmap[1] implemented as a 32-bit word. Several events are pre-defined for all tasks, the most significant bits on the 32-bit bitmap are reserved for them : the timer pending event on bit 31 -([see the corresponding section](#time)), the requested task wake (bit 29), -the event to kick the waiters on a mutex (bit 30), along with a few hardware +([see the corresponding section](#time)), the requested task wake (bit 29), the +event to kick the waiters on a mutex (bit 30), along with a few hardware specific events. The 19 least significant bits are available for task-specific meanings. diff --git a/docs/ec-3po-design.md b/docs/ec-3po-design.md index 56a217849b..9a7b3c4742 100644 --- a/docs/ec-3po-design.md +++ b/docs/ec-3po-design.md @@ -32,21 +32,22 @@ while trying to parse strings from the EC console. This method can be fairly fragile as debug output can be interleaved with the console input. A lot of items could be improved by switching to this host command packet interface. -* Communicating in packets makes testing easier and more robust. - * When FAFT is running, the EC could be in a binary mode where it only - communicates in host command packets. These packets are easier to parse, - create, and filter on. - * With filtering, you get the added bonus of not having unwanted debug output. - * It allows us to really test the host command interface which is how the EC - talks to the AP anyways. -* Better testing of existing host command handlers. - * By speaking in host command packets, we can reuse the existing host command - handlers which is nice since we'll be using the same handlers that are used - to respond to the AP. -* FAFT would no longer have to worry about the console dropping characters. - * We can add error checking to the interpreter which would automatically retry - errors. This alleviates FAFT from trying to check if the EC had properly - received a line of input. (Ctrl+L) +* Communicating in packets makes testing easier and more robust. + * When FAFT is running, the EC could be in a binary mode where it only + communicates in host command packets. These packets are easier to parse, + create, and filter on. + * With filtering, you get the added bonus of not having unwanted debug + output. + * It allows us to really test the host command interface which is how the + EC talks to the AP anyways. +* Better testing of existing host command handlers. + * By speaking in host command packets, we can reuse the existing host + command handlers which is nice since we'll be using the same handlers + that are used to respond to the AP. +* FAFT would no longer have to worry about the console dropping characters. + * We can add error checking to the interpreter which would automatically + retry errors. This alleviates FAFT from trying to check if the EC had + properly received a line of input. (Ctrl+L) With better and more reliable tests, we can improve the quality of our EC codebase. @@ -63,15 +64,15 @@ be restricted by the type of chip. ### A richer EC console -* We could do things like on-the-fly console channel filtering. -* Coloring specific channels such as "mark all USB PD messages in green". -* Adding colors in general. -* Adding temporary console commands. -* Longer command history which survives EC reboot -* Searching command history -* Redirecting debug output to log files (which causes no interleaving of command - and debug output) -* Bang commands (`!foo`) +* We could do things like on-the-fly console channel filtering. +* Coloring specific channels such as "mark all USB PD messages in green". +* Adding colors in general. +* Adding temporary console commands. +* Longer command history which survives EC reboot +* Searching command history +* Redirecting debug output to log files (which causes no interleaving of + command and debug output) +* Bang commands (`!foo`) ### Better debuggability @@ -80,9 +81,9 @@ such as the keyboard locking up on certain keys or rows. At times like that, it would be nice to have an EC console to see what's going on. Other times maybe having a servo connected might make the issue not present itself. -* We could do cool things like having an EC console without having to hook up - servo. -* Run `ectool` from the chroot using a PTY interface. +* We could do cool things like having an EC console without having to hook up + servo. +* Run `ectool` from the chroot using a PTY interface. ## Deployment Strategy @@ -99,28 +100,28 @@ Phase 1 will most likely consist of getting EC-3PO in place in between servo and the EC while not modifying the behavior of the console too much. In this phase, we can replicate the console interface and achieve the following things. -* Replicate command editing. -* Save command history. -* Add error checking to the console commands. +* Replicate command editing. +* Save command history. +* Add error checking to the console commands. ### Phase 2: Assimilation Phase 2 will start to introduce the host command packet communication. -* Printing will be done via packets and assembled in EC-3PO. -* Console commands now are sent using the host command packets. - * This will be incremental as console commands are converted. -* Add debug output filtering and redirection/logging. +* Printing will be done via packets and assembled in EC-3PO. +* Console commands now are sent using the host command packets. + * This will be incremental as console commands are converted. +* Add debug output filtering and redirection/logging. ### Phase 3: Expansion Phase 3 will expand the feature set of EC-3PO. -* Add PTY interface to `ectool`. -* Add on-device console without `servod`. -* Colored output. -* Command history search. -* Bang commands (`!foo`) +* Add PTY interface to `ectool`. +* Add on-device console without `servod`. +* Colored output. +* Command history search. +* Bang commands (`!foo`) ## High Level Design & Highlights @@ -170,12 +171,12 @@ EC-3PO and the EC can perform error checking when sending the commands to the EC. This feature would be implemented prior to switching to the binary format. The interpreter can package the command in the following manner. -* 2 Ampersands -* 2 hex digits representing the length of the command -* 2 hex digits representing the CRC-8 of the command -* 1 Ampersand -* The command itself -* 2 newline characters. +* 2 Ampersands +* 2 hex digits representing the length of the command +* 2 hex digits representing the CRC-8 of the command +* 1 Ampersand +* The command itself +* 2 newline characters. This is robust because no commands currently start with `&`. If the EC does not see ‘`&&`', then one of the ampersands has been dropped. If the EC doesn't see @@ -295,10 +296,10 @@ prompt by pressing ‘%' . These were originally added for debug purposes. ##### Supported Commands -* `loglevel <integer>` - * Allows setting the effective loglevel of the console and interpreter. -* `interrogate <never | always | auto> [enhanced]` - * Allows control of when and how often interrogation occurs. +* `loglevel <integer>` + * Allows setting the effective loglevel of the console and interpreter. +* `interrogate <never | always | auto> [enhanced]` + * Allows control of when and how often interrogation occurs. ### Interpreter module @@ -323,4 +324,3 @@ Since the interpreter communicates using pipes, it's not necessary that the user use the console module. For example, FAFT could directly connect to the interpreter and send down commands and receive command responses instead of having to deal with the PTY and instead just deal with python objects. - diff --git a/docs/ec-3po.md b/docs/ec-3po.md index 83877374aa..dae7b9babb 100644 --- a/docs/ec-3po.md +++ b/docs/ec-3po.md @@ -5,9 +5,9 @@ ## What is EC-3PO? EC-3PO is the console interpreter that will one day replace the EC console that -we have today. EC-3PO aims to migrate our rich debug console from the EC itself -to the host. This allows us to maintain our rich debug console without -impacting our EC image sizes while also allowing us to add new features. +we have today. EC-3PO aims to migrate our rich debug console from the EC itself +to the host. This allows us to maintain our rich debug console without impacting +our EC image sizes while also allowing us to add new features. For more information, see [the design doc](./ec-3po-design.md). @@ -42,9 +42,9 @@ apparently, `cu` wants group write permissions. On Ubuntu at least, the PTY is created with the `tty` group. If on your machine it's not, then just replace `tty` with whatever group it's created with. -1. Create a `tty` group if you don't have one already. -1. Add root to the `tty` group. -1. Rerun `cu` with `sudo` and it should work now. +1. Create a `tty` group if you don't have one already. +1. Add root to the `tty` group. +1. Rerun `cu` with `sudo` and it should work now. ## Why does the console seem "laggier" than before? @@ -57,10 +57,10 @@ delay is unbearable. To disable the delay: -1. Open the EC console. -1. Press `%` -1. Enter `interrogate never` -1. Then press enter. +1. Open the EC console. +1. Press `%` +1. Enter `interrogate never` +1. Then press enter. \**For `socat` users, due to the line buffered nature, you'll have to just enter `%interrogate never`. Notice the lack of the space character between `%` and the diff --git a/docs/ec_terms.md b/docs/ec_terms.md index 4f1b590b1a..7e3dadce86 100644 --- a/docs/ec_terms.md +++ b/docs/ec_terms.md @@ -1,12 +1,13 @@ # EC Acronyms and Technologies ## Glossary -* **8042 Interface**{#8042} + +* **8042 Interface** {#8042} Interface for sending keyboard events to the [AP](#ap) and for receiving commands from the AP. Only supported by x86 based APs. -* **ACCEL - Accelerometer**{#accel} +* **ACCEL - Accelerometer** {#accel} A sensor that measures acceleration, typically over 3-axis. Nominally provides information about the orientation of a device. On Chromebook 2-in-1 @@ -14,57 +15,57 @@ the measurements from both accelerometers allows for a precise calculation of the lid angle, used to switch between tablet and laptop mode. -* **ACCELGYRO - Accelerometer/Gyroscope**{#accelgyro} +* **ACCELGYRO - Accelerometer/Gyroscope** {#accelgyro} A combination [accelerometer](#accel) and [gyroscope](#gyro) sensor that provides more precise orientation information by measuring both linear and rotational motion. -* **ADC - Analog to Digital Converter**{#adc} +* **ADC - Analog to Digital Converter** {#adc} A sensor that converts an analog voltage to a digital reading. -* **ALS - Ambient Light Sensor**{#als} +* **ALS - Ambient Light Sensor** {#als} A sensor that measures the ambient light present. Used to automatically control the screen and keyboard backlight level. -* **AP - Application Processor**{#ap} +* **AP - Application Processor** {#ap} The processor on the board that boots and runs ChromeOS. -* **BAR - Barometer**{#bar} +* **BAR - Barometer** {#bar} A sensor that measures atmospheric pressure. -* **BC12 - Battery Charging**{#bc12} +* **BC12 - Battery Charging** {#bc12} A device that implements the USB Battery Charging specification, version 1.2. The complete [BC 1.2 Specification] is available from the USB Implementers Forum. -* **CBI - CROS Board Information**{#cbi} +* **CBI - CROS Board Information** {#cbi} A collection of properties describing the board. This includes board version, SKU, model name, and other fields. More details are found in the [CrOS Board Info] documentation. -* **CEC - Consumer Electronics Control**{#cec} +* **CEC - Consumer Electronics Control** {#cec} - A one-wire bidirectional bus. More details are on the [CEC Wikipedia page]. + A one-wire bidirectional bus. More details are on the [CEC Wikipedia page]. -* **DPTF - Dynamic Power and Thermal Framework (Intel)**{#dptf} +* **DPTF - Dynamic Power and Thermal Framework (Intel)** {#dptf} Intel's platform based power and thermal management. See the [DPTF Readme] for details on the implementation used in ChromeOS. -* **EC - Embedded Controller**{#ec} +* **EC - Embedded Controller** {#ec} The [MCU](#mcu) used to control the keyboard, battery charging, USB port switching, sensor management, and other functions, offloading these tasks from the [AP](#ap). -* **EC-3PO**{#ec-3po} +* **EC-3PO** {#ec-3po} A replacement of the current UART-based console which moves much of the code off the EC into a host tool, reducing the amount of flash space required. @@ -73,47 +74,47 @@ See the [USB-C documentation](./usb-c.md#emark) for more details. -* **eSPI - Enhanced Serial Peripheral Interface (Intel)**{#espi} +* **eSPI - Enhanced Serial Peripheral Interface (Intel)** {#espi} Intel's synchronous communication interface between the [AP](#ap) and the [EC](#ec). Supports quad I/O mode and clock speeds up to 66 Mhz, providing bandwidth up to 264 Mbps. The full [eSPI Specification] is available from Intel. -* **FAFT - Fully Automated Firmware Tests**{#faft} +* **FAFT - Fully Automated Firmware Tests** {#faft} A collection of tests and related infrastructure that exercise and verify - capabilities of Chrome OS. See the [FAFT design doc] and [chromium.org - documentation](https://www.chromium.org/for-testers/faft) for more details. - Replaced [SAFT](#saft). + capabilities of Chrome OS. See the [FAFT design doc] and + [chromium.org documentation](https://www.chromium.org/for-testers/faft) for + more details. Replaced [SAFT](#saft). * **GMR - Giant Magnetoresistance Sensor** {#gmr} A sensor device that detects a magnetic field. These sensors differ from [MAG](#mag) sensors, in that they only detect magnetic fields in close proximity to the sensor. On Chromebooks, GMR sensors are used to detect when - the lid is opened. On convertible Chromebooks, the GMR sensor also detects + the lid is opened. On convertible Chromebooks, the GMR sensor also detects tablet mode when lid the is opened a full 360 degrees. -* **GPIO - General Purpose Input/Output**{#gpio} +* **GPIO - General Purpose Input/Output** {#gpio} - An individual signal that can independently controlled and read. GPIOs are + An individual signal that can independently controlled and read. GPIOs are used to enable/disable power rails, drive reset signals, and receive - interrupts from devices connected to the EC. GPIOs may also be connected - to [I/O expanders](#ioexpander). + interrupts from devices connected to the EC. GPIOs may also be connected to + [I/O expanders](#ioexpander). -* **GYRO - Gyroscope**{#gyro} +* **GYRO - Gyroscope** {#gyro} A sensor that measures angular momentum, providing information about rotational motion of the device. -* **I/O Expander**{#ioexpander} +* **I/O Expander** {#ioexpander} An [I2C](#i2c) peripheral device that provides additional GPIO signals - (anywhere from 8 - 32 signals). GPIOs behind an I/O expander are written - and read using I2C register accesses from the I2C controller in the EC. + (anywhere from 8 - 32 signals). GPIOs behind an I/O expander are written and + read using I2C register accesses from the I2C controller in the EC. -* **I2C - Inter-Integrated Circuit**{#i2c} +* **I2C - Inter-Integrated Circuit** {#i2c} A 2-wire synchronous communication bus, consisting of a clock signal and a bidirectional data signal. An I2C bus typically contains one controller @@ -121,101 +122,101 @@ supported clock speeds of 100 KHz and 400 KHz. The full [I2C Specification] is available from NXP (formerly Phillips). -* **LED - Light Emitting Diode**{#led} +* **LED - Light Emitting Diode** {#led} A Light Emitting Diode is a semiconductor that emits light when current flows through it. -* **LPC - [Low Pin Count bus]**{#lpc} +* **LPC - [Low Pin Count bus]** {#lpc} Legacy communication bus between the [AP](#ap) and [EC](#ec). Runs at 33 - MHz, providing a 133 Mbps bandwidth connection. Replaced by the + MHz, providing a 133 Mbps bandwidth connection. Replaced by the [eSPI](#espi) interface. -* **MAG - Magnetometer**{#mag} +* **MAG - Magnetometer** {#mag} A digital compass sensor, providing orientation for navigation. -* **MCU - Microcontroller Unit**{#mcu} +* **MCU - Microcontroller Unit** {#mcu} A small integrated chip containing a CPU core, on-chip ROM, on-chip RAM. Also contains multiple peripheral interfaces, including GPIO, I2C buses, SPI buses, ADC, PWM, etc. -* **MKBP - Matrix Keyboard Protocol**{#mkbp} +* **MKBP - Matrix Keyboard Protocol** {#mkbp} Message based protocol for communicating asynchronous events from the [EC](#ec) to the [AP](#ap). Events are not limited to keyboard events with the sensor subsystem as one of the main users. An EC board implementation - can be configured to send keyboard events through MKBP or using the [8042 - interface](#8042). This is the [EC MKBP driver] implementation. + can be configured to send keyboard events through MKBP or using the + [8042 interface](#8042). This is the [EC MKBP driver] implementation. -* **MST - Multi Stream Transport**{#mst} +* **MST - Multi Stream Transport** {#mst} Part of the Display Port 1.2 standard, used to drive multiple independent video streams from a single display port. The EC code is typically responsible for enabling and disabling the MST hub chipset. -* **OOBM - Out of Band Management**{#oobm} +* **OOBM - Out of Band Management** {#oobm} A command in the [EC-3PO protocol](#ec-3po) that allows commands to be entered to alter the behaviour of the console and interpreter during runtime. -* **PD - USB Power Delivery**{#pd} +* **PD - USB Power Delivery** {#pd} See the [USB-C documentation](./usb-c.md#pd) for more details. -* **PMIC - Power Management IC**{#pmic} +* **PMIC - Power Management IC** {#pmic} An integrated circuit used to turn power rails on and off. -* **PPC - USB Power Path Controller**{#ppc} +* **PPC - USB Power Path Controller** {#ppc} See the [USB-C documentation](./usb-c.md#ppc) for more details. -* **PWM - Pulse Width Modulation**{#pwm} +* **PWM - Pulse Width Modulation** {#pwm} Method of varying the duty cycle of a signal to control another device. A typical application is to control fan speeds or the brightness of a backlight. -* **SAFT - Semi-Automated Firmware Tests**{#saft} +* **SAFT - Semi-Automated Firmware Tests** {#saft} A suite of tests for firmware, succeeded by [FAFT](#faft). See the [chromium.org documentation](https://www.chromium.org/for-testers/saft) for more details. -* **SPI - Serial Peripheral Interconnect**{#spi} +* **SPI - Serial Peripheral Interconnect** {#spi} A 4-wire synchronous communication bus consisting of the signals CLK (clock), SDO (Serial Data Out), SDI (Serial Data In), and CS (chip-select, - one per SPI peripheral). The SDO and SDI pins are defined from the + one per SPI peripheral). The SDO and SDI pins are defined from the perspective of the device: the SPI controller's SDO pin connects to the SPI peripheral's SDI pin and vice-versa. Clock speeds over 100 MHz are supported. SPI communication involves the following sequence: - * SPI controller asserts CS. - * SPI controller transmits one or bytes on its SDO signal, received by the - SPI peripheral on its SDI signal. - * SPI peripheral transmits zero or more bytes on its SDO signal, received - by the SPI controller on its SDI signal. - * SPI controller de-asserts CS. + * SPI controller asserts CS. + * SPI controller transmits one or bytes on its SDO signal, received by the + SPI peripheral on its SDI signal. + * SPI peripheral transmits zero or more bytes on its SDO signal, received + by the SPI controller on its SDI signal. + * SPI controller de-asserts CS. The specific contents of a SPI frame varies based on the SPI peripheral type. -* **SVDM - Structured Vendor Defined Messages**{#svdm} +* **SVDM - Structured Vendor Defined Messages** {#svdm} See the [USB-C documentation](./usb-c.md#svdm) for more details. -* **TCPC - USB Type-C Port Controller**{#tcpc} +* **TCPC - USB Type-C Port Controller** {#tcpc} See the [USB-C documentation](./usb-c.md#tcpc) for more details. -* **UART - Universal Asynchronous Receiver Transceiver**{#uart} +* **UART - Universal Asynchronous Receiver Transceiver** {#uart} - Also known as a serial port. An asynchronous communication channel between + Also known as a serial port. An asynchronous communication channel between two devices with a dedicated receive pin, transmit pin, and ground. Optional hardware flow control signals require additional connections between the devices. Standard transmission rates are slow (up to 115200 bits per @@ -226,7 +227,6 @@ See the [USB-C documentation](./usb-c.md#vconn) for more details. - [BC 1.2 Specification]: <https://www.usb.org/document-library/battery-charging-v12-spec-and-adopters-agreement> [CrOS Board Info]: <https://chromium.googlesource.com/chromiumos/docs/+/master/design_docs/cros_board_info.md> [CEC Wikipedia page]: <https://en.wikipedia.org/wiki/Consumer_Electronics_Control> diff --git a/docs/fingerprint/fingerprint-firmware-testing-for-partners.md b/docs/fingerprint/fingerprint-firmware-testing-for-partners.md index d82c164874..b96d94b1de 100644 --- a/docs/fingerprint/fingerprint-firmware-testing-for-partners.md +++ b/docs/fingerprint/fingerprint-firmware-testing-for-partners.md @@ -2,9 +2,9 @@ This document is intended to help partners (sensor vendors, MCU vendors, etc) run the Chrome OS fingerprint team's firmware tests, as part of the AVL process. -The document assumes that you‘re using Linux to do the development; preferably -a recent version of Ubuntu or Debian. It may be possible to use a virtual -machine, but that is not a configuration we test. +The document assumes that you‘re using Linux to do the development; preferably a +recent version of Ubuntu or Debian. It may be possible to use a virtual machine, +but that is not a configuration we test. [TOC] @@ -39,7 +39,8 @@ This document will assume you are using Servo V4. fingerprint sensor. * Connect the "DUT POWER" side of Servo V4 to power supply. * Make sure the USB cable from the host machine to Servo V4 is in data - transfer mode (i.e. if there's an LED, it should be yellow instead of green). + transfer mode (i.e. if there's an LED, it should be yellow instead of + green). * Make sure the you can ssh into the Chromebook from the chroot on the host machine. diff --git a/docs/fingerprint/fingerprint.md b/docs/fingerprint/fingerprint.md index a27f513c80..1004545453 100644 --- a/docs/fingerprint/fingerprint.md +++ b/docs/fingerprint/fingerprint.md @@ -337,7 +337,8 @@ When the MCU is idling waiting for an AP message: @@ pp3300_dx_mcu_mw 1285 21.26 0.08 22.36 20.99 ``` -When the MCU is in **low power** mode during the AP suspend (as emulated by `dut-control slp_s3:on`): +When the MCU is in **low power** mode during the AP suspend (as emulated by +`dut-control slp_s3:on`): ``` @@ NAME COUNT AVERAGE STDDEV MAX MIN diff --git a/docs/i2c-debugging.md b/docs/i2c-debugging.md index 7ab84f9d8d..125e72b777 100644 --- a/docs/i2c-debugging.md +++ b/docs/i2c-debugging.md @@ -1,13 +1,10 @@ -I²C Debugging Tips -================== +# I²C Debugging Tips -The EC codebase has functionality to help you debug I²C errors without -pulling out the scope. Some of the debug functionality is disabled by -default to save space, but can be enabled with the `CONFIG_I2C_DEBUG` -option. +The EC codebase has functionality to help you debug I²C errors without pulling +out the scope. Some of the debug functionality is disabled by default to save +space, but can be enabled with the `CONFIG_I2C_DEBUG` option. -Tracing -------- +## Tracing You can use the `i2ctrace` command to monitor (ranges of) addresses: @@ -51,4 +48,4 @@ Note that `i2ctrace enable` will merge debug entries when possible: id port address -- ---- ------- 0 0 0x10 to 0x50 -```
\ No newline at end of file +``` diff --git a/docs/low_battery_startup.md b/docs/low_battery_startup.md index de346546c8..48f9c28f49 100644 --- a/docs/low_battery_startup.md +++ b/docs/low_battery_startup.md @@ -1,8 +1,8 @@ # Configuring the EC for Low-Battery Startup Near the bottom of charge, starting up a ChromeOS device can be a tricky -proposition. Several features interact to make it difficult to reliably turn on -the machine without browning out. Over the years, a variety of configuration +proposition. Several features interact to make it difficult to reliably turn on +the machine without browning out. Over the years, a variety of configuration options have been written to maximize ChromeOS's compatibility with the basic user expectation, @@ -26,23 +26,23 @@ which are available. ### Battery and Charging Circuit For the most part, ChromeOS device power systems are much like other laptop -battery power systems. A variable-voltage rail is connected to the battery via -a series of cutoff MOSFETs. Several system power rails derive their power from -the system's variable-voltage rail. Mains power is delivered to the -variable-voltage system rail by a buck/boost charging circuit. Mains power is -itself rectified, isolated, and stepped down by an external power supply. +battery power systems. A variable-voltage rail is connected to the battery via a +series of cutoff MOSFETs. Several system power rails derive their power from the +system's variable-voltage rail. Mains power is delivered to the variable-voltage +system rail by a buck/boost charging circuit. Mains power is itself rectified, +isolated, and stepped down by an external power supply. During most of the battery charge, the charger operates in current mode, acting as a constant current source that delivers current to the variable-voltage rail. -Load transients are served by the capacitance on the rail and the battery. By +Load transients are served by the capacitance on the rail and the battery. By superposition, load transients during the charge don't necessarily draw current from the battery, they may just reduce the current flow into the battery. References to AC power in the EC codebase are actually references to an external -power supply's DC source. External supplies that are actually USB-PD-speaking +power supply's DC source. External supplies that are actually USB-PD-speaking battery packs are indistinguishable from AC/DC adapters as far as the EC is -concerned. Variables and functions which refer to external supplies all refer -to them as 'AC', though. +concerned. Variables and functions which refer to external supplies all refer to +them as 'AC', though. ### Source Current Negotiation @@ -50,13 +50,13 @@ A device may draw power from an AC adapter via a few methods. #### USB BC1.2 Current Sources -BC1.2 negotiation is usually managed entirely by an external IC. Once it is -complete, the EC limits itself to 2.4A max. Additionally, the charger may be +BC1.2 negotiation is usually managed entirely by an external IC. Once it is +complete, the EC limits itself to 2.4A max. Additionally, the charger may be configured to switch to an input voltage regulation mode if the input voltage begins to sag too low. Ideally, the input source provides a voltage droop, such that it is not quite -overloaded at the input voltage regulation setpoint of about 4.5V. Thus, 4.5V +overloaded at the input voltage regulation setpoint of about 4.5V. Thus, 4.5V serves as a reasonable reference voltage for the charger to use when it is in an input voltage-regulation mode. @@ -68,45 +68,45 @@ See also `driver/bc12/max14637.c:bc12_detect()`. #### USB-PD Sources High-current power supplies are negotiated via the USB Type C Current Source and -USB Power Delivery specifications (PD). PD sources must support Type-C Current -Source, but the reverse is not true. Both types of current sources are managed +USB Power Delivery specifications (PD). PD sources must support Type-C Current +Source, but the reverse is not true. Both types of current sources are managed via the PD protocol module in the EC codebase. Type-C Current Source capabilities of up to 15W (3A, 5V) are advertised via -analog signaling alone. Via digital communication in the PD protocol, much -higher power states may be negotiated. However, higher power states also -usually run at a higher voltage state as well. Any time the voltage level is -changing, the power sink (the ChromeOS device) must lower its power consumption -during the transient. The standby current level is governed by +analog signaling alone. Via digital communication in the PD protocol, much +higher power states may be negotiated. However, higher power states also usually +run at a higher voltage state as well. Any time the voltage level is changing, +the power sink (the ChromeOS device) must lower its power consumption during the +transient. The standby current level is governed by `CONFIG_CHARGER_INPUT_CURRENT`. -PD port partners are capable of both soft and hard resets. Hard resets will +PD port partners are capable of both soft and hard resets. Hard resets will cause a dead-bus state for a brief interval before PD can renegotiate, from -scratch, because it is intended to emulate a cable disconnect. Therefore, a -hard reset without a connected battery will brownout the Chromebook. +scratch, because it is intended to emulate a cable disconnect. Therefore, a hard +reset without a connected battery will brownout the Chromebook. ### Locked and Unlocked Firmware The Verified Boot implementation normally limits the complexity of the code -which executes in the locked Read-Only firmware package. The consequences for +which executes in the locked Read-Only firmware package. The consequences for the EC are: -- Locked RO EC firmware does not process any digital PD messages at all, it only - recognizes the analog advertisement of USB Current Source (15W max). -- Installation of user-provided firmware is supported, but the write-protect pin - must be cleared to enable it. -- On recent systems, write-protect is cleared by removing the system battery. +- Locked RO EC firmware does not process any digital PD messages at all, it + only recognizes the analog advertisement of USB Current Source (15W max). +- Installation of user-provided firmware is supported, but the write-protect + pin must be cleared to enable it. +- On recent systems, write-protect is cleared by removing the system battery. ### ChromeOS `powerd` The power management daemon provided by ChromeOS displays a "low-power charger" warning message via the system tray whenever the charger is limited to less than -20W. Therefore, if a USB-PD source is restricted to analog signaling, or a -BC1.2 source is connected, the user gets alerted to the situation. +20W. Therefore, if a USB-PD source is restricted to analog signaling, or a BC1.2 +source is connected, the user gets alerted to the situation. Systems that can run on very little power may be rapidly charged with a 15W charger, while a high power system may require a 40W state or more for a decent -battery charging user experience. Therefore, a board's overlay may override the +battery charging user experience. Therefore, a board's overlay may override the warning threshold by replacing `/usr/share/power_manager/usb_min_ac_watts` in the board's filesystem. @@ -116,7 +116,7 @@ See also `platform2/power_manager/` source code. Under normal conditions, the battery pack is equipped with a management IC which is solely responsible for the safety of the battery, measurement of the state of -charge, and the balance of its cells. Examples include (but are not limited to) +charge, and the balance of its cells. Examples include (but are not limited to) the TI BQ40Z50 and Renesas RAJ240. However, after very long periods of rest without a battery charging cycle, the @@ -124,7 +124,7 @@ natural self-discharge rate of each cell will cause them to diverge somewhat from each other. Some IC's can be configured to report a pack total state of charge of zero if -any one cell's voltage is below a certain threshold. However, many do not. +any one cell's voltage is below a certain threshold. However, many do not. Therefore, after an extended rest period, one cell can be very close to the cell undervoltage cutoff threshold, even though the pack as a whole is considered to be at 3% charge or more. @@ -132,14 +132,14 @@ be at 3% charge or more. ### Power Profile During Boot The power profile during the boot sequence is substantially different than that -seen during typical use. Dynamic voltage and frequency scaling of the AP is -partially governed by the temperature of the processor core. As the processor +seen during typical use. Dynamic voltage and frequency scaling of the AP is +partially governed by the temperature of the processor core. As the processor gets hotter, it will reduce its maximum core voltage and frequency to settle out -at some maximum design junction temperature for the core. For passively cooled +at some maximum design junction temperature for the core. For passively cooled devices, the profile may also be chosen to limit the external case temperature. -At startup, the case and core are cold. The bootloaders and kernel are also -optimized to boot as fast as possible for a responsive user experience. So, the +At startup, the case and core are cold. The bootloaders and kernel are also +optimized to boot as fast as possible for a responsive user experience. So, the power drawn during the boot is much higher than that seen during typical productivity and entertainment tasks. @@ -148,17 +148,15 @@ productivity and entertainment tasks. After verification and optional update of the EC's RW firwmare, Depthcharge will poll the EC to verify that it is allowed to proceed to boot to the kernel. -It does this by polling via the: -- `EC_CMD_CHARGE_STATE` host command. -- `CHARGE_STATE_CMD_GET_PARAM` subcommand. -- `CS_PARAM_LIMIT_POWER` parameter. +It does this by polling via the: - `EC_CMD_CHARGE_STATE` host command. - +`CHARGE_STATE_CMD_GET_PARAM` subcommand. - `CS_PARAM_LIMIT_POWER` parameter. When the EC returns 0, power draw by the AP is unlimited and depthcharge resumes -the boot. If the EC fails to return 0 in three seconds, depthcharge shuts down. +the boot. If the EC fails to return 0 in three seconds, depthcharge shuts down. See also vb2ex_ec_vboot_done() in Depthcharge, and option -`CONFIG_CHARGER_LIMIT_POWER_THRESH_CHG_MW` in the EC. By default, this option -is not set, and the EC immediately allows the boot to proceed. +`CONFIG_CHARGER_LIMIT_POWER_THRESH_CHG_MW` in the EC. By default, this option is +not set, and the EC immediately allows the boot to proceed. ## Example Low-Battery Boot Sequences and Configurations @@ -166,7 +164,7 @@ Most ChromeOS devices power needs will be met by one of the following templates. ### Low-Power Device -Low-power devices require 15W or less of power to boot the AP. The battery pack +Low-power devices require 15W or less of power to boot the AP. The battery pack is robust enough to support the device during brief intervals of PD negotiation without browning out. @@ -178,33 +176,33 @@ without browning out. A detailed boot sequence under this configuration, with a low battery and available AC power via a USB-PD charger: -1. EC ROM bootloader loads and jumps to the EC's read-only firmware image. -1. RO firmware negotiates a 15W state via Current Source analog signaling and - begins charging the battery with it. -1. RO firmware verifies conditions to begin booting the AP: - - Battery state of charge > 1% - - OR charger power greater or equal to 15W (met by Current Source analog - signaling). -1. AP firmware performs verification of the EC's RW image, upgrades it if - necessary, and sysjumps the EC to it. -1. AP firmware queries the charge state limit power flag via EC-host command, - and the EC immediately responds that it is clear. -1. Depthcharge continues the boot. - 1. In parallel with kernel loading and Linux's boot, the EC performs PD - negotiation. Charger power lowers to 2.5W for up to 500ms as the source +1. EC ROM bootloader loads and jumps to the EC's read-only firmware image. +1. RO firmware negotiates a 15W state via Current Source analog signaling and + begins charging the battery with it. +1. RO firmware verifies conditions to begin booting the AP: + - Battery state of charge > 1% + - OR charger power greater or equal to 15W (met by Current Source analog + signaling). +1. AP firmware performs verification of the EC's RW image, upgrades it if + necessary, and sysjumps the EC to it. +1. AP firmware queries the charge state limit power flag via EC-host command, + and the EC immediately responds that it is clear. +1. Depthcharge continues the boot. + 1. In parallel with kernel loading and Linux's boot, the EC performs PD + negotiation. Charger power lowers to 2.5W for up to 500ms as the source transitions from vSafe5V to its highest supported voltage (15V or 20V - are typical). During this transition time some power is drawn from the + are typical). During this transition time some power is drawn from the battery. - 1. After PD negotiation is complete, the EC raises the charger current + 1. After PD negotiation is complete, the EC raises the charger current limit to the negotiated limit (45W is typical). ### Low-Power Device Startup With Marginal Battery Compatibility Similar in configuration to the low-power device startup, this system enables additional options to maximize its compatibility with marginal batteries near -the bottom of charge. The Grunt family is an exemplar. This system will -complete software sync with less than 15W of power, but may require more power -to boot the kernel and get to the login screen. +the bottom of charge. The Grunt family is an exemplar. This system will complete +software sync with less than 15W of power, but may require more power to boot +the kernel and get to the login screen. ``` /* Limit battery impact during PD voltage changes. */ @@ -229,34 +227,32 @@ battery must support per-cell voltage measurement. A detailed boot sequence under this configuration, with a low battery and available AC power: -1. EC ROM bootloader loads and jumps to the EC's read-only firmware image. -1. RO firmware negotiates a 15W state via Current Source analog signaling and - begins charging the battery with it. -1. RO firmware verifies conditions to begin booting the AP: - - battery state of charge >= 3% AND cell imbalance < 200 mV - - OR battery state of charge >= 5% - - OR charger power greater or equal to 15W (met by Current Source analog - signaling). -1. AP firmware performs verification of the EC's RW image, upgrades it if - necessary, and sysjumps the EC to it. -1. AP firmware polls the charge state limit power flag via EC-host command for - up to 3 seconds, in 50ms intervals. The EC will return `1` (power limited) - so long as the charger power is < 15.001W and the battery is less than 3%. - 1. Meanwhile, the EC performs PD negotiation. Charger power lowers to 2.5W +1. EC ROM bootloader loads and jumps to the EC's read-only firmware image. +1. RO firmware negotiates a 15W state via Current Source analog signaling and + begins charging the battery with it. +1. RO firmware verifies conditions to begin booting the AP: + - battery state of charge >= 3% AND cell imbalance < 200 mV + - OR battery state of charge >= 5% + - OR charger power greater or equal to 15W (met by Current Source analog + signaling). +1. AP firmware performs verification of the EC's RW image, upgrades it if + necessary, and sysjumps the EC to it. +1. AP firmware polls the charge state limit power flag via EC-host command for + up to 3 seconds, in 50ms intervals. The EC will return `1` (power limited) + so long as the charger power is < 15.001W and the battery is less than 3%. + 1. Meanwhile, the EC performs PD negotiation. Charger power lowers to 2.5W for up to 500ms as the source transitions from vSafe5V to its highest supported voltage (15V or 20V are typical). - 1. After negotiation is complete, the EC raises the charger current limit + 1. After negotiation is complete, the EC raises the charger current limit to the negotiated limit (45W is typical). - 1. The EC returns 0 (unlimited) on the next `LIMIT_POWER` request. -1. Depthcharge continues to boot Linux. - + 1. The EC returns 0 (unlimited) on the next `LIMIT_POWER` request. +1. Depthcharge continues to boot Linux. ### High-Power Boot Device Startup A "high-power device" in this case is one that requires significantly more than -15W of power to boot the AP. These devices may complete software sync at 15W or -less. Very briefly drawing current out of the battery does not cause a -brownout. +15W of power to boot the AP. These devices may complete software sync at 15W or +less. Very briefly drawing current out of the battery does not cause a brownout. Example configuration: @@ -267,42 +263,40 @@ Example configuration: #define CONFIG_CHARGER_LIMIT_POWER_THRESH_CHG_MW 27000 ``` -Where the low-power device specified a threshold that just barely -requires PD negotiation to happen before booting, this device has a definite -minimum power to boot Linux (27W). A detailed boot sequence under this -configuration, with a low battery and available AC power: - -1. EC ROM bootloader loads and jumps to the EC's read-only firmware image. -1. RO firmware negotiates a 15W state via Current Source analog signaling and - begins charging the battery with it. -1. RO firmware verifies conditions to begin booting the AP: - - battery state of charge >= 3% - - OR charger power greater or equal to 15W (met by Current Source analog - signaling). -1. AP firmware performs verification of the EC's RW image, upgrades it if - necessary, and sysjumps the EC to it. -1. AP firmware polls the charge state limit power flag via EC-host command for - up to 3 seconds, in 50ms intervals. The EC will return `1` (power limited) - so long as the charger power is < 27W and the battery is less than 3%. - 1. Meanwhile, the EC performs PD negotiation. Charger power lowers to 2.5W +Where the low-power device specified a threshold that just barely requires PD +negotiation to happen before booting, this device has a definite minimum power +to boot Linux (27W). A detailed boot sequence under this configuration, with a +low battery and available AC power: + +1. EC ROM bootloader loads and jumps to the EC's read-only firmware image. +1. RO firmware negotiates a 15W state via Current Source analog signaling and + begins charging the battery with it. +1. RO firmware verifies conditions to begin booting the AP: + - battery state of charge >= 3% + - OR charger power greater or equal to 15W (met by Current Source analog + signaling). +1. AP firmware performs verification of the EC's RW image, upgrades it if + necessary, and sysjumps the EC to it. +1. AP firmware polls the charge state limit power flag via EC-host command for + up to 3 seconds, in 50ms intervals. The EC will return `1` (power limited) + so long as the charger power is < 27W and the battery is less than 3%. + 1. Meanwhile, the EC performs PD negotiation. Charger power lowers to 2.5W for up to 500ms as the source transitions from vSafe5V to its highest supported voltage (15V or 20V are typical). - 1. After negotiation is complete, the EC raises the charger current limit + 1. After negotiation is complete, the EC raises the charger current limit to the negotiated limit (45W is typical). - 1. The EC returns 0 (unlimited) on the next `LIMIT_POWER` request. -1. Depthcharge continues to boot Linux. - + 1. The EC returns 0 (unlimited) on the next `LIMIT_POWER` request. +1. Depthcharge continues to boot Linux. ### High-Power SwSync Device Startup Like the high-power boot device startup, these devices draw less than 15W during most of the software sync process, but may briefly exceed 15W during short -intervals of software sync. However, there is substantial risk of brownout -during those intervals unless the battery is charged up a bit first. Therefore, +intervals of software sync. However, there is substantial risk of brownout +during those intervals unless the battery is charged up a bit first. Therefore, they strictly require 1% battery capacity to perform software sync. Additionally, this configuration requires PD negotiation to be complete prior to -performing a no-battery boot. Nami is an exemplar. - +performing a no-battery boot. Nami is an exemplar. Example configuration: @@ -319,28 +313,27 @@ Example configuration: #define CONFIG_CHARGER_LIMIT_POWER_THRESH_CHG_MW 27000 ``` -1. EC ROM bootloader loads and jumps to the EC's read-only firmware image. -1. RO firmware negotiates a 15W state via Current Source analog signaling and - begins charging the battery with it. -1. RO firmware verifies conditions to begin booting the AP: - - Battery state of charge is greater than 1% AND charger power is greater - than 15W (met after a minute or so of charging on analog signaling) - - OR Battery state of charge is greater than 3% - - OR Charger power is greater than 27W (met after PD negotiation in - unlocked RO firmware). -1. AP firmware performs verification of the EC's RW image, upgrades it if - necessary, and sysjumps the EC to it. -1. AP firmware polls the charge state limit power flag via EC-host command for - up to 3 seconds, in 50ms intervals. The EC will return `1` (power limited) - so long as the charger power is < 27W and the battery is less than 3%. - 1. Meanwhile, the EC performs PD negotiation. Charger power lowers to 2.5W +1. EC ROM bootloader loads and jumps to the EC's read-only firmware image. +1. RO firmware negotiates a 15W state via Current Source analog signaling and + begins charging the battery with it. +1. RO firmware verifies conditions to begin booting the AP: + - Battery state of charge is greater than 1% AND charger power is greater + than 15W (met after a minute or so of charging on analog signaling) + - OR Battery state of charge is greater than 3% + - OR Charger power is greater than 27W (met after PD negotiation in + unlocked RO firmware). +1. AP firmware performs verification of the EC's RW image, upgrades it if + necessary, and sysjumps the EC to it. +1. AP firmware polls the charge state limit power flag via EC-host command for + up to 3 seconds, in 50ms intervals. The EC will return `1` (power limited) + so long as the charger power is < 27W and the battery is less than 3%. + 1. Meanwhile, the EC performs PD negotiation. Charger power lowers to 2.5W for up to 500ms as the source transitions from vSafe5V to its highest supported voltage (15V or 20V are typical). - 1. After negotiation is complete, the EC raises the charger current limit + 1. After negotiation is complete, the EC raises the charger current limit to the negotiated limit (45W is typical). - 1. The EC returns 0 (unlimited) on the next `LIMIT_POWER` request. -1. Depthcharge continues to boot Linux. - + 1. The EC returns 0 (unlimited) on the next `LIMIT_POWER` request. +1. Depthcharge continues to boot Linux. ## Configuration Option Details @@ -348,12 +341,12 @@ Example configuration: Required. -The lowest current limit programmed into the charger. This determines both the +The lowest current limit programmed into the charger. This determines both the default level used on startup, and the value used during the voltage transients in PD negotiation. It should not be higher than 512 mA unless the device ships with a discrete -power supply. Raising this term above 512 mA is contrary to USB-PD. It may be +power supply. Raising this term above 512 mA is contrary to USB-PD. It may be lowered in order to improve compatibility with marginal BC1.2 chargers. ### `CONFIG_CHARGER_MIN_BAT_PCT_FOR_POWER_ON` @@ -372,7 +365,7 @@ than `CHARGER_MIN_BAT_PCT_FOR_POWER_ON`, in milliwatts. ### `CONFIG_BATTERY_MEASURE_IMBALANCE` -Optional. Only set this option if one or more batteries shipped with this board +Optional. Only set this option if one or more batteries shipped with this board support per-cell battery voltage measurement. When enabled, the EC will query the attached battery for its per-cell voltages. @@ -381,15 +374,15 @@ is inhibited. #### `CONFIG_CHARGER_MIN_BAT_PCT_IMBALANCED_POWER_ON` -Default: 5%. Above this battery state of charge, cell voltage balance is +Default: 5%. Above this battery state of charge, cell voltage balance is ignored. #### `CONFIG_BATTERY_MAX_IMBALANCE_MV` -Default: 200 mV. If the difference between the highest and lowest cell exceeds +Default: 200 mV. If the difference between the highest and lowest cell exceeds this value, then the pack is considered to be imbalanced. -Note that lithium chemistry cells will almost always read similar voltages. It +Note that lithium chemistry cells will almost always read similar voltages. It is only near the top and bottom of charge that the slope of dV/dQ increases enough for small cell imbalances to be visible as a voltage difference. @@ -425,4 +418,3 @@ Optional. Similar to `CONFIG_CHARGER_MIN_POWER_MW_FOR_POWER_ON`, this is the minimum charger power needed to boot even when the battery is less than `CONFIG_CHARGER_MIN_BAT_PCT_FOR_POWER_ON_WITH_AC` - diff --git a/docs/new_board_checklist.md b/docs/new_board_checklist.md index 22e8d25988..69a9e78638 100644 --- a/docs/new_board_checklist.md +++ b/docs/new_board_checklist.md @@ -6,38 +6,47 @@ This document describes the high-level steps needed to create a new EC board. If you're creating a new board based on existing baseboard, you can jump straight -to the relevant link found under [Configuring EC -Features](#Configure-EC-Features) and focus on known board changes. +to the relevant link found under +[Configuring EC Features](#Configure-EC-Features) and focus on known board +changes. ## Conventions + ### Key Files + Before you get started, it's important to understand the role of a few key files in the EC codebase. -- [`include/config.h`](../include/config.h) {#config_h} - Contains the list of - top-level configuration options for the Chrome EC codebase. Each configuration - option is documented inline and is considered the authoritative definition. - -- `baseboard/<name>/` - This directory contains header files and source files - shared by all boards in a baseboard family. - - `baseboard.h` - Contains the EC configuration options shared by all - devices in the baseboard family. - - `baseboard.c` - Contains code shared by all devices in the baseboard - family. - - `build.mk` - The board family makefile specifies C source files compiled - into all boards in the baseboard family. - -- `board/<board>` - Files in this directory are only built for a single board. - - `board.h` - EC configuration options specific to a single board. - - `board.c` - Code built only on this board. - - `build.mk` {#board_build_mk} - The board makefile defines the EC chipset family, defines the - baseboard name, and specifies the C source files that are compiled. - - `gpio.inc` - This C header file defines the interrupts, GPIOs, and - alternate function selection for all pins on the EC chipset. - - `ec.tasklist` - This C header defines the lists of tasks that are enabled - on the board. See the main EC documentation more details on [EC tasks]. +- [`include/config.h`](../include/config.h) {#config_h} - Contains the list of + top-level configuration options for the Chrome EC codebase. Each + configuration option is documented inline and is considered the + authoritative definition. + +- `baseboard/<name>/` - This directory contains header files and source files + shared by all boards in a baseboard family. + + - `baseboard.h` - Contains the EC configuration options shared by all + devices in the baseboard family. + - `baseboard.c` - Contains code shared by all devices in the baseboard + family. + - `build.mk` - The board family makefile specifies C source files compiled + into all boards in the baseboard family. + +- `board/<board>` - Files in this directory are only built for a single board. + + - `board.h` - EC configuration options specific to a single board. + - `board.c` - Code built only on this board. + - `build.mk` {#board_build_mk} - The board makefile defines the EC chipset + family, defines the baseboard name, and specifies the C source files + that are compiled. + - `gpio.inc` - This C header file defines the interrupts, GPIOs, and + alternate function selection for all pins on the EC chipset. + - `ec.tasklist` - This C header defines the lists of tasks that are + enabled on the board. See the main EC documentation more details on + [EC tasks]. ### GPIO Naming + Many drivers and libraries in the common EC code rely on board variants defining an exact GPIO signal name. Examples include the `GPIO_LID_OPEN`, `GPIO_ENTERING_RW`, and `GPIO_SYS_RESET_L` signals. The net names in schematics @@ -46,7 +55,7 @@ all the `GPIO_INT()`, `GPIO()`, `ALTERNATE()`, and `UNIMPLEMENTED()` definitions in `gpio.inc` use the schematic net name. You then create `#define` macros in `board.h` to map the net names to the EC common names. -Below is an example configuration for the SYS_RESET_L signal. The schematic net +Below is an example configuration for the SYS_RESET_L signal. The schematic net name of this signal is EC_RST_ODL and the signal connects to the EC chipset pin GPIO02. @@ -63,6 +72,7 @@ Please see the [GPIO](./configuration/gpio.md) documentation for additional details on the GPIO macros. ## How to use this document + Each of the following sections details a single feature set that may need to be modified or configured for your new board. The feature sets are organized so they can be implemented with a reasonably sized change list, and can be worked @@ -70,34 +80,31 @@ on independently. Each configuration feature document includes the following sub-tasks: -- **Config Options** - This section details the `CONFIG_*` options relevant to - the feature. Use the documentation found in [config.h] to determine whether - each option should be enabled (using #define) or disabled (using #undef) in - the relevant `baseboard.h` or `board.h` file. -- **Feature Parameters** - This section details parameters that control the - operation of the feature. Similar to the config options, feature parameters - are defined in [config.h] and prefixed with `CONFIG_*`. However, feature - parameters are assigned a default value, which can be overridden in by - `baseboard.h` or `board.h` using an `#undef/#define` pair. - ```c - #undef CONFIG_UART_TX_BUF_SIZE - #define CONFIG_UART_TX_BUF_SIZE 4096 - ``` -- **GPIOs and Alternate Pins** - This section details signals and pins relevant - to the feature. Add the required `GPIO_INT()`, `GPIO()`, `ALTERNATE()`, and - `UNIMPLEMENTED()` definitions to `gpio.inc`, making sure to follow the [GPIO - naming conventions]. -- **Data Structures** - This section details the data structures required to - configure the feature for correct operation. Add the data structures to - `baseboard.c` or `board.c`. Note that most data structures required by the - common EC code should be declared `const` to save on RAM usage. -- **Tasks** - This section details the tasks that the EC feature requires for - operation. -- **Testing and Debugging** - This section details strategies for testing the EC - feature set and for debugging issues. This section also documents EC console - commands related to the feature set. -- **Example** - When present, this section walks through a complete example for - configuring an EC feature based on an existing board implementation. +- **Config Options** - This section details the `CONFIG_*` options relevant to + the feature. Use the documentation found in [config.h] to determine whether + each option should be enabled (using #define) or disabled (using #undef) in + the relevant `baseboard.h` or `board.h` file. +- **Feature Parameters** - This section details parameters that control the + operation of the feature. Similar to the config options, feature parameters + are defined in [config.h] and prefixed with `CONFIG_*`. However, feature + parameters are assigned a default value, which can be overridden in by + `baseboard.h` or `board.h` using an `#undef/#define` pair. `c #undef + CONFIG_UART_TX_BUF_SIZE #define CONFIG_UART_TX_BUF_SIZE 4096` +- **GPIOs and Alternate Pins** - This section details signals and pins + relevant to the feature. Add the required `GPIO_INT()`, `GPIO()`, + `ALTERNATE()`, and `UNIMPLEMENTED()` definitions to `gpio.inc`, making sure + to follow the [GPIO naming conventions]. +- **Data Structures** - This section details the data structures required to + configure the feature for correct operation. Add the data structures to + `baseboard.c` or `board.c`. Note that most data structures required by the + common EC code should be declared `const` to save on RAM usage. +- **Tasks** - This section details the tasks that the EC feature requires for + operation. +- **Testing and Debugging** - This section details strategies for testing the + EC feature set and for debugging issues. This section also documents EC + console commands related to the feature set. +- **Example** - When present, this section walks through a complete example + for configuring an EC feature based on an existing board implementation. ## Create the new EC board @@ -113,8 +120,8 @@ are found in the corresponding [README.md] documentation. The [new_variant.py] script also verifies the new EC board compiles and prepares a changelist to upload to Gerrit. You should upload this changelist unmodified -for review and submission (you may need to run `make buildall -k` to satisfy -the EC pre-submit tests). +for review and submission (you may need to run `make buildall -k` to satisfy the +EC pre-submit tests). The next step is to review the following sections to make any needed modifications to your new board files, test the changes, and upload the changes @@ -128,8 +135,8 @@ populate these directories with the minimum set of files required compile the EC board. The initial changelists for the Hatch and Volteer reference boards provide good examples for how to start. - * [Volteer EC skeleton build] - * [Hatch EC skeleton build] +* [Volteer EC skeleton build] +* [Hatch EC skeleton build] After submitting the skeleton builds, review the following sections and add each feature set as required by your design. @@ -143,20 +150,20 @@ priority and should be ready before the first prototypes arrive. Use the documentation link for details about the code changes required to implement each feature. -| EC Feature | Needed for Power On | -| :--------- | ------------------: | -| [Configure EC Chipset](./configuration/ec_chipset.md) | yes | -| [Configure AP to EC Communication](./configuration/config_ap_to_ec_comm.md) | yes | -| [Configure AP Power Sequencing](./configuration/ap_power_sequencing.md) | yes | -| [Configure USB-C](./usb-c.md) | yes | -| [Configure Charger (TODO)](./configuration/template.md) | yes | -| [Configure I2C Buses](./configuration/i2c.md) | no | -| [Configure CrOS Board Information (CBI)](./configuration/cbi.md) | no | -| [Configure Keyboard](./configuration/keyboard.md) | no | -| [Configure LEDs](./configuration/leds.md) | no | -| [Configure Motion Sensors (TODO)](./configuration/motion_sensors.md) | no | -| [Configure BC1.2 Charger Detector (TODO)](./configuration/template.md) | no | -| [Configure Battery (TODO)](./configuration/template.md) | no | +EC Feature | Needed for Power On +:-------------------------------------------------------------------------- | ------------------: +[Configure EC Chipset](./configuration/ec_chipset.md) | yes +[Configure AP to EC Communication](./configuration/config_ap_to_ec_comm.md) | yes +[Configure AP Power Sequencing](./configuration/ap_power_sequencing.md) | yes +[Configure USB-C](./usb-c.md) | yes +[Configure Charger (TODO)](./configuration/template.md) | yes +[Configure I2C Buses](./configuration/i2c.md) | no +[Configure CrOS Board Information (CBI)](./configuration/cbi.md) | no +[Configure Keyboard](./configuration/keyboard.md) | no +[Configure LEDs](./configuration/leds.md) | no +[Configure Motion Sensors (TODO)](./configuration/motion_sensors.md) | no +[Configure BC1.2 Charger Detector (TODO)](./configuration/template.md) | no +[Configure Battery (TODO)](./configuration/template.md) | no After finishing the changes required for all EC features, it is recommended that you make one final pass over all the GPIOs and pin assignments used on your @@ -169,4 +176,4 @@ board. Refer to the [GPIO](./configuration/gpio.md) documentation for details. [Hatch EC skeleton build]:https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/1377569/ [config.h]: ./new_board_checklist.md#config_h [EC tasks]: ../README.md#Tasks -[GPIO naming conventions]: ./new_board_checklist.md#GPIO-Naming
\ No newline at end of file +[GPIO naming conventions]: ./new_board_checklist.md#GPIO-Naming diff --git a/docs/sitemap.md b/docs/sitemap.md index 7c9f73a5dd..e3367b78de 100644 --- a/docs/sitemap.md +++ b/docs/sitemap.md @@ -35,7 +35,7 @@ ## Testing * [Unit Tests](./unit_tests.md) - * [Porting EC unit tests to Ztest](./ztest.md) + * [Porting EC unit tests to Ztest](./ztest.md) * [Code Coverage](./code_coverage.md) ## Updaters diff --git a/docs/unit_tests.md b/docs/unit_tests.md index eeb618fbb7..1b79b727d8 100644 --- a/docs/unit_tests.md +++ b/docs/unit_tests.md @@ -31,19 +31,19 @@ Build and run all unit tests: Unit tests live in the [`test`] subdirectory of the CrOS EC codebase. All new unit tests should be written to use the Zephyr Ztest -[API](https://docs.zephyrproject.org/latest/guides/test/ztest.html). -If you are making significant changes to an existing test, you should also -look at porting the test from the EC test API to the Ztest API. +[API](https://docs.zephyrproject.org/latest/guides/test/ztest.html). If you are +making significant changes to an existing test, you should also look at porting +the test from the EC test API to the Ztest API. -Using the Ztest API makes the unit tests suitable for submitting upstream to -the Zephyr project, and reduces the porting work when the EC transitions to -the Zephyr RTOS. +Using the Ztest API makes the unit tests suitable for submitting upstream to the +Zephyr project, and reduces the porting work when the EC transitions to the +Zephyr RTOS. ### File headers -Include [`test_util.h`] and any other required includes. In this example, -the function being tested is defined in the test, but a real unit test would -include the header file for the module that defines `some_function`. +Include [`test_util.h`] and any other required includes. In this example, the +function being tested is defined in the test, but a real unit test would include +the header file for the module that defines `some_function`. `test/my_test.c`: @@ -57,9 +57,9 @@ static bool some_function(void) } ``` -[`test_util.h`] includes `ztest.h` if `CONFIG_ZEPHYR` is defined, -or defines a mapping from the `zassert` macros to the EC -`TEST_ASSERT` macros if `CONFIG_ZEPHYR` is not defined. +[`test_util.h`] includes `ztest.h` if `CONFIG_ZEPHYR` is defined, or defines a +mapping from the `zassert` macros to the EC `TEST_ASSERT` macros if +`CONFIG_ZEPHYR` is not defined. ### Test cases @@ -96,14 +96,8 @@ test_static EC_TEST_RETURN test_my_function(void) ``` The only difference between those two versions of `test/my_test.c` is the -assertion: -```c - zassert_true(condition, NULL); -``` -versus -```c - TEST_EQ(condition, true, "%d"); -``` +assertion: `c zassert_true(condition, NULL);` versus `c TEST_EQ(condition, true, +"%d");` ### Specify the test cases to run @@ -185,22 +179,24 @@ Build and run the test as an EC unit test: ``` For building the test as a Zephyr Ztest unit test, follow the instructions in -[Porting EC unit tests to Ztest](./ztest.md) to build the unit test for -Zephyr's "native_posix" host-based target. +[Porting EC unit tests to Ztest](./ztest.md) to build the unit test for Zephyr's +"native_posix" host-based target. +<!-- mdformat off(b/139308852) --> *** note **TIP**: Unit tests should be independent from each other as much as possible. This keeps the test (and any system state) simple to reason about and also allows running unit tests in parallel. You can use the [`before_test` hook][`test_util.h`] to reset the state before each test is run. *** +<!-- mdformat on --> ## Mocks -We do not yet support mocks for Zephyr Ztest-based tests. -[Mocks][`mock`] enable you to simulate behavior for parts of the system that -you're not directly testing. They can also be useful for testing specific edge -cases that are hard to exercise during normal use (e.g., error conditions). +We do not yet support mocks for Zephyr Ztest-based tests. [Mocks][`mock`] enable +you to simulate behavior for parts of the system that you're not directly +testing. They can also be useful for testing specific edge cases that are hard +to exercise during normal use (e.g., error conditions). See the [Mock README] for details. diff --git a/docs/usb-c.md b/docs/usb-c.md index 1549b2abcc..1e009f82b2 100644 --- a/docs/usb-c.md +++ b/docs/usb-c.md @@ -71,14 +71,17 @@ Modes in the EC codebase. * Upstream Facing Port. The USB data role that is typical for a peripheral (e.g. HID keyboard). * DFP {#dfp} + * Downstream Facing Port. The USB Data role that is typical for a host machine (e.g. device running ChromeOS). * E-Mark {#emark} + * Electronically marked cable. A USB-C cable that contains an embedded chip in the cable, used to identify the capabilities of the cable. * VCONN {#vconn} + * Connector Voltage. A dedicated power supply rail for [E-Mark](#emark) cables and other accessory functions (such as display dongles, and docks). VCONN re-uses one of the CC1/CC2 signals to provide 5 volt, 1 @@ -205,8 +208,8 @@ TODO(https://crbug.com/974302): mention `USB_CHG_P#` and `CHARGER` ## Upgrading FW for TCPCs -TODO(https://crbug.com/974302): Mention how this works even though it is in depthcharge. -Probing now. Need new driver in depthcharge +TODO(https://crbug.com/974302): Mention how this works even though it is in +depthcharge. Probing now. Need new driver in depthcharge [Case Closed Debugging (CCD)]: https://chromium.googlesource.com/chromiumos/platform/ec/+/cr50_stab/docs/case_closed_debugging_cr50.md [Introduction to USB Power Delivery]: https://www.microchip.com/wwwAppNotes/AppNotes.aspx?appnote=en575003 diff --git a/docs/usb-tcpmv2.md b/docs/usb-tcpmv2.md index 0afd07c3e6..b942b048d8 100644 --- a/docs/usb-tcpmv2.md +++ b/docs/usb-tcpmv2.md @@ -1,6 +1,11 @@ # EC USB-C Power Delivery TCPMv2 Overview -As the original USB-C Power Delivery (PD) solution for the ChromeOS Embedded Controller has aged, it has grown to the point where it is difficult to add new features and address bugs. A new PD stack (generally referred to as TCPMv2) has been introduced to the codebase for use moving forward. It implements a layered, state-based design which tracks more closely with the USB Type-C and USB PD specifications. +As the original USB-C Power Delivery (PD) solution for the ChromeOS Embedded +Controller has aged, it has grown to the point where it is difficult to add new +features and address bugs. A new PD stack (generally referred to as TCPMv2) has +been introduced to the codebase for use moving forward. It implements a layered, +state-based design which tracks more closely with the USB Type-C and USB PD +specifications. [TOC] @@ -8,38 +13,51 @@ As the original USB-C Power Delivery (PD) solution for the ChromeOS Embedded Con Boards may enable TCPMv2 by adding the following defines: - - * `CONFIG_USB_PD_TCPMV2`Configures the board to use the new stack. -* `CONFIG_USB_DRP_ACC_TRYSRC`: Configures the type of state machine to run (in this case, a DRP which performs Try.SRC behavior). Currently available are DRP and charge-through Vconn-powered device options -* `CONFIG_USB_PD_DECODE_SOP`: Sets up messaging for SOP’ and SOP’’, which is strongly encouraged in the TCPMv2 code moving forward -* `CONFIG_USB_PID 0x1234`: Sets the USB Product Identifier. This will be shared for all boards within one reference design, and new PIDs may be requested by sending an email to the ChromeOS FW Team. -* `CONFIG_USB_PD_REV30`: The TCPMv2 stack defaults to PD2.0 operation but defining this macro enables PD3.0 functionality. - -Other configurations to specify behaviors within the task still apply (ex. `CONFIG_USB_PD_ALT_MODE_DFP` and `CONFIG_USB_PD_TCPC_LOW_POWER`). - +* `CONFIG_USB_DRP_ACC_TRYSRC`: Configures the type of state machine to run (in + this case, a DRP which performs Try.SRC behavior). Currently available are + DRP and charge-through Vconn-powered device options +* `CONFIG_USB_PD_DECODE_SOP`: Sets up messaging for SOP’ and SOP’’, which is + strongly encouraged in the TCPMv2 code moving forward +* `CONFIG_USB_PID 0x1234`: Sets the USB Product Identifier. This will be + shared for all boards within one reference design, and new PIDs may be + requested by sending an email to the ChromeOS FW Team. +* `CONFIG_USB_PD_REV30`: The TCPMv2 stack defaults to PD2.0 operation but + defining this macro enables PD3.0 functionality. + +Other configurations to specify behaviors within the task still apply (ex. +`CONFIG_USB_PD_ALT_MODE_DFP` and `CONFIG_USB_PD_TCPC_LOW_POWER`). ## State Machine Framework -The basis of the TCPMv2 state machines is a generic state machine framework. This framework can be found in common/usbc/usb\_sm.c. For each state, there may be defined: - - +The basis of the TCPMv2 state machines is a generic state machine framework. +This framework can be found in common/usbc/usb\_sm.c. For each state, there may +be defined: * Entry: Called upon entering a state * Run: Called while steady in a state * Exit: Called upon leaving a state -* Parent: Superstate. Enters, exits, and runs alongside the child state. Only enters and exits when transitioning between states which do not share the parent. - -All fields are optional and may be set to NULL. A new state is transitioned to with a call into set\_state(), which exits the old state and parents and enters the new parents and state. States may be changed with set\_state() in any entry or run function, but any call from an exit function is ignored since exit is only called when a change is already in progress. While in a state, run\_state() executes the run function for the current state and parents. If set\_state() is called from either an entry function or a run function, the remaining run or entry functions are stopped. - -Below is a graphical example of what some states may look like. States 1 and 2 share Parent State 1, while State 3 has Parent State of 2. - +* Parent: Superstate. Enters, exits, and runs alongside the child state. Only + enters and exits when transitioning between states which do not share the + parent. + +All fields are optional and may be set to NULL. A new state is transitioned to +with a call into set\_state(), which exits the old state and parents and enters +the new parents and state. States may be changed with set\_state() in any entry +or run function, but any call from an exit function is ignored since exit is +only called when a change is already in progress. While in a state, run\_state() +executes the run function for the current state and parents. If set\_state() is +called from either an entry function or a run function, the remaining run or +entry functions are stopped. + +Below is a graphical example of what some states may look like. States 1 and 2 +share Parent State 1, while State 3 has Parent State of 2.  - -Translated into code, this would be something like below (note it is not necessary that the states be a part of an array, but the TCPMv2 code generally organizes the states in this way): - +Translated into code, this would be something like below (note it is not +necessary that the states be a part of an array, but the TCPMv2 code generally +organizes the states in this way): ``` static const struct usb_state test_states[] = { @@ -74,23 +92,18 @@ static const struct usb_state test_states[] = { }; ``` - -For this example, each test state is written simply to produce a print of its function name. The two exceptions are: - - +For this example, each test state is written simply to produce a print of its +function name. The two exceptions are: * parent\_1\_run() calls set\_state() into STATE\_2 when called a second time * state\_2\_entry() calls set\_state() into STATE\_3 Graphically, this is represented below: -  - And the following code output is produced: - ``` Calling run_state() state_1_run @@ -112,74 +125,97 @@ state_3_run parent_2_run ``` - - ## TCPMv2 PD Task -The TCPMv2 PD task is built upon state machines using the above framework and is located in common/usbc/usbc\_task.c. It is separated into three layers which track with the USB Type-C and USB PD specification states and run in a loop with 5 ms periods between executions. A graphical representation of these layers is below. - - +The TCPMv2 PD task is built upon state machines using the above framework and is +located in common/usbc/usbc\_task.c. It is separated into three layers which +track with the USB Type-C and USB PD specification states and run in a loop with +5 ms periods between executions. A graphical representation of these layers is +below.  - -The task is designed such that the Type-C (TC) layer could run independently for any application which doesn’t wish to enable PD messaging. Boards define their appropriate Policy Engine (PE) and TC state machines through their selection of a CONFIG\_USB\_\* define, with current options supporting both Dual-Role Ports (DRPs) and Charge-Through Vconn-Powered Device (CTVPD). All boards use the same Protocol Layer (PRL) code. - +The task is designed such that the Type-C (TC) layer could run independently for +any application which doesn’t wish to enable PD messaging. Boards define their +appropriate Policy Engine (PE) and TC state machines through their selection of +a CONFIG\_USB\_\* define, with current options supporting both Dual-Role Ports +(DRPs) and Charge-Through Vconn-Powered Device (CTVPD). All boards use the same +Protocol Layer (PRL) code. ## TCPMv2 Layers - ### Overview -The three state machines mentioned above interact with each other and the EC drivers in order to orchestrate all Type-C connection behavior. Graphically, they are represented below. - - +The three state machines mentioned above interact with each other and the EC +drivers in order to orchestrate all Type-C connection behavior. Graphically, +they are represented below.  - -Layers communicate with each other using atomic operations on flags and shared buffers. Functions calling into each layer are clearly named to indicate the layer they are acting on, and anything calling into the PD task should be doing so through pd\_\* named functions. - -Some specific examples of how this communication works between layers is below. If a port partner sends in a Vconn\_swap request, then: - - - -* PRL will communicate that a message was received to the PE layer through pe\_message\_received(), which sets PE\_FLAGS\_MSG\_RECEIVED and indicates the receive buffer has a message -* PE asks with the TC whether the board is sourcing Vconn with tc\_is\_vconn\_src() which checks TC\_FLAGS\_VCONN\_ON -* PE tells the PRL to send an ACCEPT message to the port partner through prl\_send\_ctrl\_msg() which fills in shared message information and sets PRL\_FLAGS\_MSG\_XMIT -* PRL lets the PE know that the message transmit was successful through pe\_message\_sent() which sets PE\_FLAGS\_TX\_COMPLETE -* TC tells the PE layer that the Vconn swap completed with pe\_vconn\_swap\_complete() which sets PE\_FLAGS\_VCONN\_SWAP\_COMPLETE - +Layers communicate with each other using atomic operations on flags and shared +buffers. Functions calling into each layer are clearly named to indicate the +layer they are acting on, and anything calling into the PD task should be doing +so through pd\_\* named functions. + +Some specific examples of how this communication works between layers is below. +If a port partner sends in a Vconn\_swap request, then: + +* PRL will communicate that a message was received to the PE layer through + pe\_message\_received(), which sets PE\_FLAGS\_MSG\_RECEIVED and indicates + the receive buffer has a message +* PE asks with the TC whether the board is sourcing Vconn with + tc\_is\_vconn\_src() which checks TC\_FLAGS\_VCONN\_ON +* PE tells the PRL to send an ACCEPT message to the port partner through + prl\_send\_ctrl\_msg() which fills in shared message information and sets + PRL\_FLAGS\_MSG\_XMIT +* PRL lets the PE know that the message transmit was successful through + pe\_message\_sent() which sets PE\_FLAGS\_TX\_COMPLETE +* TC tells the PE layer that the Vconn swap completed with + pe\_vconn\_swap\_complete() which sets PE\_FLAGS\_VCONN\_SWAP\_COMPLETE ### Type-C Layer -Defined in the USB Type-C specification, this layer is responsible for basic connection. It takes care of setting the CC lines, detecting and debouncing the partner CC lines, and performs most of the interactions needed with the PPC and USB mux. Once the TC layer has gotten the connection to the point of being Attached.SNK or Attached.SRC, it will enable the PRL and PE layers accordingly. - +Defined in the USB Type-C specification, this layer is responsible for basic +connection. It takes care of setting the CC lines, detecting and debouncing the +partner CC lines, and performs most of the interactions needed with the PPC and +USB mux. Once the TC layer has gotten the connection to the point of being +Attached.SNK or Attached.SRC, it will enable the PRL and PE layers accordingly. ### Protocol Layer -A part of the USB PD specification, the protocol layer is responsible for the actual sending and receiving of PD messages with the TCPCs. The layer is actually composed of 4 separate state machines running one after the other. These state machines are: - - - -* Chunked receive (RCH): passes messages up to the PE and requests chunks when chunking -* Chunked transmit (TCH): receives messages from the PE and waits for chunk requests when chunking -* Protocol transmit (PRL\_TX): passes messages to the TCPCs and handles PD 3.0 collision avoidance -* Protocol hard reset (PRL\_HR): responds to or transmits hard resets, resets PRL layer variables, notifies PE of hard reset receipt or sent +A part of the USB PD specification, the protocol layer is responsible for the +actual sending and receiving of PD messages with the TCPCs. The layer is +actually composed of 4 separate state machines running one after the other. +These state machines are: +* Chunked receive (RCH): passes messages up to the PE and requests chunks when + chunking +* Chunked transmit (TCH): receives messages from the PE and waits for chunk + requests when chunking +* Protocol transmit (PRL\_TX): passes messages to the TCPCs and handles PD 3.0 + collision avoidance +* Protocol hard reset (PRL\_HR): responds to or transmits hard resets, resets + PRL layer variables, notifies PE of hard reset receipt or sent ### Policy Engine Layer -The PE layer states are defined as a part of the USB PD specification. State names are meant to track very closely with the specification so they can be easily searchable and understood. The PE’s primary responsibility is to send and process PD messages in order to implement the port’s policy. - +The PE layer states are defined as a part of the USB PD specification. State +names are meant to track very closely with the specification so they can be +easily searchable and understood. The PE’s primary responsibility is to send and +process PD messages in order to implement the port’s policy. ## Best Practices - - -* Always call return after set\_state(). Once the state has been changed, nothing further should be done in the current state. -* Never call set\_state() from an exit function. The call will be ignored as there is already a state transition taking place. -* Never call set\_state() from outside the PD task. The task may be waiting in any number of locations and the context should not change around it while it does so. -* Always use flags to communicate between layers, and to communicate with the PD task from other tasks. Flags should be accessed through atomic operations. +* Always call return after set\_state(). Once the state has been changed, + nothing further should be done in the current state. +* Never call set\_state() from an exit function. The call will be ignored as + there is already a state transition taking place. +* Never call set\_state() from outside the PD task. The task may be waiting in + any number of locations and the context should not change around it while it + does so. +* Always use flags to communicate between layers, and to communicate with the + PD task from other tasks. Flags should be accessed through atomic + operations. * Always use pd\_\* functions to access the PD task from other tasks. -* Always write unit tests as code is added, to verify new code works and protect against regressions as development continues. +* Always write unit tests as code is added, to verify new code works and + protect against regressions as development continues. diff --git a/docs/usb_power.md b/docs/usb_power.md index 860e7fe589..acdbd47269 100644 --- a/docs/usb_power.md +++ b/docs/usb_power.md @@ -139,8 +139,8 @@ in-depth information can be found in the [USB Type-C Specification] \(section and is not present in the codebase currently. ChromeOS devices currently source power to external USB devices at 5V with a -typical current of 1.5A for each Type-C port. In certain scenarios, a -Type-C port can source up to 3A @ 5V. +typical current of 1.5A for each Type-C port. In certain scenarios, a Type-C +port can source up to 3A @ 5V. ChromeOS prefers that the first PD-capable Type-C device **that requires 3A** should get 3A guaranteed at 5V. Once the maximum supported number of PD-capable @@ -149,15 +149,15 @@ offered a maximum of 1.5A. If there are no PD-capable Type-C devices requiring 3A, then the first non-PD device will be given 3A until a PD-capable device **that requires 3A** is -inserted. Devices will indicate they require 3A in their sink capabilities, -and this will be used as the trigger to let the EC know to offer that port a -3A source contract. This policy is laid out in the following flow chart. +inserted. Devices will indicate they require 3A in their sink capabilities, and +this will be used as the trigger to let the EC know to offer that port a 3A +source contract. This policy is laid out in the following flow chart.  When a device that is currently claiming 3A is removed, then the next oldest -PD-capable device is offered 3A. If no PD-capable devices require 3A, -then the oldest non-PD capable device is given 3A through a CC resistor change. +PD-capable device is offered 3A. If no PD-capable devices require 3A, then the +oldest non-PD capable device is given 3A through a CC resistor change.  @@ -202,7 +202,7 @@ with a board with a maximum number of 1 3A-ports supported: * Since this is a PD device, query its operational current through requesting Sink Capabilities. * Tablet would like 3A, but the board has reached its maximum number of - supported 3A ports. Note this port's desired current for later. + supported 3A ports. Note this port's desired current for later. * Current state: `keyboard @ 1.5A` and `mouse @ 1.5A` and `dock @ 1.5A` and `phone @ 3A` and `tablet @ 1.5A`. 7. The PD-capable phone is removed @@ -217,11 +217,11 @@ with a board with a maximum number of 1 3A-ports supported: change. * Current state: `keyboard @ 3A` and `mouse @ 1.5A` and `dock @ 1.5A` 9. The non-PD capable keyboard is removed - * The next oldest PD-capable device requiring 3A is offered 3A.. If there - are no PD-capable devices requiring 3A, then the next oldest non-PD capable - device is given 3A. - * The dock only requires 1.5A, so mouse is given 3A via CC - resistor change. + * The next oldest PD-capable device requiring 3A is offered 3A.. If there + are no PD-capable devices requiring 3A, then the next oldest non-PD + capable device is given 3A. + * The dock only requires 1.5A, so mouse is given 3A via CC resistor + change. * Current state: `mouse @ 3A` and `dock @ 1.5A`. 10. The non-PD capable mouse is removed * The dock does not require 3A. diff --git a/docs/usb_updater.md b/docs/usb_updater.md index 476b50f316..f1505550d1 100644 --- a/docs/usb_updater.md +++ b/docs/usb_updater.md @@ -1,48 +1,44 @@ -EC update over USB -================== +# EC update over USB chip/g (Cr50) and common code (hammer, servo_micro/v4) update over USB protocols share a lot in terms of protocol and ideas, but use different code bases. -chip/g EC-side implementation is found in `chip/g/*upgrade*`, and the -userspace tool which provides updates over USB among with supporting other -features and interfaces is found in `extra/usb_updater/gsctool.c`. +chip/g EC-side implementation is found in `chip/g/*upgrade*`, and the userspace +tool which provides updates over USB among with supporting other features and +interfaces is found in `extra/usb_updater/gsctool.c`. Common code uses implementations in `common/*update*.c` and `include/*update*.h`, and `extra/usb_updater/usb_updater2.c` for the userspace updater. -Cr50-specific notes -------------------- +## Cr50-specific notes -The Cr50 firmware image consists of multiple sections, of interest to the -USB updater are the RO and RW code sections, two of each. When firmware update +The Cr50 firmware image consists of multiple sections, of interest to the USB +updater are the RO and RW code sections, two of each. When firmware update session is established, the Cr50 device reports locations of backup RW and RO sections (those not currently used by the device). Based on this information the updater carves out the appropriate sections from -the full Cr50 firmware binary image and sends them to the device for -programming into flash. Once the new sections are programmed and the device -is restarted, the new RO and RW are used if they pass verification and are -logically newer than the existing sections. +the full Cr50 firmware binary image and sends them to the device for programming +into flash. Once the new sections are programmed and the device is restarted, +the new RO and RW are used if they pass verification and are logically newer +than the existing sections. There are two ways to communicate with the Cr50 device: USB and `/dev/tpm0` (when `gsctool` is running on a chromebook with the Cr50 device). Originally -different protocols were used to communicate over different channels, -starting with version 3 the same protocol is used. +different protocols were used to communicate over different channels, starting +with version 3 the same protocol is used. -Common-code notes ------------------ +## Common-code notes -For non-Cr50 or chip/g devices (common code), the layout is a bit different, -as devices usually have a single RO and a single RW, where RO is truly read-only -in production, and verifies RW before jumping to it. +For non-Cr50 or chip/g devices (common code), the layout is a bit different, as +devices usually have a single RO and a single RW, where RO is truly read-only in +production, and verifies RW before jumping to it. For testing and development, `usb_updater2` is provided, while production code will use `hammerd` (in `src/platform/hammerd`) to update the device. -Update protocol ---------------- +## Update protocol The host (either a local AP or a workstation) is the master of the firmware update protocol, it sends data to the Cr50 device, which processes it and @@ -50,75 +46,76 @@ responds. The encapsulation format is different between the `/dev/tpm0` and USB cases: - 4 bytes 4 bytes 4 bytes variable size - +-----------+--------------+---------------+----------~~--------------+ - + total size| block digest | dest address | data | - +-----------+--------------+---------------+----------~~--------------+ - \ \ / - \ \ / - \ +----- FW update PDU sent over /dev/tpm0 -----------+ - \ / - +--------- USB frame, requires total size field ------------+ +``` + 4 bytes 4 bytes 4 bytes variable size ++-----------+--------------+---------------+----------~~--------------+ ++ total size| block digest | dest address | data | ++-----------+--------------+---------------+----------~~--------------+ + \ \ / + \ \ / + \ +----- FW update PDU sent over /dev/tpm0 -----------+ + \ / + +--------- USB frame, requires total size field ------------+ +``` The update protocol data units (PDUs) are passed over `/dev/tpm0`, the -encapsulation includes integrity verification and destination address of -the data (more of this later). `/dev/tpm0` transactions pretty much do not -have size limits, whereas the USB data is sent in chunks of the size -determined when the USB connection is set up. This is why USB requires an -additional encapsulation into frames to communicate the PDU size to the -client side so that the PDU can be reassembled before passing to the -programming function. - -In general, the protocol consists of two phases: connection establishment -and actual image transfer. - -The very first PDU of the transfer session is used to establish the -connection. The first PDU does not have any data, and the `dest address` -field is set to zero. Receiving such a PDU signals the programming function -that the host intends to transfer a new image. +encapsulation includes integrity verification and destination address of the +data (more of this later). `/dev/tpm0` transactions pretty much do not have size +limits, whereas the USB data is sent in chunks of the size determined when the +USB connection is set up. This is why USB requires an additional encapsulation +into frames to communicate the PDU size to the client side so that the PDU can +be reassembled before passing to the programming function. + +In general, the protocol consists of two phases: connection establishment and +actual image transfer. + +The very first PDU of the transfer session is used to establish the connection. +The first PDU does not have any data, and the `dest address` field is set to +zero. Receiving such a PDU signals the programming function that the host +intends to transfer a new image. The response to the first PDU varies depending on the protocol version. -Note that protocol versions before 5 are described here for completeness, -but are not supported any more. +Note that protocol versions before 5 are described here for completeness, but +are not supported any more. -Version 1 is used over `/dev/tpm0`. The response is either 4 or 1 bytes in -size. The 4 byte response is the *base address* of the backup RW section, -and there is no support for RO updates. The one byte response is an error -indication, possibly reporting flash erase failure, command format error, etc. +Version 1 is used over `/dev/tpm0`. The response is either 4 or 1 bytes in size. +The 4 byte response is the *base address* of the backup RW section, and there is +no support for RO updates. The one byte response is an error indication, +possibly reporting flash erase failure, command format error, etc. Version 2 is used over USB. The response is 8 bytes in size. The first four bytes are either the *base address* of the backup RW section (still no RO -updates), or an error code, the same as in Version 1. The second 4 bytes -are the protocol version number (set to 2). +updates), or an error code, the same as in Version 1. The second 4 bytes are the +protocol version number (set to 2). All versions above 2 behave the same over `/dev/tpm0` and USB. -Version 3 response is 16 bytes in size. The first 4 bytes are the error code -the second 4 bytes are the protocol version (set to 3) and then 4 byte -*offset* of the RO section followed by the 4 byte *offset* of the RW section. +Version 3 response is 16 bytes in size. The first 4 bytes are the error code the +second 4 bytes are the protocol version (set to 3) and then 4 byte *offset* of +the RO section followed by the 4 byte *offset* of the RW section. -Version 4 response in addition to version 3 provides header revision fields -for active RO and RW images running on the target. +Version 4 response in addition to version 3 provides header revision fields for +active RO and RW images running on the target. -Once the connection is established, the image to be programmed into flash -is transferred to the Cr50 in 1K PDUs. In versions 1 and 2 the address in -the header is the absolute address to place the block to, in version 3 and -later it is the offset into the flash. +Once the connection is established, the image to be programmed into flash is +transferred to the Cr50 in 1K PDUs. In versions 1 and 2 the address in the +header is the absolute address to place the block to, in version 3 and later it +is the offset into the flash. Protocol version 5 includes RO and RW key ID information into the first PDU -response. The key ID could be used to tell between prod and dev signing -modes, among other things. +response. The key ID could be used to tell between prod and dev signing modes, +among other things. -Protocol version 6 does not change the format of the first PDU response, -but it indicates the target's ability to channel TPM vendor commands -through USB connection. +Protocol version 6 does not change the format of the first PDU response, but it +indicates the target's ability to channel TPM vendor commands through USB +connection. Common-code updater also uses protocol version 6, but has a fairly different `first_response_pdu` header, indicated by setting `1` in the higher 16-bit for -the protocol version field (`header_type`). The response includes fields -such as maximum PDU size (which is not fixed to 1KB like for Cr50), flash -protection status, version string, and a minimum rollback version. +the protocol version field (`header_type`). The response includes fields such as +maximum PDU size (which is not fixed to 1KB like for Cr50), flash protection +status, version string, and a minimum rollback version. Details can be found in `include/update_fw.h`. @@ -128,54 +125,55 @@ This describes the EC-side state machine for update over USB. IDLE state: -* If host sends update start PDU (a command without any payload, digest = 0 - and base = 0): +* If host sends update start PDU (a command without any payload, digest = 0 + and base = 0): - * Reply with `first_update_pdu` block. Go to OUTSIDE_BLOCK state. + * Reply with `first_update_pdu` block. Go to OUTSIDE_BLOCK state. -* If host sends a vendor command (see below), execute that, reply, and stay - in IDLE state. Note that vendor commands are only accepted in IDLE state. +* If host sends a vendor command (see below), execute that, reply, and stay in + IDLE state. Note that vendor commands are only accepted in IDLE state. OUTSIDE_BLOCK (preparing to receive start of PDU): -* If no data is received in 5 seconds, go back to IDLE state. -* If host sends `UPDATE_DONE` command (by setting `dest address` to - `0xb007ab1e`), go back to IDLE state. -* If host sends a valid block start with a valid address, copy the rest - of the payload and go to INSIDE_BLOCK state. +* If no data is received in 5 seconds, go back to IDLE state. +* If host sends `UPDATE_DONE` command (by setting `dest address` to + `0xb007ab1e`), go back to IDLE state. +* If host sends a valid block start with a valid address, copy the rest of the + payload and go to INSIDE_BLOCK state. INSIDE_BLOCK (in a middle of a PDU): -* If no data is received in 5 seconds, go back to IDLE state. -* Copy data to a buffer. +* If no data is received in 5 seconds, go back to IDLE state. +* Copy data to a buffer. - * If buffer is full (i.e. matches the total expected PDU size), write the - data and go to OUTSIDE_BLOCK. - * Else, stay in INSIDE_BLOCK. + * If buffer is full (i.e. matches the total expected PDU size), write the + data and go to OUTSIDE_BLOCK. + * Else, stay in INSIDE_BLOCK. ### Vendor commands (channeled TPM command, Cr50) When channeling TPM vendor commands the USB frame looks as follows: - 4 bytes 4 bytes 4 bytes 2 bytes variable size - +-----------+--------------+---------------+-----------+------~~~-------+ - + total size| block digest | EXT_CMD | vend. sub.| data | - +-----------+--------------+---------------+-----------+------~~~-------+ +``` + 4 bytes 4 bytes 4 bytes 2 bytes variable size ++-----------+--------------+---------------+-----------+------~~~-------+ ++ total size| block digest | EXT_CMD | vend. sub.| data | ++-----------+--------------+---------------+-----------+------~~~-------+ +``` Where `Vend. sub` is the vendor subcommand, and data field is subcommand dependent. The target tells between update PDUs and encapsulated vendor -subcommands by looking at the `EXT_CMD` value - it is set to `0xbaccd00a` and -as such is guaranteed not to be a valid update PDU destination address. +subcommands by looking at the `EXT_CMD` value - it is set to `0xbaccd00a` and as +such is guaranteed not to be a valid update PDU destination address. -These commands cannot exceed the USB packet size (typically 64 bytes), as -no reassembly is performed for such frames. +These commands cannot exceed the USB packet size (typically 64 bytes), as no +reassembly is performed for such frames. The vendor command response size is not fixed, it is subcommand dependent. -The Cr50 device responds to each update PDU with a confirmation which is 4 -bytes in size in protocol version 2, and 1 byte in size in all other -versions. Zero value means success, non-zero value is the error code -reported by Cr50. +The Cr50 device responds to each update PDU with a confirmation which is 4 bytes +in size in protocol version 2, and 1 byte in size in all other versions. Zero +value means success, non-zero value is the error code reported by Cr50. Again, vendor command responses are subcommand specific. @@ -186,17 +184,18 @@ above, except that we use `UPDATE_EXTRA_CMD` (`b007ab1f`) instead of `EXT_CMD`, and `Vend. sub.` have a limit set of values (unless otherwise noted, commands take no parameter, and reply with a single 1-byte status code): -* UPDATE_EXTRA_CMD_IMMEDIATE_RESET (0): Tell EC to reboot immediately. -* UPDATE_EXTRA_CMD_JUMP_TO_RW (1): Tell EC (in RO) to jump to RW, if the - signature verifies. -* UPDATE_EXTRA_CMD_STAY_IN_RO (2): Tell EC (in RO), to stay in RO, and not - jump to RW automatically. After this command is sent, a reset is necessary - for the EC to accept to jump to RW again. -* UPDATE_EXTRA_CMD_UNLOCK_RW (3): Tell EC to unlock RW on next reset. -* UPDATE_EXTRA_CMD_UNLOCK_ROLLBACK (4): Tell EC to unlock ROLLBACK on next reset. -* UPDATE_EXTRA_CMD_INJECT_ENTROPY (5): Inject entropy into the device-specific - unique identifier (takes at least CONFIG_ROLLBACK_SECRET_SIZE=32 bytes of - data). -* UPDATE_EXTRA_CMD_PAIR_CHALLENGE (6): Tell EC to answer a X25519 challenge - for pairing. Takes in a `struct pair_challenge` as data, answers with a - `struct pair_challenge_response`. +* UPDATE_EXTRA_CMD_IMMEDIATE_RESET (0): Tell EC to reboot immediately. +* UPDATE_EXTRA_CMD_JUMP_TO_RW (1): Tell EC (in RO) to jump to RW, if the + signature verifies. +* UPDATE_EXTRA_CMD_STAY_IN_RO (2): Tell EC (in RO), to stay in RO, and not + jump to RW automatically. After this command is sent, a reset is necessary + for the EC to accept to jump to RW again. +* UPDATE_EXTRA_CMD_UNLOCK_RW (3): Tell EC to unlock RW on next reset. +* UPDATE_EXTRA_CMD_UNLOCK_ROLLBACK (4): Tell EC to unlock ROLLBACK on next + reset. +* UPDATE_EXTRA_CMD_INJECT_ENTROPY (5): Inject entropy into the device-specific + unique identifier (takes at least CONFIG_ROLLBACK_SECRET_SIZE=32 bytes of + data). +* UPDATE_EXTRA_CMD_PAIR_CHALLENGE (6): Tell EC to answer a X25519 challenge + for pairing. Takes in a `struct pair_challenge` as data, answers with a + `struct pair_challenge_response`. diff --git a/docs/write_protection.md b/docs/write_protection.md index 95c4bb0476..a71b3d095a 100644 --- a/docs/write_protection.md +++ b/docs/write_protection.md @@ -41,7 +41,7 @@ firmware jumps to it. On modern Chrome OS devices, the Cr50 (aka GSC / TPM) provides a "hardware write protect" GPIO that is connected to the AP SPI flash, EC SPI flash, EEPROM, and FPMCU via a [GPIO][write_protect_gpio]. This "hardware write protect" can only -be disabled with [Servo] or [SuzyQ] (["CCD open"]) and corresponds to +be disabled with [Servo] or [SuzyQ](["CCD open"]) and corresponds to [`OverrideWP`] in ccd. Disabling this write protect disables it for everything connected to this signal. diff --git a/docs/ztest.md b/docs/ztest.md index 1dd4c91a0c..2b8af31581 100644 --- a/docs/ztest.md +++ b/docs/ztest.md @@ -2,58 +2,67 @@ [TOC] -This HOWTO shows the process for porting the EC's `base32` unit test to -Zephyr's Ztest framework. All of the work is done in `src/platform/ec`. +This HOWTO shows the process for porting the EC's `base32` unit test to Zephyr's +Ztest framework. All of the work is done in `src/platform/ec`. -See [Test Framework - Zephyr Project Documentation](https://docs.zephyrproject.org/1.12.0/subsystems/test/ztest.html#quick-start-unit-testing) for details about Zephyr's Ztest framework. +See +[Test Framework - Zephyr Project Documentation](https://docs.zephyrproject.org/1.12.0/subsystems/test/ztest.html#quick-start-unit-testing) +for details about Zephyr's Ztest framework. - -For examples of porting an EC unit test to the Ztest API, see: -* [base32](https://crrev.com/c/2492527) and [improvements](https://crrev.com/c/2634401) -* [accel_cal](https://crrev.com/c/2645198) +For examples of porting an EC unit test to the Ztest API, see: * +[base32](https://crrev.com/c/2492527) and +[improvements](https://crrev.com/c/2634401) * +[accel_cal](https://crrev.com/c/2645198) ## Porting Considerations -Not every EC unit test can be ported to Ztest. This section describes cases -that are not supported and cases where caveats apply. +Not every EC unit test can be ported to Ztest. This section describes cases that +are not supported and cases where caveats apply. ### EC Mocks Are Not Supported -If a test has a `$TEST.mocklist` file associated with the unit test, it is -using the EC mocking framework, which is unsupported in the Ztest framework. -Ztest has its own mocking framework which the EC does not support. +If a test has a `$TEST.mocklist` file associated with the unit test, it is using +the EC mocking framework, which is unsupported in the Ztest framework. Ztest has +its own mocking framework which the EC does not support. ### Multiple Task Caveats The EC unit test framework starts a single task to call `run_test`, and this -task will then call the functions for the various test cases. Some unit tests -have multiple threads of execution, which is enabled by a `$TEST.tasklist` -file associated with the unit test. The test runner task has a task ID of +task will then call the functions for the various test cases. Some unit tests +have multiple threads of execution, which is enabled by a `$TEST.tasklist` file +associated with the unit test. The test runner task has a task ID of `TASK_ID_TEST_RUNNER`, which can be used as an argument to any of the task -functions. See for example the [`charge_ramp` unit test](https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/master/test/charge_ramp.c#81) -and the [`host_command` unit test](https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/master/test/host_command.c#32) +functions. See for example the +[`charge_ramp` unit test](https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/master/test/charge_ramp.c#81) +and the +[`host_command` unit test](https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/master/test/host_command.c#32) When a unit test is ported to Ztest, `test_main` doesn't have a thread ID, so -`TASK_ID_TEST_RUNNER` is undefined. `charge_ramp` and `host_command` cannot -be ported at this time. `test_main` also cannot call any of the task functions -that must be called from a task, such as `task_wake`; these functions can pend -the calling task, but since `test_main` doesn't have a thread ID, the pend -will fail. See the [`mutex` unit test](https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/master/test/mutex.c#116) +`TASK_ID_TEST_RUNNER` is undefined. `charge_ramp` and `host_command` cannot be +ported at this time. `test_main` also cannot call any of the task functions that +must be called from a task, such as `task_wake`; these functions can pend the +calling task, but since `test_main` doesn't have a thread ID, the pend will +fail. See the +[`mutex` unit test](https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/master/test/mutex.c#116) for an example. ## Determine source files being tested Determine which C files the unit test requires by finding the test in `test/test_config.h`: + ``` #ifdef TEST_BASE32 #define CONFIG_BASE32 #endif ``` + Locate the `CONFIG` item(s) in `common/build.mk`: + ``` common-$(CONFIG_BASE32)+=base32.o ``` + So for the `base32` test, we only need to shim `common/base32.c`. Add the C files to `zephyr/shim/CMakeLists.txt`, in the "Shimmed modules" @@ -71,30 +80,29 @@ Refer to [zephyr: shim in base32.c](https://crrev.com/c/2468631). Create a new directory for the unit test in `zephyr/test/base32`. Create `zephyr/test/base32/prj.conf` with these contents: + ``` CONFIG_ZTEST=y CONFIG_PLATFORM_EC=y ``` Create `zephyr/test/base32/CMakeLists.txt` with these contents: -``` -cmake_minimum_required(VERSION 3.13.1) -project(base32) -find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE}) +``` target_sources(app PRIVATE ${PLATFORM_EC}/test/base32.c) ``` ## Modify test source code ### Test cases + In the unit test, replace `run_test` with `TEST_MAIN()`. This will allow both platform/ec tests and Ztests to share the same entry point. Change `RUN_TEST` to `ztest_unit_test` and add the `ztest_test_suite` wrapper plus the call to `ztest_run_test_suite`. -``` +```c /* * Define the test cases to run. We need to do this twice, once in the format * that Ztest uses, and again in the format the the EC test framework uses. @@ -102,68 +110,73 @@ plus the call to `ztest_run_test_suite`. */ TEST_MAIN() { - ztest_test_suite(test_base32_lib, - ztest_unit_test(test_crc5), - ztest_unit_test(test_encode), - ztest_unit_test(test_decode)); - ztest_run_test_suite(test_base32_lib); + ztest_test_suite(test_base32_lib, + ztest_unit_test(test_crc5), + ztest_unit_test(test_encode), + ztest_unit_test(test_decode)); + ztest_run_test_suite(test_base32_lib); } ``` Each function that is called by `ztest_unit_test` needs to be declared using -`DECLARE_EC_TEST`. Keep the `return EC_SUCCESS;` at the end -of the test function. Note that for the EC build, `TEST_MAIN` will call -`test_reset` before running the test cases, and `test_print_result` after. +`DECLARE_EC_TEST`. Keep the `return EC_SUCCESS;` at the end of the test +function. Note that for the EC build, `TEST_MAIN` will call `test_reset` before +running the test cases, and `test_print_result` after. ### Assert macros -Change the `TEST_ASSERT` macros to `zassert` macros. There are plans to -automate this process, but for now, it's a manual process involving some -intelligent find-and-replace. - -* `TEST_ASSERT(n)` to `zassert_true(n, NULL)` -* `TEST_EQ(a, b, fmt)` to `zassert_equal(a, b, fmt ## ", " ## fmt, a, b)` - * e.g. `TEST_EQ(a, b, "%d")` becomes `zassert_equal(a, b, "%d, %d", a, b)` -* `TEST_NE(a, b, fmt)` to `zassert_not_equal(a, b, fmt ## ", " ## fmt, a, b)` -* `TEST_LT(a, b, fmt)` to `zassert_true(a < b, fmt ## ", " ## fmt, a, b)` -* `TEST_LE(a, b, fmt)` to `zassert_true(a <= b, fmt ## ", " ## fmt, a, b)` -* `TEST_GT(a, b, fmt)` to `zassert_true(a > b, fmt ## ", " ## fmt, a, b)` -* `TEST_GE(a, b, fmt)` tp `zassert_true(a >= b, fmt ## ", " ## fmt, a, b)` -* `TEST_BITS_SET(a, bits)` to `zassert_true(a & (int)bits == (int)bits, "%u, %u", a & (int)bits, (int)bits)` -* `TEST_BITS_CLEARED(a, bits)` to `zassert_true(a & (int)bits == 0, "%u, 0", a & (int)bits)` -* `TEST_ASSERT_ARRAY_EQ(s, d, n)` to `zassert_mem_equal(s, d, b, NULL)` -* `TEST_CHECK(n)` to `zassert_true(n, NULL)` -* `TEST_NEAR(a, b, epsilon, fmt)` to `zassert_within(a, b, epsilon, fmt, a)` - * Currently, every usage of `TEST_NEAR` involves floating point values -* `TEST_ASSERT_ABS_LESS(n, t)` to `zassert_true(abs(n) < t, "%d, %d", n, t)` - * Currently, every usage of `TEST_ASSERT_ANS_LESS` involves signed integers. - -There isn't a good replacement for `TEST_ASSERT_MEMSET(d, c, n)`, but it is -only used in two tests, `printf.c` and `utils.c`. If you need this test, -you'll need to code up a loop over the `n` bytes starting at `d`, and -`zassert_equal` that each byte is equal to `c`. - -Also note that some tests use constructs like `TEST_ASSERT(var == const)`, -which would have been better write as `TEST_EQ(var, const)`. These should be -rewritten to use `zassert_equal`. + +Change the `TEST_ASSERT` macros to `zassert` macros. There are plans to automate +this process, but for now, it's a manual process involving some intelligent +find-and-replace. + +* `TEST_ASSERT(n)` to `zassert_true(n, NULL)` +* `TEST_EQ(a, b, fmt)` to `zassert_equal(a, b, fmt ## ", " ## fmt, a, b)` + * e.g. `TEST_EQ(a, b, "%d")` becomes `zassert_equal(a, b, "%d, %d", a, b)` +* `TEST_NE(a, b, fmt)` to `zassert_not_equal(a, b, fmt ## ", " ## fmt, a, b)` +* `TEST_LT(a, b, fmt)` to `zassert_true(a < b, fmt ## ", " ## fmt, a, b)` +* `TEST_LE(a, b, fmt)` to `zassert_true(a <= b, fmt ## ", " ## fmt, a, b)` +* `TEST_GT(a, b, fmt)` to `zassert_true(a > b, fmt ## ", " ## fmt, a, b)` +* `TEST_GE(a, b, fmt)` tp `zassert_true(a >= b, fmt ## ", " ## fmt, a, b)` +* `TEST_BITS_SET(a, bits)` to `zassert_true(a & (int)bits == (int)bits, "%u, + %u", a & (int)bits, (int)bits)` +* `TEST_BITS_CLEARED(a, bits)` to `zassert_true(a & (int)bits == 0, "%u, 0", a + & (int)bits)` +* `TEST_ASSERT_ARRAY_EQ(s, d, n)` to `zassert_mem_equal(s, d, b, NULL)` +* `TEST_CHECK(n)` to `zassert_true(n, NULL)` +* `TEST_NEAR(a, b, epsilon, fmt)` to `zassert_within(a, b, epsilon, fmt, a)` + * Currently, every usage of `TEST_NEAR` involves floating point values +* `TEST_ASSERT_ABS_LESS(n, t)` to `zassert_true(abs(n) < t, "%d, %d", n, t)` + * Currently, every usage of `TEST_ASSERT_ANS_LESS` involves signed + integers. + +There isn't a good replacement for `TEST_ASSERT_MEMSET(d, c, n)`, but it is only +used in two tests, `printf.c` and `utils.c`. If you need this test, you'll need +to code up a loop over the `n` bytes starting at `d`, and `zassert_equal` that +each byte is equal to `c`. + +Also note that some tests use constructs like `TEST_ASSERT(var == const)`, which +would have been better write as `TEST_EQ(var, const)`. These should be rewritten +to use `zassert_equal`. Refer to -[test: Allow EC unit test to use Ztest API](https://crrev.com/c/2492527) for -the changes to the base32.c source code. +[test: Allow EC unit test to use Ztest API](https://crrev.com/c/2492527) for the +changes to the base32.c source code. ### Tasklist For any test that has a corresponding `${TESTNAME}.tasklist`, add the file `shimmed_test_tasks.h` in the zephyr test directory, and in that file, -`#include` the tasklist file. See [accel_cal](https://crrev.com/c/2645198) -for an example. +`#include` the tasklist file. See [accel_cal](https://crrev.com/c/2645198) for +an example. Add `CONFIG_HAS_TEST_TASKS=y` to the `prj.conf` file, as well as the appropriate -`CONFIG_PLATFORM_EC` defines to include or exclude code that the unit under -test uses. +`CONFIG_PLATFORM_EC` defines to include or exclude code that the unit under test +uses. ## Build and run Use `zmake` to build and run the test: + ``` (cr) $ zmake -l DEBUG configure --test -B build/ztest/base32 zephyr/test/base32 ... @@ -185,4 +198,3 @@ Test suite test_base32_lib succeeded PROJECT EXECUTION SUCCESSFUL (cr) $ ``` - |