# dasharo/ec architecture

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

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

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Deployment & Build Subgraph
    subgraph "Deployment & Build"
        BuildMake["Makefile"]
        BuildScript["build.sh"]
    end

    %% External Tools Subgraph
    subgraph "External Tools"
        RustTools["Rust Host Tools (tool)"]
        ShellScripts["Script Utilities (scripts)"]
    end

    %% Firmware Components Subgraph
    subgraph "Firmware Components"
        HAL["HAL (src/arch: 8051, AVR)"]
        BSP["BSP (src/board: System76, Arduino, Clevo, novacustom)"]
        EC["EC Specific Code (src/ec: ite, atmega)"]
        Common["Common Libraries (src/common)"]
        Core["Central Firmware Core"]
        Keyboard["Keyboard Subsystem (src/keyboard)"]
    end

    %% Relationships for Deployment & Build and External Tools
    BuildMake -->|"builds"| Core
    BuildScript -->|"builds"| Core
    RustTools -->|"flashes/debugs"| Core
    ShellScripts -->|"runs scripts on"| Core

    %% Firmware Relationships
    HAL -->|"interfaces"| BSP
    HAL -->|"provides low-level calls to"| EC
    BSP -->|"initializes peripherals for"| EC
    Common -->|"shares functionality with"| EC
    EC -->|"integrates into"| Core
    Common -->|"integrates into"| Core
    Keyboard -->|"customizes input for"| Core

    %% Class definitions for color styling
    class BuildMake,BuildScript deployment
    class RustTools,ShellScripts external
    class HAL,BSP,EC,Common,Core,Keyboard firmware

    %% Styles for classes
    classDef deployment fill:#cce5ff,stroke:#2a72bb,stroke-width:2px;
    classDef external fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef firmware fill:#fff3cd,stroke:#856404,stroke-width:2px;

    %% Click events
    click BuildMake "https://github.com/dasharo/ec/tree/master/Makefile"
    click BuildScript "https://github.com/dasharo/ec/blob/master/build.sh"
    click RustTools "https://github.com/dasharo/ec/tree/master/tool"
    click ShellScripts "https://github.com/dasharo/ec/tree/master/scripts"
    click HAL "https://github.com/dasharo/ec/tree/master/src/arch"
    click BSP "https://github.com/dasharo/ec/tree/master/src/board"
    click EC "https://github.com/dasharo/ec/tree/master/src/ec"
    click Common "https://github.com/dasharo/ec/tree/master/src/common"
    click Keyboard "https://github.com/dasharo/ec/tree/master/src/keyboard"
```
