# polarfire-soc/polarfire-soc-bare-metal-examples architecture

> Architecture diagram of the GitHub repository polarfire-soc/polarfire-soc-bare-metal-examples, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/polarfire-soc/polarfire-soc-bare-metal-examples
- Repository: https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples

## Overview

This repository is a collection of PolarFire SoC bare-metal applications and peripheral-driver examples, rather than one application with a single runtime flow. The documented user workflow is to choose an example for a supported board, configure its memory/debug or release variant, and run it on hardware. The graph highlights the blank bare-metal platform’s HAL layers and representative driver families alongside the documented example collections. Source excerpts do not show application-to-driver calls, so those relationships are intentionally omitted.

Main entry points: [`applications/mpfs-blank-baremetal/src/platform/mpfs_hal/mss_hal.h`](https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/platform/mpfs_hal/mss_hal.h) (MPFS HAL), [`applications/mpfs-blank-baremetal/src/application/hart0/e51.c`](https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/application/hart0/e51.c) (Blank application), [`applications`](https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/tree/main/applications) (Applications), [`driver-examples`](https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/tree/main/driver-examples) (Driver examples)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collections["Example collections"]
  node_applications["Applications"]
  node_driver_examples["Driver examples"]
end

subgraph group_app["Bare-metal application"]
  node_blank_app["Blank application<br/>[e51.c]"]
  node_board_config["Board configs"]
end

subgraph group_hal["Hardware abstraction"]
  node_hal_api["HAL API<br/>[hal.h]"]
  node_mpfs_hal["MPFS HAL<br/>[mss_hal.h]"]
  node_encoding["CPU encoding<br/>[encoding.h]"]
  node_sysreg["System registers<br/>[mss_sysreg.h]"]
  node_ddr["DDR support<br/>[mss_ddr.h]"]
  node_irq["IRQ stubs"]
end

subgraph group_mss["MSS drivers"]
  node_mss_uart["MSS UART<br/>[mss_uart.c]"]
  node_mss_eth["MSS Ethernet<br/>[mss_ethernet_mac.c]"]
  node_mss_usb["MSS USB<br/>[mss_usb_device.c]"]
  node_mss_services["System services<br/>[mss_sys_services.h]"]
end

subgraph group_fpga["FPGA IP drivers"]
  node_fpga_uart["FPGA UART<br/>[core_uart_apb.c]"]
  node_fpga_i2c["FPGA I2C<br/>[core_i2c.c]"]
  node_fpga_tse["FPGA Ethernet<br/>[core_tse.c]"]
  node_fpga_sysservices["FPGA services"]
end

node_user(("Developer"))
node_board["PolarFire board"]

node_user -->|"chooses example"| node_applications
node_user -->|"chooses example"| node_driver_examples
node_applications -->|"includes"| node_blank_app
node_driver_examples -->|"demonstrates drivers"| node_mss_uart
node_user -->|"configures target"| node_board_config
node_board_config -.->|"targets"| node_board
node_blank_app -.->|"runs on"| node_board
node_mpfs_hal -->|"includes"| node_encoding
node_mpfs_hal -->|"includes"| node_sysreg
node_mpfs_hal -->|"includes"| node_ddr
node_mpfs_hal -->|"uses"| node_irq
node_user -.->|"runs example"| node_blank_app

click node_applications "https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/tree/main/applications"
click node_driver_examples "https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/tree/main/driver-examples"
click node_blank_app "https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/application/hart0/e51.c"
click node_board_config "https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/tree/main/applications/mpfs-blank-baremetal/src/boards"
click node_hal_api "https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/platform/hal/hal.h"
click node_mpfs_hal "https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/platform/mpfs_hal/mss_hal.h"
click node_encoding "https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/platform/mpfs_hal/common/encoding.h"
click node_sysreg "https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/platform/mpfs_hal/common/mss_sysreg.h"
click node_ddr "https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/platform/mpfs_hal/common/nwc/mss_ddr.h"
click node_irq "https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/platform/mpfs_hal/common/mss_irq_handler_stubs.c"
click node_mss_uart "https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/platform/drivers/mss/mss_mmuart/mss_uart.c"
click node_mss_eth "https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/platform/drivers/mss/mss_ethernet_mac/mss_ethernet_mac.c"
click node_mss_usb "https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/platform/drivers/mss/mss_usb/mss_usb_device.c"
click node_mss_services "https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/platform/drivers/mss/mss_sys_services/mss_sys_services.h"
click node_fpga_uart "https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/platform/drivers/fpga_ip/CoreUARTapb/core_uart_apb.c"
click node_fpga_i2c "https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/platform/drivers/fpga_ip/CoreI2C/core_i2c.c"
click node_fpga_tse "https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/platform/drivers/fpga_ip/CoreTSE/core_tse.c"
click node_fpga_sysservices "https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/platform/drivers/fpga_ip/CoreSysServices_PF/core_sysservices_pf.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_applications,node_driver_examples toneBlue
class node_blank_app,node_board_config toneAmber
class node_hal_api,node_mpfs_hal,node_encoding,node_sysreg,node_ddr,node_irq toneMint
class node_mss_uart,node_mss_eth,node_mss_usb,node_mss_services toneRose
class node_fpga_uart,node_fpga_i2c,node_fpga_tse,node_fpga_sysservices,node_user,node_board toneIndigo
```

## Components

### Example collections

- [Applications](https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/tree/main/applications): `applications`
- [Driver examples](https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/tree/main/driver-examples): `driver-examples`

### Bare-metal application

- [Blank application](https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/application/hart0/e51.c): `applications/mpfs-blank-baremetal/src/application/hart0/e51.c`
- [Board configs](https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/tree/main/applications/mpfs-blank-baremetal/src/boards): `applications/mpfs-blank-baremetal/src/boards`

### Hardware abstraction

- [HAL API](https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/platform/hal/hal.h): `applications/mpfs-blank-baremetal/src/platform/hal/hal.h`
- [MPFS HAL](https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/platform/mpfs_hal/mss_hal.h): `applications/mpfs-blank-baremetal/src/platform/mpfs_hal/mss_hal.h`
- [CPU encoding](https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/platform/mpfs_hal/common/encoding.h): `applications/mpfs-blank-baremetal/src/platform/mpfs_hal/common/encoding.h`
- [System registers](https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/platform/mpfs_hal/common/mss_sysreg.h): `applications/mpfs-blank-baremetal/src/platform/mpfs_hal/common/mss_sysreg.h`
- [DDR support](https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/platform/mpfs_hal/common/nwc/mss_ddr.h): `applications/mpfs-blank-baremetal/src/platform/mpfs_hal/common/nwc/mss_ddr.h`
- [IRQ stubs](https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/platform/mpfs_hal/common/mss_irq_handler_stubs.c): `applications/mpfs-blank-baremetal/src/platform/mpfs_hal/common/mss_irq_handler_stubs.c`

### MSS drivers

- [MSS UART](https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/platform/drivers/mss/mss_mmuart/mss_uart.c): `applications/mpfs-blank-baremetal/src/platform/drivers/mss/mss_mmuart/mss_uart.c`
- [MSS Ethernet](https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/platform/drivers/mss/mss_ethernet_mac/mss_ethernet_mac.c): `applications/mpfs-blank-baremetal/src/platform/drivers/mss/mss_ethernet_mac/mss_ethernet_mac.c`
- [MSS USB](https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/platform/drivers/mss/mss_usb/mss_usb_device.c): `applications/mpfs-blank-baremetal/src/platform/drivers/mss/mss_usb/mss_usb_device.c`
- [System services](https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/platform/drivers/mss/mss_sys_services/mss_sys_services.h): `applications/mpfs-blank-baremetal/src/platform/drivers/mss/mss_sys_services/mss_sys_services.h`

### FPGA IP drivers

- [FPGA UART](https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/platform/drivers/fpga_ip/CoreUARTapb/core_uart_apb.c): `applications/mpfs-blank-baremetal/src/platform/drivers/fpga_ip/CoreUARTapb/core_uart_apb.c`
- [FPGA I2C](https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/platform/drivers/fpga_ip/CoreI2C/core_i2c.c): `applications/mpfs-blank-baremetal/src/platform/drivers/fpga_ip/CoreI2C/core_i2c.c`
- [FPGA Ethernet](https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/platform/drivers/fpga_ip/CoreTSE/core_tse.c): `applications/mpfs-blank-baremetal/src/platform/drivers/fpga_ip/CoreTSE/core_tse.c`
- [FPGA services](https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples/blob/main/applications/mpfs-blank-baremetal/src/platform/drivers/fpga_ip/CoreSysServices_PF/core_sysservices_pf.h): `applications/mpfs-blank-baremetal/src/platform/drivers/fpga_ip/CoreSysServices_PF/core_sysservices_pf.h`

### Other components

- **Developer**
- **PolarFire board**

## Connections

- Developer → Applications: chooses example (evidence: `README.md`)
- Developer → Driver examples: chooses example (evidence: `README.md`)
- Applications → Blank application: includes (evidence: `README.md`)
- Driver examples → MSS UART: demonstrates drivers (evidence: `README.md`)
- Developer → Board configs: configures target (evidence: `README.md`)
- Board configs → PolarFire board: targets
- Blank application → PolarFire board: runs on
- MPFS HAL → CPU encoding: includes (evidence: `applications/mpfs-blank-baremetal/src/platform/mpfs_hal/mss_hal.h`)
- MPFS HAL → System registers: includes (evidence: `applications/mpfs-blank-baremetal/src/platform/mpfs_hal/mss_hal.h`)
- MPFS HAL → DDR support: includes (evidence: `applications/mpfs-blank-baremetal/src/platform/mpfs_hal/mss_hal.h`)
- MPFS HAL → IRQ stubs: uses (evidence: `applications/mpfs-blank-baremetal/src/platform/mpfs_hal/common/mss_irq_handler_stubs.c`)
- Developer → Blank application: runs example
