# ambiqmicro/lv_port_ambiq architecture

> Architecture diagram of the GitHub repository ambiqmicro/lv_port_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/ambiqmicro/lv_port_ambiq
- Repository: https://github.com/ambiqmicro/lv_port_ambiq

## Overview

##### Main Components
- Hardware/SoC – Ambiq Apollo series microcontroller that is the target hardware.
- MCU Abstraction/Drivers – The BSP and CMSIS directories (including bsp/CMSIS, bsp/mcu, bsp/boards, bsp/devices, bsp/utils) provide the low-level hardware abstraction layer (HAL) for MCU peripherals, GPIO, ADC, timers, etc.
- GPU/Accelerator Module – The bsp/gpu directory includes the NemaGFX SDK. This component handles GPU acceleration for rendering graphical content.
- LVGL Core – The LVGL library (inferred from “LVGL_V8” and the lvgl_ambiq_demo & lvgl_ambiq_porting directories) that provides the graphics API and widgets.
- And Touch Drivers – Drivers for displays and touchpads, which are part of the lvgl_ambiq_porting (and related board drivers in bsp/boards) that interface with the hardware.
- RTOS & Middleware – The modules directory includes FreeRTOS (the real-time OS providing task management, scheduling, etc.) and FatFs (for file system support if needed).
- Application Layer – Demo applications (like lvgl_ambiq_demo) that bring together the LVGL core, GPU acceleration, and underlying board drivers to run test or production UI tasks.

##### Relationships & Interactions
- The Application/Demo layer makes calls into LVGL to create and manipulate graphical interfaces.
- LVGL in turn relies on the GPU acceleration layer for efficient rendering. This GPU layer is implemented via the NemaGFX SDK, which interacts with low-level hardware.
- The LVGL port (lv_port_ambiq) and porting code bridge the gap between LVGL’s generic hardware abstraction and the Ambiq-specific drivers.
- Underneath these layers, the MCU Abstraction/Drivers (BSP) manage low-level hardware details (CMSIS, HAL routines, board-specific configurations), providing interfaces for display, touch, and peripheral communications.
- The Real-Time Operating System (FreeRTOS) schedules tasks (including GUI tasks) and facilitates concurrency. Middleware like FatFs supports file system operations if the UI or data logging requires storage access.
- All components communicate via well-defined APIs. For example, LVGL calls a display driver function from the board layer, which in turn invokes the GPU or MCU HAL call to write to the display hardware.

##### Important Architectural Patterns & Design Principles
- Layered Architecture – The project clearly separates hardware-specific layers (BSP, MCU HAL) from the graphics middleware (LVGL) and application (demo/porting code).
- Modular Design – Each major functionality (GPU acceleration, touch input, file systems) is encapsulated in its own module or directory. This makes the system extensible and easier to maintain.
- Abstraction and Portability – The LVGL porting code abstracts the underlying hardware, allowing LVGL’s generic interface to be used on the Ambiq platform with minimal changes.

##### Relevant Technologies, Frameworks, and Libraries
- LVGL (LVGL_V8) – The core graphics library.
- NemaGFX – The GPU acceleration SDK within bsp/gpu for optimized rendering.
- CMSIS – ARM’s Cortex Microcontroller Software Interface Standard files provided under bsp/CMSIS.
- FreeRTOS – The real-time operating system (see modules/FreeRTOSv10.5.1) for managing concurrency and task scheduling.
- FatFs – A lightweight file system module from modules/FatFs, if file storage is needed.
- Ambiq MCU HAL – Provided in bsp/mcu for board initialization, peripheral control, etc.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Layer: Application & RTOS/Middleware
    subgraph "Application & RTOS/Middleware"
        FT1("FreeRTOS"):::middleware
        FT2("FatFs"):::middleware
        APP("Demo Applications"):::application
    end

    %% Middle Layer: Graphics Layer
    subgraph "Graphics Layer"
        LVGL("LVGL Core (LVGL_V8)"):::graphics
        PORT("LVGL Porting (lvgl_ambiq_porting)"):::graphics
        DISP("Display/Touch Drivers"):::graphics
        GPU("GPU Acceleration (NemaGFX)"):::graphics
    end

    %% Lower Layer: MCU Abstraction/Drivers
    subgraph "MCU Abstraction/Drivers"
        CMSIS("CMSIS"):::drivers
        HAL("MCU HAL"):::drivers
        BOARD("Board Support"):::drivers
    end

    %% Bottom Layer: Hardware
    HW("Ambiq Apollo MCU"):::hardware

    %% Connections for Application & Middleware
    FT1 -->|"schedules"| APP
    FT2 -->|"files"| APP
    APP -->|"calls_Interface"| PORT

    %% Connections within Graphics Layer
    PORT -->|"integrates_with"| LVGL
    LVGL -->|"calls_displayAPI"| DISP
    LVGL -->|"requests_GPU"| GPU
    DISP -->|"display_commands"| GPU

    %% Connection from Graphics to Drivers
    PORT -->|"abstracts_HW"| HAL

    %% Drivers to Hardware Connections
    CMSIS -->|"provides_interface"| HW
    HAL -->|"controls"| HW
    BOARD -->|"configures"| HW

    %% GPU to Hardware Connection
    GPU -->|"renders_on"| HW

    %% Styling Classes
    classDef application fill:#ffcc66,stroke:#333,stroke-width:2px;
    classDef middleware fill:#ffffcc,stroke:#333,stroke-width:2px;
    classDef graphics fill:#ffddcc,stroke:#333,stroke-width:2px;
    classDef drivers fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef hardware fill:#ffcccc,stroke:#333,stroke-width:2px;

    %% Click Events
    click FT1 "https://github.com/ambiqmicro/lv_port_ambiq/blob/main/modules/FreeRTOSv10.5.1"
    click FT2 "https://github.com/ambiqmicro/lv_port_ambiq/tree/main/modules/FatFs"
    click APP "https://github.com/ambiqmicro/lv_port_ambiq/tree/main/lvgl_ambiq_demo"
    click LVGL "https://github.com/ambiqmicro/lv_port_ambiq/tree/main/LVGL_V8"
    click PORT "https://github.com/ambiqmicro/lv_port_ambiq/tree/main/lvgl_ambiq_porting"
    click DISP "https://github.com/ambiqmicro/lv_port_ambiq/tree/main/lvgl_ambiq_porting"
    click GPU "https://github.com/ambiqmicro/lv_port_ambiq/tree/main/bsp/gpu"
    click CMSIS "https://github.com/ambiqmicro/lv_port_ambiq/tree/main/bsp/CMSIS/AmbiqMicro"
    click HAL "https://github.com/ambiqmicro/lv_port_ambiq/tree/main/bsp/mcu/apollo4b"
    click BOARD "https://github.com/ambiqmicro/lv_port_ambiq/tree/main/bsp/boards"
```
