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>

17 files changed, 1301 insertions, 1 deletions

diff --git a/README.md b/README.md
index 5826343909..e3274487de 100644
--- a/README.md
+++ b/README.md
@@ -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.
 
diff --git a/docs/configuration/ap_power_sequencing.md b/docs/configuration/ap_power_sequencing.md
new file mode 100644
index 0000000000..2b78592e57
--- /dev/null
+++ b/docs/configuration/ap_power_sequencing.md
@@ -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
diff --git a/docs/configuration/cbi.md b/docs/configuration/cbi.md
new file mode 100644
index 0000000000..f285e8a8c2
--- /dev/null
+++ b/docs/configuration/cbi.md
@@ -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#
\ No newline at end of file
diff --git a/docs/configuration/config_ap_to_ec_comm.md b/docs/configuration/config_ap_to_ec_comm.md
new file mode 100644
index 0000000000..2fdcc5a147
--- /dev/null
+++ b/docs/configuration/config_ap_to_ec_comm.md
@@ -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
diff --git a/docs/configuration/ec_chipset.md b/docs/configuration/ec_chipset.md
new file mode 100644
index 0000000000..5f04c4d81e
--- /dev/null
+++ b/docs/configuration/ec_chipset.md
@@ -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
\ No newline at end of file
diff --git a/docs/configuration/gpio.md b/docs/configuration/gpio.md
new file mode 100644
index 0000000000..86fd21db6a
--- /dev/null
+++ b/docs/configuration/gpio.md
@@ -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
diff --git a/docs/configuration/i2c.md b/docs/configuration/i2c.md
new file mode 100644
index 0000000000..92bfe7ad0a
--- /dev/null
+++ b/docs/configuration/i2c.md
@@ -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
diff --git a/docs/configuration/keyboard.md b/docs/configuration/keyboard.md
new file mode 100644
index 0000000000..f2dc585e1b
--- /dev/null
+++ b/docs/configuration/keyboard.md
@@ -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`
diff --git a/docs/configuration/leds.md b/docs/configuration/leds.md
new file mode 100644
index 0000000000..72a548a306
--- /dev/null
+++ b/docs/configuration/leds.md
@@ -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
\ No newline at end of file
diff --git a/docs/configuration/motion_sensors.md b/docs/configuration/motion_sensors.md
new file mode 100644
index 0000000000..4dac939b10
--- /dev/null
+++ b/docs/configuration/motion_sensors.md
@@ -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
+
diff --git a/docs/configuration/template.md b/docs/configuration/template.md
new file mode 100644
index 0000000000..be4d2378a5
--- /dev/null
+++ b/docs/configuration/template.md
@@ -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
diff --git a/docs/images/alternate_example.png b/docs/images/alternate_example.png
new file mode 100644
index 0000000000..b2fcdb51e1
--- /dev/null
+++ b/docs/images/alternate_example.png
diff --git a/docs/images/gpio_example.png b/docs/images/gpio_example.png
new file mode 100644
index 0000000000..b2092b5e30
--- /dev/null
+++ b/docs/images/gpio_example.png
diff --git a/docs/images/gpio_int_example.png b/docs/images/gpio_int_example.png
new file mode 100644
index 0000000000..fe231e9b55
--- /dev/null
+++ b/docs/images/gpio_int_example.png
diff --git a/docs/images/i2c_example.png b/docs/images/i2c_example.png
new file mode 100644
index 0000000000..73ee880541
--- /dev/null
+++ b/docs/images/i2c_example.png
diff --git a/docs/new_board_checklist.md b/docs/new_board_checklist.md
new file mode 100644
index 0000000000..22e8d25988
--- /dev/null
+++ b/docs/new_board_checklist.md
@@ -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
\ No newline at end of file
diff --git a/docs/sitemap.md b/docs/sitemap.md
index f80b7501b0..387e1be5f0 100644
--- a/docs/sitemap.md
+++ b/docs/sitemap.md
@@ -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)