1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
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
|
