EC Firmware Devicetree Generator (zephyr_dtsi)

zephyr_dtsi is a tool for generating Zephyr EC Devicetree configuration files (generated.dtsi) for Chromium OS EC board bringup.

It ingests hardware pinout CSV spreadsheets prepared by board design teams and outputs a self-contained Zephyr Devicetree overlay containing named GPIOs, ADC channels, PWM channels, I2C ports, TACH channels, and Keyboard matrix configurations.

Features

• Variant Pinout Filtering (--pin-col): Selects variant-specific pin mapping columns directly from multi-variant board spreadsheets (e.g., --pin-col="NPCX99 (NPCX)" or --pin-col="IT82002 (ITE)").
• Pin Maps: Built-in chip pin maps are stored as embedded JSON data files (data/chips/*.json) and can be extended dynamically at runtime using --chip-data-dir.

Supported EC Chips

CLI Reference

./firmweaver dtsi --chip=<chip_name> --csv=<path_to_csv> [options]

Options

Usage Examples

1. Generating Devicetree Using the Bundled Test Example

To test generating a generated.dtsi file from the example test CSV included in zephyr_dtsi/test/:

For NPCX (using npcx99 chip):

./firmweaver dtsi --chip=npcx99 \
               --csv=zephyr_dtsi/test/ExampleEcPinout.csv \
               --pin-col="NPCX99 (NPCX)" \
               --output=zephyr_dtsi/test/generated_npcx.dtsi

For ITE (using it82002 chip):

./firmweaver dtsi --chip=it82002 \
               --csv=zephyr_dtsi/test/ExampleEcPinout.csv \
               --pin-col="IT82002 (ITE)" \
               --output=zephyr_dtsi/test/generated_ite.dtsi

2. Generating Devicetree for Board Variants

To generate a generated.dtsi file for the Fatcat RVP (NPCX chip):

./firmweaver dtsi --chip=npcx99 \
               --csv=/path/to/fatcat.csv \
               --pin-col="NPCx9 RVP" \
               --output=/path/to/platform/ec/zephyr/program/fatcat/generated_npcx.dtsi

To generate for the Fatcat ITE variant:

./firmweaver dtsi --chip=it82002 \
               --csv=/path/to/fatcat.csv \
               --pin-col="IT82002 Ref" \
               --output=/path/to/platform/ec/zephyr/program/fatcat/generated_ite.dtsi

3. Building and Running Binary

Build the standalone zephyr_dtsi binary from the repository root:

go build -o firmweaver .
./firmweaver dtsi --chip=it82202ax --csv=/path/to/hylia.csv --output=generated.dtsi

4. Adding Custom Chip Pin Maps

To register custom EC chip models at runtime without modifying code:

1. Create a JSON file (e.g. custom_chip.json):

   {
     "name": "custom_chip",
     "aliases": ["custom_v1"],
     "pin_map": {
       "A1": "GPIOB4/I2C0_SDA0",
       "A2": "GPIOB5/I2C0_SCL0"
     }
   }
   

2. Pass the directory containing your JSON file to --chip-data-dir:

   ./firmweaver dtsi --chip-data-dir=/path/to/custom_chips --chip=custom_chip --csv=board.csv
   

5. Running Tests

Run unit tests across the zephyr_dtsi tool:

go test -v ./zephyr_dtsi/...