# nxp-mcuxpresso/mcux-freemaster architecture

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

- Interactive diagram: https://gitdiagram.com/nxp-mcuxpresso/mcux-freemaster
- Repository: https://github.com/nxp-mcuxpresso/mcux-freemaster

## Overview

##### Project type and purpose
- This is a middleware/driver “library” repository (part of the NXP MCUXpresso SDK) that implements the FreeMASTER communication protocol on an MCU.
- It exposes a layered architecture for transport-agnostic recorders, command interfaces, TSA (type-safe application tables), pipes, etc., over multiple physical interfaces (Serial, CAN, USB, Network, BDM/JTAG).

##### File structure
- src/common – Core protocol implementation, APIs, utilities, recorder, scope, TSA, pipes, etc.
- src/drivers – Transport-specific drivers organized by HAL/vendor (ampxsdk, dreg, mcuxsdk, zephyr).
- src/platforms – Platform headers and abstractions per MCU family or OS (bare-metal or Zephyr).
- src/support – Supplemental code (e.g., USB device descriptors).
- src/template – User-provided configuration templates for different targets.
- zephyr – Zephyr integration (CMakeLists, Kconfig, patches, module.yml).
- doc – User guide, API reference, examples.

##### README for additional insights
- Confirms this is the FreeMASTER driver delivery for MCUXpresso SDK.
- Mentions supported interfaces and points to overall SDK docs.

##### Detailed capturing of essential elements
- Don’t simply list folders; group them by role in the data path.
- Build-time flow: templates + platform headers + core + drivers → final binary.
- Zephyr integration path separately to show how it patches core and injects configs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers
    subgraph "Application Layer" 
        style App fill:#D6E9FE,stroke:#4A90E2
        App["MCU Firmware\n(calls FreeMASTER APIs)"]:::app
    end

    subgraph "FreeMASTER Core (src/common)"
        style Core fill:#E8F1FE,stroke:#4A90E2
        Core["Protocol Engine,\nRecorder, TSA, Pipes,\nUtilities"]:::core
    end

    subgraph "Transport Abstraction Layer"
        style Abstr fill:#E8F1FE,stroke:#4A90E2
        Abstr["Generic TX/RX Interface\n(send_frame, recv_frame)"]:::core
    end

    subgraph "Transport Drivers"
        style TD fill:#E6F5E0,stroke:#3B8E23
        ampxsdk["AMPX SDK\n(Serial, CAN)"]:::driver
        dreg["D-REG\n(UART, CAN, LINFlex,\nMSCAN, QSCI)"]:::driver
        mcuxsdk["MCUXpresso SDK\n(Serial, CAN, Network)"]:::driver
        zephyrdrv["Zephyr RTOS\n(Serial, CAN, Network, RTT)"]:::driver
    end

    subgraph "Platform Abstraction"
        style Plat fill:#FFF1E0,stroke:#E67C00
        subgraph "NXP MCU Families"
            P1["56F800E"]:::platform
            P2["GEN32BE"]:::platform
            P3["GEN32LE"]:::platform
            P4["S12Z"]:::platform
        end
        zephyrOS["Zephyr OS Integration\n(autoconf, shell,\nZephyr hooks)"]:::platform
    end

    subgraph "Build-Time Components"
        style Build fill:#FFF7D6,stroke:#D8A10A
        subgraph "Configuration Templates"
            T1["56F800E freemaster_cfg.h"]:::config
            T2["GEN32LE freemaster_cfg.h"]:::config
        end
        Support["USB Descriptors & Logic\n(src/support/mcuxsdk_usb)"]:::support
        subgraph "Zephyr Module & Build"
            Z1["CMakeLists.txt"]:::build
            Z2["Kconfig"]:::build
            Z3["module.yml"]:::build
            Z4["patch"]:::build
        end
    end

    Documentation["User Guide & Examples\n(doc/user_guide)"]:::doc
    APIRef["API Reference\n(doc/user_guide/api)"]:::doc
    SBOM["SBOM\n(SBOM.spdx.json)"]:::doc
    External["FreeMASTER Desktop/Lite\n(PC Host)"]:::external

    %% Connections
    App -->|"fmstr_init,\nfmstr_recorder,\nfmstr_appcmd"| Core
    Core -->|"send_frame,\nrecv_frame"| Abstr
    Abstr -->|"invoke driver"| ampxsdk
    Abstr -->|"invoke driver"| dreg
    Abstr -->|"invoke driver"| mcuxsdk
    Abstr -->|"invoke driver"| zephyrdrv
    ampxsdk -->|"HAL calls"| P1
    dreg -->|"HAL calls"| P2
    mcuxsdk -->|"HAL calls"| P3
    zephyrdrv -->|"OS calls"| zephyrOS
    ampxsdk <-->|"Physical Link"| External
    dreg <-->|"Physical Link"| External
    mcuxsdk <-->|"Physical Link"| External
    zephyrdrv <-->|"Physical Link"| External

    T1 -->|"generate headers"| Core
    T1 -->|"generate headers"| ampxsdk
    T2 -->|"generate headers"| Core
    T2 -->|"generate headers"| mcuxsdk
    Support -->|"provides USB logic"| mcuxsdk
    Z1 -->|"influences build"| zephyrOS
    Z2 -->|"influences build"| zephyrOS
    Z3 -->|"influences build"| zephyrOS
    Z4 -->|"patches core"| Core

    Documentation --- Core
    APIRef --- Abstr
    SBOM --- Core

    %% Click Events
    click Core "https://github.com/nxp-mcuxpresso/mcux-freemaster/tree/main/src/common"
    click ampxsdk "https://github.com/nxp-mcuxpresso/mcux-freemaster/tree/main/src/drivers/ampxsdk"
    click dreg "https://github.com/nxp-mcuxpresso/mcux-freemaster/tree/main/src/drivers/dreg"
    click mcuxsdk "https://github.com/nxp-mcuxpresso/mcux-freemaster/tree/main/src/drivers/mcuxsdk"
    click zephyrdrv "https://github.com/nxp-mcuxpresso/mcux-freemaster/tree/main/src/drivers/zephyr"
    click P1 "https://github.com/nxp-mcuxpresso/mcux-freemaster/tree/main/src/platforms/56f800e"
    click P2 "https://github.com/nxp-mcuxpresso/mcux-freemaster/tree/main/src/platforms/gen32be"
    click P3 "https://github.com/nxp-mcuxpresso/mcux-freemaster/tree/main/src/platforms/gen32le"
    click P4 "https://github.com/nxp-mcuxpresso/mcux-freemaster/tree/main/src/platforms/s12z"
    click zephyrOS "https://github.com/nxp-mcuxpresso/mcux-freemaster/tree/main/src/platforms/zephyr"
    click T1 "https://github.com/nxp-mcuxpresso/mcux-freemaster/blob/main/src/template/56f800e/freemaster_cfg.h"
    click T2 "https://github.com/nxp-mcuxpresso/mcux-freemaster/blob/main/src/template/gen32le/freemaster_cfg.h"
    click Support "https://github.com/nxp-mcuxpresso/mcux-freemaster/tree/main/src/support/mcuxsdk_usb"
    click Z1 "https://github.com/nxp-mcuxpresso/mcux-freemaster/blob/main/zephyr/CMakeLists.txt"
    click Z2 "https://github.com/nxp-mcuxpresso/mcux-freemaster/tree/main/zephyr/Kconfig"
    click Z3 "https://github.com/nxp-mcuxpresso/mcux-freemaster/blob/main/zephyr/module.yml"
    click Z4 "https://github.com/nxp-mcuxpresso/mcux-freemaster/tree/main/zephyr/patch"
    click Documentation "https://github.com/nxp-mcuxpresso/mcux-freemaster/tree/main/doc/user_guide"
    click APIRef "https://github.com/nxp-mcuxpresso/mcux-freemaster/tree/main/doc/user_guide/api"
    click SBOM "https://github.com/nxp-mcuxpresso/mcux-freemaster/blob/main/SBOM.spdx.json"

    %% Styles
    classDef app fill:#D6E9FE,stroke:#4A90E2
    classDef core fill:#E8F1FE,stroke:#4A90E2
    classDef driver fill:#E6F5E0,stroke:#3B8E23
    classDef platform fill:#FFF1E0,stroke:#E67C00
    classDef config fill:#FFF7D6,stroke:#D8A10A
    classDef support fill:#F2F2F2,stroke:#888888
    classDef build fill:#FFF7D6,stroke:#D8A10A
    classDef doc fill:#F7F7F7,stroke:#AAAAAA
    classDef external fill:#F2F2F2,stroke:#888888,stroke-dasharray: 5 5
```
