Repository files navigation

This project holds the code used for the Framework Laptop Embedded Controller.

The Embedded Controller on your Framework Laptop handles low level functions, including power sequencing the system. Modifying the EC code can cause your system to not power on or boot or cause damage to the mainboard, battery, or other parts of the system or devices attached to the system.Hardware damage caused by EC firmware modifications would not be covered under the Framework Limited Warranty.

The Framework Laptop EC code can be built easily outside the Chromium development environment as a standalone project with a minimal set of tools.

On Ubuntu you can install the development tools easily.

sudo apt install gcc-arm-none-eabi libftdi1-dev build-essential pkg-configsudo apt-get install gawk

The different Framework Laptops are each implemented as their own board:

Building the project - run the command for the processor you have:

# hx20 (11th Gen)make BOARD=hx20 CROSS_COMPILE=arm-none-eabi-# hx30 (12th and 13th Gen)make BOARD=hx30 CROSS_COMPILE=arm-none-eabi-

The output artifact isbuild/hx20/ec.bin which can be flashed to the EC SPI flash ROM.

When flashing the EC for Framework Laptops with Intel 11th Gen Core Processors, do not erase or overwrite the sectors 0x3C000 to 0x3FFFF, or 0x79000 to 0x7FFFF.

Currently the EC only runs from the ro region.

00000000:00000fff bootsector00001000:00039fff lfwro00040000:00078fff rw

The EC is a MEC1521H-B0-I-SZ WFBGA144 which has 256kB of RAM.

Most changes are limited to the following folders, however there are some modifications in common.

board/hx20chip/mchp

Note that the EC has a checksum and header verification of the EC code image. Arbitarily modifying code, for example with a reverse engineering tool will cause the EC to fail to boot. Compiling the code from source will correctly generate the required checksum information to allow the EC to boot.

The EC has debug header in the upper right corner of the Mainboard next to the on-board power button. This is the 10 pin EC debug connector JECDB. Pin 1 is nearest the power button. The EC is configured for 2 wire SWD.

The Framework Laptop EC is based upon the Google Chromium EC repository:https://chromium.googlesource.com/chromiumos/platform/ec. We upstream common features where they fit into the design decisions of Chrome OS. However, there are a number of features and changes that will be unlikely to be upstreamed because they are unnecessary for Chrome OS operation or do not fit the philosophy of Chrome OS.

For example, we implement memory mapped regions that are not used in Chrome OS such as the UCSI driver.

The remainder of this README file is directly from Google's Chromium EC project.

[TOC]

The Chromium OS project includes open source software for embedded controllers(EC) used in recent ARM and x86 based Chromebooks. This software includes alightweight, multitasking OS with modules for power sequencing, keyboardcontrol, thermal control, battery charging, and verified boot. The EC softwareis written in C and supportsa variety of micro-controllers.

This document is a guide to help make you familiar with the EC code, currentfeatures, and the process for submitting code patches.

For more see the Chrome OS Embedded Controllerpresentationandvideo from the2014 Firmware Summit.

1. A Chromebook with a compatible EC. This includes the Samsung Chromebook(XE303C12) and all Chromebooks shipped after the Chromebook Pixel 2013(inclusive). See theChrome OS devicespage for a list.
2. A Linux development environment. Ubuntu 14.04 Trusty (x86_64) is wellsupported. Linux in a VM may work if you have a powerful host machine.
3. Aservo debug board (andheader) is highly recommended for serial console and JTAG access to the EC.
4. A sense of adventure!

EC (aka Embedded Controller) can refer to many things in the Chrome OSdocumentation due to historical reasons. If you just see the term "EC", itprobably refers to "the" EC (i.e. the first one that existed). Most Chrome OSdevices have an MCU, known as "the EC" that controls lots of things (keypresses, turning the AP on/off). The OS that was written for "the" EC is nowrunning 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 quiteconfusing, so try to be specific and use terms like FPMCU to distinguish thefingerprint MCU from "the EC".

See theEC Acronyms and Technologies for a more completeglossary.

The code for the EC is open source and is included in the Chromium OSdevelopment environment (~/trunk/src/platform/ec/</code>).See http://www.chromium.org/chromium-os/quick-start-guidefor build setup instructions. If you want instant gratification, you can fetchthe source code directly. However, you will need the tool-chain provided by theChromium OS development environment to build a binary.

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/

The following is a quick overview of the top-level directories in the ECrepository:

baseboard - Code and configuration details shared by a collection of boardvariants. Tightly linked with theboard directory described below.

board - Board specific code and configuration details. This includes theGPIO map, battery parameters, and set of tasks to run for the device.

build - Build artifacts are generated here. Be sure to delete this andrebuild when switching branches and before "emerging" (see Building an EC binarybelow). 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. Thisincludes the charge state machine, fan control, and the keyboard driver (amongother 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 ina mock "host" environment or compiled for a target board.If building for a target board, the test must be flashed andrun manually on the device.All unit tests and fuzzers are build/run using the localhost environment during abuildall.To run all unit tests locally, runmake runhosttests -j.To build a specific unit test for a specific board, runmake test-<test_name> BOARD=<board_name>.Please contribute new tests if writing new functionality.Please runmake help for more detail.

fuzz - Fuzzers for EC components. These fuzzers are expected torun in the mock host environment. They follow the same rulesas unit tests, as thus use the same commands to build and run.

Each Chrome device has a firmware branch created when the read-only firmware islocked down prior to launch. This is done so that updates can be made to theread-write firmware with a minimal set of changes from the read-only. SomeChrome devices only have build targets on firmware branches and not oncros/master. Run “git branch -a | grep firmware” to locate the firmware branchfor your board. Note that for devices still under development, the boardconfiguration may be on the branch for the platform reference board.

To build EC firmware on a branch, just check it out and build it:

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:

git branch --track firmware-falco_peppy-4389.B cros/firmware-falco_peppy-4389.Bgit checkout firmware-falco_peppy-4389.Bmake 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 thebranch1...branch2 as needed):

git log --left-right --graph --cherry-pick --oneline branch1...branch2

For example, to see the difference between cros/master and the HEAD of thecurrent branch:

git log --left-right --graph --cherry-pick --oneline cros/master...HEAD# Note: Use three dots “...” or it won’t work!

Note: The EC is normally built from within the Chromium OS development chroot touse the correct toolchain.

Building directly from the EC repository:

cros_sdkcd~/trunk/src/platform/ecmake -j BOARD=<boardname>

Where is replaced by the name of the board you want to build anEC binary for. For example, the boardname for the Chromebook Pixel is “link”.The make command will generate an EC binary atbuild/<boardname>/ec.bin. The-j tells make to build multi-threaded which can be much faster on a multi-coremachine.

(optional) Run this command if you want to build from local source instead ofthe most recent stable version:

cros_workon-<boardname> start chromeos-ec

Build the EC binary:

emerge-<boardname> chromeos-ec

Please be careful if doing both localmakes and running emerge. The emerge canpick up build artifacts from the build subdirectory. It’s best to delete thebuild directory before running emerge withmake clobber.

The generated EC binary from emerge is found at:

(chroot) $ /build/<boardname>/firmware/ec.bin

The ebuild file used by Chromium OS is foundhere:

(chroot) $~/trunk/src/third_party/chromiumos-overlay/chromeos-base/chromeos-ec/chromeos-ec-9999.ebuild

If you get an error, you may not have set up the dependencies for servocorrectly. The EC (on current Chromebooks) must be powered either by externalpower or a charged battery for re-flashing to succeed. You can re-flash viaservo even if your existing firmware is bad.

(chroot) $ sudo emerge openocd

(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 themake BOARD=<boardname> command thefirmware image will be at:

(chroot) $~/trunk/src/platform/ec/build/<boardname>/ec.bin

If you build Chrome OS withbuild_packages the firmware image will be at:

(chroot) $ /build/<boardname>/firmware/ec.bin

Specifying--image is optional. If you leave off the--image argument, theflash_ec script will first look for a locally builtec.bin followed by onegenerated byemerge.

Assuming your devices boots, you can flash it using theflashrom utility. Copyyour binary to the device and run:

(chroot) $ flashrom -p ec -w<path-to/ec.bin>

Note:-p internal:bus=lpc also works on x86 boards...but why would you want toremember and type all that?

A feature called "Software Sync" keeps a copy of the read-write (RW) EC firmwarein the RW part of the system firmware image. At boot, if the RW EC firmwaredoesn't match the copy in the system firmware, the EC’s RW section isre-flashed. While this is great for normal use as it makes updating the EC andsystem firmware a unified operation, it can be a challenge for EC firmwaredevelopment. 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 Syncand turn on other developer-friendly flags (note that write protect must bedisabled for this to work):

(chroot) $ /usr/share/vboot/bin/set_gbb_flags.sh 0x239

(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

TheGBB (Google Binary Block) flags are defined in thevboot_reference source.A varying subset of these flags are implemented and/or relevant for anyparticular board.

The EC has an interactive serial console available only through the UARTconnected via servo. This console is essential to developing and debugging theEC.

Find the serial device of the ec console (on your workstation):

(chroot) $ dut-control ec_uart_pty

Connect to the console:

(chroot) $ socat READLINE /dev/pts/XX

WhereXX is the device number. Usecu,minicom, orscreen if you preferthem oversocat.

help - get a list of commands. help to get help on a specificcommand.

chan - limit logging message to specific tasks (channels). Useful if you’relooking for a specific error or warning and don’t want spam from other tasks.

battfake - Override the reported battery charge percentage. Good for testinglow battery conditions (LED behavior for example). Set “battfake -1” to go backto 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 varyinglevels of detail (see include/ec_commands.h for the data structures).

The way in which messages are exchanged between the AP and EC isdocumented separately.

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 andthere is no heap (malloc). All variable storage must be explicitly declared atbuild-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() orusleep() to set a delay in uSec before continuing. A watchdog will trigger if atask runs for too long. The watchdog timeout varies by EC chip and the clockspeed the EC is running at.

The list of tasks for a board is specified in ec.tasklist in theboard/$BOARD/sub-directory. Tasks are listed in priority order with the lowest priority tasklisted first. A task runs until it exits its main function or puts itself tosleep. The highest priority task that wants to run is scheduled next. Tasks canbe preempted at any time by an interrupt and resumed after the handler isfinished.

The consoletaskinfo command will print run-time stats on each task:

> taskinfoTask 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

TheStkUsed column reports the largest size the stack for each task grew sincereset (or sysjump).

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 calledin priority order if more than one callback needs to be run. There are alsohooks for running functions periodically:HOOK_TICK (fires everyHOOK_TICK_INVERVAL ms which varies by EC chip) andHOOK_SECOND. Seehook_type ininclude/hooks.hfor a complete list.

Deferred functions allow you to call a function after a delay specified in uSecwithout blocking. Deferred functions run in the HOOKS task. Here is an exampleof an interrupt handler. The deferred function allows the handler itself to belightweight. Delaying the deferred call by 30 mSec also allows the interrupt tobe 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);}

While there is no heap, there is a shared memory buffer that can be borrowedtemporarily (ideally before a context switch). The size of the buffer depends onthe EC chip being used. The buffer can only be used by one task at a time. Seecommon/shared_mem.cfor more information. At present (May 2014), this buffer is only used by debugcommands.

If you see a bug or want to make an improvement to the EC code please file anissue atcrbug.com/new. It's best to discuss the changeyou want to make first on an issue report to make sure the EC maintainers areon-board before digging into the fun part (writing code).

In general, make more, smaller changes that solve single problems rather thanbigger changes that solve multiple problems. Smaller changes are easier andfaster to review. When changing common code shared between boards along withboard specific code, please split the shared code change into its own changelist (CL). The board specific CL can depend on the shared code CL.

The EC code follows theLinux Kernel style guide.Please adopt the same style used in the existing code. Use tabs, not spaces, 80column lines etc...

Other style notes:

1. Globals should either bestatic orconst. Use them for persistent statewithin a file or for constant data (such as the GPIO list in board.c). Donot use globals to pass information between modules without accessors. Formodule scope, accessors are not needed.

2. If you add a new#define config option to the code, please document it ininclude/config.hwith an#undef statement and descriptive comment.

3. The Chromium copyright header must be included at the top of new files inall 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. */

Prior to uploading a new change for review, please run the EC unit tests with:

(chroot) $ make -j buildall

(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 torun these checks manually first, commit your change locally then run thefollowing command from within the chroot and while in thesrc/platform/ecdirectory:

(chroot) $~/trunk/src/repohooks/pre-upload.py

The pre-submit checks include checking the commit message. Commit messages musthave aBUG,BRANCH, andTEST line along withSigned-off-by: First Last <name@company.com>. The signed-off-by line is a statement that you have writtenthis code and it can be contributed under the terms of theLICENSE file.

Please refer to existing commits (git log) to see the proper format for thecommit message. If you have configured git properly, runninggit commit withthe-s argument will add the Signed-off-by line for you.

While addingprintf statements can be handy, there are some other options fordebugging problems during development.

There may already be a message on the serial console that indicates yourproblem. If you don’t have a servo connected, theectool console command willshow the current contents of the console buffer (the buffer’s size varies by ECchip). This log persists across warm resets of the host but is cleared if the ECresets. Theectool console command will only work when the EC is not writeprotected.

If you have interactive access to the serial console via servo, you can use theread wordrw and write wordww commands to peek and poke the EC's RAM. Youmay need to refer to the datasheet for your EC chip or the disassembled code tofind the memory address you need. There are other handy commands on the serialconsole to read temperatures, view the state of tasks (taskinfo) which may help.Typehelp for a list.

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 :000000ffr4 :ffffffed r5 :00000799 r6 :0000f370 r7 :00000000r8 :00000001 r9 :00000003 r10:20002fe0 r11:00000000r12:00000008 sp :20000fd8 lr :000012e1 pc :0000105e

The most interesting information are the program counter (pc) and the linkregister (return address,lr) as they give you an indication of what code theEC was running when the panic occurred.HANDLER EXCEPTIONS indicate the panicoccurred while servicing an interrupt.PROCESS EXCEPTIONS occur in regulartasks. If you see “Imprecise data bus error” listed, the program counter valueis incorrect as the panic occurred when flushing a write buffer. If using acortex-m based EC, addCONFIG_DEBUG_DISABLE_WRITE_BUFFER to your board.h todisable write buffering (with a performance hit) to get a “Precise bus error”with an accurate program counter value.

If you have a program counter address you need to make sense of, you cangenerate the assembly code for the EC by checking out the code at the matchingcommit for your binary (ectool version) and running:

(chroot) $ make BOARD=$board dis

This outputs two files with assembly code:

build/$board/RO/ec.RO.disbuild/$board/RW/ec.RW.dis

which (in the case of the LM4 and STM32) are essentially the same, but the RWaddresses are offset.

SeeFirmware Write Protection.

The read-only and read-write sections of the EC firmware each have a versionstring. This string tells you the branch and last change at which the firmwarewas built. On a running machine, runectool version from a shell to seeversion information:

RO version:    peppy_v1.5.103-7abb4f7RW version:    peppy_v1.5.129-cd1a1e9Firmware copy: RWBuild info:    peppy_v1.5.129-cd1a1e9 2014-03-07 17:18:27 @build120-m2

You can also run theversion command on the EC serial console for a similaroutput.

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 tagfor 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).

Runutil/getversion.sh to see the current version string. The board name ispassed as an environment variableBOARD:

(chroot) $ BOARD="cheese" ./util/getversion.sh

cheese_v1.1.1755-4da9520