Google Git
Sign in
chromium / chromiumos / platform / ec / HEAD / . / README.md
blob: 485de4720be35ea7878b07850684463dd7c7034a [file] [log] [blame] [view]
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]1# Embedded Controller (EC)
2
3[TOC]
4
Keith Short76f39452022-02-18 19:49:11[diff] [blame]5> **Note** - This document covers the legacy Chrome EC implementation. The
6> legacy EC implementation is used by all Chromebook reference designs prior to
7> July 2021. On newer Chromebook designs, the EC implementation is based on the
8> Zephyr RTOS. Refer to the [Zephyr EC Introduction](./docs/zephyr/README.md)
9> for details on the Zephyr EC implementation.
10
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]11## Introduction
12
13The Chromium OS project includes open source software for embedded controllers
14(EC) used in recent ARM and x86 based Chromebooks. This software includes a
15lightweight, multitasking OS with modules for power sequencing, keyboard
16control, thermal control, battery charging, and verified boot. The EC software
Tom Hughes2f40b712021-01-26 18:38:55[diff] [blame]17is written in C and supports
Dossym Nurmukhanov7d9a4252021-02-02 05:45:38[diff] [blame]18[a variety of micro-controllers](https://chromium.googlesource.com/chromiumos/platform/ec/+/main/chip/).
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]19
20This document is a guide to help make you familiar with the EC code, current
21features, and the process for submitting code patches.
22
23For more see the Chrome OS Embedded Controller
24[presentation](https://docs.google.com/presentation/d/1Xa_Z6SjW-soPvkugAR8__TEJFrJpzoZUa9HNR14Sjs8/pub?start=false&loop=false&delayms=3000)
25and [video](http://youtu.be/Ie7LRGgCXC8) from the
26[2014 Firmware Summit](http://dev.chromium.org/chromium-os/2014-firmware-summit).
27
28## What you will need
29
301. A Chromebook with a compatible EC. This includes the Samsung Chromebook
31 (XE303C12) and all Chromebooks shipped after the Chromebook Pixel 2013
32 (inclusive). See the
33 [Chrome OS devices](http://dev.chromium.org/chromium-os/developer-information-for-chrome-os-devices)
34 page for a list.
Aseda Aboagye1b5a84c2021-04-09 21:45:58[diff] [blame]351. A Linux development environment. The latest Debian Stable (x86_64) is commonly used.
36 Linux in a VM may work if you have a powerful host machine.
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]371. A [servo debug board](http://dev.chromium.org/chromium-os/servo) (and
38 header) is highly recommended for serial console and JTAG access to the EC.
391. A sense of adventure!
40
Tom Hughes6f76b0a2019-06-13 18:24:19[diff] [blame]41## Terminology
42
43### EC
44
45EC (aka Embedded Controller) can refer to many things in the Chrome OS
46documentation due to historical reasons. If you just see the term "EC", it
47probably refers to "the" EC (i.e. the first one that existed). Most Chrome OS
48devices have an MCU, known as "the EC" that controls lots of things (key
49presses, turning the AP on/off). The OS that was written for "the" EC is now
Tom Hughes2f40b712021-01-26 18:38:55[diff] [blame]50running on several different MCUs on Chrome OS devices with various tweaks (e.g.
51the FPMCU, the touchpad one that can do palm rejection, etc.). It's quite
Tom Hughes6f76b0a2019-06-13 18:24:19[diff] [blame]52confusing, so try to be specific and use terms like FPMCU to distinguish the
53fingerprint MCU from "the EC".
54
Keith Short0596ecd2019-08-13 23:07:04[diff] [blame]55See the [EC Acronyms and Technologies](./docs/ec_terms.md) for a more complete
56glossary.
57
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]58## Getting the EC code
59
60The code for the EC is open source and is included in the Chromium OS
61development environment (`~/trunk/src/platform/ec/</code>`).
62See[ http://www.chromium.org/chromium-os/quick-start-guide](http://dev.chromium.org/chromium-os/quick-start-guide)
63for build setup instructions. If you want instant gratification, you can fetch
64the source code directly. However, you will need the tool-chain provided by the
65Chromium OS development environment to build a binary.
66
67```bash
68git clone https://chromium.googlesource.com/chromiumos/platform/ec
69```
70
Keith Shortf634e7c2019-08-20 22:50:13[diff] [blame]71The source code can also be browsed on the web at:
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]72
73https://chromium.googlesource.com/chromiumos/platform/ec/
74
75## Code Overview
76
77The following is a quick overview of the top-level directories in the EC
78repository:
79
Keith Shortf634e7c2019-08-20 22:50:13[diff] [blame]80**baseboard** - Code and configuration details shared by a collection of board
81variants. Tightly linked with the `board` directory described below.
82
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]83**board** - Board specific code and configuration details. This includes the
84GPIO map, battery parameters, and set of tasks to run for the device.
85
86**build** - Build artifacts are generated here. Be sure to delete this and
87rebuild when switching branches and before "emerging" (see Building an EC binary
88below). make clobber is a convenient way to clean up before building.
89
90**chip** - IC specific code for interfacing with registers and hardware blocks
91(adc, jtag, pwm, uart etc…)
92
93**core** - Lower level code for task and memory management.
94
95**common** - A mix of upper-level code that is shared across boards. This
96includes the charge state machine, fan control, and the keyboard driver (among
97other things).
98
99**driver** - Low-level drivers for light sensors, charge controllers,
100I2C/onewire LED controllers, and I2C temperature sensors.
101
102**include** - Header files for core and common code.
103
104**util** - Host utilities and scripts for flashing the EC. Also includes
105“ectool” used to query and send commands to the EC from userspace.
106
Tom Hughes2f40b712021-01-26 18:38:55[diff] [blame]107**test** - Unit tests for EC components. These can be run locally in a mock
108"host" environment or compiled for a target board. If building for a target
109board, the test must be flashed and run manually on the device. All unit tests
110and fuzzers are build/run using the local host environment during a `buildall`.
111To run all unit tests locally, run `make runhosttests -j`. To build a specific
112unit test for a specific board, run `make test-<test_name> BOARD=<board_name>`.
113Please contribute new tests if writing new functionality. Please run `make help`
114for more detail.
Craig Hesling053491b2019-07-02 01:10:37[diff] [blame]115
Tom Hughes2f40b712021-01-26 18:38:55[diff] [blame]116**fuzz** - Fuzzers for EC components. These fuzzers are expected to run in the
117mock host environment. They follow the same rules as unit tests, as thus use the
118same commands to build and run.
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]119
120## Firmware Branches
121
122Each Chrome device has a firmware branch created when the read-only firmware is
123locked down prior to launch. This is done so that updates can be made to the
124read-write firmware with a minimal set of changes from the read-only. Some
125Chrome devices only have build targets on firmware branches and not on
Dossym Nurmukhanov7d9a4252021-02-02 05:45:38[diff] [blame]126cros/main. Run “`git branch -a | grep firmware`” to locate the firmware branch
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]127for your board. Note that for devices still under development, the board
128configuration may be on the branch for the platform reference board.
129
130To build EC firmware on a branch, just check it out and build it:
131
132```bash
133git checkout cros/firmware-falco_peppy-4389.B
134```
135
136To make changes on a branch without creating a whole new development environment
137(chroot), create a local tracking branch:
138
139```bash
140git branch --track firmware-falco_peppy-4389.B cros/firmware-falco_peppy-4389.B
141
142git checkout firmware-falco_peppy-4389.B
143
144make clobber
145
146# <make changes, test, and commit them>
147
148repo upload --cbr .
149
150# (The --cbr means "upload to the current branch")
151```
152
153Here is a useful command to see commit differences between branches (change the
154branch1...branch2 as needed):
155
156```bash
157git log --left-right --graph --cherry-pick --oneline branch1...branch2
158```
159
Tom Hughesc15e3c72021-02-02 18:32:14[diff] [blame]160For example, to see the difference between cros/main and the HEAD of the current
161branch:
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]162
163```bash
Dossym Nurmukhanov7d9a4252021-02-02 05:45:38[diff] [blame]164git log --left-right --graph --cherry-pick --oneline cros/main...HEAD
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]165
166# Note: Use three dots “...” or it won’t work!
167```
168
169## Building an EC binary
170
171Note: The EC is normally built from within the Chromium OS development chroot to
172use the correct toolchain.
173
174Building directly from the EC repository:
175
176```bash
177cros_sdk
Keith Short0f52d7a2023-01-12 16:01:44[diff] [blame]178cd ~/chromiumos/src/platform/ec
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]179make -j BOARD=<boardname>
180```
181
Patrick Thompsona77fc182022-07-06 18:06:03[diff] [blame]182Where `<boardname>` is replaced by the name of the board you want to build an
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]183EC binary for. For example, the boardname for the Chromebook Pixel is “link”.
184The make command will generate an EC binary at `build/<boardname>/ec.bin`. The
185`-j` tells make to build multi-threaded which can be much faster on a multi-core
186machine.
187
188### Building via emerge (the build file used when you build Chrome OS):
189
190(optional) Run this command if you want to build from local source instead of
191the most recent stable version:
192
193```bash
194cros_workon-<boardname> start chromeos-ec
195```
196
197Build the EC binary:
198
199```
200emerge-<boardname> chromeos-ec
201```
202
203Please be careful if doing both local `make`s and running emerge. The emerge can
204pick up build artifacts from the build subdirectory. It’s best to delete the
205build directory before running emerge with `make clobber`.
206
207The generated EC binary from emerge is found at:
208
209```
210(chroot) $ /build/<boardname>/firmware/ec.bin
211```
212
mparuchuri1bd59912022-05-04 08:37:00[diff] [blame]213or
214
215```
216(chroot) $ /build/<boardname>/firmware/<devicename>/ec.bin
217```
218
219The `devicename` is the name of a device (also referred as board or variant) which belongs to a family of baseboard. `boardname` is the baseboard name in this case. Example : `/build/dedede/firmware/madoo/ec.bin`
220
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]221The ebuild file used by Chromium OS is found
Dossym Nurmukhanov7d9a4252021-02-02 05:45:38[diff] [blame]222[here](https://chromium.googlesource.com/chromiumos/overlays/chromiumos-overlay/+/main/chromeos-base/chromeos-ec/chromeos-ec-9999.ebuild):
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]223
224```bash
225(chroot) $ ~/trunk/src/third_party/chromiumos-overlay/chromeos-base/chromeos-ec/chromeos-ec-9999.ebuild
226```
227
228## Flashing an EC binary to a board
229
230### Flashing via the servo debug board
231
232If you get an error, you may not have set up the dependencies for servo
233correctly. The EC (on current Chromebooks) must be powered either by external
234power or a charged battery for re-flashing to succeed. You can re-flash via
235servo even if your existing firmware is bad.
236
237```bash
238(chroot) $ sudo emerge openocd
239```
240
241```bash
242(chroot) $ ~/trunk/src/platform/ec/util/flash_ec --board=<boardname> [--image=<path/to/ec.bin>]
243```
244
245Note: This command will fail if write protect is enabled.
246
247If you build your own EC firmware with the `make BOARD=<boardname>` command the
248firmware image will be at:
249
250```bash
251(chroot) $ ~/trunk/src/platform/ec/build/<boardname>/ec.bin
252```
253
254If you build Chrome OS with `build_packages` the firmware image will be at:
255
256```bash
257(chroot) $ /build/<boardname>/firmware/ec.bin
258```
259
mparuchuri1bd59912022-05-04 08:37:00[diff] [blame]260or
261
262```
263(chroot) $ /build/<boardname>/firmware/<devicename>/ec.bin
264```
265
266The `devicename` is the name of a device (also referred as board or variant) which belongs to a family of baseboard. `boardname` is the baseboard name in this case. Example : `/build/dedede/firmware/madoo/ec.bin`
267
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]268Specifying `--image` is optional. If you leave off the `--image` argument, the
269`flash_ec` script will first look for a locally built `ec.bin` followed by one
270generated by `emerge`.
271
272### Flashing on-device via flashrom
273
274Assuming your devices boots, you can flash it using the `flashrom` utility. Copy
275your binary to the device and run:
276
277```bash
278(chroot) $ flashrom -p ec -w <path-to/ec.bin>
279```
280
281Note: `-p internal:bus=lpc` also works on x86 boards...but why would you want to
282remember and type all that?
283
284## Preventing the RW EC firmware from being overwritten by Software Sync at boot
285
286A feature called "Software Sync" keeps a copy of the read-write (RW) EC firmware
287in the RW part of the system firmware image. At boot, if the RW EC firmware
288doesn't match the copy in the system firmware, the EC’s RW section is
289re-flashed. While this is great for normal use as it makes updating the EC and
290system firmware a unified operation, it can be a challenge for EC firmware
291development. To disable software sync a flag can be set in the system firmware.
292Run the following commands from a shell on the device to disable Software Sync
293and turn on other developer-friendly flags (note that write protect must be
294disabled for this to work):
295
296```bash
Edward O'Callaghan611a9ab2023-01-12 22:25:05[diff] [blame]297# futility gbb --set --flash --flags=0x239
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]298```
299
300```bash
Fabio Baltieribcbd9532021-01-21 22:19:35[diff] [blame]301# reboot
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]302```
303
304This turns on the following flags:
305
306* `GBB_FLAG_DEV_SCREEN_SHORT_DELAY`
307* `GBB_FLAG_FORCE_DEV_SWITCH_ON`
308* `GBB_FLAG_FORCE_DEV_BOOT_USB`
309* `GBB_FLAG_DISABLE_FW_ROLLBACK_CHECK`
310* `GBB_FLAG_DISABLE_EC_SOFTWARE_SYNC`
311
Fabio Baltierie9254222023-06-08 09:09:57[diff] [blame]312
313Alternatively, if the OS cannot be accessed, the same flag can be set over a servo with:
314
315```bash
316$ sudo futility gbb -s --flags=0x239 --servo
317```
318
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]319The `GBB` (Google Binary Block) flags are defined in the
Dossym Nurmukhanov7d9a4252021-02-02 05:45:38[diff] [blame]320[vboot_reference source](https://chromium.googlesource.com/chromiumos/platform/vboot_reference/+/main/firmware/2lib/include/2struct.h).
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]321A varying subset of these flags are implemented and/or relevant for any
322particular board.
323
324## Using the EC serial console
325
326The EC has an interactive serial console available only through the UART
327connected via servo. This console is essential to developing and debugging the
328EC.
329
330Find the serial device of the ec console (on your workstation):
331
332```bash
Mary Ruthven076dd702019-09-20 18:10:15[diff] [blame]333(chroot) $ dut-control ec_uart_pty
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]334```
335
336Connect to the console:
337
338```bash
339(chroot) $ socat READLINE /dev/pts/XX
340```
341
342Where `XX` is the device number. Use `cu`, `minicom`, or `screen` if you prefer
343them over `socat`.
344
345### Useful EC console commands:
346
347**help** - get a list of commands. help <command> to get help on a specific
348command.
349
350**chan** - limit logging message to specific tasks (channels). Useful if you’re
351looking for a specific error or warning and don’t want spam from other tasks.
352
353**battfake** - Override the reported battery charge percentage. Good for testing
354low battery conditions (LED behavior for example). Set “battfake -1” to go back
355to the actual value.
356
357**fanduty** - Override automatic fan control. “fanduty 0” turns the fan off.
358“autofan” switches back to automated control.
359
360**hcdebug** - Display the commands that the host sends to the EC, in varying
361levels of detail (see include/ec_commands.h for the data structures).
362
363## Host commands
364
365The way in which messages are exchanged between the AP and EC is
Harry Cutts14b13d32019-11-06 01:14:44[diff] [blame]366[documented separately](./docs/ap-ec-comm.md).
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]367
368## Software Features
369
370### Tasks
371
372Most code run on the EC after initialization is run in the context of a task
373(with the rest in interrupt handlers). Each task has a fixed stack size and
374there is no heap (malloc). All variable storage must be explicitly declared at
375build-time. The EC (and system) will reboot if any task has a stack overflow.
376Tasks typically have a top-level loop with a call to task_wait_event() or
Patryk Duda85d75982024-04-10 13:10:59[diff] [blame]377crec_usleep() to set a delay in uSec before continuing. A watchdog will trigger
378if a task runs for too long. The watchdog timeout varies by EC chip and the
379clock speed the EC is running at.
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]380
381The list of tasks for a board is specified in ec.tasklist in the `board/$BOARD/`
382sub-directory. Tasks are listed in priority order with the lowest priority task
383listed first. A task runs until it exits its main function or puts itself to
384sleep. The highest priority task that wants to run is scheduled next. Tasks can
385be preempted at any time by an interrupt and resumed after the handler is
386finished.
387
388The console `taskinfo` command will print run-time stats on each task:
389
390```
391> taskinfo
392Task Ready Name Events Time (s) StkUsed
393 0 R << idle >> 00000000 32.975554 196/256
394 1 R HOOKS 00000000 0.007835 192/488
395 2 VBOOTHASH 00000000 0.042818 392/488
396 3 POWERLED 00000000 0.000096 120/256
397 4 CHARGER 00000000 0.029050 392/488
398 5 CHIPSET 00000000 0.017558 400/488
399 6 HOSTCMD 00000000 0.379277 328/488
400 7 R CONSOLE 00000000 0.042050 348/640
401 8 KEYSCAN 00000000 0.002988 292/488
402```
403
404The `StkUsed` column reports the largest size the stack for each task grew since
405reset (or sysjump).
406
407### Hooks
408
409Hooks allow you to register a function to be run when specific events occur;
410such as the host suspending or external power being applied:
411
412```
413DECLARE_HOOK(HOOK_AC_CHANGE, ac_change_callback, HOOK_PRIO_DEFAULT);
414```
415
416Registered functions are run in the HOOKS task. Registered functions are called
417in priority order if more than one callback needs to be run. There are also
418hooks for running functions periodically: `HOOK_TICK` (fires every
419`HOOK_TICK_INVERVAL` ms which varies by EC chip) and `HOOK_SECOND`. See
420hook_type in
Dossym Nurmukhanov7d9a4252021-02-02 05:45:38[diff] [blame]421[include/hooks.h](https://chromium.googlesource.com/chromiumos/platform/ec/+/main/include/hooks.h)
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]422for a complete list.
423
424### Deferred Functions
425
426Deferred functions allow you to call a function after a delay specified in uSec
427without blocking. Deferred functions run in the HOOKS task. Here is an example
428of an interrupt handler. The deferred function allows the handler itself to be
429lightweight. Delaying the deferred call by 30 mSec also allows the interrupt to
430be debounced.
431
432```
433static int debounced_gpio_state;
434
435static void some_interrupt_deferred(void)
436{
437
438 int gpio_state = gpio_get_level(GPIO_SOME_SIGNAL);
439
440 if (gpio_state == debounced_gpio_state)
441 return;
442
443 debounced_gpio_state = gpio_state;
444
445 dispense_sandwich(); /* Or some other useful action. */
446}
447
448/* A function must be explicitly declared as being deferrable. */
449DECLARE_DEFERRED(some_interrupt_deferred);
450
451void some_interrupt(enum gpio_signal signal)
452{
453 hook_call_deferred(some_interrupt_deferred, 30 * MSEC);
454}
455```
456
457### Shared Memory Buffer
458
459While there is no heap, there is a shared memory buffer that can be borrowed
460temporarily (ideally before a context switch). The size of the buffer depends on
461the EC chip being used. The buffer can only be used by one task at a time. See
Dossym Nurmukhanov7d9a4252021-02-02 05:45:38[diff] [blame]462[common/shared_mem.c](https://chromium.googlesource.com/chromiumos/platform/ec/+/main/common/shared_mem.c)
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]463for more information. At present (May 2014), this buffer is only used by debug
464commands.
465
466## Making Code Changes
467
468If you see a bug or want to make an improvement to the EC code please file an
469issue at [crbug.com/new](http://crbug.com/new). It's best to discuss the change
470you want to make first on an issue report to make sure the EC maintainers are
471on-board before digging into the fun part (writing code).
472
473In general, make more, smaller changes that solve single problems rather than
474bigger changes that solve multiple problems. Smaller changes are easier and
475faster to review. When changing common code shared between boards along with
476board specific code, please split the shared code change into its own change
477list (CL). The board specific CL can depend on the shared code CL.
478
479### Coding style
480
481The EC code follows the
482[Linux Kernel style guide](https://www.kernel.org/doc/html/latest/process/coding-style.html).
483Please adopt the same style used in the existing code. Use tabs, not spaces, 80
484column lines etc...
485
486Other style notes:
487
4881. Globals should either be `static` or `const`. Use them for persistent state
489 within a file or for constant data (such as the GPIO list in board.c). Do
490 not use globals to pass information between modules without accessors. For
491 module scope, accessors are not needed.
4921. If you add a new `#define` config option to the code, please document it in
Dossym Nurmukhanov7d9a4252021-02-02 05:45:38[diff] [blame]493 [include/config.h](https://chromium.googlesource.com/chromiumos/platform/ec/+/main/include/config.h)
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]494 with an `#undef` statement and descriptive comment.
4951. The Chromium copyright header must be included at the top of new files in
496 all contributions to the Chromium project:
497
498 ```
Mike Frysinger71b2ef72022-09-12 18:54:36[diff] [blame]499 /* Copyright <year> The ChromiumOS Authors
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]500 * Use of this source code is governed by a BSD-style license that can be
501 * found in the LICENSE file.
502 */
503 ```
504
505### Submitting changes
506
507Prior to uploading a new change for review, please run the EC unit tests with:
508
509```bash
510(chroot) $ make -j buildall
511```
512
513```bash
Ting Shenc32a6592023-09-13 07:52:28[diff] [blame]514(chroot) $ make -j runtests
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]515```
516
Ting Shenc32a6592023-09-13 07:52:28[diff] [blame]517These commands will build and run unit tests on your host.
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]518
Jack Rosenthal6db4ddb2023-05-02 01:23:42[diff] [blame]519Pre-upload checks are run when you try to upload a change-list. If you wish to
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]520run these checks manually first, commit your change locally then run the
521following command from within the chroot and while in the `src/platform/ec`
522directory:
523
524```bash
525(chroot) $ ~/trunk/src/repohooks/pre-upload.py
526```
527
Jack Rosenthal6db4ddb2023-05-02 01:23:42[diff] [blame]528The pre-upload checks include checking the commit message. Commit messages must
529have a `BUG` and `TEST`. You may also optionally include a `BRANCH` line with a
530list of board names for which the CL should be cherry-picked back to old
531branches for.
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]532
533Please refer to existing commits (`git log`) to see the proper format for the
Jack Rosenthal6db4ddb2023-05-02 01:23:42[diff] [blame]534commit message.
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]535
Keith Short0f52d7a2023-01-12 16:01:44[diff] [blame]536Note that code you submit must adhere to the [ChromeOS EC Firmware Test
537Requirements].
538
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]539## Debugging
540
541While adding `printf` statements can be handy, there are some other options for
542debugging problems during development.
543
544### Serial Console
545
546There may already be a message on the serial console that indicates your
547problem. If you don’t have a servo connected, the `ectool console` command will
548show the current contents of the console buffer (the buffer’s size varies by EC
549chip). This log persists across warm resets of the host but is cleared if the EC
550resets. The `ectool console` command will only work when the EC is not write
551protected.
552
553If you have interactive access to the serial console via servo, you can use the
554read word `rw` and write word `ww` commands to peek and poke the EC's RAM. You
555may need to refer to the datasheet for your EC chip or the disassembled code to
556find the memory address you need. There are other handy commands on the serial
557console to read temperatures, view the state of tasks (taskinfo) which may help.
558Type `help` for a list.
559
560### Panicinfo
561
562The EC may save panic data which persists across resets. Use the “`ectool
563panicinfo`” command or console “`panicinfo`” command to view the saved data:
564
565```
566Saved panic data: (NEW)
567=== HANDLER EXCEPTION: 05 ====== xPSR: 6100001e ===
568r0 :00000001 r1 :00000f15 r2 :4003800c r3 :000000ff
569r4 :ffffffed r5 :00000799 r6 :0000f370 r7 :00000000
570r8 :00000001 r9 :00000003 r10:20002fe0 r11:00000000
571r12:00000008 sp :20000fd8 lr :000012e1 pc :0000105e
572```
573
574The most interesting information are the program counter (`pc`) and the link
575register (return address, `lr`) as they give you an indication of what code the
576EC was running when the panic occurred. `HANDLER EXCEPTIONS` indicate the panic
577occurred while servicing an interrupt. `PROCESS EXCEPTIONS` occur in regular
578tasks. If you see “Imprecise data bus error” listed, the program counter value
579is incorrect as the panic occurred when flushing a write buffer. If using a
580cortex-m based EC, add `CONFIG_DEBUG_DISABLE_WRITE_BUFFER` to your board.h to
581disable write buffering (with a performance hit) to get a “Precise bus error”
582with an accurate program counter value.
583
584### Assembly Code
585
586If you have a program counter address you need to make sense of, you can
587generate the assembly code for the EC by checking out the code at the matching
588commit for your binary (`ectool version`) and running:
589
590```bash
591(chroot) $ make BOARD=$board dis
592```
593
594This outputs two files with assembly code:
595
596```
597build/$board/RO/ec.RO.dis
598build/$board/RW/ec.RW.dis
599```
600
601which (in the case of the LM4 and STM32) are essentially the same, but the RW
602addresses are offset.
603
604## Write Protect
605
Tom Hughes6f76b0a2019-06-13 18:24:19[diff] [blame]606See [Firmware Write Protection].
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]607
608## EC Version Strings
609
610The read-only and read-write sections of the EC firmware each have a version
611string. This string tells you the branch and last change at which the firmware
612was built. On a running machine, run `ectool version` from a shell to see
613version information:
614
615```
616RO version: peppy_v1.5.103-7abb4f7
617RW version: peppy_v1.5.129-cd1a1e9
618Firmware copy: RW
619Build info: peppy_v1.5.129-cd1a1e9 2014-03-07 17:18:27 @build120-m2
620```
621
622You can also run the `version` command on the EC serial console for a similar
623output.
624
625The format of the version string is:
626
627```
628<board>_<branch number>.<number of commits since the branch tag was created>-<git hash of most recent change>
629```
630
631If the version is: `rambi_v1.6.68-a6608c8`:
632
633* board name = rambi
634* branch number = v1.6 (which is for the firmware-rambi branch)
635* number of commits on this branch (since the tag was added) = 68
636* latest git hash = a6608c8
637
638The branch numbers (as of May 2014) are:
639
Dossym Nurmukhanov7d9a4252021-02-02 05:45:38[diff] [blame]640* v1.0.0 cros/main
641* v1.1.0 cros/main
Tom Hughes80ea7fa2019-06-11 21:02:40[diff] [blame]642* v1.2.0 cros/firmware-link-2695.2.B
643* v1.3.0 cros/firmware-snow-2695.90.B
644* v1.4.0 cros/firmware-skate-3824.129.B
645* v1.5.0 cros/firmware-4389.71.B
646* v1.6.0 cros/firmware-rambi-5216.B
647
648Hack command to check the branch tags:
649
650```
651git tag
652
653for hash in $(git for-each-ref --format='%(objectname)' refs/tags/); do
654 git branch -a --contains $hash | head -1;
655done
656```
657
658(If anyone can come up with something prettier, make a CL).
659
660Run `util/getversion.sh` to see the current version string. The board name is
661passed as an environment variable `BOARD`:
662
663```bash
664(chroot) $ BOARD="cheese" ./util/getversion.sh
665```
666
667```
668cheese_v1.1.1755-4da9520
669```
Tom Hughes6f76b0a2019-06-13 18:24:19[diff] [blame]670
671[Firmware Write Protection]: ./docs/write_protection.md
Jeremy Bettisb3b38362022-03-16 16:20:26[diff] [blame]672
673## CQ builder
674
675To test the cq builder script run these commands:
676
677### firmware-ec-cq
678```
679rm -rf /tmp/artifact_bundles /tmp/artifact_bundle_metadata \
680 ~/chromiumos/src/platform/ec/build
681./firmware_builder.py --metrics /tmp/metrics_build build && \
682./firmware_builder.py --metrics /tmp/metrics_test test && \
683./firmware_builder.py --metrics /tmp/metrics_bundle bundle && \
684echo PASSED
685cat /tmp/artifact_bundle_metadata
686cat /tmp/metrics_build
687ls -l /tmp/artifact_bundles/
688```
Keith Short0f52d7a2023-01-12 16:01:44[diff] [blame]689
690[ChromeOS EC Firmware Test Requirements]: ./docs/chromeos-ec-firmware-test-requirements.md