# system76/ec architecture

> Architecture diagram of the GitHub repository system76/ec, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/system76/ec
- Repository: https://github.com/system76/ec

## Overview

System76 EC is embedded-controller firmware for System76 laptops, with companion host tools for EC access and firmware programming. Its principal product role is handling laptop hardware functions—power, charging, thermal sensing, keyboard, and related controller interfaces—while host-side tools provide access and flashing support. The tree exposes these major firmware domains and tool components, but the sampled sources do not show the firmware’s top-level dispatch wiring or the ectool CLI flow; those connections are therefore not inferred. The graph focuses on relationships directly visible in excerpts.

Main entry points: [`src/drivers/usbpd/tps65987.c`](https://github.com/system76/ec/blob/master/src/drivers/usbpd/tps65987.c) (USB-PD driver), [`tools/mega2560/src/parallel.c`](https://github.com/system76/ec/blob/master/tools/mega2560/src/parallel.c) (Parallel interface), [`src/drivers/dgpu/nvidia.c`](https://github.com/system76/ec/blob/master/src/drivers/dgpu/nvidia.c) (GPU telemetry), [`tools/mega2560/src/main.c`](https://github.com/system76/ec/blob/master/tools/mega2560/src/main.c) (Programmer entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_firmware["EC firmware"]
  node_ecmain["EC application<br/>[main.c]"]
  node_power["Power management<br/>[intel.c]"]
  node_battery["Battery charging<br/>[battery.c]"]
  node_fan["Fan control<br/>[interp.c]"]
  node_keyboard["Keyboard scan<br/>[kbscan.c]"]
  node_keymap["Keymaps<br/>[keymap.c]"]
  node_flash["Flash handling<br/>[main.c]"]
end

subgraph group_hardware["Hardware drivers"]
  node_usbpd["USB-PD driver<br/>[tps65987.c]"]
  node_dgpu["GPU telemetry<br/>[nvidia.c]"]
  node_security["Flash security<br/>[security.c]"]
  node_i2c["EC I2C bus<br/>[i2c.c]"]
end

subgraph group_hosttools["Host tools"]
  node_ectool["EC command tool<br/>[main.rs]"]
  node_lpc["Linux LPC access<br/>[linux.rs]"]
  node_timeout["Command timeout<br/>[timeout.rs]"]
end

subgraph group_programmer["Programmer"]
  node_mega["Programmer entry<br/>[main.c]"]
  node_parallel["Parallel interface<br/>[parallel.c]"]
  node_gpio["Programmer GPIO<br/>[gpio.h]"]
  node_uart["Programmer UART<br/>[uart.h]"]
end

node_laptop(("Laptop hardware"))

node_usbpd -->|"reads and writes"| node_i2c
node_usbpd -->|"checks power state"| node_power
node_usbpd -->|"updates charge limit"| node_battery
node_dgpu -->|"reads temperature"| node_i2c
node_dgpu -->|"checks power state"| node_power
node_security -->|"sets security GPIO"| node_laptop
node_mega -->|"starts interface"| node_parallel
node_mega -->|"initializes console"| node_uart
node_parallel -->|"controls pins"| node_gpio
node_parallel -->|"serial transfers"| node_uart
node_lpc -->|"waits with timeout"| node_timeout

click node_ecmain "https://github.com/system76/ec/blob/master/src/app/main/main.c"
click node_power "https://github.com/system76/ec/blob/master/src/app/main/power/intel.c"
click node_battery "https://github.com/system76/ec/blob/master/src/app/main/battery.c"
click node_fan "https://github.com/system76/ec/blob/master/src/app/main/fan/interp.c"
click node_keyboard "https://github.com/system76/ec/blob/master/src/app/main/kbscan.c"
click node_keymap "https://github.com/system76/ec/blob/master/src/common/keymap.c"
click node_flash "https://github.com/system76/ec/blob/master/src/app/main/flash/main.c"
click node_usbpd "https://github.com/system76/ec/blob/master/src/drivers/usbpd/tps65987.c"
click node_dgpu "https://github.com/system76/ec/blob/master/src/drivers/dgpu/nvidia.c"
click node_security "https://github.com/system76/ec/blob/master/src/drivers/security/security.c"
click node_i2c "https://github.com/system76/ec/blob/master/src/ec/ite/i2c.c"
click node_ectool "https://github.com/system76/ec/blob/master/tools/system76_ectool/src/main.rs"
click node_lpc "https://github.com/system76/ec/blob/master/tools/system76_ectool/src/access/lpc/linux.rs"
click node_timeout "https://github.com/system76/ec/blob/master/tools/system76_ectool/src/timeout.rs"
click node_mega "https://github.com/system76/ec/blob/master/tools/mega2560/src/main.c"
click node_parallel "https://github.com/system76/ec/blob/master/tools/mega2560/src/parallel.c"
click node_gpio "https://github.com/system76/ec/blob/master/tools/mega2560/src/gpio.h"
click node_uart "https://github.com/system76/ec/blob/master/tools/mega2560/src/uart.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ecmain,node_power,node_battery,node_fan,node_keyboard,node_keymap,node_flash toneBlue
class node_usbpd,node_dgpu,node_security,node_i2c toneAmber
class node_ectool,node_lpc,node_timeout toneMint
class node_mega,node_parallel,node_gpio,node_uart toneRose
class node_laptop toneIndigo
```

## Components

### EC firmware

- [EC application](https://github.com/system76/ec/blob/master/src/app/main/main.c): `src/app/main/main.c`
- [Power management](https://github.com/system76/ec/blob/master/src/app/main/power/intel.c): `src/app/main/power/intel.c`
- [Battery charging](https://github.com/system76/ec/blob/master/src/app/main/battery.c): `src/app/main/battery.c`
- [Fan control](https://github.com/system76/ec/blob/master/src/app/main/fan/interp.c): `src/app/main/fan/interp.c`
- [Keyboard scan](https://github.com/system76/ec/blob/master/src/app/main/kbscan.c): `src/app/main/kbscan.c`
- [Keymaps](https://github.com/system76/ec/blob/master/src/common/keymap.c): `src/common/keymap.c`
- [Flash handling](https://github.com/system76/ec/blob/master/src/app/main/flash/main.c): `src/app/main/flash/main.c`

### Hardware drivers

- [USB-PD driver](https://github.com/system76/ec/blob/master/src/drivers/usbpd/tps65987.c): `src/drivers/usbpd/tps65987.c`
- [GPU telemetry](https://github.com/system76/ec/blob/master/src/drivers/dgpu/nvidia.c): `src/drivers/dgpu/nvidia.c`
- [Flash security](https://github.com/system76/ec/blob/master/src/drivers/security/security.c): `src/drivers/security/security.c`
- [EC I2C bus](https://github.com/system76/ec/blob/master/src/ec/ite/i2c.c): `src/ec/ite/i2c.c`

### Host tools

- [EC command tool](https://github.com/system76/ec/blob/master/tools/system76_ectool/src/main.rs): `tools/system76_ectool/src/main.rs`
- [Linux LPC access](https://github.com/system76/ec/blob/master/tools/system76_ectool/src/access/lpc/linux.rs): `tools/system76_ectool/src/access/lpc/linux.rs`
- [Command timeout](https://github.com/system76/ec/blob/master/tools/system76_ectool/src/timeout.rs): `tools/system76_ectool/src/timeout.rs`

### Programmer

- [Programmer entry](https://github.com/system76/ec/blob/master/tools/mega2560/src/main.c): `tools/mega2560/src/main.c`
- [Parallel interface](https://github.com/system76/ec/blob/master/tools/mega2560/src/parallel.c): `tools/mega2560/src/parallel.c`
- [Programmer GPIO](https://github.com/system76/ec/blob/master/tools/mega2560/src/gpio.h): `tools/mega2560/src/gpio.h`
- [Programmer UART](https://github.com/system76/ec/blob/master/tools/mega2560/src/uart.h): `tools/mega2560/src/uart.h`

### Other components

- **Laptop hardware**

## Connections

- USB-PD driver → EC I2C bus: reads and writes (evidence: `src/drivers/usbpd/tps65987.c`)
- USB-PD driver → Power management: checks power state (evidence: `src/drivers/usbpd/tps65987.c`)
- USB-PD driver → Battery charging: updates charge limit (evidence: `src/drivers/usbpd/tps65987.c`)
- GPU telemetry → EC I2C bus: reads temperature (evidence: `src/drivers/dgpu/nvidia.c`)
- GPU telemetry → Power management: checks power state (evidence: `src/drivers/dgpu/nvidia.c`)
- Flash security → Laptop hardware: sets security GPIO (evidence: `src/drivers/security/security.c`)
- Programmer entry → Parallel interface: starts interface (evidence: `tools/mega2560/src/main.c`)
- Programmer entry → Programmer UART: initializes console (evidence: `tools/mega2560/src/main.c`)
- Parallel interface → Programmer GPIO: controls pins (evidence: `tools/mega2560/src/parallel.c`)
- Parallel interface → Programmer UART: serial transfers (evidence: `tools/mega2560/src/parallel.c`)
- Linux LPC access → Command timeout: waits with timeout (evidence: `tools/system76_ectool/src/access/lpc/linux.rs`)
