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 | |
| 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>
46 files changed, 1629 insertions, 1513 deletions
@@ -8,7 +8,8 @@ The Chromium OS project includes open source software for embedded controllers (EC) used in recent ARM and x86 based Chromebooks. This software includes a lightweight, multitasking OS with modules for power sequencing, keyboard control, thermal control, battery charging, and verified boot. The EC software -is written in C and supports [a variety of micro-controllers](https://chromium.googlesource.com/chromiumos/platform/ec/+/master/chip/). +is written in C and supports +[a variety of micro-controllers](https://chromium.googlesource.com/chromiumos/platform/ec/+/master/chip/). This document is a guide to help make you familiar with the EC code, current features, and the process for submitting code patches. @@ -40,8 +41,8 @@ documentation due to historical reasons. If you just see the term "EC", it probably refers to "the" EC (i.e. the first one that existed). Most Chrome OS devices have an MCU, known as "the EC" that controls lots of things (key presses, turning the AP on/off). The OS that was written for "the" EC is now -running on several different MCUs on Chrome OS devices with various tweaks -(e.g. the FPMCU, the touchpad one that can do palm rejection, etc.). It's quite +running on several different MCUs on Chrome OS devices with various tweaks (e.g. +the FPMCU, the touchpad one that can do palm rejection, etc.). It's quite confusing, so try to be specific and use terms like FPMCU to distinguish the fingerprint MCU from "the EC". @@ -97,21 +98,18 @@ I2C/onewire LED controllers, and I2C temperature sensors. **util** - Host utilities and scripts for flashing the EC. Also includes “ectool” used to query and send commands to the EC from userspace. -**test** - Unit tests for EC components. These can be run locally in - a mock "host" environment or compiled for a target board. - If building for a target board, the test must be flashed and - run manually on the device. - All unit tests and fuzzers are build/run using the local - host environment during a `buildall`. - To run all unit tests locally, run `make runhosttests -j`. - To build a specific unit test for a specific board, run - `make test-<test_name> BOARD=<board_name>`. - Please contribute new tests if writing new functionality. - Please run `make help` for more detail. - -**fuzz** - Fuzzers for EC components. These fuzzers are expected to - run in the mock host environment. They follow the same rules - as unit tests, as thus use the same commands to build and run. +**test** - Unit tests for EC components. These can be run locally in a mock +"host" environment or compiled for a target board. If building for a target +board, the test must be flashed and run manually on the device. All unit tests +and fuzzers are build/run using the local host environment during a `buildall`. +To run all unit tests locally, run `make runhosttests -j`. To build a specific +unit test for a specific board, run `make test-<test_name> BOARD=<board_name>`. +Please contribute new tests if writing new functionality. Please run `make help` +for more detail. + +**fuzz** - Fuzzers for EC components. These fuzzers are expected to run in the +mock host environment. They follow the same rules as unit tests, as thus use the +same commands to build and run. ## Firmware Branches diff --git a/baseboard/intelrvp/README.md b/baseboard/intelrvp/README.md index 2ecad4dd0c..21e30ee417 100644 --- a/baseboard/intelrvp/README.md +++ b/baseboard/intelrvp/README.md @@ -1,39 +1,36 @@ -/* Copyright 2019 The Chromium OS Authors. All rights reserved. - * Use of this source code is governed by a BSD-style license that can be - * found in the LICENSE file. - */ - This folder is for the baseboard for the board specific files which use Intel Reference Validation Platform (RVP) for developing the EC and other peripherals which can be hooked on EC or RVP. This baseboard follows the Intel Modular Embedded Controller Card (MECC) -specification for pinout and these pin definitions remain same on all the -RVPs. Chrome MECC spec is standardized for Icelake and successor RVPs hence -this baseboard code is applicable to Icelake and its successors only. +specification for pinout and these pin definitions remain same on all the RVPs. +Chrome MECC spec is standardized for Icelake and successor RVPs hence this +baseboard code is applicable to Icelake and its successors only. Following hardware features are supported on MECC header by RVP and can be validated by software by MECC. -MECC version 0.9 features -1. Power to MECC is provide by RVP (battery + DC Jack + Type C) -2. Power control pins for Intel SOC are added -3. Servo V2 header need to be added by MECC -4. Google H1 chip need to be added by MECC (optional for EC vendors) -5. 2 Type-C port support (SRC/SNK/BC1.2/MUX/Rerimer) -6. 6 Temperature sensors -7. 4 ADC -8. 4 I2C Channels -9. 1 Fan control +## MECC version 0.9 features + +1. Power to MECC is provide by RVP (battery + DC Jack + Type C) +2. Power control pins for Intel SOC are added +3. Servo V2 header need to be added by MECC +4. Google H1 chip need to be added by MECC (optional for EC vendors) +5. 2 Type-C port support (SRC/SNK/BC1.2/MUX/Rerimer) +6. 6 Temperature sensors +7. 4 ADC +8. 4 I2C Channels +9. 1 Fan control + +## MECC version 1.0 features -MECC version 1.0 features -1. Power to MECC is provide by RVP (battery + DC Jack + Type C) -2. Power control pins for Intel SOC are added -3. Servo V2 header need to be added by MECC -4. Google H1 chip need to be added by MECC (optional for EC vendors) -5. 4 Type-C port support (SRC/SNK/BC1.2/MUX/Rerimer) as Add In Card (AIC) - on RVP -6. Optional 2 Type-C port routed to MECC for integrated TCPC support -7. 6 I2C Channels -8. 2 SMLINK Channels -9. 2 I3C channels +1. Power to MECC is provide by RVP (battery + DC Jack + Type C) +2. Power control pins for Intel SOC are added +3. Servo V2 header need to be added by MECC +4. Google H1 chip need to be added by MECC (optional for EC vendors) +5. 4 Type-C port support (SRC/SNK/BC1.2/MUX/Rerimer) as Add In Card (AIC) on + RVP +6. Optional 2 Type-C port routed to MECC for integrated TCPC support +7. 6 I2C Channels +8. 2 SMLINK Channels +9. 2 I3C channels diff --git a/board/nucleo-f412zg/README.md b/board/nucleo-f412zg/README.md index fcdd5e40df..f2fa682e6f 100644 --- a/board/nucleo-f412zg/README.md +++ b/board/nucleo-f412zg/README.md @@ -1,22 +1,19 @@ # Nucleo F412ZG -This is a simpler EC example for the ST Nucleo F412ZG -development board. +This is a simpler EC example for the ST Nucleo F412ZG development board. # Quick Start -The Nucleo dev boards have lots of developer friendly features, -like an in-circuit debugger/programmer/UART-bridge, programmable -LEDs, and a button, to name a few. +The Nucleo dev boards have lots of developer friendly features, like an +in-circuit debugger/programmer/UART-bridge, programmable LEDs, and a button, to +name a few. -The built-in debugger can be connected to using a Micro USB cable. -It provides three great interfaces to the host. -1. Mass storage interface for drag-drop programming -2. Full ST-Link in-circuit debugger -3. UART bridge for logs/consoles +The built-in debugger can be connected to using a Micro USB cable. It provides +three great interfaces to the host. 1. Mass storage interface for drag-drop +programming 2. Full ST-Link in-circuit debugger 3. UART bridge for logs/consoles -We will use a few of these interfaces below to program and interact -with out Nucleo dev board. +We will use a few of these interfaces below to program and interact with out +Nucleo dev board. ## Build @@ -26,17 +23,17 @@ make BOARD=nucleo-f412zg -j ## Program -The easiest way to flash the Nucleo board is to Copy-Paste/Drag-Drop -the firmware image onto the exposed mass storage drive. +The easiest way to flash the Nucleo board is to Copy-Paste/Drag-Drop the +firmware image onto the exposed mass storage drive. -Open a file browser and `Copy` the file in `build/nucleo-f412zg/ec.bin`. -Now, find the removable storage that the Nucleo device has presented, -and `Paste` the file into the directory. +Open a file browser and `Copy` the file in `build/nucleo-f412zg/ec.bin`. Now, +find the removable storage that the Nucleo device has presented, and `Paste` the +file into the directory. ## Interact -After the Nucelo finishes programming, you can open the EC console. -On GNU/Linux, this is mapped to `/dev/ttyACM0`. +After the Nucleo finishes programming, you can open the EC console. On +GNU/Linux, this is mapped to `/dev/ttyACM0`. Install `minicom` and issue the following command: @@ -48,9 +45,9 @@ minicom -D/dev/ttyACM0 A fun EC feature is that unit tests can be run on-device. -This is made possible by an alternative build rule that generates a -test image per unit test. These test images use a unit test specific taskset -and console command to trigger them. +This is made possible by an alternative build rule that generates a test image +per unit test. These test images use a unit test specific taskset and console +command to trigger them. ## Create @@ -67,19 +64,20 @@ To build all unit test images for this board, run the following command: make BOARD=nucleo-f412zg tests ``` -You can build a specific unit test image by changing `tests` to `test-aes`, -for the `aes` unit test. +You can build a specific unit test image by changing `tests` to `test-aes`, for +the `aes` unit test. ## Flash -Copy/paste the `build/nucleo-f412zg/${TEST}/${TEST}.bin` file to the -Nucleo's mass storage drive, where `${TEST}` is the name of the unit test, -like `aes`. +Copy/paste the `build/nucleo-f412zg/${TEST}/${TEST}.bin` file to the Nucleo's +mass storage drive, where `${TEST}` is the name of the unit test, like `aes`. ## Run -1. Connect to UART console - ```bash - minicom -D/dev/ttyACM0 - ``` -2. Run the `runtest` command
\ No newline at end of file +1. Connect to UART console + +```bash +minicom -D/dev/ttyACM0 +``` + +1. Run the `runtest` command diff --git a/board/nucleo-h743zi/README.md b/board/nucleo-h743zi/README.md index 58d47219da..7ba8a143a3 100644 --- a/board/nucleo-h743zi/README.md +++ b/board/nucleo-h743zi/README.md @@ -1,22 +1,19 @@ # Nucleo H743ZI -This is a simpler EC example for the ST Nucleo H743ZI -development board. +This is a simpler EC example for the ST Nucleo H743ZI development board. # Quick Start -The Nucleo dev boards have lots of developer friendly features, -like an in-circuit debugger/programmer/UART-bridge, programmable -LEDs, and a button, to name a few. +The Nucleo dev boards have lots of developer friendly features, like an +in-circuit debugger/programmer/UART-bridge, programmable LEDs, and a button, to +name a few. -The built-in debugger can be connected to using a Micro USB cable. -It provides three great interfaces to the host. -1. Mass storage interface for drag-drop programming -2. Full ST-Link in-circuit debugger -3. UART bridge for logs/consoles +The built-in debugger can be connected to using a Micro USB cable. It provides +three great interfaces to the host. 1. Mass storage interface for drag-drop +programming 2. Full ST-Link in-circuit debugger 3. UART bridge for logs/consoles -We will use a few of these interfaces below to program and interact -with out Nucleo dev board. +We will use a few of these interfaces below to program and interact with out +Nucleo dev board. ## Build @@ -26,17 +23,17 @@ make BOARD=nucleo-h743zi -j ## Program -The easiest way to flash the Nucleo board is to Copy-Paste/Drag-Drop -the firmware image onto the exposed mass storage drive. +The easiest way to flash the Nucleo board is to Copy-Paste/Drag-Drop the +firmware image onto the exposed mass storage drive. -Open a file browser and `Copy` the file in `build/nucleo-h743zi/ec.bin`. -Now, find the removable storage that the Nucleo device has presented, -and `Paste` the file into the directory. +Open a file browser and `Copy` the file in `build/nucleo-h743zi/ec.bin`. Now, +find the removable storage that the Nucleo device has presented, and `Paste` the +file into the directory. ## Interact -After the Nucelo finishes programming, you can open the EC console. -On GNU/Linux, this is mapped to `/dev/ttyACM0`. +After the Nucleo finishes programming, you can open the EC console. On +GNU/Linux, this is mapped to `/dev/ttyACM0`. Install `minicom` and issue the following command: @@ -48,9 +45,9 @@ minicom -D/dev/ttyACM0 A fun EC feature is that unit tests can be run on-device. -This is made possible by an alternative build rule that generates a -test image per unit test. These test images use a unit test specific taskset -and console command to trigger them. +This is made possible by an alternative build rule that generates a test image +per unit test. These test images use a unit test specific taskset and console +command to trigger them. ## Create @@ -67,19 +64,20 @@ To build all unit test images for this board, run the following command: make BOARD=nucleo-h743zi tests ``` -You can build a specific unit test image by changing `tests` to `test-aes`, -for the `aes` unit test. +You can build a specific unit test image by changing `tests` to `test-aes`, for +the `aes` unit test. ## Flash -Copy/paste the `build/nucleo-h743zi/${TEST}/${TEST}.bin` file to the -Nucleo's mass storage drive, where `${TEST}` is the name of the unit test, -like `aes`. +Copy/paste the `build/nucleo-h743zi/${TEST}/${TEST}.bin` file to the Nucleo's +mass storage drive, where `${TEST}` is the name of the unit test, like `aes`. ## Run -1. Connect to UART console - ```bash - minicom -D/dev/ttyACM0 - ``` -2. Run the `runtest` command
\ No newline at end of file +1. Connect to UART console + +```bash +minicom -D/dev/ttyACM0 +``` + +1. Run the `runtest` command diff --git a/board/pdeval-stm32f072/PD_evaluation.md b/board/pdeval-stm32f072/PD_evaluation.md index 95e31996fc..4f1c8636c6 100644 --- a/board/pdeval-stm32f072/PD_evaluation.md +++ b/board/pdeval-stm32f072/PD_evaluation.md @@ -1,17 +1,17 @@ -USB PD chip evaluation configuration -==================================== +# USB PD chip evaluation configuration -This board configuration implements a USB Power Delivery TCPM -in order to evaluate various TCPC chips. -The code tries to follow the preliminary USB PD interface standard but for TCPC chip implementing proprietary I2C protocol, a new TCPM file can be implemented as explained in the [Updating the code](#Updating-the-code) section below. +This board configuration implements a USB Power Delivery TCPM in order to +evaluate various TCPC chips. The code tries to follow the preliminary USB PD +interface standard but for TCPC chip implementing proprietary I2C protocol, a +new TCPM file can be implemented as explained in the +[Updating the code](#Updating-the-code) section below. -Building --------- +## Building -### ChromiumOS chroot +### Chromium OS chroot -All the following instructions have been verified in a ChromiumOS chroot. -You can find how to set one up on the Chromium development wiki: +All the following instructions have been verified in a ChromiumOS chroot. You +can find how to set one up on the Chromium development: [http://dev.chromium.org/chromium-os/quick-start-guide](http://dev.chromium.org/chromium-os/quick-start-guide) ### Build the TCPM code @@ -20,34 +20,52 @@ You can find how to set one up on the Chromium development wiki: `make BOARD=pdeval-stm32f072` - -Updating the code ------------------ +## Updating the code ### TCPC Communication code -Please duplicate [driver/tcpm/tcpci.c](../../driver/tcpm/tcpci.c) into **driver/tcpm/##chip#name##.c**. -Then update the control logic through I2C there. +Please duplicate [driver/tcpm/tcpci.c](../../driver/tcpm/tcpci.c) into +**driver/tcpm/##chip#name##.c**. Then update the control logic through I2C +there. -In order for your new code to compile, you need to update [driver/build.mk](../../driver/build.mk) with the new file : -`driver-$(CONFIG_USB_PD_TCPM_##CHIP#NAME##)+=tcpm/##chip#name##.o` -then document the new `CONFIG_USB_PD_TCPM_` variable in the [include/config.h](../../include/config.h) file and define it in the board configuration in [board/pdeval-stm32f072/board.h](board.h). +In order for your new code to compile, you need to update +[driver/build.mk](../../driver/build.mk) with the new file : +`driver-$(CONFIG_USB_PD_TCPM_##CHIP#NAME##)+=tcpm/##chip#name##.o` then document +the new `CONFIG_USB_PD_TCPM_` variable in the +[include/config.h](../../include/config.h) file and define it in the board +configuration in [board/pdeval-stm32f072/board.h](board.h). ### Board configuration -In [board/pdeval-stm32f072/board.h](board.h), you can update `CONFIG_USB_PD_PORT_MAX_COUNT` to the actual number of ports on your board. -You also need to create/delete the corresponding `PD_Cx` tasks in [board/pdeval-stm32f072/ec.tasklist](ec.tasklist). - -By default, the firmware is using I2C1 with SCL/SDA on pins PB6 and PB7, running with a 100kHz clock, and tries to talk to TCPCs at i2c slave addresses 0x9c and 0x9e. -To change the pins or speed, you need to edit `i2c_ports` in [board/pdeval-stm32f072/board.c](board.c), update `I2C_PORT_TCPC` in [board/pdeval-stm32f072/board.h](board.h) with the right controller number, and change the pin mux in [board/pdeval-stm32f072/gpio.inc](gpio.inc). To change TCPC i2c slave addresses, update `TCPC1_I2C_ADDR` and `TCPC2_I2C_ADDR` in [board/pdeval-stm32f072/board.h](board.h). - -The I2C bus needs pull-up resistors on SCL/SDA. If your setup doesn't have external pull-ups on those lines, you can activate the chip internal pull-ups (but they are a bit weak for I2C) by editing [board/pdeval-stm32f072/gpio.inc](gpio.inc) and updating the alternate mode configuration flags with `GPIO_PULL_UP` e.g. : -`ALTERNATE(PIN_MASK(B, 0x00c0), 1, MODULE_I2C, GPIO_PULL_UP) /* I2C MASTER:PB6/7 */` - -An interrupt line, PA1, is configured to be used for the TCPC to get the attention of the TCPM. The GPIO is configured to trigger an interrupt on the falling edge and will call `tcpc_alert()`, which must be implemented in **driver/tcpm/<vendor>.c**, and should determine the cause of the interrupt and take action. The GPIO can be changed in [board/pdeval-stm32f072/gpio.inc](gpio.inc). - -Flashing and Running --------------------- +In [board/pdeval-stm32f072/board.h](board.h), you can update +`CONFIG_USB_PD_PORT_MAX_COUNT` to the actual number of ports on your board. You +also need to create/delete the corresponding `PD_Cx` tasks in +[board/pdeval-stm32f072/ec.tasklist](ec.tasklist). + +By default, the firmware is using I2C1 with SCL/SDA on pins PB6 and PB7, running +with a 100kHz clock, and tries to talk to TCPCs at i2c slave addresses 0x9c and +0x9e. To change the pins or speed, you need to edit `i2c_ports` in +[board/pdeval-stm32f072/board.c](board.c), update `I2C_PORT_TCPC` in +[board/pdeval-stm32f072/board.h](board.h) with the right controller number, and +change the pin mux in [board/pdeval-stm32f072/gpio.inc](gpio.inc). To change +TCPC i2c slave addresses, update `TCPC1_I2C_ADDR` and `TCPC2_I2C_ADDR` in +[board/pdeval-stm32f072/board.h](board.h). + +The I2C bus needs pull-up resistors on SCL/SDA. If your setup doesn't have +external pull-ups on those lines, you can activate the chip internal pull-ups +(but they are a bit weak for I2C) by editing +[board/pdeval-stm32f072/gpio.inc](gpio.inc) and updating the alternate mode +configuration flags with `GPIO_PULL_UP` e.g. : `ALTERNATE(PIN_MASK(B, 0x00c0), +1, MODULE_I2C, GPIO_PULL_UP) /* I2C MASTER:PB6/7 */` + +An interrupt line, PA1, is configured to be used for the TCPC to get the +attention of the TCPM. The GPIO is configured to trigger an interrupt on the +falling edge and will call `tcpc_alert()`, which must be implemented in +**driver/tcpm/<vendor>.c**, and should determine the cause of the interrupt and +take action. The GPIO can be changed in +[board/pdeval-stm32f072/gpio.inc](gpio.inc). + +## Flashing and Running ### Flashing the firmware binary @@ -55,37 +73,46 @@ To flash through JTAG with OpenOCD, you can just run: `sudo make flash BOARD=pdeval-stm32f072` -Note: you need to do that with your USB mini-B cable is connected to the **USB ST-LINK** plug on the discovery board. +Note: you need to do that with your USB mini-B cable is connected to the **USB +ST-LINK** plug on the discovery board. ### Connecting to the firmware console -Connect a USB cable to the **USB USER** mini-B receptacle on the board. -`lsusb` should show you a device with the following ID : 18d1:500f +Connect a USB cable to the **USB USER** mini-B receptacle on the board. `lsusb` +should show you a device with the following ID : 18d1:500f -You can get a console over USB by issuing the following command on a Linux computer: +You can get a console over USB by issuing the following command on a Linux +computer: `echo '18d1 500f' | sudo tee /sys/bus/usb-serial/drivers/generic/new_id` -Testing -------- +## Testing -Currently, the TCPM is expecting to have a GPIO to detect VBUS, but to minimize the HW setup with the discovery board the alternative is to fake VBUS detection using either the **USER** button on the discovery board, or the `vbus` console command, both of which toggle the state of VBUS detected. For example, to make get a PD contract with a power adapter, plug in the adapter and then toggle VBUS on. When a PD contract above 6V is made, LED5 on the discovery board will light. To disconnect, toggle VBUS off. +Currently, the TCPM is expecting to have a GPIO to detect VBUS, but to minimize +the HW setup with the discovery board the alternative is to fake VBUS detection +using either the **USER** button on the discovery board, or the `vbus` console +command, both of which toggle the state of VBUS detected. For example, to make +get a PD contract with a power adapter, plug in the adapter and then toggle VBUS +on. When a PD contract above 6V is made, LED5 on the discovery board will light. +To disconnect, toggle VBUS off. EC command line commands -- `help` List all available EC console commands -- `vbus` Toggle VBUS on/off -- `pd <port> state` Print PD protocol state information -- `pd <port> swap data` Request data role swap on port -- `pd <port> swap power` Request power role swap on port -- `i2cscan` Scan i2c bus for any responsive devices -- `i2cxfer` Perform an i2c transaction - -On the console, you will the PD state machine transitioning through its states with traces like `C0 st5`. -You can always the human readable name of the current state by doing `pd 0 state` returning something like : -`Port C0 CC1, Ena - Role: SNK-UFP State: SNK_DISCOVERY, Flags: 0x0608` -else the numbering of the state is defined in [include/usb_pd.h](../../include/us_pd.h) by the `PD_STATE_` constants. -It should be by default : +- `help` List all available EC console commands +- `vbus` Toggle VBUS on/off +- `pd <port> state` Print PD protocol state information +- `pd <port> swap data` Request data role swap on port +- `pd <port> swap power` Request power role swap on port +- `i2cscan` Scan i2c bus for any responsive devices +- `i2cxfer` Perform an i2c transaction + +On the console, you will the PD state machine transitioning through its states +with traces like `C0 st5`. You can always the human readable name of the current +state by doing `pd 0 state` returning something like : `Port C0 CC1, Ena - Role: +SNK-UFP State: SNK_DISCOVERY, Flags: 0x0608` else the numbering of the state is +defined in [include/usb_pd.h](../../include/us_pd.h) by the `PD_STATE_` +constants. It should be by default : + ``` [0] DISABLED [1] SUSPENDED @@ -125,27 +152,26 @@ It should be by default : [35] BIST_TX ``` -Known Issues ------------- - -1. This doc is not finished yet ... +## Known Issues -2. You might need a ChromeOS chroot ... +1. This doc is not finished yet ... -Troubleshooting ---------------- +2. You might need a ChromeOS chroot ... -1. OpenOCD is not finding the device. +## Troubleshooting - 1. Check that your USB mini-B cable is connected to the **USB ST-LINK** plug on the discovery board. - 2. What color is the LD1 LED on the board ? +1. OpenOCD is not finding the device. -1. On the I2C bus, SDA/SCL lines are staying always low + 1. Check that your USB mini-B cable is connected to the **USB ST-LINK** + plug on the discovery board. + 2. What color is the LD1 LED on the board ? - 1. You might be missing some pull-up resistors on the bus. - 1. Check the [Board configuration](#Board-configuration) section if you cannot add external pull-ups. +1. On the I2C bus, SDA/SCL lines are staying always low -1. You got black smoke + 1. You might be missing some pull-up resistors on the bus. + 1. Check the [Board configuration](#Board-configuration) section if you + cannot add external pull-ups. - 1. Time to buy a new one. +1. You got black smoke + 1. Time to buy a new one. diff --git a/board/servo_micro/ccd.md b/board/servo_micro/ccd.md index acb82adb94..d05fa726fd 100644 --- a/board/servo_micro/ccd.md +++ b/board/servo_micro/ccd.md @@ -6,30 +6,31 @@ # Case-Closed Debug in Chromebooks and Servo Micro -The Servo debug/test-automation connector has been required on all -chromebooks. It has proved essential to performing the required testing to meet -the six week OS release cycle, for bringing up new systems and qualifying new -components. In newer form-factors it is becoming hard to fit the Servo connector -(and related flex) and in some designs the thermal solution stops working when -the connector is used. The secure Case-Closed Debugging solution provides the -same capabilities and can take advantage of the Debug Mode detection available -on the USB-C connector. This application note gives an overview of Case-Closed -Debug (CCD) but does not address the related security issues. - +The Servo debug/test-automation connector has been required on all chromebooks. +It has proved essential to performing the required testing to meet the six week +OS release cycle, for bringing up new systems and qualifying new components. In +newer form-factors it is becoming hard to fit the Servo connector (and related +flex) and in some designs the thermal solution stops working when the connector +is used. The secure Case-Closed Debugging solution provides the same +capabilities and can take advantage of the Debug Mode detection available on the +USB-C connector. This application note gives an overview of Case-Closed Debug +(CCD) but does not address the related security issues. ## Introduction to Case-Closed Debug -Case-Closed Debug provides the same set of features as are available on the Servo connector: +Case-Closed Debug provides the same set of features as are available on the +Servo connector: * Access to console UART connections to AP, EC and on some systems a third MCU * Ability to reprogram firmware/BIOS SPI flash used by the AP * Ability to reprogram SPI flash used by the EC or use a firmware update mode to reprogram the internal flash on the EC (using UART or I2C) * GPIOs for holding the EC (and thus entire system) or AP in reset -* Act as master on a debug I2C that is primarily used for power - measurements. This bus normally contains INA voltage/current monitors and - temperature monitors that will not be populated on final MP systems. -* JTAG/SWD could be provided but has not been implemented on any existing system. +* Act as master on a debug I2C that is primarily used for power measurements. + This bus normally contains INA voltage/current monitors and temperature + monitors that will not be populated on final MP systems. +* JTAG/SWD could be provided but has not been implemented on any existing + system. When the Servo connector is used these interfaces are presented on well defined pins of the board-to-board connector and a flex is used to attach to the @@ -43,7 +44,6 @@ be used for the debug USB while the main link on the connector continues to be available. (The SBU pins are also used by some Alternate Modes, so the connector cannot be used for video out at the same time as debugging.) - ## Servo Micro: Using CCD with existing boards The Servo Micro implements the CCD functions in a way that can connect to @@ -60,8 +60,8 @@ original Servo connector, but on some designs) can be connected to either the JTAG pins or the SPI pins. It is capable of providing the SPI flash supply voltages. -The schematics for Servo Micro are available [as a -pdf](servo_micro_sch_20180404.pdf). +The schematics for Servo Micro are available +[as a pdf](servo_micro_sch_20180404.pdf). Servo Micro has a USB micro-B connector and acts as a USB device. @@ -75,8 +75,8 @@ UART connection on CN2. Schematic sheet 3 shows the I2C GPIO expander and the buffers for JTAG/SWD. The buffers adapt to the voltage needed on the DUT that is provided on -`PPDUT_JTAG_VREF`. In the SWD case the TDI becomes the bidirectional SWDIO but the -STM32 continues to use a discrete input and output pin. The DUT signal is +`PPDUT_JTAG_VREF`. In the SWD case the TDI becomes the bidirectional SWDIO but +the STM32 continues to use a discrete input and output pin. The DUT signal is received through U55 and a selection made with U1 to determine if to forward TDO from the DUT or the TDI/SWDIO. Because of the shared pins on the STM32 the JTAG interface can alternatively be used to connect UART3 to the DUT for a few @@ -103,26 +103,23 @@ load switches are carefully selected to have reverse blocking (protecting against a DUT providing a voltage or both being enabled). The code for the STM32 in Servo Micro is open source as the -[`servo_micro`](../../board/servo_micro) -board in the [Chromium EC -codebase](https://chromium.googlesource.com/chromiumos/platform/ec/). Essentially -it is a USB device that provides the standard control endpoint and 7 function -endpoints defined in -[`board.h`](board.h). +[`servo_micro`](../../board/servo_micro) board in the +[Chromium EC codebase](https://chromium.googlesource.com/chromiumos/platform/ec/). +Essentially it is a USB device that provides the standard control endpoint and 7 +function endpoints defined in [`board.h`](board.h). <!-- does not work in emacs/markdown preview but should in gitlies --> -``` c - #define USB_EP_USART4_STREAM 1 - #define USB_EP_UPDATE 2 - #define USB_EP_SPI 3 - #define USB_EP_CONSOLE 4 - #define USB_EP_I2C 5 - #define USB_EP_USART3_STREAM 6 - #define USB_EP_USART2_STREAM 7 +```c +#define USB_EP_USART4_STREAM 1 +#define USB_EP_UPDATE 2 +#define USB_EP_SPI 3 +#define USB_EP_CONSOLE 4 +#define USB_EP_I2C 5 +#define USB_EP_USART3_STREAM 6 +#define USB_EP_USART2_STREAM 7 ``` - The USART endpoints use the simple `GOOGLE_SERIAL` vendor class to connect the STM32 UARTs. The CONSOLE endpoint also uses `GOOGLE_STREAM` to connect to the console of the code running on the STM32. `GOOGLE_STREAM` provides simple byte @@ -131,32 +128,27 @@ standard Linux `drivers/usb/serial/usb-serial-simple.c` The SPI endpoint is described in [`chip/stm32/usb_spi.h`](../../chip/stm32/usb_spi.h) and provides a simple -connection to the SPI port. The host support is provided as a [driver in -flashrom](https://chromium.googlesource.com/chromiumos/third_party/flashrom/+/master/raiden_debug_spi.c). +connection to the SPI port. The host support is provided as a +[driver in flashrom](https://chromium.googlesource.com/chromiumos/third_party/flashrom/+/master/raiden_debug_spi.c). The I2C endpoint is described in [`include/usb_i2c.h`](../../include/usb_i2c.h) and provides a simple connection to the I2C bus. The host support is provided in -the [hdctools servo -support](https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/master/servo/stm32i2c.py). +the +[hdctools servo support](https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/master/servo/stm32i2c.py). The GPIO endpoint is cryptically described in -[`chip/stm32/usb_gpio.h`](../../chip/stm32/usb_gpio.h) and provides simple access -to set/clear and read the GPIO pins. The host support is provided in the -[hdctools servo -support](https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/master/servo/stm32gpio.py). +[`chip/stm32/usb_gpio.h`](../../chip/stm32/usb_gpio.h) and provides simple +access to set/clear and read the GPIO pins. The host support is provided in the +[hdctools servo support](https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/master/servo/stm32gpio.py). The UPDATE endpoint is not part of CCD. It provides a method for updating the -STM32 without needing the special boot modes. This uses the [Chromium EC update -over -USB](../../docs/usb_updater.md) -method. The STM32 runs the code in -[`common/usb_update.c`](../../common/usb_update.c). -The host side code is in -[`extra/usb_updater/usb_updater2.c`](../../extra/usb_updater/usb_updater2.c) -and the -[`extra/usb_updater`](../../extra/usb_updater/) -directory contains additional scripts. - +STM32 without needing the special boot modes. This uses the +[Chromium EC update over USB](../../docs/usb_updater.md) method. The STM32 runs +the code in [`common/usb_update.c`](../../common/usb_update.c). The host side +code is in +[`extra/usb_updater/usb_updater2.c`](../../extra/usb_updater/usb_updater2.c) and +the [`extra/usb_updater`](../../extra/usb_updater/) directory contains +additional scripts. ## Using CCD on new designs diff --git a/common/mock/README.md b/common/mock/README.md index bb85217bde..c7695531b6 100644 --- a/common/mock/README.md +++ b/common/mock/README.md @@ -1,25 +1,24 @@ # Common Mocks + This directory holds mock implementations for use in fuzzers and tests. -Each mock is given some friendly build name, like ROLLBACK or FP_SENSOR. -This name is defined in [common/mock/build.mk](build.mk) and referenced -from unit tests and fuzzers' `.mocklist` file. +Each mock is given some friendly build name, like ROLLBACK or FP_SENSOR. This +name is defined in [common/mock/build.mk](build.mk) and referenced from unit +tests and fuzzers' `.mocklist` file. ## Creating a new mock -* Add the mock source to [common/mock](/common/mock) and the - optional header file to [include/mock](/include/mock). - Header files are only necessary if you want to expose additional - [mock control](#mock-controls) functions/variables. - See the [Design Patterns](#design-patterns) section - for more detail on design patterns. -* Add a new entry in [common/mock/build.mk](build.mk) - that is conditioned on your mock's name. +* Add the mock source to [common/mock](/common/mock) and the optional header + file to [include/mock](/include/mock). Header files are only necessary if + you want to expose additional [mock control](#mock-controls) + functions/variables. See the [Design Patterns](#design-patterns) section for + more detail on design patterns. +* Add a new entry in [common/mock/build.mk](build.mk) that is conditioned on + your mock's name. -If a unit test or fuzzer requests this mock, the build system will -set the variable `HAS_MOCK_<BUILD_NAME>` to `y` at build time. -This variable is used to conditionally include the mock source -in [common/mock/build.mk](build.mk). +If a unit test or fuzzer requests this mock, the build system will set the +variable `HAS_MOCK_<BUILD_NAME>` to `y` at build time. This variable is used to +conditionally include the mock source in [common/mock/build.mk](build.mk). Example line from [common/mock/build.mk](build.mk): @@ -29,11 +28,12 @@ mock-$(HAS_MOCK_ROLLBACK) += mock/rollback_mock.o ``` ## Using a mock -Unit tests and fuzzers can request a particular mock by adding an entry to -their `.mocklist` file. The mocklist file is similar to a `.tasklist` -file, where it is named according to the test/fuzz's name followed by -`.mocklist`, like `fpsensor.mocklist`. -The mocklist file is optional, so you may need to create one. + +Unit tests and fuzzers can request a particular mock by adding an entry to their +`.mocklist` file. The mocklist file is similar to a `.tasklist` file, where it +is named according to the test/fuzz's name followed by `.mocklist`, like +`fpsensor.mocklist`. The mocklist file is optional, so you may need to create +one. Example `.mocklist`: @@ -44,13 +44,13 @@ Example `.mocklist`: */ #define CONFIG_TEST_MOCK_LIST \ - MOCK(ROLLBACK) \ - MOCK(FP_SENSOR) + MOCK(ROLLBACK) \ + MOCK(FP_SENSOR) ``` -If you need additional [mock control](#mock-controls) functionality, -you may need to include the mock's header file, which is prepended -with `mock/` in the include line. +If you need additional [mock control](#mock-controls) functionality, you may +need to include the mock's header file, which is prepended with `mock/` in the +include line. For example, to control the return values of the rollback mock: @@ -58,30 +58,31 @@ For example, to control the return values of the rollback mock: #include "mock/rollback_mock.h" void yourfunction() { - mock_ctrl_rollback.get_secret_fail = true; + mock_ctrl_rollback.get_secret_fail = true; } ``` ## Mock Controls + Mocks can change their behavior by exposing "mock controls". -We do this, most commonly, by exposing an additional global struct -per mock that acts as the settings for the mock implementation. -The mock user can then modify fields of the struct to change the mock's behavior. -For example, the `fp_sensor_init_return` field may control what value -the mocked `fp_sensor_init` function returns. +We do this, most commonly, by exposing an additional global struct per mock that +acts as the settings for the mock implementation. The mock user can then modify +fields of the struct to change the mock's behavior. For example, the +`fp_sensor_init_return` field may control what value the mocked `fp_sensor_init` +function returns. The declaration for these controls are specified in the mock's header file, which resides in [include/mock](/include/mock). ## Design Patterns -* When creating mock controls, consider placing all your mock parameters in - one externally facing struct, like in - [fp_sensor_mock.h](/include/mock/fp_sensor_mock.h). - The primary reason for this is to allow the mock to be easily used - by a fuzzer (write random bytes into the struct with memcpy). -* When following the above pattern, please provide a macro for resetting - default values for this struct, like in - [fp_sensor_mock.h](/include/mock/fp_sensor_mock.h). - This allows unit tests to quickly reset the mock state/parameters - before each unrelated unit test. + +* When creating mock controls, consider placing all your mock parameters in + one externally facing struct, like in + [fp_sensor_mock.h](/include/mock/fp_sensor_mock.h). The primary reason for + this is to allow the mock to be easily used by a fuzzer (write random bytes + into the struct with memcpy). +* When following the above pattern, please provide a macro for resetting + default values for this struct, like in + [fp_sensor_mock.h](/include/mock/fp_sensor_mock.h). This allows unit tests + to quickly reset the mock state/parameters before each unrelated unit test. 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) $ ``` - diff --git a/extra/stack_analyzer/README.md b/extra/stack_analyzer/README.md index bead6d10b4..d1c77b57d2 100644 --- a/extra/stack_analyzer/README.md +++ b/extra/stack_analyzer/README.md @@ -1,27 +1,22 @@ -Stack Size Analysis Tool for EC Firmware -======================================== +# Stack Size Analysis Tool for EC Firmware This tool does static analysis on EC firmwares to get the maximum stack usage of each function and task. The maximum stack usage of a function includes the stack used by itself and the functions it calls. -Usage ------ +## Usage Make sure the firmware of your target board has been built. -In `src/platform/ec`, run -``` -make BOARD=${BOARD} SECTION=${SECTION} ANNOTATION=${ANNOTATION} analyzestack -``` -The `${SECTION}` can be `RO` or `RW`. The `${ANNOTATION}` is a optional -annotation file, see the example_annotation.yaml, by default, -board/$BOARD/analyzestack.yaml is used. +In `src/platform/ec`, run `make BOARD=${BOARD} SECTION=${SECTION} +ANNOTATION=${ANNOTATION} analyzestack` The `${SECTION}` can be `RO` or `RW`. The +`${ANNOTATION}` is a optional annotation file, see the example_annotation.yaml, +by default, board/$BOARD/analyzestack.yaml is used. -Output ------- +## Output For each task, it will output the result like below, + ``` Task: PD_C1, Max size: 1156 (932 + 224), Allocated size: 640 Call Trace: @@ -34,9 +29,12 @@ Call Trace: pd_send_request_msg.lto_priv.263 (56) [common/usb_pd_protocol.c:653] 1009a0b4 -> pd_send_request_msg.lto_priv.263[common/usb_pd_protocol.c:712] 1009a22e0 ``` -The `pd_task` uses 160 bytes on the stack and calls `pd_send_request_msg.lto_priv.263`. + +The `pd_task` uses 160 bytes on the stack and calls +`pd_send_request_msg.lto_priv.263`. The callsites to the next function will be shown like below, + ``` -> pd_task[common/usb_pd_protocol.c:1808] 1008ac8a - handle_request[common/usb_pd_protocol.c:1191] @@ -44,37 +42,42 @@ The callsites to the next function will be shown like below, -> pd_task[common/usb_pd_protocol.c:2672] 1008c222 -> [annotation] ``` -This means one callsite to the next function is at `usb_pd_protocol.c:798`, -but it is inlined to the current function and you can follow the trace: + +This means one callsite to the next function is at `usb_pd_protocol.c:798`, but +it is inlined to the current function and you can follow the trace: `usb_pd_protocol.c:1808 -> usb_pd_protocol.c:1191 -> usb_pd_protocol.c:798` to find the callsite. The second callsite is at `usb_pd_protocol.c:2672`. And the third one is added by annotation. The unresolved indirect callsites have the similar format to the above. -Annotating Indirect Call ------------------------- +## Annotating Indirect Call To annotate an indirect call like this, + ``` Unresolved indirect callsites: pd_transmit -> pd_transmit[common/usb_pd_protocol.c:407] 802c9c8 - tcpm_transmit[driver/tcpm/tcpm.h:142] ``` -It is an indirect call in the `tcpm_transmit`, which is inlined to the `pd_transmit`. + +It is an indirect call in the `tcpm_transmit`, which is inlined to the +`pd_transmit`. You can add a annotation like the below to eliminate it. + ``` add: tcpm_transmit[driver/tcpm/tcpm.h:142]: - anx74xx_tcpm_transmit ``` -The source `tcpm_transmit[driver/tcpm/tcpm.h:142]` must be a full signature (function_name[path:line number]). -So the resolver can know which indirect call you want to annotate and eliminate (even if it is inlined). -Annotating arrays (hooks, console commands, host commands) ----------------------------------------------------------- +The source `tcpm_transmit[driver/tcpm/tcpm.h:142]` must be a full signature +(function_name[path:line number]). So the resolver can know which indirect call +you want to annotate and eliminate (even if it is inlined). + +## Annotating arrays (hooks, console commands, host commands) When a callsite calls a number of functions based on values from an constant array (in `.rodata` section), one can use the following syntax: @@ -89,8 +92,8 @@ array (in `.rodata` section), one can use the following syntax: Where `name` is the symbol name for the start of the array (the end of the array is `<name>_end`), stride is the array element size, and offset is the offset of the function pointer in the structure. For example, above, `__deferred_funcs` is -a simple array of function pointers, while `__hooks_tick` is an array of -`struct hook_data` (size 8, pointer at offset 0): +a simple array of function pointers, while `__hooks_tick` is an array of `struct +hook_data` (size 8, pointer at offset 0): ``` struct hook_data { diff --git a/extra/tigertool/README.md b/extra/tigertool/README.md index e808536e7b..407a58a751 100644 --- a/extra/tigertool/README.md +++ b/extra/tigertool/README.md @@ -1,18 +1,28 @@ # tigertool -tigertool.py is a commandline utility to control the tigertail USB-C mux. -It supports changing the mux status to port A, B, or off. -You can set a serial number to use multiple tigertails at once. +tigertool.py is a commandline utility to control the tigertail USB-C mux. It +supports changing the mux status to port A, B, or off. You can set a serial +number to use multiple tigertails at once. ## Usage -Typical usage to set the mux port<br> -```./tigertail.py -m [A|B|off] -s [serialno]```<br> + +Typical usage to set the mux port + +``` +./tigertail.py -m [A|B|off] -s [serialno] +``` Reboot the tigertail<br> -```./tigertail.py --reboot```<br> -Set the serial number, when only one tigertail is plugged<br> -```./tigertail.py --setserialno=[serialno]```<br> +``` +./tigertail.py --reboot +``` + +Set the serial number, when only one tigertail is plugged + +``` +./tigertail.py --setserialno=[serialno] +``` -Tigertail can support up to 20V 3A on the mux and passes through all -USB-C lines except SBU. +Tigertail can support up to 20V 3A on the mux and passes through all USB-C lines +except SBU. diff --git a/extra/usb_power/powerlog.README.md b/extra/usb_power/powerlog.README.md index a5ce379670..105516330a 100644 --- a/extra/usb_power/powerlog.README.md +++ b/extra/usb_power/powerlog.README.md @@ -9,57 +9,58 @@ this session, a `.scenario` file. ## Converting from servo_ina configs -- Method 1 (not limited to chroot) +- Method 1 (not limited to chroot) - Many configs can be found for the servo_ina_board in `hdctools/servo/data/`. - Sweetberry is plug compatible with servo_ina headers, and config files can be - converted with the following tool: + Many configs can be found for the servo_ina_board in `hdctools/servo/data/`. + Sweetberry is plug compatible with servo_ina headers, and config files can + be converted with the following tool: - ``` - ./convert_servo_ina.py <board>_r0_loc.py - ``` + ``` + ./convert_servo_ina.py <board>_r0_loc.py + ``` - This will generate `<board>_r0_loc.board` and `<board>_r0_loc.scenario` - locally, which can be used with `powerlog.py`. + This will generate `<board>_r0_loc.board` and `<board>_r0_loc.scenario` + locally, which can be used with `powerlog.py`. -- Method 2 (recommended for Chrome OS developers, requires chroot) +- Method 2 (recommended for Chrome OS developers, requires chroot) - If you are using `powerlog.py` within the chroot, copy `<board>_r0_loc.py` to - `src/third_party/hdctools/servo/data`, then add this line to file: + If you are using `powerlog.py` within the chroot, copy `<board>_r0_loc.py` + to `src/third_party/hdctools/servo/data`, then add this line to file: - ```python - config_type = 'sweetberry' - ``` + ```python + config_type = 'sweetberry' + ``` - And run command in chroot: + And run command in chroot: - ``` - (Anywhere in chroot, just ONCE) cros_workon --host start dev-util/hdctools - ``` + ``` + (Anywhere in chroot, just ONCE) cros_workon --host start dev-util/hdctools + ``` - Then every time you make a change to `<board>_r0_loc.py`, run: + Then every time you make a change to `<board>_r0_loc.py`, run: - ``` - (Anywhere in chroot) sudo emerge dev-util/hdctools - ``` + ``` + (Anywhere in chroot) sudo emerge dev-util/hdctools + ``` - The command will install the corresponding `.board` and `.scenario` file in - the chroot. To use `powerlog.py` use the command: + The command will install the corresponding `.board` and `.scenario` file in + the chroot. To use `powerlog.py` use the command: - ``` - (Anywhere in chroot) powerlog -b <board>_r0_loc.board -c <board>_r0_loc.scenario - ``` + ``` + (Anywhere in chroot) powerlog -b <board>_r0_loc.board -c <board>_r0_loc.scenario + ``` - There is no need to specify the absolute path to the `.board` and `.scenario` - file, once they are installed into the chroot. If there is any changes to - `<board>_r0_loc.py`, you need to `sudo emerge dev-util/hdctools` again. + There is no need to specify the absolute path to the `.board` and + `.scenario` file, once they are installed into the chroot. If there is any + changes to `<board>_r0_loc.py`, you need to `sudo emerge dev-util/hdctools` + again. ## Board files Board files contain a list of rails, supporting 48 channels each on up to two Sweetberries. For each rail you must specify a name, sense resistor value, and -channel number. You can optionally list expected voltage and net name. -The format is as follows, in json: +channel number. You can optionally list expected voltage and net name. The +format is as follows, in json: example.board: @@ -81,9 +82,8 @@ example.board: Scenario files contain the set of rails to monitor in this session. The file format is simply a list of rail names from the board file. -Optionally, you can specify the type of measurement, from the set of -`"POWER"`, `"BUSV"`, `"CURRENT"`, `"SHUNTV"`. If not specified, the default is -power. +Optionally, you can specify the type of measurement, from the set of `"POWER"`, +`"BUSV"`, `"CURRENT"`, `"SHUNTV"`. If not specified, the default is power. example.scenario: @@ -109,93 +109,90 @@ An example run of: ./powerlog.py -b board/marlin/marlin.board -c board/marlin/marlin_short.scenario -t 100000 ``` -Will result in: -``` -ts:32976us, VBAT uW, VDD_MEM uW, VDD_CORE uW, VDD_GFX uW, VDD_1V8_PANEL uW -0.033004, 12207.03, 4882.81, 9155.27, 2441.41, 0.00 -0.066008, 12207.03, 3662.11, 9155.27, 2441.41, 0.00 -0.099012, 12207.03, 3662.11, 9155.27, 2441.41, 0.00 -... -``` +Will result in: `ts:32976us, VBAT uW, VDD_MEM uW, VDD_CORE uW, VDD_GFX uW, +VDD_1V8_PANEL uW 0.033004, 12207.03, 4882.81, 9155.27, 2441.41, 0.00 0.066008, +12207.03, 3662.11, 9155.27, 2441.41, 0.00 0.099012, 12207.03, 3662.11, 9155.27, +2441.41, 0.00 ...` The output format is as follows: -- `ts:32976us` +- `ts:32976us` - Timestamps either zero based or synced to system clock, in seconds. The column - header indicates the selected sampling interval. Since the INA231 has specific - hardware defines sampling options, this will be the closest supported option - lower than the requested `-t` value on the command line. + Timestamps either zero based or synced to system clock, in seconds. The + column header indicates the selected sampling interval. Since the INA231 has + specific hardware defines sampling options, this will be the closest + supported option lower than the requested `-t` value on the command line. -- `VBAT uW` +- `VBAT uW` - Microwatt reading from this rail, generated on the INA by integrating the - voltage/amperage on the sense resistor over the sampling time, and multiplying - by the sampled bus voltage. + Microwatt reading from this rail, generated on the INA by integrating the + voltage/amperage on the sense resistor over the sampling time, and + multiplying by the sampled bus voltage. -- `... uW` +- `... uW` - Further microwatt entry columns for each rail specified in your scenario file. + Further microwatt entry columns for each rail specified in your scenario + file. -- `... xX` +- `... xX` - Measurement in uW, mW, mV, uA, uV as per config. + Measurement in uW, mW, mV, uA, uV as per config. ## Calculate stats and store data and stats When appropriate flag is set, powerlog.py is capable of calculating statistics and storing statistics and raw data. -- Example 1 +- Example 1 - ``` - ./powerlog.py -b board/eve_dvt2_loc/eve_dvt2_loc.board -c board/eve_dvt2_loc/eve_dvt2_loc.scenario --save_stats [<directory>] - ``` + ``` + ./powerlog.py -b board/eve_dvt2_loc/eve_dvt2_loc.board -c board/eve_dvt2_loc/eve_dvt2_loc.scenario --save_stats [<directory>] + ``` - If `<directory>` is specified, this will save stats as: - `<directory>/sweetberry<timestemp>/summary.txt`. - If `<directory>` does not exist, it will be created. + If `<directory>` is specified, this will save stats as: + `<directory>/sweetberry<timestamp>/summary.txt`. If `<directory>` does not + exist, it will be created. - If `<directory>` is not specified but the flag is set, this will save stats - under the directory which `powerlog.py` is in: - `<directory of powerlog.py>/sweetberry<timestemp>/summary.txt`. + If `<directory>` is not specified but the flag is set, this will save stats + under the directory which `powerlog.py` is in: `<directory of + powerlog.py>/sweetberry<timestamp>/summary.txt`. - If `--save_stats` flag is not set, stats will not be saved. + If `--save_stats` flag is not set, stats will not be saved. -- Example 2 +- Example 2 - ``` - ./powerlog.py -b board/eve_dvt2_loc/eve_dvt2_loc.board -c board/eve_dvt2_loc/eve_dvt2_loc.scenario --save_raw_data [<directory>] - ``` + ``` + ./powerlog.py -b board/eve_dvt2_loc/eve_dvt2_loc.board -c board/eve_dvt2_loc/eve_dvt2_loc.scenario --save_raw_data [<directory>] + ``` - If `<directory>` is specified, this will save raw data in: - `<directory>/sweetberry<timestemp>/raw_data/`. - If `<directory>` does not exist, it will be created. + If `<directory>` is specified, this will save raw data in: + `<directory>/sweetberry<timestamp>/raw_data/`. If `<directory>` does not + exist, it will be created. - If `<directory>` is not specified but the flag is set, this will save raw data - under the directory which `powerlog.py` is in: - `<directory of powerlog.py>/sweetberry<timestemp>/raw_data/`. + If `<directory>` is not specified but the flag is set, this will save raw + data under the directory which `powerlog.py` is in: `<directory of + powerlog.py>/sweetberry<timestamp>/raw_data/`. - If `--save_raw_data` flag is not set, raw data will not be saved. + If `--save_raw_data` flag is not set, raw data will not be saved. -- Example 3: +- Example 3: - ``` - ./powerlog.py -b board/eve_dvt2_loc/eve_dvt2_loc.board -c board/eve_dvt2_loc/eve_dvt2_loc.scenario --save_stats_json [<directory>] - ``` + ``` + ./powerlog.py -b board/eve_dvt2_loc/eve_dvt2_loc.board -c board/eve_dvt2_loc/eve_dvt2_loc.scenario --save_stats_json [<directory>] + ``` - If `<directory>` is specified, this will save MEANS in json as: - `<directory>/sweetberry<timestemp>/summary.json`. - If `<directory>` does not exist, it will be created. + If `<directory>` is specified, this will save MEANS in json as: + `<directory>/sweetberry<timestamp>/summary.json`. If `<directory>` does not + exist, it will be created. - If `<directory>` is not specified but the flag is set, this will save MEANS in - json under the directory which `powerlog.py` is in: - `<directory of powerlog.py>/sweetberry<timestemp>/summary.json`. + If `<directory>` is not specified but the flag is set, this will save MEANS + in json under the directory which `powerlog.py` is in: `<directory of + powerlog.py>/sweetberry<timestamp>/summary.json`. - If `--save_stats` flag is not set, stats will not be saved. + If `--save_stats` flag is not set, stats will not be saved. - `--save_stats_json` is designed for `power_telemetry_logger` for easy reading - and writing. + `--save_stats_json` is designed for `power_telemetry_logger` for easy + reading and writing. ## Making developer changes to `powerlog.py` diff --git a/extra/usb_serial/README.md b/extra/usb_serial/README.md index 6806620a62..7cc6030d0a 100644 --- a/extra/usb_serial/README.md +++ b/extra/usb_serial/README.md @@ -1,5 +1,4 @@ -Case Closed Debugging Serial Consoles over USB -============================================== +# Case Closed Debugging Serial Consoles over USB Please see the documentation in [case_closed_debugging doc][1] @@ -3,9 +3,9 @@ [logo]: https://chromium-review.googlesource.com/plugins/chromium-style/static/chromium_logo.png [home]: /README.md -* [Home][home] -* [Documentation](/docs/sitemap.md) -* [Getting Started Quickly](/docs/getting_started_quickly.md) -* [File a Bug](https://bugs.chromium.org/p/chromium/issues/entry?components=OS%3EFirmware%3EEC) -* [Report Security Issue](https://chromium.googlesource.com/chromiumos/docs/+/master/reporting_bugs.md#security) -* [Chromium OS Docs](https://chromium.googlesource.com/chromiumos/docs/+/master/README.md) +* [Home][home] +* [Documentation](/docs/sitemap.md) +* [Getting Started Quickly](/docs/getting_started_quickly.md) +* [File a Bug](https://bugs.chromium.org/p/chromium/issues/entry?components=OS%3EFirmware%3EEC) +* [Report Security Issue](https://chromium.googlesource.com/chromiumos/docs/+/master/reporting_bugs.md#security) +* [Chromium OS Docs](https://chromium.googlesource.com/chromiumos/docs/+/master/README.md) diff --git a/third_party/incbin/README.md b/third_party/incbin/README.md index cada41fa16..da32103e9e 100644 --- a/third_party/incbin/README.md +++ b/third_party/incbin/README.md @@ -4,7 +4,7 @@ Include binary files in your C/C++ applications with ease ## Example -``` c +```c #include "incbin.h" INCBIN(Icon, "icon.png"); @@ -28,52 +28,56 @@ Include binary files in your C/C++ applications with ease Known to work on the following compilers -* GCC -* Clang -* PathScale -* Intel -* Solaris & Sun Studio -* Green Hills -* SNC (ProDG) -* Diab C++ (WindRiver) -* XCode -* ArmCC -* RealView -* ImageCraft -* Stratus VOS C -* TinyCC -* cparser & libfirm -* LCC -* MSVC _See MSVC below_ - -If your compiler is not listed, as long as it supports GCC inline assembler, this -should work. +* GCC +* Clang +* PathScale +* Intel +* Solaris & Sun Studio +* Green Hills +* SNC (ProDG) +* Diab C++ (WindRiver) +* XCode +* ArmCC +* RealView +* ImageCraft +* Stratus VOS C +* TinyCC +* cparser & libfirm +* LCC +* MSVC _See MSVC below_ + +If your compiler is not listed, as long as it supports GCC inline assembler, +this should work. ## MISRA -INCBIN can be used in MISRA C setting. However it should be independently checked -due to its use of inline assembly to achieve what it does. Independent verification -of the header has been done several times based on commit: 7e327a28ba5467c4202ec37874beca7084e4b08c + +INCBIN can be used in MISRA C setting. However it should be independently +checked due to its use of inline assembly to achieve what it does. Independent +verification of the header has been done several times based on commit: +7e327a28ba5467c4202ec37874beca7084e4b08c ## Alignment -The data included by this tool will be aligned on the architectures word boundary -unless some variant of SIMD is detected, then it's aligned on a byte boundary that -respects SIMD convention just incase your binary data may be used in vectorized -code. The table of the alignments for SIMD this header recognizes is as follows: +The data included by this tool will be aligned on the architectures word +boundary unless some variant of SIMD is detected, then it's aligned on a byte +boundary that respects SIMD convention just in case your binary data may be used +in vectorized code. The table of the alignments for SIMD this header recognizes +is as follows: -| SIMD | Alignment | -|-----------------------------------------|-----------| -| SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2 | 16 | -| Neon | 16 | -| AVX, AVX2 | 32 | -| AVX512 | 64 | +SIMD | Alignment +-------------------------------------- | --------- +SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2 | 16 +Neon | 16 +AVX, AVX2 | 32 +AVX512 | 64 ## Prefix + By default, `incbin.h` emits symbols with a `g` prefix. This can be adjusted by defining `INCBIN_PREFIX` before including `incbin.h` with a desired prefix. For instance -``` c +```c #define INCBIN_PREFIX g_ #include "incbin.h" INCBIN(test, "test.txt"); @@ -84,9 +88,10 @@ instance // const unsigned int g_testSize; ``` -You can also choose to have no prefix by defining the prefix with nothing, for example: +You can also choose to have no prefix by defining the prefix with nothing, for +example: -``` c +```c #define INCBIN_PREFIX #include "incbin.h" INCBIN(test, "test.txt"); @@ -98,16 +103,17 @@ You can also choose to have no prefix by defining the prefix with nothing, for e ``` ## Style -By default, `incbin.h` emits symbols with `CamelCase` style. This can be adjusted -by defining `INCBIN_STYLE` before including `incbin.h` to change the style. There -are two possible styles to choose from -* INCBIN_STYLE_CAMEL (CamelCase) -* INCBIN_STYLE_SNAKE (snake_case) +By default, `incbin.h` emits symbols with `CamelCase` style. This can be +adjusted by defining `INCBIN_STYLE` before including `incbin.h` to change the +style. There are two possible styles to choose from + +* INCBIN_STYLE_CAMEL (CamelCase) +* INCBIN_STYLE_SNAKE (snake_case) For instance: -``` c +```c #define INCBIN_STYLE INCBIN_STYLE_SNAKE #include "incbin.h" INCBIN(test, "test.txt"); @@ -122,14 +128,15 @@ Combining both the style and prefix allows for you to adjust `incbin.h` to suite your existing style and practices. ## Overriding Linker Output section + By default, `incbin.h` emits into the read-only linker output section used on -the detected platform. If you need to override this for whatever reason, you -can manually specify the linker output section. +the detected platform. If you need to override this for whatever reason, you can +manually specify the linker output section. For example, to emit data into program memory for [esp8266/Arduino](github.com/esp8266/Arduino): -``` c +```c #define INCBIN_OUTPUT_SECTION ".irom.text" #include "incbin.h" INCBIN(Foo, "foo.txt"); @@ -141,27 +148,27 @@ INCBIN(Foo, "foo.txt"); `INCBIN` is a macro which uses the inline assembler provided by almost all compilers to include binary files. It achieves this by utilizing the `.incbin` directive of the inline assembler. It then uses the assembler to calculate the -size of the included binary and exports two global symbols that can be externally -referenced in other translation units which contain the data and size of the -included binary data respectively. +size of the included binary and exports two global symbols that can be +externally referenced in other translation units which contain the data and size +of the included binary data respectively. ## MSVC Supporting MSVC is slightly harder as MSVC lacks an inline assembler which can include data. To support this we ship a tool which can process source files containing `INCBIN` macro usage and generate an external source file containing -the data of all of them combined. This file is named `data.c` by default. -Just include it into your build and use the `incbin.h` to reference data as -needed. It's suggested you integrate this tool as part of your projects's -pre-build events so that this can be automated. A more comprehensive list of -options for this tool can be viewed by invoking the tool with `-help` +the data of all of them combined. This file is named `data.c` by default. Just +include it into your build and use the `incbin.h` to reference data as needed. +It's suggested you integrate this tool as part of your projects's pre-build +events so that this can be automated. A more comprehensive list of options for +this tool can be viewed by invoking the tool with `-help` If you're using a custom prefix, be sure to specify the prefix on the command line with `-p <prefix>` so that everything matches up; similarly, if you're -using a custom style, be sure to specify the style on the command line with -`-S <style>` as well. +using a custom style, be sure to specify the style on the command line with `-S +<style>` as well. ## Miscellaneous -Documentation for the API is provided by the header using Doxygen notation. -For licensing information see UNLICENSE. +Documentation for the API is provided by the header using Doxygen notation. For +licensing information see UNLICENSE. diff --git a/util/iteflash.md b/util/iteflash.md index fb4e35dc58..4f4a7d2853 100644 --- a/util/iteflash.md +++ b/util/iteflash.md @@ -6,7 +6,8 @@ First written: 2019-04-02 <br> Last updated: 2019-04-03 -Familiarity with [Chromium OS](https://www.chromium.org/chromium-os) [Embedded Controller (EC) development](../README.md) is assumed. +Familiarity with [Chromium OS](https://www.chromium.org/chromium-os) +[Embedded Controller (EC) development](../README.md) is assumed. [TOC] @@ -14,106 +15,153 @@ Familiarity with [Chromium OS](https://www.chromium.org/chromium-os) [Embedded C ### Terminology -**ITE EC** refers to the [ITE](http://www.ite.com.tw/) [IT8320](http://www.ite.com.tw/en/product/view?mid=96) [Embedded Controller (EC)](https://en.wikipedia.org/wiki/Embedded_controller) microcontroller when used as a Chromium OS / Chrome OS EC. - -**CrOS** refers to Chromium OS, Chrome OS, or both, depending on the context. The distinction between Chromium OS and Chrome OS is largely immaterial to this document. - -**Servo** refers to a debug board providing direct debug access to various circuits on a Chrome OS device motherboard. As of this writing, the most common [servos](https://www.chromium.org/chromium-os/servo) used by CrOS developers are [CR50 (CCD)](https://www.chromium.org/chromium-os/ccd), [Servo Micro](https://www.chromium.org/chromium-os/servo/servomicro), and [Servo v2](https://www.chromium.org/chromium-os/servo/servo-v2). (Note that [Servo v4](https://www.chromium.org/chromium-os/servo/servov4) is **not** a Servo in this sense. It is a USB hub with a microcontroller that proxies Servo functionality from either CR50 or Servo Micro.) See also [Case-Closed Debug in Chromebooks and Servo Micro](https://chromium.googlesource.com/chromiumos/platform/ec/+/master/board/servo_micro/ccd.md). +**ITE EC** refers to the [ITE](http://www.ite.com.tw/) +[IT8320](http://www.ite.com.tw/en/product/view?mid=96) +[Embedded Controller (EC)](https://en.wikipedia.org/wiki/Embedded_controller) +microcontroller when used as a Chromium OS / Chrome OS EC. + +**CrOS** refers to Chromium OS, Chrome OS, or both, depending on the context. +The distinction between Chromium OS and Chrome OS is largely immaterial to this +document. + +**Servo** refers to a debug board providing direct debug access to various +circuits on a Chrome OS device motherboard. As of this writing, the most common +[servos](https://www.chromium.org/chromium-os/servo) used by CrOS developers are +[CR50 (CCD)](https://www.chromium.org/chromium-os/ccd), +[Servo Micro](https://www.chromium.org/chromium-os/servo/servomicro), and +[Servo v2](https://www.chromium.org/chromium-os/servo/servo-v2). (Note that +[Servo v4](https://www.chromium.org/chromium-os/servo/servov4) is **not** a +Servo in this sense. It is a USB hub with a microcontroller that proxies Servo +functionality from either CR50 or Servo Micro.) See also +[Case-Closed Debug in Chromebooks and Servo Micro](https://chromium.googlesource.com/chromiumos/platform/ec/+/master/board/servo_micro/ccd.md). ### How ITE EC reflashing works An ITE EC is reflashed using a Servo by: -1. Sending special non-I2C waveforms over its I2C clock and data lines, to enable a debug mode / direct firmware update (DFU) mode. +1. Sending special non-I2C waveforms over its I2C clock and data lines, to + enable a debug mode / direct firmware update (DFU) mode. -1. Communicating with it using I2C, including transferring the actual EC image over I2C. The ITE EC will only respond over I2C after receiving the special waveforms. +1. Communicating with it using I2C, including transferring the actual EC image + over I2C. The ITE EC will only respond over I2C after receiving the special + waveforms. ### Further reading -Googlers, and Partners involved in ITE EC projects, see [The State of ITE CrOS EC Reflashing](https://docs.google.com/document/d/1fs29eBvwKrOWYozLZXTg7ObwAO5dyM4Js2Vq301EwAU/preview). That document is not public, do not request access if you lack it. +Googlers, and Partners involved in ITE EC projects, see +[The State of ITE CrOS EC Reflashing](https://docs.google.com/document/d/1fs29eBvwKrOWYozLZXTg7ObwAO5dyM4Js2Vq301EwAU/preview). +That document is not public, do not request access if you lack it. ## How to reflash ### Prerequisites for CR50 CCD -This section applies whether using CR50 CCD via [Servo v4](https://www.chromium.org/chromium-os/servo/servov4) or [SuzyQ aka SuzyQable](https://www.sparkfun.com/products/14746). +This section applies whether using CR50 CCD via +[Servo v4](https://www.chromium.org/chromium-os/servo/servov4) or +[SuzyQ aka SuzyQable](https://www.sparkfun.com/products/14746). CR50 MP minimum firmware version: `0.3.15` <br> CR50 pre-PVT minimum firmware version: `0.4.15` -Googlers, to upgrade CR50 firmware if needed see [How to use CCD on CR50](https://docs.google.com/document/d/1MqDAoBsmGTmrFi-WNOoC5R-UFeuQK37_9kaEdCFU8QE/preview). That document is not public, do not request access if you lack it. +Googlers, to upgrade CR50 firmware if needed see +[How to use CCD on CR50](https://docs.google.com/document/d/1MqDAoBsmGTmrFi-WNOoC5R-UFeuQK37_9kaEdCFU8QE/preview). +That document is not public, do not request access if you lack it. -The CR50 CCD capabilities must be set to `always`. To achieve this: +The CR50 CCD capabilities must be set to `always`. To achieve this: -1. Open CCD. - * root shell: `$ gsctool -o` - * CR50 console: `ccd open` -1. Reset CCD to `factory` mode. - * CR50 console: `ccd reset factory` +1. Open CCD. + * root shell: `$ gsctool -o` + * CR50 console: `ccd open` +1. Reset CCD to `factory` mode. + * CR50 console: `ccd reset factory` -Reflashing with CR50 also requires the [i2c-pseudo kernel module](#i2c-pseudo), unless using the [CR50 CCD sans servod](#ccd-sans-servod) alternative method. +Reflashing with CR50 also requires the [i2c-pseudo kernel module](#i2c-pseudo), +unless using the [CR50 CCD sans servod](#ccd-sans-servod) alternative method. ### Prerequisites for Servo Micro -This section applies whether the [Servo Micro](https://www.chromium.org/chromium-os/servo/servomicro) is connected directly to your development host, or through a [Servo v4](https://www.chromium.org/chromium-os/servo/servov4). +This section applies whether the +[Servo Micro](https://www.chromium.org/chromium-os/servo/servomicro) is +connected directly to your development host, or through a +[Servo v4](https://www.chromium.org/chromium-os/servo/servov4). Servo Micro minimum firmware version: `servo_micro_v2.3.5` To upgrade Servo Micro firmware if needed: -1. Enter the chroot. - * `$ cros_sdk` -1. Run servo_updater. - * `$ sudo servo_updater --board=servo_micro` +1. Enter the chroot. + * `$ cros_sdk` +1. Run servo_updater. + * `$ sudo servo_updater --board=servo_micro` -If that still results in too old of a firmware version, use `repo sync` and `update_chroot` to update your CrOS development environment, then try again. +If that still results in too old of a firmware version, use `repo sync` and +`update_chroot` to update your CrOS development environment, then try again. -Reflashing with Servo Micro also requires the [i2c-pseudo kernel module](#i2c-pseudo). +Reflashing with Servo Micro also requires the +[i2c-pseudo kernel module](#i2c-pseudo). ### Installing i2c-pseudo {#i2c-pseudo} -1. Install the `i2c-pseudo` Linux kernel module. (Do this **outside** of the chroot!) - * `$ cd src/platform/ec/extra/i2c_pseudo` - * `$ ./install` +1. Install the `i2c-pseudo` Linux kernel module. (Do this **outside** of the + chroot!) + * `$ cd src/platform/ec/extra/i2c_pseudo` + * `$ ./install` -If the above fails, your system may be missing packages necessary for building kernel modules. Consult your Linux distribution's documentation and support forums. After installing any packages that might be missing, simply try the install script again. +If the above fails, your system may be missing packages necessary for building +kernel modules. Consult your Linux distribution's documentation and support +forums. After installing any packages that might be missing, simply try the +install script again. You will need to reinstall `i2c-pseudo` after each kernel upgrade. -There is an intention to [upstream i2c-pseudo](https://issuetracker.google.com/129565355), though even if accepted upstream, it may or may not become included with common Linux distribution kernels. +There is an intention to +[upstream i2c-pseudo](https://issuetracker.google.com/129565355), though even if +accepted upstream, it may or may not become included with common Linux +distribution kernels. ### Common reflash instructions -These instructions apply when using any kind of Servo, including those with no special prerequisites (such as [Servo v2](https://www.chromium.org/chromium-os/servo/servo-v2) with its Yoshi flex cable connected to the DUT). - -1. Enter the chroot (for servod). - * `$ cros_sdk --no-ns-pid` -1. Start servod. - * `$ sudo servod --board=<servod_board_name>` - * For some boards the servod board name is different than the EC codebase board name used below! -1. Enter the chroot (for flash_ec). - * `$ cros_sdk` -1. Build the EC image for your board. - * `$ cd ~/trunk/src/platform/ec` - * `$ board=<board_name>` - * `$ make -j BOARD="$board"` -1. Run flash_ec from the util directory. - * `$ util/flash_ec --board="$board" --image=build/"$board"/ec.bin` +These instructions apply when using any kind of Servo, including those with no +special prerequisites (such as +[Servo v2](https://www.chromium.org/chromium-os/servo/servo-v2) with its Yoshi +flex cable connected to the DUT). + +1. Enter the chroot (for servod). + * `$ cros_sdk --no-ns-pid` +1. Start servod. + * `$ sudo servod --board=<servod_board_name>` + * For some boards the servod board name is different than the EC codebase + board name used below! +1. Enter the chroot (for flash_ec). + * `$ cros_sdk` +1. Build the EC image for your board. + * `$ cd ~/trunk/src/platform/ec` + * `$ board=<board_name>` + * `$ make -j BOARD="$board"` +1. Run flash_ec from the util directory. + * `$ util/flash_ec --board="$board" --image=build/"$board"/ec.bin` ## CR50 CCD sans servod alternative {#ccd-sans-servod} -This section applies whether using CR50 CCD via [Servo v4](https://www.chromium.org/chromium-os/servo/servov4) or [SuzyQ aka SuzyQable](https://www.sparkfun.com/products/14746). - -When using CR50 CCD, it is possible to reflash without servod, which _must not_ be running when using this method. - -1. Enter the chroot. - * `$ cros_sdk` -1. Build the EC image for your board. - * `$ cd ~/trunk/src/platform/ec` - * `$ board=<board_name>` - * `$ make -j BOARD="$board"` -1. Run iteflash from the build/\<board\>/util directory. - * `$ build/"$board"/util/iteflash --i2c-interface=ccd --i2c-mux --send-waveform=1 --erase --write=build/"$board"/ec.bin` - -WARNING: The `--i2c-mux` flag is only required for some ITE EC boards. For boards without an I2C mux between CR50 and the EC, that flag _must not_ be specified. (This is handled for you when using `flash_ec` + `servod` because the latter has knowledge of which boards are expected to have the I2C mux.) +This section applies whether using CR50 CCD via +[Servo v4](https://www.chromium.org/chromium-os/servo/servov4) or +[SuzyQ aka SuzyQable](https://www.sparkfun.com/products/14746). + +When using CR50 CCD, it is possible to reflash without servod, which _must not_ +be running when using this method. + +1. Enter the chroot. + * `$ cros_sdk` +1. Build the EC image for your board. + * `$ cd ~/trunk/src/platform/ec` + * `$ board=<board_name>` + * `$ make -j BOARD="$board"` +1. Run iteflash from the build/\<board\>/util directory. + * `$ build/"$board"/util/iteflash --i2c-interface=ccd --i2c-mux + --send-waveform=1 --erase --write=build/"$board"/ec.bin` + +WARNING: The `--i2c-mux` flag is only required for some ITE EC boards. For +boards without an I2C mux between CR50 and the EC, that flag _must not_ be +specified. (This is handled for you when using `flash_ec` + `servod` because the +latter has knowledge of which boards are expected to have the I2C mux.) |