• Embedded Software Engineer @ National Instruments
• Work on the USRP
• Very small team, focus on open-source
• Try to work upstream first (U-Boot, Kernel, ...)

• Firmware of Embedded Controllers
• License: 3 Clause BSD
• Currently supported ports to MCU with
  • ARM Cortex M{0,3,4}
  • AndeStar NDS32
  • Minute-IA (x86)
• Kernel Coding style!

• Configuration options are defined and documented in include/config.h
• Configuration options exist for debug levels, modules, features, etc
• Each board has a board.h file in board/<board>/board.h
• Datastructures get initialized in board/<board>/board.c

• Have individual stacks (250-640 bytes)
• Interrupt driven task switching
• Priority based preemption
• Mutexes
• Timers
• Events
• NO heap (malloc() / free())

• Common stuff that includes state machines is grouped into modules
• They are self contained, and often optional compile-time options
• Each module will have init function, setup statemachine
• Declare hook with initialization priority
• Examples: I2C, SPI, ADC, CHIPSET, DMA, GPIO ....

• ccprintf() and similar functions
• Show selective debug via 'channels'
• Allows for easy debug of a lot of commands
• Adding custom commands is fairly simple
• MCU UART or USB possible

• Packet based, i.e. header w/checksum + data
• Two versions of protocol v2 vs v3
• Busses have very different semantics, protocol hides that
• Some EC's speak both versions !?

• older version, send commands as follows
  • Byte 0: EC_CMD_VERSION + (command version)
  • Byte 1: Command number
  • Byte 2: Length of parameters (N)
  • Byte 3..N+2: Parameters
  • Byte N+3: 8 bit checksum over bytes 0 .. N+2
• with a response like
  • Byte 0: Result code
  • Byte 1: Length of params (M)
  • Byte 2:M+1: Parameters
  • Byte M+2: checksum

• SPI
  • Officially recommended, Fast
  • Requires decent SPI controller
• I2C
  • Requires I2C controller that can do repeated start
  • Drawback: Slow
• LPC
  • Drawback: Limited subset of SoCs can do it

• What do you want the EC to do?
• Minimal recommended set of peripherals
  • 1+ SPI, 1+ I2C
  • HW PWM
  • Lots of GPIO
  • DMA channels for SPI/I2C
  • UART
• Optional: USB (Console, DFU...), UARTs

• Pins are either
  • Inputs / outputs (strap pins, leds, write-protect)
  • Interrupt sources (external reset, buttons, switches ...)
  • Assigned to alternate functions (I2C, SPI, timer, pwm ...)
  • pin assignment and muxing happens in gpio.inc, transformed by build

• Mostly generic, some EC MCU specific flags
• Name, Pin, Flags (i.e. Level on reset, Pull-ups, Open Drain ...)
• see include/gpio.h

GPIO(WP_L,        PIN(B, 4), GPIO_INPUT)
[...]
GPIO(BAT_LED_RED, PIN(B, 11), GPIO_OUT_HIGH)
[...]
GPIO(EC_INT_L,    PIN(B, 9),  GPIO_OUT_LOW)

• Again, mostly generic
• Name, Pin, Flags (i.e. Edge, Pull-ups, Open Drain ...), handler
• examples: board/*/gpio.inc

GPIO_INT(SPI1_NSS,   PIN(A, 4),  GPIO_INT_BOTH, spi_event)
GPIO_INT(AC_PRESENT, PIN(C, 6),  GPIO_INT_BOTH | GPIO_PULL_UP, extpower_interrupt)
GPIO_INT(SUSPEND_L,  PIN(C, 7),  GPIO_INT_BOTH, power_signal_interrupt)

• Defined by architecture
• PIN_MASK(A,0x00f0) = PA4, PA5, PA6, PA7
• Alternate number 0 (from datasheet)
• Module that will deal with it (SPI)
• Flags same as before

ALTERNATE(PIN_MASK(A, 0x00f0), 0, MODULE_SPI,  0)
ALTERNATE(PIN_MASK(A, 0x0600), 1, MODULE_UART, 0)
ALTERNATE(PIN_MASK(B, 0x00c0), 1, MODULE_I2C,  0)

• Some generic code expects certain signals to be there (WP_L, ...)
• Makes stuff work, by pretending UNIMPLEMENTED GPIOs exist
• E.g. use generic LED code, but you have only one LED
• Flags same as before

UNIMPLEMENTED(WP_L)
UNIMPLEMENTED(LED_BAT)

• Most modern SoCs need certain sequence
• Usually goes like this
  • Turn on X volt rail
  • Wait max time Y for power good signal
  • If timeout happened, handle it, otherwise proceed
  • power subfolder contains sequences for common chromebooks
    • RK3399, RK3288-C
    • Apollolake, Baytrail, Haswell, Skylake
    • Tegra
    • Mediatek

• Implement statemachine
• Use ACPI S/G states G3/S5/S3/S0 ...
• Describe what needs to happen to proceed, and how to handle failure

case POWER_S0:
	if (!power_has_signals(IN_PGOOD_S3) ||
	    forcing_shutdown ||
	    !(power_get_signals() & IN_SUSPEND_DEASSERTED))
		return POWER_S0S3;
	[...]
	if (power_wait_signals_timeout(IN_PGOOD_AP | IN_PGOOD_SYS,
				       PGOOD_AP_DEBOUNCE_TIMEOUT)
				       == EC_ERROR_TIMEOUT)
	return POWER_S0S3;

• I2C (Master) API
  • i2c_readX() / i2c_writeX() ... X = 8,16,32
• I2C tunnel
  • Simulates i2c bus over SPI/I2C/LPC connection
  • Allows host to access slave devices
  • Might come in handy
• SPI (Master) API
  • spi_transaction() data, txlen, rxdata, rxlen
  • spi_transaction_async() same, but hand over to DMA
  • supports (some) SPI flash devices

• I like to work with upstream stuff
• Chromebooks use Linux Kernel, so that works really well
• Most use depthcharge instead of u-boot, code gets less flight time
• I'm still working on adding software sync to u-boot
• I didn't look at adding verified boot

	&spi0 {
		ec: embedded-controller@0 {
			reg = <0x0>;
			compatible = "google,cros-ec-spi";
			interrupts = <14 IRQ_TYPE_LEVEL_LOW>;
			interrupt-parent = <&gpio0>;
			wakeup-source;
		};
	};
      

• Nothing too exciting, MFD device
• MFD subdevices include
  • I2C tunnel (i2c bus)
  • PWM channels (pwm)
  • Battery (power-supply)
  • Lightbar
• Character device allowing for ioctl(2) for ectool / flashrom
• Code mostly
  • drivers/mfd/cros_ec_{i2c,spi}.c
  • drivers/platform/chrome/

• Useful tool to test and inspect
• Uses characterdev with ioctl(2) to
  • GPIO state
  • Firmware Versions
  • Reboot the EC
  • Flash info
  • Read / write Firmware
  • Send commands, useful for development
  • ...

• Nothing too exciting, misc device
• Functionality exposed
  • I2C tunnel (i2c bus integrated in dm)
  • Reading / Writing firmware (crosec read / write)
  • Getting flash information (crosec flashinfo)
  • Reboot EC into RO / RW (crosec reboot RO / RW)
• Code mostly
  • drivers/misc/cros_ec_{i2c,spi}.c
  • cmd/cros_ec.c

• Mostly Google driven development
• Roadmap very nebulous
• Code review via gerrit :(
• Mailing list very low traffic
• Very receptive to patches, quick reviews