coreboot-mirror/chrome-ec
1
0
Fork 0
mirror of https://review.coreboot.org/chrome-ec.git synced 2024-09-09 14:22:41 +02:00
Code Issues Releases Wiki Activity

docs: point md files in master to main/HEAD

Browse source 
Master md files are out of date. Point to main branch in case someone
lands in master branch from an old link.

BUG=b:180952272,b:180921286
BRANCH=None
TEST=Preview changes with gerrit

Exempt-From-Owner-Approval: fixing docs
Change-Id: I6583b6c7fc21248eb49a6cd71e077fbdb5de2435
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/2727846
Reviewed-by: Sean Abraham <seanabraham@chromium.org>
Reviewed-by: Rob Barnes <robbarnes@google.com>
Auto-Submit: Sean Abraham <seanabraham@chromium.org>
Tested-by: Sean Abraham <seanabraham@chromium.org>
This commit is contained in:
Sean Abraham 2021-03-01 15:13:48 -07:00
parent ef6a915de0
commit 1e800ac838
57 changed files with 219 additions and 10061 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
.vscode/README.md vendored
View file

@ -1,3 +1,5 @@
# VSCode Setting
*** note
**Warning: This document is old & has moved. Please update any links:**<br>
https://chromium.googlesource.com/chromiumos/platform/ec/+/HEAD/.vscode/README.md
***
See [docs/ide-support.md](/docs/ide-support.md).

645
README.md
View file

@ -1,642 +1,5 @@
# Embedded Controller (EC)
*** note
**Warning: This document is old & has moved. Please update any links:**<br>
https://chromium.googlesource.com/chromiumos/platform/ec/+/HEAD/README.md
***
[TOC]
## Introduction
The Chromium OS project includes open source software for embedded controllers
(EC) used in recent ARM and x86 based Chromebooks. This software includes a
lightweight, multitasking OS with modules for power sequencing, keyboard
control, thermal control, battery charging, and verified boot. The EC software
is written in C and supports [a variety of micro-controllers](https://chromium.googlesource.com/chromiumos/platform/ec/+/master/chip/).
This document is a guide to help make you familiar with the EC code, current
features, and the process for submitting code patches.
For more see the Chrome OS Embedded Controller
[presentation](https://docs.google.com/presentation/d/1Xa_Z6SjW-soPvkugAR8__TEJFrJpzoZUa9HNR14Sjs8/pub?start=false&loop=false&delayms=3000)
and [video](http://youtu.be/Ie7LRGgCXC8) from the
[2014 Firmware Summit](http://dev.chromium.org/chromium-os/2014-firmware-summit).
## What you will need
1. A Chromebook with a compatible EC. This includes the Samsung Chromebook
(XE303C12) and all Chromebooks shipped after the Chromebook Pixel 2013
(inclusive). See the
[Chrome OS devices](http://dev.chromium.org/chromium-os/developer-information-for-chrome-os-devices)
page for a list.
1. A Linux development environment. Ubuntu 14.04 Trusty (x86_64) is well
supported. Linux in a VM may work if you have a powerful host machine.
1. A [servo debug board](http://dev.chromium.org/chromium-os/servo) (and
header) is highly recommended for serial console and JTAG access to the EC.
1. A sense of adventure!
## Terminology
### EC
EC (aka Embedded Controller) can refer to many things in the Chrome OS
documentation due to historical reasons. If you just see the term "EC", it
probably refers to "the" EC (i.e. the first one that existed). Most Chrome OS
devices have an MCU, known as "the EC" that controls lots of things (key
presses, turning the AP on/off). The OS that was written for "the" EC is now
running on several different MCUs on Chrome OS devices with various tweaks
(e.g. the FPMCU, the touchpad one that can do palm rejection, etc.). It's quite
confusing, so try to be specific and use terms like FPMCU to distinguish the
fingerprint MCU from "the EC".
See the [EC Acronyms and Technologies](./docs/ec_terms.md) for a more complete
glossary.
## Getting the EC code
The code for the EC is open source and is included in the Chromium OS
development environment (`~/trunk/src/platform/ec/</code>`).
See[ http://www.chromium.org/chromium-os/quick-start-guide](http://dev.chromium.org/chromium-os/quick-start-guide)
for build setup instructions. If you want instant gratification, you can fetch
the source code directly. However, you will need the tool-chain provided by the
Chromium OS development environment to build a binary.
```bash
git clone https://chromium.googlesource.com/chromiumos/platform/ec
```
The source code can also be browsed on the web at:
https://chromium.googlesource.com/chromiumos/platform/ec/
## Code Overview
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.
**build** - Build artifacts are generated here. Be sure to delete this and
rebuild when switching branches and before "emerging" (see Building an EC binary
below). make clobber is a convenient way to clean up before building.
**chip** - IC specific code for interfacing with registers and hardware blocks
(adc, jtag, pwm, uart etc…)
**core** - Lower level code for task and memory management.
**common** - A mix of upper-level code that is shared across boards. This
includes the charge state machine, fan control, and the keyboard driver (among
other things).
**driver** - Low-level drivers for light sensors, charge controllers,
I2C/onewire LED controllers, and I2C temperature sensors.
**include** - Header files for core and common code.
**util** - Host utilities and scripts for flashing the EC. Also includes
“ectool” used to query and send commands to the EC from userspace.
**test** - Unit tests for EC components. These can be run locally in
a mock "host" environment or compiled for a target board.
If building for a target board, the test must be flashed and
run manually on the device.
All unit tests and fuzzers are build/run using the local
host environment during a `buildall`.
To run all unit tests locally, run `make runhosttests -j`.
To build a specific unit test for a specific board, run
`make test-<test_name> BOARD=<board_name>`.
Please contribute new tests if writing new functionality.
Please run `make help` for more detail.
**fuzz** - Fuzzers for EC components. These fuzzers are expected to
run in the mock host environment. They follow the same rules
as unit tests, as thus use the same commands to build and run.
## Firmware Branches
Each Chrome device has a firmware branch created when the read-only firmware is
locked down prior to launch. This is done so that updates can be made to the
read-write firmware with a minimal set of changes from the read-only. Some
Chrome devices only have build targets on firmware branches and not on
cros/master. Run “`git branch -a | grep firmware`” to locate the firmware branch
for your board. Note that for devices still under development, the board
configuration may be on the branch for the platform reference board.
To build EC firmware on a branch, just check it out and build it:
```bash
git checkout cros/firmware-falco_peppy-4389.B
```
To make changes on a branch without creating a whole new development environment
(chroot), create a local tracking branch:
```bash
git branch --track firmware-falco_peppy-4389.B cros/firmware-falco_peppy-4389.B
git checkout firmware-falco_peppy-4389.B
make clobber
# <make changes, test, and commit them>
repo upload --cbr .
# (The --cbr means "upload to the current branch")
```
Here is a useful command to see commit differences between branches (change the
branch1...branch2 as needed):
```bash
git log --left-right --graph --cherry-pick --oneline branch1...branch2
```
For example, to see the difference between cros/master and the HEAD of the
current branch:
```bash
git log --left-right --graph --cherry-pick --oneline cros/master...HEAD
# Note: Use three dots “...” or it won’t work!
```
## Building an EC binary
Note: The EC is normally built from within the Chromium OS development chroot to
use the correct toolchain.
Building directly from the EC repository:
```bash
cros_sdk
cd ~/trunk/src/platform/ec
make -j BOARD=<boardname>
```
Where **<boardname>** is replaced by the name of the board you want to build an
EC binary for. For example, the boardname for the Chromebook Pixel is “link”.
The make command will generate an EC binary at `build/<boardname>/ec.bin`. The
`-j` tells make to build multi-threaded which can be much faster on a multi-core
machine.
### Building via emerge (the build file used when you build Chrome OS):
(optional) Run this command if you want to build from local source instead of
the most recent stable version:
```bash
cros_workon-<boardname> start chromeos-ec
```
Build the EC binary:
```
emerge-<boardname> chromeos-ec
```
Please be careful if doing both local `make`s and running emerge. The emerge can
pick up build artifacts from the build subdirectory. It’s best to delete the
build directory before running emerge with `make clobber`.
The generated EC binary from emerge is found at:
```
(chroot) $ /build/<boardname>/firmware/ec.bin
```
The ebuild file used by Chromium OS is found
[here](https://chromium.googlesource.com/chromiumos/overlays/chromiumos-overlay/+/master/chromeos-base/chromeos-ec/chromeos-ec-9999.ebuild):
```bash
(chroot) $ ~/trunk/src/third_party/chromiumos-overlay/chromeos-base/chromeos-ec/chromeos-ec-9999.ebuild
```
## Flashing an EC binary to a board
### Flashing via the servo debug board
If you get an error, you may not have set up the dependencies for servo
correctly. The EC (on current Chromebooks) must be powered either by external
power or a charged battery for re-flashing to succeed. You can re-flash via
servo even if your existing firmware is bad.
```bash
(chroot) $ sudo emerge openocd
```
```bash
(chroot) $ ~/trunk/src/platform/ec/util/flash_ec --board=<boardname> [--image=<path/to/ec.bin>]
```
Note: This command will fail if write protect is enabled.
If you build your own EC firmware with the `make BOARD=<boardname>` command the
firmware image will be at:
```bash
(chroot) $ ~/trunk/src/platform/ec/build/<boardname>/ec.bin
```
If you build Chrome OS with `build_packages` the firmware image will be at:
```bash
(chroot) $ /build/<boardname>/firmware/ec.bin
```
Specifying `--image` is optional. If you leave off the `--image` argument, the
`flash_ec` script will first look for a locally built `ec.bin` followed by one
generated by `emerge`.
### Flashing on-device via flashrom
Assuming your devices boots, you can flash it using the `flashrom` utility. Copy
your binary to the device and run:
```bash
(chroot) $ flashrom -p ec -w <path-to/ec.bin>
```
Note: `-p internal:bus=lpc` also works on x86 boards...but why would you want to
remember and type all that?
## Preventing the RW EC firmware from being overwritten by Software Sync at boot
A feature called "Software Sync" keeps a copy of the read-write (RW) EC firmware
in the RW part of the system firmware image. At boot, if the RW EC firmware
doesn't match the copy in the system firmware, the EC’s RW section is
re-flashed. While this is great for normal use as it makes updating the EC and
system firmware a unified operation, it can be a challenge for EC firmware
development. To disable software sync a flag can be set in the system firmware.
Run the following commands from a shell on the device to disable Software Sync
and turn on other developer-friendly flags (note that write protect must be
disabled for this to work):
```bash
(chroot) $ /usr/share/vboot/bin/set_gbb_flags.sh 0x239
```
```bash
(chroot) $ reboot
```
This turns on the following flags:
* `GBB_FLAG_DEV_SCREEN_SHORT_DELAY`
* `GBB_FLAG_FORCE_DEV_SWITCH_ON`
* `GBB_FLAG_FORCE_DEV_BOOT_USB`
* `GBB_FLAG_DISABLE_FW_ROLLBACK_CHECK`
* `GBB_FLAG_DISABLE_EC_SOFTWARE_SYNC`
The `GBB` (Google Binary Block) flags are defined in the
[vboot_reference source](https://chromium.googlesource.com/chromiumos/platform/vboot_reference/+/master/firmware/include/gbb_header.h).
A varying subset of these flags are implemented and/or relevant for any
particular board.
## Using the EC serial console
The EC has an interactive serial console available only through the UART
connected via servo. This console is essential to developing and debugging the
EC.
Find the serial device of the ec console (on your workstation):
```bash
(chroot) $ dut-control ec_uart_pty
```
Connect to the console:
```bash
(chroot) $ socat READLINE /dev/pts/XX
```
Where `XX` is the device number. Use `cu`, `minicom`, or `screen` if you prefer
them over `socat`.
### Useful EC console commands:
**help** - get a list of commands. help <command> to get help on a specific
command.
**chan** - limit logging message to specific tasks (channels). Useful if you’re
looking for a specific error or warning and don’t want spam from other tasks.
**battfake** - Override the reported battery charge percentage. Good for testing
low battery conditions (LED behavior for example). Set “battfake -1” to go back
to the actual value.
**fanduty** - Override automatic fan control. “fanduty 0” turns the fan off.
“autofan” switches back to automated control.
**hcdebug** - Display the commands that the host sends to the EC, in varying
levels of detail (see include/ec_commands.h for the data structures).
## Host commands
The way in which messages are exchanged between the AP and EC is
[documented separately](./docs/ap-ec-comm.md).
## Software Features
### Tasks
Most code run on the EC after initialization is run in the context of a task
(with the rest in interrupt handlers). Each task has a fixed stack size and
there is no heap (malloc). All variable storage must be explicitly declared at
build-time. The EC (and system) will reboot if any task has a stack overflow.
Tasks typically have a top-level loop with a call to task_wait_event() or
usleep() to set a delay in uSec before continuing. A watchdog will trigger if a
task runs for too long. The watchdog timeout varies by EC chip and the clock
speed the EC is running at.
The list of tasks for a board is specified in ec.tasklist in the `board/$BOARD/`
sub-directory. Tasks are listed in priority order with the lowest priority task
listed first. A task runs until it exits its main function or puts itself to
sleep. The highest priority task that wants to run is scheduled next. Tasks can
be preempted at any time by an interrupt and resumed after the handler is
finished.
The console `taskinfo` command will print run-time stats on each task:
```
> taskinfo
Task Ready Name Events Time (s) StkUsed
0 R << idle >> 00000000 32.975554 196/256
1 R HOOKS 00000000 0.007835 192/488
2 VBOOTHASH 00000000 0.042818 392/488
3 POWERLED 00000000 0.000096 120/256
4 CHARGER 00000000 0.029050 392/488
5 CHIPSET 00000000 0.017558 400/488
6 HOSTCMD 00000000 0.379277 328/488
7 R CONSOLE 00000000 0.042050 348/640
8 KEYSCAN 00000000 0.002988 292/488
```
The `StkUsed` column reports the largest size the stack for each task grew since
reset (or sysjump).
### Hooks
Hooks allow you to register a function to be run when specific events occur;
such as the host suspending or external power being applied:
```
DECLARE_HOOK(HOOK_AC_CHANGE, ac_change_callback, HOOK_PRIO_DEFAULT);
```
Registered functions are run in the HOOKS task. Registered functions are called
in priority order if more than one callback needs to be run. There are also
hooks for running functions periodically: `HOOK_TICK` (fires every
`HOOK_TICK_INVERVAL` ms which varies by EC chip) and `HOOK_SECOND`. See
hook_type in
[include/hooks.h](https://chromium.googlesource.com/chromiumos/platform/ec/+/master/include/hooks.h)
for a complete list.
### Deferred Functions
Deferred functions allow you to call a function after a delay specified in uSec
without blocking. Deferred functions run in the HOOKS task. Here is an example
of an interrupt handler. The deferred function allows the handler itself to be
lightweight. Delaying the deferred call by 30 mSec also allows the interrupt to
be debounced.
```
static int debounced_gpio_state;
static void some_interrupt_deferred(void)
{
int gpio_state = gpio_get_level(GPIO_SOME_SIGNAL);
if (gpio_state == debounced_gpio_state)
return;
debounced_gpio_state = gpio_state;
dispense_sandwich(); /* Or some other useful action. */
}
/* A function must be explicitly declared as being deferrable. */
DECLARE_DEFERRED(some_interrupt_deferred);
void some_interrupt(enum gpio_signal signal)
{
hook_call_deferred(some_interrupt_deferred, 30 * MSEC);
}
```
### Shared Memory Buffer
While there is no heap, there is a shared memory buffer that can be borrowed
temporarily (ideally before a context switch). The size of the buffer depends on
the EC chip being used. The buffer can only be used by one task at a time. See
[common/shared_mem.c](https://chromium.googlesource.com/chromiumos/platform/ec/+/master/common/shared_mem.c)
for more information. At present (May 2014), this buffer is only used by debug
commands.
## Making Code Changes
If you see a bug or want to make an improvement to the EC code please file an
issue at [crbug.com/new](http://crbug.com/new). It's best to discuss the change
you want to make first on an issue report to make sure the EC maintainers are
on-board before digging into the fun part (writing code).
In general, make more, smaller changes that solve single problems rather than
bigger changes that solve multiple problems. Smaller changes are easier and
faster to review. When changing common code shared between boards along with
board specific code, please split the shared code change into its own change
list (CL). The board specific CL can depend on the shared code CL.
### Coding style
The EC code follows the
[Linux Kernel style guide](https://www.kernel.org/doc/html/latest/process/coding-style.html).
Please adopt the same style used in the existing code. Use tabs, not spaces, 80
column lines etc...
Other style notes:
1. Globals should either be `static` or `const`. Use them for persistent state
within a file or for constant data (such as the GPIO list in board.c). Do
not use globals to pass information between modules without accessors. For
module scope, accessors are not needed.
1. If you add a new `#define` config option to the code, please document it in
[include/config.h](https://chromium.googlesource.com/chromiumos/platform/ec/+/master/include/config.h)
with an `#undef` statement and descriptive comment.
1. The Chromium copyright header must be included at the top of new files in
all contributions to the Chromium project:
```
/* Copyright <year> The Chromium OS Authors. All rights reserved.
* Use of this source code is governed by a BSD-style license that can be
* found in the LICENSE file.
*/
```
### Submitting changes
Prior to uploading a new change for review, please run the EC unit tests with:
```bash
(chroot) $ make -j buildall
```
```bash
(chroot) $ make -j tests
```
These commands will build and run unit tests in an emulator on your host.
Pre-submit checks are run when you try to upload a change-list. If you wish to
run these checks manually first, commit your change locally then run the
following command from within the chroot and while in the `src/platform/ec`
directory:
```bash
(chroot) $ ~/trunk/src/repohooks/pre-upload.py
```
The pre-submit checks include checking the commit message. Commit messages must
have a `BUG`, `BRANCH`, and `TEST` line along with `Signed-off-by: First Last
<name@company.com>`. The signed-off-by line is a statement that you have written
this code and it can be contributed under the terms of the `LICENSE` file.
Please refer to existing commits (`git log`) to see the proper format for the
commit message. If you have configured git properly, running `git commit` with
the `-s` argument will add the Signed-off-by line for you.
## Debugging
While adding `printf` statements can be handy, there are some other options for
debugging problems during development.
### Serial Console
There may already be a message on the serial console that indicates your
problem. If you don’t have a servo connected, the `ectool console` command will
show the current contents of the console buffer (the buffer’s size varies by EC
chip). This log persists across warm resets of the host but is cleared if the EC
resets. The `ectool console` command will only work when the EC is not write
protected.
If you have interactive access to the serial console via servo, you can use the
read word `rw` and write word `ww` commands to peek and poke the EC's RAM. You
may need to refer to the datasheet for your EC chip or the disassembled code to
find the memory address you need. There are other handy commands on the serial
console to read temperatures, view the state of tasks (taskinfo) which may help.
Type `help` for a list.
### Panicinfo
The EC may save panic data which persists across resets. Use the “`ectool
panicinfo`” command or console “`panicinfo`” command to view the saved data:
```
Saved panic data: (NEW)
=== HANDLER EXCEPTION: 05 ====== xPSR: 6100001e ===
r0 :00000001 r1 :00000f15 r2 :4003800c r3 :000000ff
r4 :ffffffed r5 :00000799 r6 :0000f370 r7 :00000000
r8 :00000001 r9 :00000003 r10:20002fe0 r11:00000000
r12:00000008 sp :20000fd8 lr :000012e1 pc :0000105e
```
The most interesting information are the program counter (`pc`) and the link
register (return address, `lr`) as they give you an indication of what code the
EC was running when the panic occurred. `HANDLER EXCEPTIONS` indicate the panic
occurred while servicing an interrupt. `PROCESS EXCEPTIONS` occur in regular
tasks. If you see “Imprecise data bus error” listed, the program counter value
is incorrect as the panic occurred when flushing a write buffer. If using a
cortex-m based EC, add `CONFIG_DEBUG_DISABLE_WRITE_BUFFER` to your board.h to
disable write buffering (with a performance hit) to get a “Precise bus error”
with an accurate program counter value.
### Assembly Code
If you have a program counter address you need to make sense of, you can
generate the assembly code for the EC by checking out the code at the matching
commit for your binary (`ectool version`) and running:
```bash
(chroot) $ make BOARD=$board dis
```
This outputs two files with assembly code:
```
build/$board/RO/ec.RO.dis
build/$board/RW/ec.RW.dis
```
which (in the case of the LM4 and STM32) are essentially the same, but the RW
addresses are offset.
## Write Protect
See [Firmware Write Protection].
## EC Version Strings
The read-only and read-write sections of the EC firmware each have a version
string. This string tells you the branch and last change at which the firmware
was built. On a running machine, run `ectool version` from a shell to see
version information:
```
RO version: peppy_v1.5.103-7abb4f7
RW version: peppy_v1.5.129-cd1a1e9
Firmware copy: RW
Build info: peppy_v1.5.129-cd1a1e9 2014-03-07 17:18:27 @build120-m2
```
You can also run the `version` command on the EC serial console for a similar
output.
The format of the version string is:
```
<board>_<branch number>.<number of commits since the branch tag was created>-<git hash of most recent change>
```
If the version is: `rambi_v1.6.68-a6608c8`:
* board name = rambi
* branch number = v1.6 (which is for the firmware-rambi branch)
* number of commits on this branch (since the tag was added) = 68
* latest git hash = a6608c8
The branch numbers (as of May 2014) are:
* v1.0.0 cros/master
* v1.1.0 cros/master
* v1.2.0 cros/firmware-link-2695.2.B
* v1.3.0 cros/firmware-snow-2695.90.B
* v1.4.0 cros/firmware-skate-3824.129.B
* v1.5.0 cros/firmware-4389.71.B
* v1.6.0 cros/firmware-rambi-5216.B
Hack command to check the branch tags:
```
git tag
for hash in $(git for-each-ref --format='%(objectname)' refs/tags/); do
git branch -a --contains $hash | head -1;
done
```
(If anyone can come up with something prettier, make a CL).
Run `util/getversion.sh` to see the current version string. The board name is
passed as an environment variable `BOARD`:
```bash
(chroot) $ BOARD="cheese" ./util/getversion.sh
```
```
cheese_v1.1.1755-4da9520
```
[Firmware Write Protection]: ./docs/write_protection.md

42
baseboard/intelrvp/README.md
View file

@ -1,39 +1,5 @@
/* Copyright 2019 The Chromium OS Authors. All rights reserved.
* Use of this source code is governed by a BSD-style license that can be
* found in the LICENSE file.
*/
*** note
**Warning: This document is old & has moved. Please update any links:**<br>
https://chromium.googlesource.com/chromiumos/platform/ec/+/HEAD/baseboard/intelrvp/README.md
***
This folder is for the baseboard for the board specific files which use Intel
Reference Validation Platform (RVP) for developing the EC and other peripherals
which can be hooked on EC or RVP.
This baseboard follows the Intel Modular Embedded Controller Card (MECC)
specification for pinout and these pin definitions remain same on all the
RVPs. Chrome MECC spec is standardized for Icelake and successor RVPs hence
this baseboard code is applicable to Icelake and its successors only.
Following hardware features are supported on MECC header by RVP and can be
validated by software by MECC.
MECC version 0.9 features
1. Power to MECC is provide by RVP (battery + DC Jack + Type C)
2. Power control pins for Intel SOC are added
3. Servo V2 header need to be added by MECC
4. Google H1 chip need to be added by MECC (optional for EC vendors)
5. 2 Type-C port support (SRC/SNK/BC1.2/MUX/Rerimer)
6. 6 Temperature sensors
7. 4 ADC
8. 4 I2C Channels
9. 1 Fan control
MECC version 1.0 features
1. Power to MECC is provide by RVP (battery + DC Jack + Type C)
2. Power control pins for Intel SOC are added
3. Servo V2 header need to be added by MECC
4. Google H1 chip need to be added by MECC (optional for EC vendors)
5. 4 Type-C port support (SRC/SNK/BC1.2/MUX/Rerimer) as Add In Card (AIC)
on RVP
6. Optional 2 Type-C port routed to MECC for integrated TCPC support
7. 6 I2C Channels
8. 2 SMLINK Channels
9. 2 I3C channels

88
board/nucleo-f412zg/README.md
View file

@ -1,85 +1,5 @@
# Nucleo F412ZG
*** note
**Warning: This document is old & has moved. Please update any links:**<br>
https://chromium.googlesource.com/chromiumos/platform/ec/+/HEAD/board/nucleo-f412zg/README.md
***
This is a simpler EC example for the ST Nucleo F412ZG
development board.
# Quick Start
The Nucleo dev boards have lots of developer friendly features,
like an in-circuit debugger/programmer/UART-bridge, programmable
LEDs, and a button, to name a few.
The built-in debugger can be connected to using a Micro USB cable.
It provides three great interfaces to the host.
1. Mass storage interface for drag-drop programming
2. Full ST-Link in-circuit debugger
3. UART bridge for logs/consoles
We will use a few of these interfaces below to program and interact
with out Nucleo dev board.
## Build
```bash
make BOARD=nucleo-f412zg -j
```
## Program
The easiest way to flash the Nucleo board is to Copy-Paste/Drag-Drop
the firmware image onto the exposed mass storage drive.
Open a file browser and `Copy` the file in `build/nucleo-f412zg/ec.bin`.
Now, find the removable storage that the Nucleo device has presented,
and `Paste` the file into the directory.
## Interact
After the Nucelo finishes programming, you can open the EC console.
On GNU/Linux, this is mapped to `/dev/ttyACM0`.
Install `minicom` and issue the following command:
```bash
minicom -D/dev/ttyACM0
```
# Unit Testing
A fun EC feature is that unit tests can be run on-device.
This is made possible by an alternative build rule that generates a
test image per unit test. These test images use a unit test specific taskset
and console command to trigger them.
## Create
To enable an existing unit test, add it to the [build.mk](build.mk)'s
`test-list-y` variable.
See the main [README.md](/README.md) on how to write a new unit test.
## Build
To build all unit test images for this board, run the following command:
```bash
make BOARD=nucleo-f412zg tests
```
You can build a specific unit test image by changing `tests` to `test-aes`,
for the `aes` unit test.
## Flash
Copy/paste the `build/nucleo-f412zg/${TEST}/${TEST}.bin` file to the
Nucleo's mass storage drive, where `${TEST}` is the name of the unit test,
like `aes`.
## Run
1. Connect to UART console
```bash
minicom -D/dev/ttyACM0
```
2. Run the `runtest` command

88
board/nucleo-h743zi/README.md
View file

@ -1,85 +1,5 @@
# Nucleo H743ZI
*** note
**Warning: This document is old & has moved. Please update any links:**<br>
https://chromium.googlesource.com/chromiumos/platform/ec/+/HEAD/board/nucleo-h743zi/README.md
***
This is a simpler EC example for the ST Nucleo H743ZI
development board.
# Quick Start
The Nucleo dev boards have lots of developer friendly features,
like an in-circuit debugger/programmer/UART-bridge, programmable
LEDs, and a button, to name a few.
The built-in debugger can be connected to using a Micro USB cable.
It provides three great interfaces to the host.
1. Mass storage interface for drag-drop programming
2. Full ST-Link in-circuit debugger
3. UART bridge for logs/consoles
We will use a few of these interfaces below to program and interact
with out Nucleo dev board.
## Build
```bash
make BOARD=nucleo-h743zi -j
```
## Program
The easiest way to flash the Nucleo board is to Copy-Paste/Drag-Drop
the firmware image onto the exposed mass storage drive.
Open a file browser and `Copy` the file in `build/nucleo-h743zi/ec.bin`.
Now, find the removable storage that the Nucleo device has presented,
and `Paste` the file into the directory.
## Interact
After the Nucelo finishes programming, you can open the EC console.
On GNU/Linux, this is mapped to `/dev/ttyACM0`.
Install `minicom` and issue the following command:
```bash
minicom -D/dev/ttyACM0
```
# Unit Testing
A fun EC feature is that unit tests can be run on-device.
This is made possible by an alternative build rule that generates a
test image per unit test. These test images use a unit test specific taskset
and console command to trigger them.
## Create
To enable an existing unit test, add it to the [build.mk](build.mk)'s
`test-list-y` variable.
See the main [README.md](/README.md) on how to write a new unit test.
## Build
To build all unit test images for this board, run the following command:
```bash
make BOARD=nucleo-h743zi tests
```
You can build a specific unit test image by changing `tests` to `test-aes`,
for the `aes` unit test.
## Flash
Copy/paste the `build/nucleo-h743zi/${TEST}/${TEST}.bin` file to the
Nucleo's mass storage drive, where `${TEST}` is the name of the unit test,
like `aes`.
## Run
1. Connect to UART console
```bash
minicom -D/dev/ttyACM0
```
2. Run the `runtest` command

154
board/pdeval-stm32f072/PD_evaluation.md
View file

@ -1,151 +1,5 @@
USB PD chip evaluation configuration
====================================
This board configuration implements a USB Power Delivery TCPM
in order to evaluate various TCPC chips.
The code tries to follow the preliminary USB PD interface standard but for TCPC chip implementing proprietary I2C protocol, a new TCPM file can be implemented as explained in the [Updating the code](#Updating-the-code) section below.
Building
--------
### ChromiumOS chroot
All the following instructions have been verified in a ChromiumOS chroot.
You can find how to set one up on the Chromium development wiki:
[http://dev.chromium.org/chromium-os/quick-start-guide](http://dev.chromium.org/chromium-os/quick-start-guide)
### Build the TCPM code
`cd src/platform/ec`
`make BOARD=pdeval-stm32f072`
Updating the code
-----------------
### TCPC Communication code
Please duplicate [driver/tcpm/tcpci.c](../../driver/tcpm/tcpci.c) into **driver/tcpm/##chip#name##.c**.
Then update the control logic through I2C there.
In order for your new code to compile, you need to update [driver/build.mk](../../driver/build.mk) with the new file :
`driver-$(CONFIG_USB_PD_TCPM_##CHIP#NAME##)+=tcpm/##chip#name##.o`
then document the new `CONFIG_USB_PD_TCPM_` variable in the [include/config.h](../../include/config.h) file and define it in the board configuration in [board/pdeval-stm32f072/board.h](board.h).
### Board configuration
In [board/pdeval-stm32f072/board.h](board.h), you can update `CONFIG_USB_PD_PORT_MAX_COUNT` to the actual number of ports on your board.
You also need to create/delete the corresponding `PD_Cx` tasks in [board/pdeval-stm32f072/ec.tasklist](ec.tasklist).
By default, the firmware is using I2C1 with SCL/SDA on pins PB6 and PB7, running with a 100kHz clock, and tries to talk to TCPCs at i2c slave addresses 0x9c and 0x9e.
To change the pins or speed, you need to edit `i2c_ports` in [board/pdeval-stm32f072/board.c](board.c), update `I2C_PORT_TCPC` in [board/pdeval-stm32f072/board.h](board.h) with the right controller number, and change the pin mux in [board/pdeval-stm32f072/gpio.inc](gpio.inc). To change TCPC i2c slave addresses, update `TCPC1_I2C_ADDR` and `TCPC2_I2C_ADDR` in [board/pdeval-stm32f072/board.h](board.h).
The I2C bus needs pull-up resistors on SCL/SDA. If your setup doesn't have external pull-ups on those lines, you can activate the chip internal pull-ups (but they are a bit weak for I2C) by editing [board/pdeval-stm32f072/gpio.inc](gpio.inc) and updating the alternate mode configuration flags with `GPIO_PULL_UP` e.g. :
`ALTERNATE(PIN_MASK(B, 0x00c0), 1, MODULE_I2C, GPIO_PULL_UP) /* I2C MASTER:PB6/7 */`
An interrupt line, PA1, is configured to be used for the TCPC to get the attention of the TCPM. The GPIO is configured to trigger an interrupt on the falling edge and will call `tcpc_alert()`, which must be implemented in **driver/tcpm/<vendor>.c**, and should determine the cause of the interrupt and take action. The GPIO can be changed in [board/pdeval-stm32f072/gpio.inc](gpio.inc).
Flashing and Running
--------------------
### Flashing the firmware binary
To flash through JTAG with OpenOCD, you can just run:
`sudo make flash BOARD=pdeval-stm32f072`
Note: you need to do that with your USB mini-B cable is connected to the **USB ST-LINK** plug on the discovery board.
### Connecting to the firmware console
Connect a USB cable to the **USB USER** mini-B receptacle on the board.
`lsusb` should show you a device with the following ID : 18d1:500f
You can get a console over USB by issuing the following command on a Linux computer:
`echo '18d1 500f' | sudo tee /sys/bus/usb-serial/drivers/generic/new_id`
Testing
-------
Currently, the TCPM is expecting to have a GPIO to detect VBUS, but to minimize the HW setup with the discovery board the alternative is to fake VBUS detection using either the **USER** button on the discovery board, or the `vbus` console command, both of which toggle the state of VBUS detected. For example, to make get a PD contract with a power adapter, plug in the adapter and then toggle VBUS on. When a PD contract above 6V is made, LED5 on the discovery board will light. To disconnect, toggle VBUS off.
EC command line commands
- `help` List all available EC console commands
- `vbus` Toggle VBUS on/off
- `pd <port> state` Print PD protocol state information
- `pd <port> swap data` Request data role swap on port
- `pd <port> swap power` Request power role swap on port
- `i2cscan` Scan i2c bus for any responsive devices
- `i2cxfer` Perform an i2c transaction
On the console, you will the PD state machine transitioning through its states with traces like `C0 st5`.
You can always the human readable name of the current state by doing `pd 0 state` returning something like :
`Port C0 CC1, Ena - Role: SNK-UFP State: SNK_DISCOVERY, Flags: 0x0608`
else the numbering of the state is defined in [include/usb_pd.h](../../include/us_pd.h) by the `PD_STATE_` constants.
It should be by default :
```
[0] DISABLED
[1] SUSPENDED
[2] SNK_DISCONNECTED
[3] SNK_DISCONNECTED_DEBOUNCE
[4] SNK_HARD_RESET_RECOVER
[5] SNK_DISCOVERY
[6] SNK_REQUESTED
[7] SNK_TRANSITION
[8] SNK_READY
[9] SNK_SWAP_INIT
[10] SNK_SWAP_SNK_DISABLE
[11] SNK_SWAP_SRC_DISABLE
[12] SNK_SWAP_STANDBY
[13] SNK_SWAP_COMPLETE
[14] SRC_DISCONNECTED
[15] SRC_DISCONNECTED_DEBOUNCE
[16] SRC_ACCESSORY
[17] SRC_HARD_RESET_RECOVER
[18] SRC_STARTUP
[19] SRC_DISCOVERY
[20] SRC_NEGOCIATE
[21] SRC_ACCEPTED
[22] SRC_POWERED
[23] SRC_TRANSITION
[24] SRC_READY
[25] SRC_GET_SINK_CAP
[26] DR_SWAP
[27] SRC_SWAP_INIT
[28] SRC_SWAP_SNK_DISABLE
[29] SRC_SWAP_SRC_DISABLE
[30] SRC_SWAP_STANDBY
[31] SOFT_RESET
[32] HARD_RESET_SEND
[33] HARD_RESET_EXECUTE
[34] BIST_RX
[35] BIST_TX
```
Known Issues
------------
1. This doc is not finished yet ...
2. You might need a ChromeOS chroot ...
Troubleshooting
---------------
1. OpenOCD is not finding the device.
1. Check that your USB mini-B cable is connected to the **USB ST-LINK** plug on the discovery board.
2. What color is the LD1 LED on the board ?
1. On the I2C bus, SDA/SCL lines are staying always low
1. You might be missing some pull-up resistors on the bus.
1. Check the [Board configuration](#Board-configuration) section if you cannot add external pull-ups.
1. You got black smoke
1. Time to buy a new one.
*** note
**Warning: This document is old & has moved. Please update any links:**<br>
https://chromium.googlesource.com/chromiumos/platform/ec/+/HEAD/board/pdeval-stm32f072/PD_evaluation.md
***

179
board/servo_micro/ccd.md
View file

@ -1,176 +1,5 @@
<!--
Copyright 2018 The Chromium OS Authors. All rights reserved.
Use of this source code is governed by a BSD-style license that can be
found in the LICENSE file.
-->
*** note
**Warning: This document is old & has moved. Please update any links:**<br>
https://chromium.googlesource.com/chromiumos/platform/ec/+/HEAD/board/servo_micro/ccd.md
***
# Case-Closed Debug in Chromebooks and Servo Micro
The Servo debug/test-automation connector has been required on all
chromebooks. It has proved essential to performing the required testing to meet
the six week OS release cycle, for bringing up new systems and qualifying new
components. In newer form-factors it is becoming hard to fit the Servo connector
(and related flex) and in some designs the thermal solution stops working when
the connector is used. The secure Case-Closed Debugging solution provides the
same capabilities and can take advantage of the Debug Mode detection available
on the USB-C connector. This application note gives an overview of Case-Closed
Debug (CCD) but does not address the related security issues.
## Introduction to Case-Closed Debug
Case-Closed Debug provides the same set of features as are available on the Servo connector:
* Access to console UART connections to AP, EC and on some systems a third MCU
* Ability to reprogram firmware/BIOS SPI flash used by the AP
* Ability to reprogram SPI flash used by the EC or use a firmware update mode
to reprogram the internal flash on the EC (using UART or I2C)
* GPIOs for holding the EC (and thus entire system) or AP in reset
* Act as master on a debug I2C that is primarily used for power
measurements. This bus normally contains INA voltage/current monitors and
temperature monitors that will not be populated on final MP systems.
* JTAG/SWD could be provided but has not been implemented on any existing system.
When the Servo connector is used these interfaces are presented on well defined
pins of the board-to-board connector and a flex is used to attach to the
external Servo controller. The height needed for the mated board-to-board
connector is not available in newer slim designs, and the disruption caused by
the flex may interfere with thermal solutions. In a system using Case-Closed
Debug the interfaces are gathered by a part on the board into a single USB
interface that can come out of the system on an existing connector. In
particular, the USB-C connector has two SideBand Use pins (SBU1, SBU2) that can
be used for the debug USB while the main link on the connector continues to be
available. (The SBU pins are also used by some Alternate Modes, so the connector
cannot be used for video out at the same time as debugging.)
## Servo Micro: Using CCD with existing boards
The Servo Micro implements the CCD functions in a way that can connect to
existing boards and thus can also serve as an easy introduction to the CCD
implementation. The debug USB interface is expanded by a STM32F072 into an
existing Servo flex connector that can be plugged into the target board.
![block diagram](servo_micro.png)
The Servo Micro includes the voltage level buffering between the microcontroller
and the device under test (DUT), making use of the DUT supplied reference
voltages. To allow use with all the existing designs a third UART (not on the
original Servo connector, but on some designs) can be connected to either the
JTAG pins or the SPI pins. It is capable of providing the SPI flash supply
voltages.
The schematics for Servo Micro are available [as a
pdf](servo_micro_sch_20180404.pdf).
Servo Micro has a USB micro-B connector and acts as a USB device.
Schematic sheet 2 shows the STM32 powered from the uB connector. The UART3 pins
can also be used as GPIO pins when driving the JTAG interface. As a useful but
non-compliant hack if the ID pin on the uB is low then Q4 will force the STM32
to boot in programming mode. This allows initial programming of the part with
USB DFU using an illegal USB-A plug to USB-A plug cable and a USB-A receptacle
to uB plug adapter. Alternatively the initial programming can be done using a
UART connection on CN2.
Schematic sheet 3 shows the I2C GPIO expander and the buffers for JTAG/SWD. The
buffers adapt to the voltage needed on the DUT that is provided on
`PPDUT_JTAG_VREF`. In the SWD case the TDI becomes the bidirectional SWDIO but the
STM32 continues to use a discrete input and output pin. The DUT signal is
received through U55 and a selection made with U1 to determine if to forward TDO
from the DUT or the TDI/SWDIO. Because of the shared pins on the STM32 the JTAG
interface can alternatively be used to connect UART3 to the DUT for a few
chromebook models.
Schematic sheet 4 shows the buffers for the SPI interfaces. Again the
`PPDUT_SPIn_VREF` sets the voltage level required from the DUT. However, I61 and
I62 (which are expanded on sheets 7 and 8) allow the Servo Micro to supply 3.3V
or 1.8V for cases where the DUT does not provide the reference (care is needed
to select the correct voltage for the given DUT). Only one of the SPI interfaces
can be used at any time, so the buffers are also used to select which connects
to the STM32 SPI pins. Certain chromebook models connect the UART3 in place of
SPI1 which is enabled using U5 to select between the STM32 UART3 (TX,RX) and SPI
(CLK, MISO).
Schematic sheet 5 shows the buffers for the UART interfaces. The
`PPDUT_UARTn_VREF` sets the voltage level required from the DUT.
Schematic sheet 6 shows the board-to-board connector that mates with the servo
connector on the DUT.
Schematic sheets 7 and 8 are the expansion of blocks I61 and I62 on sheet 4. The
load switches are carefully selected to have reverse blocking (protecting
against a DUT providing a voltage or both being enabled).
The code for the STM32 in Servo Micro is open source as the
[`servo_micro`](../../board/servo_micro)
board in the [Chromium EC
codebase](https://chromium.googlesource.com/chromiumos/platform/ec/). Essentially
it is a USB device that provides the standard control endpoint and 7 function
endpoints defined in
[`board.h`](board.h).
<!-- does not work in emacs/markdown preview but should in gitlies -->
``` c
#define USB_EP_USART4_STREAM 1
#define USB_EP_UPDATE 2
#define USB_EP_SPI 3
#define USB_EP_CONSOLE 4
#define USB_EP_I2C 5
#define USB_EP_USART3_STREAM 6
#define USB_EP_USART2_STREAM 7
```
The USART endpoints use the simple `GOOGLE_SERIAL` vendor class to connect the
STM32 UARTs. The CONSOLE endpoint also uses `GOOGLE_STREAM` to connect to the
console of the code running on the STM32. `GOOGLE_STREAM` provides simple byte
streams on the IN and OUT of the endpoint and host support is included in the
standard Linux `drivers/usb/serial/usb-serial-simple.c`
The SPI endpoint is described in
[`chip/stm32/usb_spi.h`](../../chip/stm32/usb_spi.h) and provides a simple
connection to the SPI port. The host support is provided as a [driver in
flashrom](https://chromium.googlesource.com/chromiumos/third_party/flashrom/+/master/raiden_debug_spi.c).
The I2C endpoint is described in [`include/usb_i2c.h`](../../include/usb_i2c.h)
and provides a simple connection to the I2C bus. The host support is provided in
the [hdctools servo
support](https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/master/servo/stm32i2c.py).
The GPIO endpoint is cryptically described in
[`chip/stm32/usb_gpio.h`](../../chip/stm32/usb_gpio.h) and provides simple access
to set/clear and read the GPIO pins. The host support is provided in the
[hdctools servo
support](https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/master/servo/stm32gpio.py).
The UPDATE endpoint is not part of CCD. It provides a method for updating the
STM32 without needing the special boot modes. This uses the [Chromium EC update
over
USB](../../docs/usb_updater.md)
method. The STM32 runs the code in
[`common/usb_update.c`](../../common/usb_update.c).
The host side code is in
[`extra/usb_updater/usb_updater2.c`](../../extra/usb_updater/usb_updater2.c)
and the
[`extra/usb_updater`](../../extra/usb_updater/)
directory contains additional scripts.
## Using CCD on new designs
New chromebook designs implement the CCD in a similar way to Servo Micro. There
are two changes to the Servo Micro:
* The USB microB connector is replaced with the USB connection being carried
on the SBU pins of one of the devices USB-C ports. This will only be
activated when the USB-C port detects a debug accessory or a debug alternate
mode is entered. Use of the debug connection precludes use of the Display
Port alternate mode (which also uses the SBU pins) but allows full USB3 and
USB2 functions including both host and gadget mode.
* The system security chip will normally lock out debug access. Using secure
transactions, user authorization and proof of user physical presence it can
unlock various degrees of debug access.
The full details are part of the Cr50 firmware specification.

90
common/mock/README.md
View file

@ -1,87 +1,5 @@
# Common Mocks
This directory holds mock implementations for use in fuzzers and tests.
*** note
**Warning: This document is old & has moved. Please update any links:**<br>
https://chromium.googlesource.com/chromiumos/platform/ec/+/HEAD/common/mock/README.md
***
Each mock is given some friendly build name, like ROLLBACK or FP_SENSOR.
This name is defined in [common/mock/build.mk](build.mk) and referenced
from unit tests and fuzzers' `.mocklist` file.
## Creating a new mock
* Add the mock source to [common/mock](/common/mock) and the
optional header file to [include/mock](/include/mock).
Header files are only necessary if you want to expose additional
[mock control](#mock-controls) functions/variables.
See the [Design Patterns](#design-patterns) section
for more detail on design patterns.
* Add a new entry in [common/mock/build.mk](build.mk)
that is conditioned on your mock's name.
If a unit test or fuzzer requests this mock, the build system will
set the variable `HAS_MOCK_<BUILD_NAME>` to `y` at build time.
This variable is used to conditionally include the mock source
in [common/mock/build.mk](build.mk).
Example line from [common/mock/build.mk](build.mk):
```make
# Mocks
mock-$(HAS_MOCK_ROLLBACK) += mock/rollback_mock.o
```
## Using a mock
Unit tests and fuzzers can request a particular mock by adding an entry to
their `.mocklist` file. The mocklist file is similar to a `.tasklist`
file, where it is named according to the test/fuzz's name followed by
`.mocklist`, like `fpsensor.mocklist`.
The mocklist file is optional, so you may need to create one.
Example `.mocklist`:
```c
/* Copyright 2019 The Chromium OS Authors. All rights reserved.
* Use of this source code is governed by a BSD-style license that can be
* found in the LICENSE file.
*/
#define CONFIG_TEST_MOCK_LIST \
MOCK(ROLLBACK) \
MOCK(FP_SENSOR)
```
If you need additional [mock control](#mock-controls) functionality,
you may need to include the mock's header file, which is prepended
with `mock/` in the include line.
For example, to control the return values of the rollback mock:
```c
#include "mock/rollback_mock.h"
void yourfunction() {
mock_ctrl_rollback.get_secret_fail = true;
}
```
## Mock Controls
Mocks can change their behavior by exposing "mock controls".
We do this, most commonly, by exposing an additional global struct
per mock that acts as the settings for the mock implementation.
The mock user can then modify fields of the struct to change the mock's behavior.
For example, the `fp_sensor_init_return` field may control what value
the mocked `fp_sensor_init` function returns.
The declaration for these controls are specified in the mock's header file,
which resides in [include/mock](/include/mock).
## Design Patterns
* When creating mock controls, consider placing all your mock parameters in
one externally facing struct, like in
[fp_sensor_mock.h](/include/mock/fp_sensor_mock.h).
The primary reason for this is to allow the mock to be easily used
by a fuzzer (write random bytes into the struct with memcpy).
* When following the above pattern, please provide a macro for resetting
default values for this struct, like in
[fp_sensor_mock.h](/include/mock/fp_sensor_mock.h).
This allows unit tests to quickly reset the mock state/parameters
before each unrelated unit test.

156
docs/ap-ec-comm.md
View file

@ -1,153 +1,5 @@
# Application Processor to EC communication
*** note
**Warning: This document is old & has moved. Please update any links:**<br>
https://chromium.googlesource.com/chromiumos/platform/ec/+/HEAD/docs/ap-ec-comm.md
***
[TOC]
## Overview
The Application Processor (sometimes called the host) communicates with the EC
by issuing *host commands*, which are identified by a command ID and version
number, and then reading a response. When a host command is issued through
`ectool`, two or three software components are involved:
* `ectool`, the user-space binary,
* normally the `cros-ec` Kernel driver, and
* the code on the EC itself. This can be thought of as two parts:
* a chip-specific driver for the appropriate transport, and
* the generic host command handling code (mostly in the [host command task]).
We'll go into detail of each of these, as well as the traffic on the wire, in
the following sections.
### `ectool`
`ectool` contains wrapper functions for the host commands exposed by the EC,
providing a CLI. They call one of the transport-specific `ec_command`
implementations in the `util/comm-*.c` files to send and receive from the EC.
### EC kernel driver
In most cases, `ectool` communicates via the [`cros-ec` Kernel driver], rather
than directly from userspace. It sends raw commands to the Kernel driver, which
sends them on to the EC, bypassing a lot of the other Kernel driver
functionality.
There are other CrOS EC-related Kernel drivers, which use host commands to act
as adapters to existing Linux APIs. For example, sensors from the EC are mapped
to the Linux [Industrial I/O] system.
### On the wire
Now we come to the protocol itself. All transactions take this general form:
* Host writes the request packet, consisting of:
* a transport-specific header;
* a `struct ec_host_request` containing the command ID, data length, and a
checksum; and
* zero or more bytes of parameters for the command, the format of which
depends on the command.
* Host reads the response to its request, consisting of:
* a transport-specific header;
* a `struct ec_host_response` containing the result code, data length, and a
checksum; and
* zero or more bytes of response from the command, again with a
command-specific format.
### On the EC
The host packet is received on the EC by some chip-specific code which checks
its transport-specific header, then passes it on to the common host command code,
starting at `host_packet_receive`. The common code validates the packet and
then sends it on to the handler function (annotated with the
`DECLARE_HOST_COMMAND` macro), which runs in the `HOSTCMD` task. The handler can
set a response by modifying its arguments struct, which is sent back to the host
via the chip-specific code.
While this is happening, the EC needs to indicate to the host that it is busy
processing and not yet ready to give a response. How it does this depends on the
transport method used (see [Transport-specific details] below).
## Versions
There are two different concepts of "version" involved in host commands: version
of the overarching protocol, and versions of individual commands.
### Protocol versions
There have been three protocol versions so far, and this document describes
version 3. Version 1 was superseded by 2 before it shipped, so no devices use
it anymore. Version 2 is generally deprecated, but you might still encounter it
occasionally.
Which version is in use can be determined using the `EC_CMD_GET_PROTOCOL_INFO`
command. This was only introduced in version 3, however, so if errors,
`EC_CMD_HELLO` should be sent in version 2. If the hello command succeeds, the
EC speaks version 2.
### Command versions
Individual commands also have versions, independent of the protocol version
they're being called with. Different versions of a command may have different
parameter or response formats. `EC_CMD_GET_CMD_VERSIONS` returns the versions of
the given command supported by the EC. These version numbers start at 0.
## Transport-specific details
Although the command and response formats are the same across all transports,
some details of how they are transmitted differ, which may be of interest when
implementing the EC side of the protocol on a new chip.
### I<sup>2</sup>C
I<sup>2</sup>C is very flexible with its timing, so when the EC receives a
packet from the host, it should stretch the clock, holding it low until it is
ready for the host to read the response.
If the host tries to read more bytes than were in the response, the EC should
respond with an obvious filler byte (such as 0xEC). For example, if a command
that normally returns 50 bytes errors, its response will only be 8 bytes (the
size of the response struct). The host will probably try to read 50 bytes
anyway, so the EC should send the 8 bytes of the struct followed by 42 copies of
the filler byte.
### SPI
The SPI bus is similar to I<sup>2</sup>C, but with two major exceptions. First,
there's a minimum speed on the SPI bus. If slave devices don't respond quickly
enough, the master will assume they're broken and give up. Second, every
transaction is bidirectional. When bits are being clocked from master to slave
on the MOSI line, the master will simultaneously read bits in the other
direction on the MISO line.
Hardware devices can usually handle this, and often some hardware-based flow
control used to "stretch" the transaction by a bit or byte if the slave device
needs a little extra time to respond to the master's demands.
When exchanging messages with the EC on the SPI bus, the EC's host commands are
communicated using our own software flow-control scheme, because most of the
embedded controllers either aren't fast enough or don't have any support for
hardware flow-control.
It works like this: When the AP sends a byte to the EC, if the EC doesn't have a
response queued up in advance, a default byte is returned. The EC
preconfigures that default response byte to indicate its status (ready, busy,
waiting for more input, etc.). Once the AP has sent a complete command message,
it continues clocking bytes to the EC (which the EC ignores) and just looks at
the response byte that comes back. Once the EC has parsed the AP's command and
is ready to reply, it sends a "start of frame" byte, followed by the actual
response. The AP continues to read and ignore bytes from the EC until it sees
the start of frame byte, and then it knows that the EC's response is starting
with the next byte.
Once the response packet has been read, any additional reads should return
`EC_SPI_PAST_END`.
### LPC or eSPI
The EC should set `EC_LPC_STATUS_PROCESSING` in its command status register
after receiving a host packet and before it has a response ready.
[`cros-ec` Kernel driver]: https://chromium.googlesource.com/chromiumos/third_party/kernel/+/refs/heads/chromeos-4.19/drivers/mfd/cros_ec_dev.c
[Industrial I/O]: https://www.kernel.org/doc/html/v4.14/driver-api/iio/index.html
[host command task]: https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/master/common/host_command.c
[Transport-specific details]: #Transport_specific-details

7
docs/case_closed_debugging.md
View file

@ -1,2 +1,5 @@
The has been moved into a [different
branch](https://chromium.googlesource.com/chromiumos/platform/ec/+/cr50_stab/docs/case_closed_debugging.md)
*** note
**Warning: This document is old & has moved. Please update any links:**<br>
https://chromium.googlesource.com/chromiumos/platform/ec/+/HEAD/docs/case_closed_debugging.md
***

7
docs/case_closed_debugging_cr50.md
View file

@ -1,2 +1,5 @@
The has been moved into a [different
branch](https://chromium.googlesource.com/chromiumos/platform/ec/+/cr50_stab/docs/case_closed_debugging_cr50.md)
*** note
**Warning: This document is old & has moved. Please update any links:**<br>
https://chromium.googlesource.com/chromiumos/platform/ec/+/HEAD/docs/case_closed_debugging_cr50.md
***

7
docs/ccd_howtos.md
View file

@ -1,2 +1,5 @@
The has been moved into a [different
branch](https://chromium.googlesource.com/chromiumos/platform/ec/+/cr50_stab/docs/ccd_howtos.md)
*** note
**Warning: This document is old & has moved. Please update any links:**<br>
https://chromium.googlesource.com/chromiumos/platform/ec/+/HEAD/docs/ccd_howtos.md
***

37
docs/code_coverage.md
View file

@ -1,34 +1,5 @@
# Code Coverage
*** note
**Warning: This document is old & has moved. Please update any links:**<br>
https://chromium.googlesource.com/chromiumos/platform/ec/+/HEAD/docs/code_coverage.md
***
Provides an overview of how to use code coverage tools when running the unit
tests in the EC codebase.
[TOC]
## Availability
Code coverage is only available for host-based unit tests, as opposed to
manual tests that run on target hardware.
## Building for code coverage
To build host-based unit tests for code coverage, invoke `make` with the
`coverage` target, as follows:
`make coverage -j`
This target will compile and link the unit tests with `--coverage` flag (which
pulls in the `gcov` libraries), run the tests, and then process the profiling
data into a code coverage report using the `lcov` and `genhtml` tools.
The coverage report top-level page is `build/coverage/coverage_rpt/index.html`.
### Noise in the build output
When building for code coverage, you may see multiple warnings of the form
`geninfo: WARNING: no data found for /mnt/host/source/src/platform/ec/core/host/cpu.h`
and
`genhtml: WARNING: function data mismatch at /mnt/host/source/src/platform/ec/common/math_util.c:134`
These warnings can be ignored. (FYI, the "function data mismatch" warnings
appear to be caused in part by using relative paths instead of absolute paths.)

57
docs/code_reviews.md
View file

@ -1,54 +1,5 @@
# Code Reviews
*** note
**Warning: This document is old & has moved. Please update any links:**<br>
https://chromium.googlesource.com/chromiumos/platform/ec/+/HEAD/docs/code_reviews.md
***
The `platform/ec` repository makes use of a code review system that tries to
evenly distribute code reviews among available reviewers.
[TOC]
## How to request a review
Add `cros-ec-reviewers@google.com` to the reviewer line in Gerrit. A background
job will come around and replace the `cros-ec-reviewers@google.com` address with
the next available reviewer in the EC reviewer rotation. This typically takes on
the order of minutes.
Optionally, you can click the [FIND OWNERS] button in the UI, and select
`cros-ec-reviewers@google.com`.
## When to use review system
If you are modifying code in `common/`, `chip/`, or `core/`, feel free to use
the `cros-ec-reviewers@google.com` system. It is **never** a requirement to use
`cros-ec-reviewers@google.com`. You can always request a review from a specific
person.
## Responsibilities of reviewers
If the selected reviewer is unfamiliar with code in a CL, then that reviewer
should at least ensure that EC style and paradigms are being followed. Once EC
styles and paradigms are being followed, then the reviewer can give a +1 and add
the appropriate domain expert for that section of code.
Reviewers should try to give an initial response within 1 business day of
receiving a review request. Thereafter, they should try to respond to new
comments by the author within 1 business day.
## Review guidelines
Authors and reviewers should follow the Chrome OS firmware review
[guidelines][2] while publishing and reviewing code.
## How can I join the rotation?
Add your name to the [list of reviewers][1].
## Reference
* [Chrome OS firmware review guidelines][2]
* [Coreboot Gerrit Guidelines][3]
* [Google small CL guidelines][5]
[1]: http://google3/chrome/crosinfra/gwsq/ec_reviewers
[2]: http://chromium.googlesource.com/chromiumos/docs/+/master/firmware_code_reviews.md
[3]: https://doc.coreboot.org/getting_started/gerrit_guidelines.html
[5]: https://google.github.io/eng-practices/review/developer/small-cls.html

256
docs/configuration/ap_power_sequencing.md
View file

@ -1,253 +1,5 @@
# Configure AP Power Sequencing
*** note
**Warning: This document is old & has moved. Please update any links:**<br>
https://chromium.googlesource.com/chromiumos/platform/ec/+/HEAD/docs/configuration/ap_power_sequencing.md
***
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) \
```