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 and focus on known board changes.
Before you get started, it's important to understand the role of a few key files in the EC codebase.
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.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.
/* 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 documentation for additional details on the GPIO macros.
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 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.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 4096GPIO_INT(), GPIO(), ALTERNATE(), and UNIMPLEMENTED() definitions to gpio.inc, making sure to follow the GPIO naming conventions.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.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.
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.
After submitting the skeleton builds, review the following sections and add each feature set as required by your design.
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.
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 documentation for details.