# 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/+/HEAD/contrib/variant/README.md
[new_variant.py]:https://chromium.googlesource.com/chromiumos/platform/dev-util/+/HEAD/contrib/variant/new_variant.py
[create_initial_ec_image.sh]:https://chromium.googlesource.com/chromiumos/platform/dev-util/+/HEAD/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
