Framework Laptop Embedded Controller (EC)

Introduction

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

Warning

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.

Building

Environment Configuration

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-config
sudo apt-get install gawk 

Framework Laptop EC

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

| Laptop Generation | Board Name | | --- | --- | | Intel 11th Gen Core Processors | hx20 | | Intel 12th Gen Core Processors | hx30 | | Intel 13th Gen Core Processors | hx30 |

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 is build/hx20/ec.bin which can be flashed to the EC SPI flash ROM.

EC Flash configuration

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 bootsector
00001000:00039fff lfwro
00040000:00078fff rw

EC background information

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/hx20
chip/mchp

EC Boot process

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.

EC Debug

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.

|Pin|Description| | --- | --- | | 1 | EC_VCC_3.3 | | 2 | TDI | | 3 | TMS | | 4 | CLK | | 5 | TDO | | 6 | UART_TX | | 7 | UART_RX | | 8 | | | 9 | EC_RESETI | | 10 | GND |

Background

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.

---

Embedded Controller (EC)

[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.

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 and video from the 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 page for a list.
2. 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.
3. A servo debug board (and header) is highly recommended for serial console and JTAG access to the EC.
4. 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 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 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.

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:

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

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:

git log --left-right --graph -