diff options
Diffstat (limited to 'docs/configuration')
| -rw-r--r-- | docs/configuration/ap_power_sequencing.md | 253 | ||||
| -rw-r--r-- | docs/configuration/cbi.md | 39 | ||||
| -rw-r--r-- | docs/configuration/config_ap_to_ec_comm.md | 73 | ||||
| -rw-r--r-- | docs/configuration/ec_chipset.md | 116 | ||||
| -rw-r--r-- | docs/configuration/gpio.md | 160 | ||||
| -rw-r--r-- | docs/configuration/i2c.md | 203 | ||||
| -rw-r--r-- | docs/configuration/keyboard.md | 87 | ||||
| -rw-r--r-- | docs/configuration/leds.md | 88 | ||||
| -rw-r--r-- | docs/configuration/motion_sensors.md | 50 | ||||
| -rw-r--r-- | docs/configuration/template.md | 51 |
10 files changed, 0 insertions, 1120 deletions
diff --git a/docs/configuration/ap_power_sequencing.md b/docs/configuration/ap_power_sequencing.md deleted file mode 100644 index c5073d5809..0000000000 --- a/docs/configuration/ap_power_sequencing.md +++ /dev/null @@ -1,253 +0,0 @@ -# Configure AP Power Sequencing - -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. - -## Config options - -The AP chipset options are grouped together in [config.h]. Select exactly one of -the available AP chipset options (e.g. `CONFIG_CHIPSET_APOLLOLAKE`, -`CONFIG_CHIPSET_BRASWELL`, etc). If the AP chipset support is not available, -select `CONFIG_CHIPSET_ECDRIVEN` to enable basic support for handling S3 and S0 -power states. - -After selecting the chipset, search for additional options that start with -`CONFIG_CHIPSET*` and evaluate whether each option is appropriate to add to -`baseboard.h` or `board.h`. - -Finally, evaluate the `CONFIG_POWER_` options for use on your board. In -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. - -## Feature Parameters - -None needed in this section. - -## GPIOs and Alternate Pins - -### EC Outputs to the board - -The board should connect the enable signal of one or more voltage rails to the -EC. These enable signals will vary based on the AP type, but are typically -active high signals. For Intel Ice Lake chipsets, this includes enable signals -for the primary 3.3V and primary 5V rails. - -```c -GPIO(EN_PP3300_A, PIN(A, 3), GPIO_OUT_LOW) -GPIO(EN_PP5000, PIN(A, 4), GPIO_OUT_LOW) -``` - -### EC Outputs to AP - -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. - -### Power Signal Interrupts - -For each power signal defined in the `power_signal_list[]` array, define a -`GPIO_INT()` entry that connects to the `power_signal_interrupt`. The interrupts -are configured to trigger on both rising edge and falling edge. - -The example below shows the power signals used with Ice Lake processors. - -```c -GPIO_INT(SLP_S0_L, PIN(D, 5), GPIO_INT_BOTH, power_signal_interrupt) -GPIO_INT(SLP_S3_L, PIN(A, 5), GPIO_INT_BOTH, power_signal_interrupt) -GPIO_INT(SLP_S4_L, PIN(D, 4), GPIO_INT_BOTH, power_signal_interrupt) -GPIO_INT(PG_EC_ALL_SYS_PWRGD, PIN(F, 4), GPIO_INT_BOTH, power_signal_interrupt) -GPIO_INT(PP5000_A_PG_OD, PIN(D, 7), GPIO_INT_BOTH, power_signal_interrupt) -``` - -See the [GPIO](./gpio.md) documentation for additional details on the GPIO -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. - -## Tasks - -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. - -```c - TASK_NOTEST(CHIPSET, chipset_task, NULL, LARGER_TASK_STACK_SIZE) \ -``` - -The `POWERBTN` and task should be enabled when using x86 based AP chipsets. The -typical priority is higher than the `CONSOLE` task, but lower than the `KEYSCAN` -task. - -```c - TASK_ALWAYS(POWERBTN, power_button_task, NULL, LARGER_TASK_STACK_SIZE) \ -``` - -## Testing and Debugging - -During the first power on of prototype devices, it is recommended to enable -`CONFIG_BRINGUP`. This option prevents the EC from automatically powering on the -AP. You can use the EC console commands `gpioget` and `gpioset` to manually -check power good signals and enable power rails in a controlled manner. This -option also enables extra debug to log all power signal transitions to the EC -console. With `CONFIG_BRINGUP` enabled, you can trigger the automatic power -sequencing by running the `powerbtn` from the EC console. - -The EC console displays the following text when `CONFIG_BRINGUP` is enabled: - -``` -WARNING: BRINGUP BUILD -``` - -Once you manually press the power button, or execute the `powerbtn` command, the -EC console displays both the power state changes and the detected transitions of -all power signals. An example is shown below. - -``` -> powerbtn -Simulating 200 ms power button press. -[6.790816 power button pressed] -[6.791133 PB pressed] -[6.791410 PB task 1 = pressed] -[6.791755 PB PCH pwrbtn=LOW] -[6.792049 PB task 10 = was-off, wait 199362] -RTC: 0x000067bc (26556.00 s) -[6.792786 power state 5 = G3->S5, in 0x0000] -[6.793190 Set EN_PP3300_A: 1] -[6.793905 SW 0x03] -[6.817627 Set PCH_DSW_PWROK: 1] -[6.818007 Pass thru GPIO_DSW_PWROK: 1] -[6.818351 Set EN_PP5000_A: 1] -RTC: 0x000067bc (26556.00 s) -[6.903830 power state 1 = S5, in 0x0029] -[6.918735 Pass through GPIO_RSMRST_L_PGOOD: 1] -i2c 7 recovery! error code is 13, current state is 0 -Simulating power button release. -> [6.991576 power button released] -[6.992009 PB task 10 = was-off] -[6.992376 PB released] -[6.992635 PB task 6 = released] -[6.992958 PB PCH pwrbtn=HIGH] -[6.993256 PB task 0 = idle, wait -1] -[6.993806 PB released] -[6.994149 PB task 6 = released] -[6.994512 PB PCH pwrbtn=HIGH] -[6.994812 PB task 0 = idle, wait -1] -[6.995768 SW 0x01] -3 signal changes: - 6.807298 +0.000000 DSW_PWROK => 1 - 6.903417 +0.096119 SLP_SUS_L => 1 - 6.908471 +0.005054 PG_EC_RSMRST_ODL => 1 -1 signal changes: - 7.909941 +0.000000 SLP_S0_L => 1 -[9.026429 Fan 0 stalled!] -RTC: 0x000067bf (26559.00 s) -[9.124643 power state 6 = S5->S3, in 0x003f] -i2c 3 recovery! error code is 13, current state is 0 -[9.126543 mux config:2, port:1, res:1] -[9.127109 PD:S5->S3] -RTC: 0x000067bf (26559.00 s) -[9.127985 power state 2 = S3, in 0x003f] -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. - -The console messages shown in brackets `[]` include a timestamp. This timestamp -records when the corresponding console message was printed. - -The power signal changes are preceded by the message `<N> signal changes:`. -Power signal changes are recorded at interrupt priority into a special buffer -and are not displayed in real time. Instead, printing of the buffer is deferred -until the EC is no longer executing at interrupt priority. This causes the power -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, -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 -following: - -``` -> powerb -Simulating 200 ms power button press. -[6.790816 power button pressed] -[6.791133 PB pressed] -[6.791410 PB task 1 = pressed] -[6.791755 PB PCH pwrbtn=LOW] -[6.792049 PB task 10 = was-off, wait 199362] -RTC: 0x000067bc (26556.00 s) -[6.792786 power state 5 = G3->S5, in 0x0000] -[6.793190 Set EN_PP3300_A: 1] -[6.793905 SW 0x03] - 6.807298 +0.000000 DSW_PWROK => 1 // Manually re-ordered entry -[6.817627 Set PCH_DSW_PWROK: 1] -[6.818007 Pass thru GPIO_DSW_PWROK: 1] -[6.818351 Set EN_PP5000_A: 1] -RTC: 0x000067bc (26556.00 s) - 6.903417 +0.096119 SLP_SUS_L => 1 // Manually re-ordered entry -[6.903830 power state 1 = S5, in 0x0029] - 6.908471 +0.005054 PG_EC_RSMRST_ODL => 1 // Manually re-ordered entry -[6.918735 Pass through GPIO_RSMRST_L_PGOOD: 1] -i2c 7 recovery! error code is 13, current state is 0 -Simulating power button release. -> [6.991576 power button released] -[6.992009 PB task 10 = was-off] -[6.992376 PB released] -[6.992635 PB task 6 = released] -[6.992958 PB PCH pwrbtn=HIGH] -[6.993256 PB task 0 = idle, wait -1] -[6.993806 PB released] -[6.994149 PB task 6 = released] -[6.994512 PB PCH pwrbtn=HIGH] -[6.994812 PB task 0 = idle, wait -1] -[6.995768 SW 0x01] -1 signal changes: - 7.909941 +0.000000 SLP_S0_L => 1 -[9.026429 Fan 0 stalled!] -RTC: 0x000067bf (26559.00 s) -[9.124643 power state 6 = S5->S3, in 0x003f] -i2c 3 recovery! error code is 13, current state is 0 -[9.126543 mux config:2, port:1, res:1] -[9.127109 PD:S5->S3] -RTC: 0x000067bf (26559.00 s) -[9.127985 power state 2 = S3, in 0x003f] -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.* - -[config.h]: ../new_board_checklist.md#config_h diff --git a/docs/configuration/cbi.md b/docs/configuration/cbi.md deleted file mode 100644 index f89ee78454..0000000000 --- a/docs/configuration/cbi.md +++ /dev/null @@ -1,39 +0,0 @@ -# Configure CrOS Board Information (CBI) - -If your board includes an EEPROM to store [CBI], then this feature must be -enabled and configured. Note that the [I2C buses] must be configured and working -before enabling CBI. - -## Config options - -Add the following config options to `baseboard.h` or `board.h`. - -- `CONFIG_BOARD_VERSION_CBI` -- `CONFIG_CBI_EEPROM` - -## Feature Parameters - -- `I2C_ADDR_EEPROM_FLAGS <7-bit addr>` - Defines the 7-bit slave address for - the EEPROM containing CBI. - -## GPIOs and Alternate Pins - -None needed - the I2C pins should be configured automatically when initializing -the I2C buses. - -## Data Structures - -None required by this feature. - -## Tasks - -None required by this feature. - -## Testing and Debugging - -Refer to the [I2C debugging information] to verify communication with the CBI -EEPROM. - -[CBI]: https://chromium.googlesource.com/chromiumos/docs/+/HEAD/design_docs/cros_board_info.md -[I2C buses]: ./i2c.md -[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 deleted file mode 100644 index 24b309feb7..0000000000 --- a/docs/configuration/config_ap_to_ec_comm.md +++ /dev/null @@ -1,73 +0,0 @@ -# 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 -details a system level of the operation of this feature. - -## Config options - -Configure the AP to EC communication channel, picking exactly one of the -following options. - -- `CONFIG_HOSTCMD_SHI` - [SPI Host Interface](../ec_terms.md#shi) (SHI) -- `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. - -## Feature Parameters - -None needed in this section. - -## GPIOs and Alternate Pins - -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. - - ```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. - - ```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. - -## Data structures - -None needed in this section. - -## Tasks - -The `HOSTCMD` task is responsible for processing commands sent by the AP and is -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) \ -``` - -## 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. - -[./chip/npcx/registers.h]: ../../chip/npcx/registers.h -[AP to EC Communication]: ../ap-ec-comm.md -[config.h]: ../new_board_checklist.md#config_h diff --git a/docs/configuration/ec_chipset.md b/docs/configuration/ec_chipset.md deleted file mode 100644 index defc27eec8..0000000000 --- a/docs/configuration/ec_chipset.md +++ /dev/null @@ -1,116 +0,0 @@ -# Configure EC Chipset - -## Config options - -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 - 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 - 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 - 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 - flash. - -## GPIOs and Alternate Pins - -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. - -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. - -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 -under the Deep Sleep and Shipping states and include: - -- Power button -- AC insert -- Lid open - -## Tasks - -None required by this feature. - -## Testing and Debugging - -## Example - -For the Volteer reference board, the following wake sources are defined in -[gpio.inc]. Note that configuration of `GPIO(EC_RST_ODL)` is located after all -`GPIO_INT()` entries required by the board. - -```c -/* Wake Source interrupts */ -GPIO_INT(EC_LID_OPEN, PIN(D, 2), GPIO_INT_BOTH | GPIO_HIB_WAKE_HIGH, lid_interrupt) -GPIO_INT(EC_WP_L, PIN(A, 1), GPIO_INT_BOTH, switch_interrupt) -GPIO_INT(H1_EC_PWR_BTN_ODL, PIN(0, 1), GPIO_INT_BOTH, power_button_interrupt) -GPIO_INT(ACOK_OD, PIN(0, 0), GPIO_INT_BOTH | GPIO_HIB_WAKE_HIGH, extpower_interrupt) - -/* EC_RST_ODL - PSL input but must be locked */ -GPIO(EC_RST_ODL, PIN(0, 2), GPIO_INT_BOTH | GPIO_HIB_WAKE_HIGH | GPIO_LOCKED) -``` - -For the NPCx7 chipset, the alternate function must also be configured to connect -the wakeup pins to the PSL (power switch logic). - -```c -/* GPIOD2 = EC_LID_OPEN */ -ALTERNATE(PIN_MASK(D, BIT(2)), 0, MODULE_PMU, 0) -/* GPIO00 = ACOK_OD, - GPIO01 = H1_EC_PWR_BTN_ODL - GPIO02 = EC_RST_ODL */ -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: - -```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, -}; -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 diff --git a/docs/configuration/gpio.md b/docs/configuration/gpio.md deleted file mode 100644 index f4a5c4719a..0000000000 --- a/docs/configuration/gpio.md +++ /dev/null @@ -1,160 +0,0 @@ -# GPIO Configuration - -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 - -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. - -## `GPIO()` macro - -### Prototype - -`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). - -### Example - -![GPIO Example] - -```c -GPIO(EC_ENTERING_RW, PIN(E, 3), GPIO_OUT_LOW) -``` - -The EC common code requires the enum `GPIO_ENTERING_RW` to be defined, so you -should also map the net name to the EC name in the `board.h` file. - -```c -#define GPIO_ENTERING_RW GPIO_EC_ENTERING_RW -``` - -## `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. - -### Example - -![GPIO_INT Example] - -```c -GPIO_INT(EC_LID_OPEN, PIN(D, 2), GPIO_INT_BOTH | GPIO_HIB_WAKE_HIGH, lid_interrupt) -``` - -The EC common code requires the enum `GPIO_LID_OPEN` to be defined, so you als -need to map the net name to the EC name in the `board.h` file. - -```c -#define GPIO_LID_OPEN GPIO_EC_LID_OPEN -``` - -## `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. - -### 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`. - -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 -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 -driver the I2C SCL and SDA signals to known states, without interference by the -I2C controller in the EC chipset. - -The general recipe for overriding alternate functions is shown below. - -```c - /* Disconnect I2C1_SDA pin from I2C controller */ - gpio_config_pin(MODULE_I2C, GPIO_I2C1_SDA, 0); - - /* Setup I2C1_SDA as an GPIO open drain output and drive initial state low */ - gpio_set_flags(GPIO_I2C1_SDA, GPIO_ODR_LOW); - - /* Set GPIO high (or low) as required */ - gpio_set_level (GPIO_I2C1_SDA, 1); - - /* Restore I2C1_SDA pin to I2C function */' - gpio_config_pin(MODULE_I2C, GPIO_I2C1_SDA, 1); -``` - -### Example - -![ALTERNATE Example] - -```c -ALTERNATE(PIN_MASK(B, BIT(4) | BIT(5)), 0, MODULE_I2C, (GPIO_INPUT | GPIO_SEL_1P8V)) -``` - -<!-- Images --> - -<!-- If you make changes to the docs below make sure to regenerate the PNGs by - 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 deleted file mode 100644 index 36464bb371..0000000000 --- a/docs/configuration/i2c.md +++ /dev/null @@ -1,203 +0,0 @@ -# Configure I2C Buses - -## Config options - -The I2C options are prefixed with `CONFIG_I2C*`. Evaluate whether each option is -appropriate to add to your board. - -A typical EC and board should at a minimum set `CONFIG_I2C` and -`CONFIG_I2C_CONTROLLER`. - -## Feature Parameters - -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. - -## GPIOs and Alternate Pins - -In the gpio.inc file, you need to define a GPIO for the clock (SCL) and data -(SDA) pin used on each active I2C bus. The corresponding GPIOs are then included -in the `i2c_ports[]` array. This permits the I2C library to perform common bus -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 -I2C functionality. - -Note that many I2C buses only support 1.8V operation. This is determined by I2C -devices connected to the bus. In this case you need to include `GPIO_SEL_1P8V` -as part of the `flags` field in both the `GPIO()` and `ALTERNATE()` macros. I2C -bus 0 in the example below demonstrates configuring the SCL and SDA pins for -1.8V operation. - -See the [GPIO](./gpio.md) documentation for additional details on the GPIO -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. - -## Tasks - -None required by this feature. - -## Testing and Debugging - -### 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. - -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 - -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. - -```c -/* I2C pins - Alternate function below configures I2C module on these pins */ -GPIO(EC_I2C0_SENSOR_SCL, PIN(B, 5), GPIO_INPUT | GPIO_SEL_1P8V) -GPIO(EC_I2C0_SENSOR_SDA, PIN(B, 4), GPIO_INPUT | GPIO_SEL_1P8V) -GPIO(EC_I2C1_USB_C0_SCL, PIN(9, 0), GPIO_INPUT) -GPIO(EC_I2C1_USB_C0_SDA, PIN(8, 7), GPIO_INPUT) -GPIO(EC_I2C2_USB_C1_SCL, PIN(9, 2), GPIO_INPUT) -GPIO(EC_I2C2_USB_C1_SDA, PIN(9, 1), GPIO_INPUT) -GPIO(EC_I2C3_USB_1_MIX_SCL, PIN(D, 1), GPIO_INPUT) -GPIO(EC_I2C3_USB_1_MIX_SDA, PIN(D, 0), GPIO_INPUT) -GPIO(EC_I2C5_POWER_SCL, PIN(3, 3), GPIO_INPUT) -GPIO(EC_I2C5_POWER_SDA, PIN(3, 6), GPIO_INPUT) -GPIO(EC_I2C7_EEPROM_SCL, PIN(B, 3), GPIO_INPUT) -GPIO(EC_I2C7_EEPROM_SDA, PIN(B, 2), GPIO_INPUT) - -/* Alternate functions GPIO definitions */ -ALTERNATE(PIN_MASK(B, BIT(5) | BIT(4)), 0, MODULE_I2C, (GPIO_INPUT | GPIO_SEL_1P8V)) /* I2C0 */ -ALTERNATE(PIN_MASK(9, BIT(0) | BIT(2) | BIT(1)), 0, MODULE_I2C, 0) /* I2C1 SCL / I2C2 */ -ALTERNATE(PIN_MASK(8, BIT(7)), 0, MODULE_I2C, 0) /* I2C1 SDA */ -ALTERNATE(PIN_MASK(D, BIT(1) | BIT(0)), 0, MODULE_I2C, 0) /* I2C3 */ -ALTERNATE(PIN_MASK(3, BIT(3) | BIT(6)), 0, MODULE_I2C, 0) /* I2C5 */ -ALTERNATE(PIN_MASK(B, BIT(3) | BIT(2)), 0, MODULE_I2C, 0) /* I2C7 */ -``` - -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. - -```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 -``` - -The last piece for I2C configuration is to create the `i2c_ports[]` array using -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, - }, -}; -const unsigned int i2c_ports_used = ARRAY_SIZE(i2c_ports); -``` - -The `.flags` field is optional when using the default I2C bus setup. See -[./include/i2c.h] for the full list of supported flags. - -The flag `I2C_PORT_FLAG_DYNAMIC_SPEED` allows the I2C bus frequency to be -changed at runtime. The typical use case is to set the I2C bus frequency to -different speeds based on the BOARD_VERSION in [CBI]. For example board version -1 supports 100 kbps operation but board version 2 and greater supports 400 kbps -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. - -```c -static void board_i2c_init(void) -{ - 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 -[I2C Example]: ../images/i2c_example.png -[CBI]: https://chromium.googlesource.com/chromiumos/docs/+/HEAD/design_docs/cros_board_info.md diff --git a/docs/configuration/keyboard.md b/docs/configuration/keyboard.md deleted file mode 100644 index 8398fefbde..0000000000 --- a/docs/configuration/keyboard.md +++ /dev/null @@ -1,87 +0,0 @@ -## Configure Keyboard - -## Config options - -Keyboard options start with `CONFIG_KEYBOARD*`. Evaluate whether each option is -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. - -## Feature Parameters - -- `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. - -```c -/* Example Keyboard pin setup */ -#define GPIO_KB_INPUT (GPIO_INPUT | GPIO_PULL_UP) -ALTERNATE(PIN_MASK(3, 0x03), 0, MODULE_KEYBOARD_SCAN, GPIO_KB_INPUT) /* KSI_00-01 */ -ALTERNATE(PIN_MASK(2, 0xFC), 0, MODULE_KEYBOARD_SCAN, GPIO_KB_INPUT) /* KSI_02-07 */ -ALTERNATE(PIN_MASK(2, 0x03), 0, MODULE_KEYBOARD_SCAN, GPIO_ODR_HIGH) /* KSO_00-01 */ -ALTERNATE(PIN_MASK(1, 0x7F), 0, MODULE_KEYBOARD_SCAN, GPIO_ODR_HIGH) /* KSO_03-09 */ -ALTERNATE(PIN_MASK(0, 0xF0), 0, MODULE_KEYBOARD_SCAN, GPIO_ODR_HIGH) /* KSO_10-13 */ -ALTERNATE(PIN_MASK(8, 0x04), 0, MODULE_KEYBOARD_SCAN, GPIO_ODR_HIGH) /* KSO_14 */ -``` - -See the [GPIO](./gpio.md) documentation for additional details on the GPIO -macros. - -## Data structures - -- `struct keyboard_scan_config keyscan_config` - This can be used to customize - the keyboard scanner (e.g. scan frequency, debounce duration, etc.). - -## Tasks - -The `KEYSCAN` task monitors the keyboard matrix for new key presses and is -required by this feature. The priority is set as one of the highest priority -tasks in the system, typically only below the `PD_Cn` and `PD_INT_Cn` tasks. - -```c - TASK_NOTEST(KEYSCAN, keyboard_scan_task, NULL, TASK_STACK_SIZE) \ -``` - -The `KEYPROTO` task handles sending and receiving 8042 protocol messages from -the AP and is required when `CONFIG_KEYBOARD_PROTOCOL_8042` is used. The typical -priority is lower than the `HOSTCMD` task. - -```c - TASK_NOTEST(KEYPROTO, keyboard_protocol_task, NULL, TASK_STACK_SIZE) \ -``` - -## 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. - -### 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` diff --git a/docs/configuration/leds.md b/docs/configuration/leds.md deleted file mode 100644 index c4fe7894af..0000000000 --- a/docs/configuration/leds.md +++ /dev/null @@ -1,88 +0,0 @@ -# Configure LEDs - -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 - -LEDs can be configured as simple GPIOs, with on/off control only, or as PWM with -adjustment brightness and color. - -## Config options - -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. - -## Feature Parameters - -- `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>` - -## GPIOs and Alternate Pins - -For GPIO based LEDs, create `GPIO()` entries for all signals that connect to -platform LEDs. The default state of the pins should be set so that the LED is -off (typically high output). - -For PWM LEDs, configure the `ALTERNATE()` macro, setting the module type to -`MODULE_PWM`. - -## 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. - -See the [GPIO](./gpio.md) documentation for additional details on the GPIO -macros. - -## Tasks - -None required by this feature. - -## Testing and Debugging - -### 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. - -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. - -## LED Driver Chips - -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 diff --git a/docs/configuration/motion_sensors.md b/docs/configuration/motion_sensors.md deleted file mode 100644 index 6e84fc3307..0000000000 --- a/docs/configuration/motion_sensors.md +++ /dev/null @@ -1,50 +0,0 @@ -# Configure Motion Sensors - -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. - -*TODO* - there is good content available in the most recent [Chrome EC] overview -presentation that can be added here. - -## Config options - -*TODO* - -## Feature Parameters - -*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. - -## Data Structures - -*TODO* - -## Tasks - -*TODO* - -## Testing and Debugging - -*TODO* - -### Console Commands - -*TODO* - -## Example - -*TODO* - -[Chrome EC]: https://docs.google.com/presentation/d/1Y3PwNSnCQoCqDfL5rYqfaBP_ZqbMOTw_x83_ry4cro8/view#slide=id.g63bdbcea4b_0_27 diff --git a/docs/configuration/template.md b/docs/configuration/template.md deleted file mode 100644 index be4d2378a5..0000000000 --- a/docs/configuration/template.md +++ /dev/null @@ -1,51 +0,0 @@ -# EC Feature Configuration Template - -*Short description of the EC feature and the capabilities provided* - -## Config options - -In [config.h], search for options that start with `CONFIG_<feature>*` and -evaluate whether each option is appropriate to add to `baseboard.h` or -`board.h`. - -*Note - Avoid documenting `CONFIG_` options in the markdown as `config.h` -contains the authoritative definition.* - -## Feature Parameters - -*Detail `CONFIG_*` options that must be assigned to a value for this EC feature -to compile and operate.* - -## GPIOs and Alternate Pins - -*Document any hard-coded GPIO enumeration names required by the EC feature.* - -*For pins that require an alternate function, note the module required by the EC -feature.* - -## Data Structures - -*Document any data structures that must be defined in the board.c or baseboard.c -files in order for the EC feature to compile and operate.* - -*Document any functions that must be implemented in the board.c and baseboard.c -files.* - -## Tasks - -*Document any EC tasks that must be enabled by the feature.* - -## Testing and Debugging - -*Provide any tips for testing and debugging the EC feature.* - -### Console Commands - -*Document an EC console commands related to the feature.* - -## Example - -*Optional - provide code snippets from a working board to walk the user through -all code that must be created to enable this feature.* - -[config.h]: ../new_board_checklist.md#config_h |