coreboot-mirror
/
chrome-ec
mirror of https://review.coreboot.org/chrome-ec.git
1
0
Fork 0
Code Issues Releases Wiki Activity

doc: Add creating a new board checklist. 

Add the high-level steps for creating a new board in the EC code base.
The entry point is the docs/new_board_checklist.md file, which then
links to files found under docs/configuration/.

BUG=b:147905484
BRANCH=none
TEST=none

Change-Id: Ia0ca4f6547735a5d1ee93145ee18962cf7559fe3
Signed-off-by: Keith Short <keithshort@chromium.org>
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/1778635
Reviewed-by: Jett Rink <jettrink@chromium.org>
Reviewed-by: Paul Fagerburg <pfagerburg@chromium.org>
This commit is contained in:
Keith Short 2019-08-20 16:50:13 -06:00 committed by Commit Bot
parent c2f751f107
commit f634e7c0cc
17 changed files with 1301 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
README.md
View File

@ -61,7 +61,7 @@ Chromium OS development environment to build a binary.
git clone https://chromium.googlesource.com/chromiumos/platform/ec
```
The source code can also be broswed on the web at:
The source code can also be browsed on the web at:
https://chromium.googlesource.com/chromiumos/platform/ec/
@ -70,6 +70,9 @@ https://chromium.googlesource.com/chromiumos/platform/ec/
The following is a quick overview of the top-level directories in the EC
repository:
**baseboard** - Code and configuration details shared by a collection of board
variants. Tightly linked with the `board` directory described below.
**board** - Board specific code and configuration details. This includes the
GPIO map, battery parameters, and set of tasks to run for the device.

253
docs/configuration/ap_power_sequencing.md Normal file
View File

@ -0,0 +1,253 @@
# 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

38
docs/configuration/cbi.md Normal file
View File

@ -0,0 +1,38 @@
# 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_CROS_BOARD_INFO`
## 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/+/master/design_docs/cros_board_info.md
[I2C buses]: ./i2c.md
[I2C debugging information]: ./i2c.md#

73
docs/configuration/config_ap_to_ec_comm.md Normal file
View File

@ -0,0 +1,73 @@
# 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_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.
## 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

113
docs/configuration/ec_chipset.md Normal file
View File

@ -0,0 +1,113 @@
# 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>` - 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

155
docs/configuration/gpio.md Normal file
View File

@ -0,0 +1,155 @@
# 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 dummy 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

204
docs/configuration/i2c.md Normal file
View File

@ -0,0 +1,204 @@
# 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_MASTER`.
## 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_READ_SIZE <bytes>`
- `CONFIG_I2C_NACK_RETRY_COUNT <count>`
- `CONFIG_I2C_EXTRA_PACKET_SIZE <bytes>` - Only used on STM32 EC's if
`CONFIG_HOSTCMD_I2C_SLAVE_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/+/master/design_docs/cros_board_info.md

91
docs/configuration/keyboard.md Normal file
View File

@ -0,0 +1,91 @@
## 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 must be defined if the
`CONFIG_KEYBOARD_BOARD_CONFIG` option is defined.
## 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`

92
docs/configuration/leds.md Normal file
View File

@ -0,0 +1,92 @@
# 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

52
docs/configuration/motion_sensors.md Normal file
View File

@ -0,0 +1,52 @@
# 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

51
docs/configuration/template.md Normal file
View File

@ -0,0 +1,51 @@
# 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

BIN
docs/images/alternate_example.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 35 KiB

BIN
docs/images/gpio_example.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 33 KiB

BIN
docs/images/gpio_int_example.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 30 KiB

BIN
docs/images/i2c_example.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 62 KiB

172
docs/new_board_checklist.md Normal file
View File

@ -0,0 +1,172 @@
# Creating a new EC board
[TOC]
## Overview
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.
## 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].
### 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
often do not match these names exactly. When this occurs, best practice is that
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
name of this signal is EC_RST_ODL and the signal connects to the EC chipset pin
GPIO02.
```c
/* From gpio.inc */
GPIO(EC_RST_ODL, PIN(0, 2), GPIO_ODR_HIGH)
/* From board.h */
/* Map the schematic net name to the required EC name */
#define GPIO_SYS_RESET_L GPIO_EC_RST_ODL
```
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
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.
## Create the new EC board
The first step when creating a new EC board, is to create the required files in
the `./baseboard` and `./board` directories. When adding a new board for an
existing baseboard family, use the python script [new_variant.py] to
automatically copy the `./board` directory from an existing EC board to get you
started. The [new_variant.py] script performs additional operations not directly
related to the EC code, including copying coreboot files and modifying the yaml
files. If you want to copy the EC board files only, you can directly call the
[create_initial_ec_image.sh] script. The instructions for running this script
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).
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
for review.
### Creating a new reference board
If you are creating a new reference board, it is recommended that you manually
create new directories under the `./baseboard` and `./board` directories and
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]
After submitting the skeleton builds, review the following sections and add each
feature set as required by your design.
## Configure EC Features
The checklist below provides an overview of EC features that must be configured
for correct operation of a Chromebook. The "Needed for Power On" column
indicates which features are critical for board bringup. These features take
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 |
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
board. Refer to the [GPIO](./configuration/gpio.md) documentation for details.
[README.md]:https://chromium.googlesource.com/chromiumos/platform/dev-util/+/master/contrib/variant/README.md
[new_variant.py]:https://chromium.googlesource.com/chromiumos/platform/dev-util/+/master/contrib/variant/new_variant.py
[create_initial_ec_image.sh]:https://chromium.googlesource.com/chromiumos/platform/dev-util/+/master/contrib/variant/create_initial_ec_image.sh
[Volteer EC skeleton build]:https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/1758532
[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

3
docs/sitemap.md
View File

@ -7,6 +7,9 @@
* [Write Protection](./write_protection.md)
* [EC Acronyms and Technologies](./ec_terms.md)
## EC Bringup
* [New Board Checklist](./new_board_checklist.md)
## Case Closed Debugging (CCD)
* [Case Closed Debugging Overview](./case_closed_debugging.md)