How dasharo/ec works
Overall Layers and Components
• Central Firmware Core – the “heart” of the embedded controller firmware that runs on the target hardware.
• Hardware Abstraction Layer (HAL) – representing architecture-specific code (see the src/arch directory that includes implementations for 8051 and AVR). This layer abstracts details such as delays, I2C transfers, and timer operations.
• Board Support Package (BSP) – the board-specific code found under src/board. Each board family (for System76, Arduino variants, Clevo, and novacustom boards) provides its own initialization, GPIO handling, and peripheral support.
• Common Code and Libraries – located in src/common, which provides shared functionalities (i2c.c, keymap handling, versioning, etc.) that are used across boards and architectures.
• Embedded Controller (EC) Specific Code – in src/ec, where you see separate directories for atmega and ITE implementations. This is where the core logic for managing power, events, and peripheral communications lives.
• Keyboard Subsystem – found under src/keyboard. This area manages board-specific keymap customizations and layouts for different System76 keyboard variations.
• Host Tools and Utilities – the tool directory contains Rust-based utilities for accessing and interacting with the EC (for flashing, firmware inspection, debugging, etc.), while additional scripts (in scripts/) support tasks such as linting, flashing (ectool.sh, power.sh), and more.
• Build and Deployment – the top-level Makefile and additional build scripts (e.g., build.sh) orchestrate the build process for the firmware image.
Relationships and Data Flow
• The Build/Deployment layer (Makefile, build.sh) pulls in source from each of the above components to generate firmware for a specific board (as specified with BOARD=system76/<model>).
• The HAL (src/arch) provides low-level interface calls to the hardware, which are consumed by both the board support and EC core layers.
• The BSP (src/board) uses the HAL to initialize and manage board-specific features (GPIOs, I2C, battery management, etc.) and then interfaces with the common and EC layers.
• The EC-specific code (src/ec) implements the core logic for the controller, interfacing with common routines for configuration, interrupts, and communications.
• The Keyboard subsystem ties into the EC’s functionality to offer customizable keymaps and integrates with board operations via board-specific keymap headers.
• External tools (in tool/ and the various scripts) interact with the firmware through flashing/updating procedures or simulate operations (e.g., ecsim and ecspy).
Architectural Patterns and Design Principles
• Modularity by Separation of Concerns: Different directories represent clear modules (architecture, board-specific, common, EC, keyboard). This modular separation is key for maintainability and for supporting multiple hardware targets.
• Layered Abstraction: The firmware is layered from hardware-specific code up to board-level and core controller logic.
• Tooling Integration: The inclusion of a Rust-based host tool (alongside many shell scripts) underlines the integration of development and deployment utilities that interact with the firmware, ensuring debugging and flashing can be performed outside the microcontroller.