# zephyrproject-rtos/hal_ambiq architecture

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

- Interactive diagram: https://gitdiagram.com/zephyrproject-rtos/hal_ambiq
- Repository: https://github.com/zephyrproject-rtos/hal_ambiq

## Overview

##### Main Components
- CMSIS Layer – Represented by the "CMSIS" directory. This holds the ARM CMSIS-compliant header files and system configuration files (for example, apollo3.h, system_apollo3.h, etc.) that define the low-level hardware registers and system startup information.
- MCU/HAL Implementations – The "mcu" directory includes subdirectories for different Ambiq chips (apollo3, apollo3p, apollo4p). Each of these contains:
- HAL drivers (in hal subdirectories) for various peripherals such as ADC, BLE, GPIO, flash, etc.
- Register definitions (in the regs directories) that directly interact with hardware.
- Build and configuration scripts like Makefiles and CMakeLists.txt to compile the library.
- Device Tree Sources – The "dts" directory contains board/SoC-specific definitions for each chip family (apollo3, apollo3p, apollo4p). This is useful for configuration, especially if integrating with a framework like Zephyr.
- Additional Components – The "components" directory includes additional modules such as the Bluetooth support layer, which might act as an extension on top of the HAL services.
- Utilities – The "utils" directory provides utility functions (e.g., delay, string operations, debug routines) that support and complement the HAL functionality.
- Zephyr Integration – The "zephyr" directory suggests that there is some integration or module description for usage within the Zephyr RTOS ecosystem.

##### Relationships and Interactions
- The CMSIS layer forms the foundation by providing the core definitions and system startup files on which the MCU-specific HAL drivers depend.
- The MCU/HAL subdirectories for each device utilize both CMSIS definitions and direct register access to implement functionalities for peripherals.
- The dts files describe hardware configuration that may be used by build systems or by higher-level frameworks (for example, Zephyr uses device-tree data).
- Components such as Bluetooth support are built on top of the HAL drivers, meaning they call these routines to interact with the device peripherals.
- Utility functions are shared amongst various modules and provide common support to both HAL functions and external libraries.
- The Zephyr integration module indicates that the HAL is either being used as a native layer for Zephyr or is designed to be compatible with the Zephyr OS abstractions.

##### Recognize Architectural Patterns and Technologies
- At the bottom: CMSIS and MCU-specific low-level drivers.
- In the middle: HAL drivers and supporting device tree configuration.
- At the top: Component-specific functions (like Bluetooth), application utilities, and integration with external frameworks (Zephyr).
- Modularity – Each MCU family (Apollo3, Apollo3p, Apollo4p) is isolated in its specific directory, ensuring that branches of the architecture remain decoupled.
- Use of Build/Configuration Tools – The presence of Makefiles and CMakeLists.txt in multiple folders indicates the modular compilation and build process.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Low-Level Layer
    subgraph "Hardware Abstraction Layer"
        CMSIS["CMSIS Layer"]:::cmsis
        subgraph "MCU HAL Implementations"
            Apollo3["Apollo3"]:::mcu
            Apollo3p["Apollo3p"]:::mcu
            Apollo4p["Apollo4p"]:::mcu
        end
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        DTS["Device Tree Configurations"]:::dts
    end

    %% High-Level Components
    subgraph "High-Level Components"
        BT["Bluetooth Support"]:::component
        UTIL["Utilities"]:::util
        ZEPHYR["Zephyr Integration Module"]:::zephyr
    end

    %% Relationships: MCU HAL depend on CMSIS
    Apollo3 -->|"Uses"| CMSIS
    Apollo3p -->|"Uses"| CMSIS
    Apollo4p -->|"Uses"| CMSIS

    %% Relationships: Device Tree Configures MCU HAL
    DTS -->|"Configures"| Apollo3
    DTS -->|"Configures"| Apollo3p
    DTS -->|"Configures"| Apollo4p

    %% Relationships: Zephyr Integration integrates with MCU HAL
    ZEPHYR -->|"Integrates"| Apollo3
    ZEPHYR -->|"Integrates"| Apollo3p
    ZEPHYR -->|"Integrates"| Apollo4p

    %% Relationships: Bluetooth Support interfaces with MCU HAL
    BT -->|"Interfaces"| Apollo3
    BT -->|"Interfaces"| Apollo3p
    BT -->|"Interfaces"| Apollo4p

    %% Relationships: Utilities support both MCU HAL and Bluetooth
    UTIL -->|"Supports"| Apollo3
    UTIL -->|"Supports"| Apollo3p
    UTIL -->|"Supports"| Apollo4p
    UTIL -->|"Supports"| BT

    %% Relationships: Device Tree also configures Zephyr Integration 
    DTS -->|"Configures"| ZEPHYR

    %% Click Events
    click CMSIS "https://github.com/zephyrproject-rtos/hal_ambiq/tree/main/CMSIS/AmbiqMicro/Include"
    click Apollo3 "https://github.com/zephyrproject-rtos/hal_ambiq/tree/main/mcu/apollo3"
    click Apollo3p "https://github.com/zephyrproject-rtos/hal_ambiq/tree/main/mcu/apollo3p"
    click Apollo4p "https://github.com/zephyrproject-rtos/hal_ambiq/tree/main/mcu/apollo4p"
    click DTS "https://github.com/zephyrproject-rtos/hal_ambiq/tree/main/dts"
    click BT "https://github.com/zephyrproject-rtos/hal_ambiq/tree/main/components/bluetooth"
    click UTIL "https://github.com/zephyrproject-rtos/hal_ambiq/tree/main/utils"
    click ZEPHYR "https://github.com/zephyrproject-rtos/hal_ambiq/tree/main/zephyr"

    %% Styles
    classDef cmsis fill:#A7D7C5,stroke:#333,stroke-width:2px;
    classDef mcu fill:#A2C4C9,stroke:#333,stroke-width:2px;
    classDef dts fill:#FFD966,stroke:#333,stroke-width:2px;
    classDef component fill:#F4B183,stroke:#333,stroke-width:2px;
    classDef util fill:#C9DAF8,stroke:#333,stroke-width:2px;
    classDef zephyr fill:#D5A6BD,stroke:#333,stroke-width:2px;
```
