diff options
Diffstat (limited to 'docs/configuration')
| -rw-r--r-- | docs/configuration/ap_power_sequencing.md | 56 | ||||
| -rw-r--r-- | docs/configuration/cbi.md | 13 | ||||
| -rw-r--r-- | docs/configuration/config_ap_to_ec_comm.md | 42 | ||||
| -rw-r--r-- | docs/configuration/ec_chipset.md | 73 | ||||
| -rw-r--r-- | docs/configuration/gpio.md | 99 | ||||
| -rw-r--r-- | docs/configuration/i2c.md | 165 | ||||
| -rw-r--r-- | docs/configuration/keyboard.md | 54 | ||||
| -rw-r--r-- | docs/configuration/leds.md | 76 | ||||
| -rw-r--r-- | docs/configuration/motion_sensors.md | 18 |
9 files changed, 297 insertions, 299 deletions
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 - |