---
title: "board.yaml Reference"
description: "board.yaml is the single declarative file that describes a firmware project: which SoM SKU, which board, which runtime on each on-die core (optional — defaults from the SoM topology), which optional libraries, which IPC carve-outs, plus the declarative blocks for boot, OTA, storage, PSA security, per-core memory + power, and per-module diagnostics. The SDK's orchestrator compiles it down to per-core build slices (Zephyr Kconfig, Yocto local.conf, plain CMake), a system manifest, and generated headers — your build plumbing stays unchanged."
source: https://docs.alplab.ai/sdk/board-yaml
---

# `board.yaml` Reference

`board.yaml` is the **single declarative file** that describes a firmware project: which SoM SKU, which board, which runtime on each on-die core (optional — defaults from the SoM topology), which optional libraries, which IPC carve-outs, plus the declarative blocks for boot, OTA, storage, PSA security, per-core memory + power, and per-module diagnostics. The SDK's orchestrator compiles it down to per-core build slices (Zephyr Kconfig, Yocto `local.conf`, plain CMake), a system manifest, and generated headers — your build plumbing stays unchanged.

The customer surface is flat — `som:`, `cores:`, plus the board declaration (`preset:` shortcut or inline `name:` + `populated:` + `e1m_routes:` + optional `pins:`) all sit at the top level. Optional blocks (`libraries:`, `ipc:`, `boot:`, `ota:`, `storage:`, `security:`, `chips:`, `cameras:`, `ownership:`, `models:`, `diagnostics:`) land at the top level too. This page is the customer contract; if you need to extend the file's shape, file an issue.

## Minimum-viable example

```yaml
som:
  sku: E1M-AEN801          # your MPN — preset under metadata/e1m_modules/<MPN>.yaml

preset: e1m-evk            # stock board preset, or write the board out inline (see below)

cores:
  m55_hp:
    # os: omitted → SoM topology default (Cortex-M → zephyr).
    # Write os: only to override (off | baremetal).
    app: ./src
    peripherals: [gpio]
```

That's the whole config for a vanilla "E1M-AEN801 on the EVK running Zephyr on the M55-HP" build. All other blocks are optional. Cores omitted from `cores:` inherit the SoM preset's `topology:` defaults; use `os: off` to skip a peer core explicitly.

## Heterogeneous example (V2N: A55 Yocto + M33 Zephyr)

```yaml
som:
  sku: E1M-V2N101
  hw_rev: r1

preset: e1m-x-evk

cores:
  a55_cluster:
    # os: omitted → topology default (a55_cluster → yocto).
    app: ./linux
    image: alp-image-edge
    peripherals: [ethernet, usb, emmc]
    iot:         { wifi: true, mqtt: true, tls: true }
  m33_sm:
    # os: omitted → topology default (m33_sm → zephyr).
    app: ./m33_sm
    peripherals: [adc, pwm, i2c, gpio]

libraries:                            # top-level — one place, optionally core-scoped
  - mbedtls                           # project-wide (every core whose OS supports it)
  - { name: nlohmann-json, cores: [a55_cluster] }
  - { name: cmsis-dsp,     cores: [m33_sm] }

ipc:
  - kind: rpmsg
    endpoints: [a55_cluster, m33_sm]
    carve_out_kb: 512
    name: alp_default_rpmsg

diagnostics:
  log_level: info
```

One declaration drives both halves. The orchestrator fans out into per-slice build directories, allocates the RPMsg carve-out from the SoM preset's `memory_map:`, and emits `<alp/system_ipc.h>` with the resolved addresses + endpoint IDs that both halves `#include`.

## File location

```
your-app/
├── board.yaml             # this file
├── linux/                 # Yocto slice (path matches cores.a55_cluster.app)
│   └── CMakeLists.txt
└── m33_sm/                # Zephyr slice (path matches cores.m33_sm.app)
    ├── prj.conf           # empty; the loader generates alp.conf
    └── src/main.c
```

Slice sub-directory names are conventions, not magic — they're bound by `cores.<id>.app:`. Matching the core ID keeps the layout readable. Single-OS projects keep a flat `src/` layout under one core.

## Single source of truth

Pre-`board.yaml` you tracked configuration across `prj.conf`, CMake `-D` flags, `local.conf`, vendor Kconfig knobs, and library opt-ins. `board.yaml` collapses all of that into one place.

- **Don't edit `prj.conf` directly.** It stays empty; the loader emits `alp.conf` and Zephyr layers it on via `OVERLAY_CONFIG`.
- **Don't pass SDK `-D` flags to `cmake`.** The loader emits the right set per slice.
- **Don't hand-edit `local.conf`'s `MACHINE`.** The orchestrator picks the per-cluster MACHINE (e.g. `e1m-v2n101-a55`) from the SoM preset.
- **Don't type endpoint IDs or carve-out addresses in app code.** They live in the generated `<alp/system_ipc.h>` that both slices include.

If `board.yaml` can't express something you need, file an issue — the right fix is to extend the schema, not bypass it.

## `schemaVersion:` — lazy versioning {#schema-version}

`board.yaml` may carry an optional top-level `schemaVersion:` integer. You almost certainly don't need it.

Versioning is deliberately **lazy**: an **absent `schemaVersion:` *is* version 1** — permanently, not provisionally. It's the floor, not a missing value. So hand-written and external projects keep loading unchanged, are never reported as drift, and never need to add the key. The key only appears in a file once a migration has bumped it to v2 or later.

```yaml
# Perfectly current. Not "unversioned", not out of date — this IS v1.
som:
  sku: E1M-AEN801
cores:
  m55_hp:
    app: ./src
```

[`west alp-migrate`](https://docs.alplab.ai/sdk/tools/cli#west-alp-migrate) is the engine that versions and migrates the file when that day comes. It rewrites **byte-faithfully** — comments, flow style and indentation all survive — so an applied migration reads as a reviewable diff, not a reformat.

:::note[No migration exists yet]
The migration registry is still **empty** as of v0.17.0. The engine shipped ahead of any schema change so the first real one can arrive as a migration rather than a breakage — but today `west alp-migrate --check` passes on every file and `--apply` does nothing. Bump `schemaVersion:` by hand and you'll simply be ahead of a schema that doesn't exist.
:::

## Released MPNs

Paste any of these into `som.sku`:

| Family            | MPNs                                                                          |
|-------------------|-------------------------------------------------------------------------------|
| Alif Ensemble     | `E1M-AEN301`, `AEN401`, `AEN501`, `AEN601`, `AEN701`, `AEN801`, `AEN803`      |
| Renesas RZ/V2N    | `E1M-V2N101`, `V2N102`, `V2N103`                                              |
| RZ/V2N + DEEPX    | `E1M-V2M101`, `V2M102`, `V2M103`                                              |

`E1M-AEN803` is the E8 configuration with both external memories fitted (512 Mbit HyperRAM + 256 Mbit NOR); `E1M-V2N103` / `E1M-V2M103` are the 4 GB RAM / 16 GB eMMC memory tier of the V2N / V2M module. On both families the eMMC is 4 GB on the `101` SKU and 16 GB on the `102` / `103` SKUs.

:::warning[Removed in v0.17.0: `E1M-NX9101` (NXP i.MX 93)]
The i.MX 93 placeholder preset is gone, and the `som.sku` pattern no longer accepts an `E1M-NX9…` value — a `board.yaml` naming one now fails schema validation. The SDK supports the AEN, V2N and V2M families only.
:::

## Stock board presets

| Preset       | Form factor   | Hosts                                  |
|--------------|---------------|----------------------------------------|
| `e1m-evk`    | 35 × 35       | E1M-AEN family                         |
| `e1m-x-evk`  | 45 × 65       | E1M-X V2N family, V2N-M1 (V2M) family  |

`preset:` is the SDK-internal shortcut the demos use. For a **custom board** (your own PCB design), drop the `preset:` line and write the board out inline at the top level (`name:`, `populated:`, `e1m_routes:`) — see the "Board declaration" section below.

## Top-level fields

| Field            | Required | What it picks                                                                          |
|------------------|----------|----------------------------------------------------------------------------------------|
| `som`            | yes      | SoM SKU (+ optional `hw_rev`). Silicon-level facts live in the SKU preset and are NOT customer-tunable here. |
| `name`           | inline*  | Board name (`^[A-Za-z][A-Za-z0-9_-]*$`) — required in inline mode, forbidden when using `preset:`. Used in `alp_<name>_routes.h`. |
| `description`    | no       | Free-form one-line description.                                                        |
| `hw_rev`         | no       | Board hardware revision. Defaults to the preset's `default_hw_rev` (preset mode) or unrevisioned (inline). |
| `populated`      | inline*  | Chips populated on this board. Each `true` → `CONFIG_ALP_SDK_{CHIP,BLOCK}_<name>=y`. Mutually exclusive with `preset:`. |
| `e1m_routes`     | inline*  | E1M-pad → board-side macro routing. Read by `gen_board_header.py` → `include/alp/boards/alp_<name>_routes.h`. Mutually exclusive with `preset:`. |
| `preset`         | preset*  | SDK-internal shortcut (`e1m-evk` / `e1m-x-evk`): pulls a shared board definition from `metadata/boards/<preset>.yaml`. Mutually exclusive with inline `populated:` / `e1m_routes:` / `camera_connectors:`. |
| `camera_connectors` | no    | Inline mode only. The camera connectors your board exposes, keyed `CAM0`, `CAM1`, … See [`cameras:`](#cameras-block). |
| `cameras`        | no       | Camera modules fitted to the board's camera connectors. See [`cameras:`](#cameras-block). |
| `ownership`      | no       | Per-product core-ownership override for assignable E1M instances (V2N family). See [`ownership:`](#ownership-block). |
| `supported_boards` | no     | Board presets this project is verified to build for (e.g. `[e1m-evk, e1m-x-evk]`). Examples only — per ADR-0011 application firmware still targets one SoM family. CI builds one scenario per entry. Defaults to the single `preset:` when omitted. See [Cross-EVK portability](https://docs.alplab.ai/sdk/board-portability). |
| `pins`           | no       | Optional array naming the E1M pads the project actively uses. Validated against the resolved board's `e1m_routes:`. |
| `cores`          | yes      | Per-core app + library/peripheral knobs (min 1). Each core's `os:` is optional; the runtime is class-derived (Cortex-M → Zephyr, Cortex-A → Yocto) and only `off` / `baremetal` may be set explicitly. |
| `ipc`            | no       | Cross-core IPC carve-outs (rpmsg / raw_shmem / mailbox_only).                          |
| `boot`           | no       | MCUboot + image-signing configuration (project-wide). See [Boot block](#boot-block).   |
| `ota`            | no       | OTA provider + server config (project-wide). Mender / Hawkbit / MCUmgr emit on Zephyr; Mender server-mode on Yocto. See [OTA block](#ota-block). |
| `storage`        | no       | Filesystem partitions. Deterministic flash-partition allocator + DTS/Kconfig emit. See [Storage block](#storage-block). |
| `security`       | no       | `security.psa:` — PSA Crypto + optional TF-M sysbuild child image. See [Security block](#security-block). |
| `chips`          | no       | Project-wide chip-driver opt-ins (each → `CONFIG_ALP_SDK_CHIP_<NAME>=y`).              |
| `models`         | no       | AI models to compile + package into `.alpmodel` (silicon-agnostic; back-ends derived from `som.sku`). See [`models:` block](#models-block). |
| `diagnostics`    | no       | `last_error`, default `log_level`, `console` backend, `link` target, and per-module log levels under `diagnostics.modules:` (Alp SDK **and** wired Zephyr log modules). |
| `features`       | no       | Free-form map for app-specific feature config that doesn't fit the strict blocks.       |

\* Either `preset:` (preset mode) OR inline `name:` + `populated:` + `e1m_routes:` (customer path). Both omitted is fine too — a headless / inference-only build with no board declaration.

## `som` block

```yaml
som:
  sku: E1M-AEN801          # required

  hw_rev: r1               # optional — defaults to the preset's default_hw_rev.
                           # Validated build-time against the family's
                           # hw_revisions table — it must exist, be buildable,
                           # and cover this SDK version; cross-checked at
                           # runtime via the BOARD_ID ADC.
```

The `hw_rev:` you name is **enforced**, three independent ways — see [Hardware revision tracking](#hardware-revision-tracking).

The SoM block describes the **module** itself — silicon, on-module radio, on-module secure element / RTC / temperature sensor / EEPROM. Fixed at SoM-fab time; you can't DNI on-module parts after order.

> Custom SoM variants (e.g. a V2N built without the OPTIGA Trust M, or a non-stock DRAM/flash population) are expressed as **new SKU presets** under `metadata/e1m_modules/<MPN>.yaml`, not as project-level overrides. The pre-v0.6 `som.overrides:` / `som.memory:` knobs are gone — silicon-determined fields aren't customer-facing.

## Board declaration

The board the firmware targets is declared at the **top level** of `board.yaml` in one of two mutually-exclusive modes.

### Inline mode (the customer path)

Self-contained — write your board's chip population + E1M-pad wiring directly at the top level of your project's `board.yaml`:

```yaml
name: my-sensor-board       # required; used in alp_<name>_routes.h
description: "..."          # optional
hw_rev: r1                  # optional board hardware revision

populated:                  # chips populated on this board
  lsm6dso: true
  bmi323:  true
  bmp581:  true
  ssd1306: true

e1m_routes:                 # E1M-pad → board-side macro
  gpio:
    - { e1m: E1M_GPIO_IO15, macro: PIN_BMI323_INT1,
        doc: "BMI323 INT1 (data-ready / motion / FIFO)." }
  buses:
    - { e1m: E1M_I2C0, macro: I2C_BUS_SENSORS,
        doc: "Shared sensor bus." }
  pwm:
    - { e1m: E1M_PWM3, macro: PWM_LED_RED,
        doc: "Status LED red channel." }
```

Each `populated.<name>: true` enables the matching `CONFIG_ALP_SDK_CHIP_<NAME>=y` (or `CONFIG_ALP_SDK_BLOCK_<NAME>=y` for the SDK-level helpers `button_led` / `pdm_mic` — the loader picks the right symbol per slug).

### Preset mode (SDK-internal shortcut)

The in-repo example projects all target the EVK or X-EVK, so they share a single board definition each via the `preset:` field:

```yaml
preset: e1m-evk             # or e1m-x-evk
```

The resolved file lives at `metadata/boards/<preset>.yaml` and supplies `name`, `populated`, `e1m_routes`, `camera_connectors`, `default_hw_rev`, and `hw_revisions` wholesale. When `preset:` is set, top-level `name:`, `populated:`, `e1m_routes:`, `camera_connectors:` are forbidden — the schema rejects mixing.

### `e1m_routes:` — E1M-pad assignments

**`e1m_routes:` is the single authoritative source of pin assignments for the board.** Each entry binds one E1M-standard pad (`E1M_GPIO_IO<N>`, `E1M_PWM<N>`, `E1M_I2C<N>`, `E1M_SPI<N>`, `E1M_UART<N>`, `E1M_I3C<N>`, `E1M_ADC<N>`, `E1M_DAC<N>`, `E1M_I2S<N>`, `E1M_CAN<N>`, `E1M_ENC<N>`) to a board-side C macro. `scripts/gen_board_header.py` reads the block and emits `include/alp/boards/alp_<name>_routes.h` with one `#define <MACRO> ALP_E1M_<…>` line per entry; hand-written firmware references those macros.

:::note[Two namespaces: `E1M_*` in YAML, `ALP_E1M_*` in C]
The pad names you write inside `e1m_routes:` (and inside a SoM preset's `pad_routes:` / `e1m:` blocks) stay in the **unprefixed E1M connector namespace** — `E1M_GPIO_IO15`, `E1M_SPI1`, `E1M_X_GPIO_IO28`, … — because they name pads on the open-standard E1M / E1M-X connector, not C symbols. `gen_board_header.py` prefixes `ALP_` when it emits the C instance macro, so the generated header defines your board macro against `ALP_E1M_*` (E1M-X boards against `ALP_E1M_X_*`). Rule of thumb: write `E1M_*` in `board.yaml`, reference `ALP_E1M_*` (or your own board macro) in C.
:::

```yaml
e1m_routes:
  gpio:
    - { e1m: E1M_GPIO_IO15, macro: PIN_BMI323_INT1,
        doc: "BMI323 INT1 (data-ready / motion / FIFO)." }
    - { e1m: E1M_GPIO_IO4,  macro: PIN_USER_BUTTON,
        active_low: true, pull: up, debounce_ms: 20,
        doc: "User push-button." }
  buses:
    - { e1m: E1M_I2C0, macro: I2C_BUS_SENSORS,
        doc: "Shared sensor bus." }
    - { e1m: E1M_SPI1, macro: SPI_BUS_DISPLAY,
        doc: "ST7789 panel." }
  pwm:
    - { e1m: E1M_PWM3, macro: PWM_LED_RED,
        doc: "Status LED red channel." }
  adc:
    - { e1m: E1M_ADC2, macro: ADC_BOARD_ID,
        doc: "Board-ID divider — encodes the board-side hw_rev." }
  dac:
    - { e1m: E1M_DAC0, macro: DAC_AUDIO_LINE_OUT,
        doc: "Line-out via op-amp." }
  i2s:
    - { e1m: E1M_I2S0, macro: I2S_AUDIO_CODEC,
        doc: "WM8960 codec." }
  can:
    - { e1m: E1M_CAN0, macro: CAN_BUS_VEHICLE,
        doc: "Vehicle CAN-FD via TCAN1042." }
  qenc:
    - { e1m: E1M_ENC0, macro: QENC_UI_DIAL,
        doc: "PEC12R rotary on the front panel." }
```

Sections, one per E1M pad class:

| Section  | Pads                                                                | Notes                                                       |
|----------|---------------------------------------------------------------------|-------------------------------------------------------------|
| `gpio:`  | `E1M_GPIO_IO<N>`                                                    | Per-pin board-side macros.                                  |
| `buses:` | `E1M_I2C<N>` / `E1M_I3C<N>` / `E1M_SPI<N>` / `E1M_UART<N>`          | Bus aliases.                                                |
| `pwm:`   | `E1M_PWM<N>`                                                        | Channel aliases.                                            |
| `adc:`   | `E1M_ADC<N>`                                                        | Channel aliases (board-id, Arduino A1..A5, mikroBUS AN, …). |
| `dac:`   | `E1M_DAC<N>`                                                        | Output aliases.                                             |
| `i2s:`   | `E1M_I2S<N>`                                                        | Codec / mic / amp bus aliases.                              |
| `can:`   | `E1M_CAN<N>`                                                        | Network aliases.                                            |
| `qenc:`  | `E1M_ENC<N>`                                                        | Quadrature encoder aliases (PEC12R rotary, …).              |

Per-section pad-class validation rejects misclassified pads at validate time (e.g. an `E1M_I2C0` placed under `adc:`).

Per-entry fields:

| Field         | Required | Values                  | Notes                                                                 |
|---------------|----------|-------------------------|-----------------------------------------------------------------------|
| `e1m`         | yes      | E1M pad name            | Validated against the pad class for the enclosing section.            |
| `macro`       | yes      | `^[A-Z_][A-Z0-9_]*$`    | Uppercase C identifier emitted into `alp_<name>_routes.h`.            |
| `doc`         | no       | string                  | One-line Doxygen `@brief` documenting what the pad is wired to.       |
| `active_low`  | no       | bool                    | Board convention — pressed/asserted = 0 V. Documentation only; `<alp/peripheral.h>` has no active-low flag, so the app inverts the level itself. |
| `pull`        | no       | `up` / `down` / `none`  | Physical pull resistor on the PCB (board-static fact). Apps still pass the matching `ALP_GPIO_PULL_{UP,DOWN}` to `alp_gpio_configure()` — this field documents what the board ships with, it does not drive the controller's internal pulls. |
| `debounce_ms` | no       | integer (≥0)            | RC-debounce time constant in milliseconds for hardware debounce (buttons mostly). Documentation hint; the app may add software debounce on top. |
| `board_alias` | no       | `^BOARD_[A-Z0-9_]+$`    | Portable cross-EVK alias for a role that both EVKs expose. `gen_board_header.py` emits `#define <board_alias> <macro>` into the generated routes header. The *same* `board_alias` must be declared on every board that exposes the role (CI-enforced parity). See [Cross-EVK portability](https://docs.alplab.ai/sdk/board-portability). |
| `mux_select`  | no       | `{ polarity, default_level }` | For a carrier path-mux select pad: `polarity` is `soc_when_high` / `soc_when_low` / `TBD` (which pad level selects the SoC path), `default_level` is `high` / `low` / `floating` / `TBD` (what the carrier pulls the pad to when nothing drives it). Both are required; write `TBD` until the netlist or a bench run confirms the value rather than guessing. |

#### Pin direction is NOT a board declaration

`board.yaml` describes the **wiring** (pad ↔ feature) — universal across every app that uses the board. Direction is a per-app runtime choice set at the `alp_*_open()` call site:

```c
alp_gpio_t *btn = alp_gpio_open(PIN_USER_BUTTON);
alp_gpio_configure(btn, ALP_GPIO_INPUT, ALP_GPIO_PULL_UP);
alp_gpio_irq_enable(btn, ALP_GPIO_EDGE_FALLING, on_press, NULL);

alp_gpio_t *led = alp_gpio_open(PWM_LED_RED);
alp_gpio_configure(led, ALP_GPIO_OUTPUT, ALP_GPIO_PULL_NONE);
```

The same physical pad can have multiple legitimate directions in different apps — `gpio-button-led` uses the `PWM0` pad (`E1M_GPIO_PWM0`) as a GPIO output for the status LED; `drone-autopilot` drives the same pad as a PWM output (`E1M_PWM0`). Drive strength / slew rate / etc. are SoC-controller settings (Kconfig), not board-level facts.

For peripheral use (UART / SPI / I²C / PWM / …) the `alp_<class>_open()` call muxes the pads to the right function automatically; the app doesn't say "TX is output" by hand.

### `pins:` (optional E1M-pad usage list)

```yaml
pins:
  - { e1m: E1M_GPIO_IO4, macro: EVK_PIN_ENCODER_SW, doc: "user button" }
  - { e1m: E1M_PWM1,     macro: EVK_PWM_LED_BLUE,   doc: "blue status LED" }
  - E1M_I2C0                                                       # bare form OK
```

Optional top-level array. Names the E1M pads the project actively uses. Most useful in preset mode, where the resolved board carries the full wiring but readers can't tell which subset this firmware touches.

Each entry is either a bare E1M pad name (e.g. `E1M_GPIO_IO4`) or a `{e1m, macro?, doc?}` mapping. The loader cross-checks every entry against the resolved board's `e1m_routes:` block: the `e1m` pad must exist, and when `macro:` is supplied it must match the board's macro for that pad (catches drift if the demo references `EVK_PWM_LED_RED` but the preset moved it).

## `cores` block (per-core runtime)

The core of the schema. Keys are canonical core IDs from the SoM preset's `topology:` block (`a55_cluster`, `m33_sm`, `m55_hp`, `m55_he`, `a32_cluster`).

Per-core fields:

| Field           | Values                                       | Notes                                                          |
|-----------------|----------------------------------------------|----------------------------------------------------------------|
| `os`            | `zephyr` / `yocto` / `baremetal` / `off`     | **Optional — and not a free choice.** The OS runtime is *derived* from the core's silicon class (Cortex-M → `zephyr`, Cortex-A → `yocto`); omit `os:` to take it. The only values you may set explicitly are `off` (skip the slice) and `baremetal` (rare hand-written firmware). Setting the *other* class's OS (`zephyr` on a Cortex-A, `yocto` on a Cortex-M) is rejected by the loader's cross-file core-class check. |
| `app`           | Path to the app source directory             | Optional — when omitted, the core inherits the SoM preset's `topology.<core_id>` `app:` default (e.g. the `alp-stock-shim` M-core shim). Zephyr: either a self-contained app directory with its own `CMakeLists.txt` (the multicore convention, e.g. `./m33_sm`), or a sources-only directory such as `./src`, in which case the build falls back to the **parent** directory's `CMakeLists.txt` (the single-core convention). Baremetal: must be the directory holding the app's own `CMakeLists.txt` — no fallback. Yocto: a project-root-relative **source directory**, not a bitbake target — pair it with `recipe:`. |
| `image`         | Yocto image recipe name                      | Yocto slices only (`alp-image-edge` is the stock reference — includes the Weston/Wayland compositor + libdrm test tools for the display stack). Takes priority over `app:`/`recipe:` when both are set. |
| `recipe`        | Yocto bitbake recipe name                    | **Required for an app-only `os: yocto` slice** (`app:` set, no `image:`) — see below. |
| `toolchain`     | Toolchain identifier (free-form string)      | Optional override of the SoM preset's `topology.<core_id>.toolchain` default (e.g. `arm-zephyr-eabi` for Zephyr, `poky-glibc` for Yocto). Passed through verbatim to the build plan's `slices[].toolchain.id` and the system manifest. For `os: zephyr` it also derives the plan's `targetTriple` / `compiler` (`<toolchain>` / `<toolchain>-gcc`), so a value that isn't GCC-triple-shaped (e.g. `llvm`) sets the `id` correctly but yields a compiler name that isn't meaningful. Omit it to keep the derived default. |
| `peripherals`   | Enum subset                                  | Per-slice (not project-wide). Each entry enables the matching Zephyr Kconfig / Yocto package. Allowed: `adc`, `can`, `counter`, `dac`, `emmc`, `ethernet`, `flash`, `gpio`, `i2c`, `i2s`, `i3c`, `pwm`, `rtc`, `sensor`, `spi`, `uart`, `usb`, `watchdog`. Carrier peripherals declared here are auto-wired by codegen from the board's routing. |
| `extra_libraries` | List of `{ name, kconfig? \| profile? }`   | Open-set escape hatch for non-curated libraries — see below.   |
| `inference`     | `{ default_arena_kib: N }`                   | App-level inference tuning. Backend set is silicon-driven (TFLM CPU always; Ethos-U / DRP-AI3 / DEEPX DX-M1 per the SoM `capabilities:` matrix). Apps pick per-handle at runtime via `alp_inference_open(.backend = ...)`. |
| `iot`           | `{ wifi, mqtt, ble, tls }`                   | Connectivity toggles per-slice. `tls: true` requires `mbedtls` or `bearssl` in the top-level `libraries:` / this core's `extra_libraries:` (validator rule 3). |
| `memory`        | `{ stack_kib, heap_kib, isr_stack_kib }`     | Emits `CONFIG_MAIN_STACK_SIZE` / `CONFIG_HEAP_MEM_POOL_SIZE` / `CONFIG_ISR_STACK_SIZE`. |
| `power`         | `{ sleep_mode, wakeup_sources: [...] }`      | Emits `CONFIG_PM` + `CONFIG_PM_DEVICE`; wake sources land as comment lines only. `sleep_mode != disabled` without `wakeup_sources:` warns (validator rule 5). |

#### `peripherals:` — the 18 classes

The `peripherals:` enum in `metadata/schemas/board.schema.json` holds 18 members. Two are new:

| Class  | Portable surface                | Notes                                                                     |
|--------|---------------------------------|---------------------------------------------------------------------------|
| `dac`  | [`<alp/dac.h>`](https://docs.alplab.ai/sdk/api/dac)   | Analog output. Pads are declared under `e1m_routes.dac:` (`E1M_DAC<N>`).  |
| `i3c`  | [`<alp/i3c.h>`](https://docs.alplab.ai/sdk/api/i3c)   | MIPI I3C bus. Pads are declared under `e1m_routes.buses:` (`E1M_I3C<N>`). |

### Which cores does my SoM expose?

| SoM family    | A-class                       | M-class                          | Heterogeneous? |
|---------------|-------------------------------|----------------------------------|----------------|
| AEN E3/E4     | —                             | `m55_hp`, `m55_he` (Zephyr)      | No — RTOS-only |
| AEN E5..E8    | `a32_cluster` (Yocto)         | `m55_hp`, `m55_he` (Zephyr)      | Yes            |
| V2N / V2N-M1  | `a55_cluster` (Yocto)         | `m33_sm` (Zephyr)                | Yes            |

A bare `som: { sku: <MPN> }` plus an empty `cores:` block produces a working dual-image build for every heterogeneous SoM — the per-core OS defaults come from the SoM preset.

### Yocto slices: `app:` + `recipe:` vs `image:` {#yocto-recipe}

A Yocto slice can be declared two ways, and the distinction is load-bearing:

```yaml
cores:
  a55_cluster:
    image: alp-image-edge         # (a) build a stock image — app: is ignored if also set
  # ── or ──
  a55_cluster:
    app: ./linux                  # (b) app-only slice: a SOURCE DIRECTORY…
    recipe: alp-lvgl-dashboard    # …plus the bitbake recipe that packages it
```

For `os: yocto`, `app:` is a project-root-relative **source directory — not a bitbake target**. An app-only slice therefore needs `recipe:` to name the bitbake recipe that packages it. Omit it and the slice doesn't silently build the wrong thing: the emitted build plan carries `command: null` plus a `yocto-recipe-missing` warning, rather than an invalid `bitbake <path>` command. When `image:` is set it takes priority and any `app:` is retained for tooling but not built directly.

## `libraries:` block (curated libraries) {#libraries}

**One top-level key, optionally core-scoped.** There is a single place libraries are declared:

```yaml
libraries:
  - mbedtls                                      # shorthand: project-wide
  - { name: cmsis-dsp, cores: [m33_sm] }         # scoped to named cores
  - { name: lvgl,      cores: [a55_cluster] }
```

Each entry is a `{name, cores?}` object, or a bare name as shorthand for a project-wide `{name}`. Omit `cores:` and the library applies to every core whose OS the manifest supports; list core ids to scope it. `name` resolves to a manifest at `metadata/libraries/<name>.yaml` — **the manifest directory is the curated set**. There's no closed enum in the schema: a typo is caught by the loader, which errors listing every available library, so it's self-correcting.

The orchestrator emits the per-OS wiring (Zephyr Kconfig / Yocto `IMAGE_INSTALL` / baremetal CMake) through the `--emit` contract and rejects a selection incompatible with the resolved SoM/core, naming the failing constraint. It never forks or fetches — west and OpenEmbedded own the actual pin.

:::warning[`cores.<id>.libraries:` was removed]
Libraries used to be declared **per-core** (`cores.<id>.libraries:`). That key no longer exists — move every selection to the top-level `libraries:` block and use `cores:` on the entry to scope it. `cores.<id>.extra_libraries:` is unaffected and stays per-core.
:::

**Canonical names are hyphenated.** The manifest names are `cmsis-dsp`, `nlohmann-json`, `madgwick-ahrs`, `tflite-micro`, `gfx-compat`. The older underscore spellings (`cmsis_dsp`, `nlohmann_json`, `madgwick_ahrs`, `tflite_micro`, `gfx_compat`, plus `libcoap` → `coap`) still resolve through an alias table (`metadata/library-aliases-v1.json`), which the loader canonicalises on load — but prefer the canonical hyphenated name in new files.

:::warning[Removed in v0.17.0: `coremqtt-sn`]
The `coremqtt-sn` curated library was dropped because its upstream repository no longer exists. Its manifest is gone and `coremqtt_sn` is no longer in the alias table, so a `libraries:` entry naming either spelling now fails with the loader's list of available libraries.
:::

Two opt-in tokens worth calling out, both of which make a previously metadata-only profile consumable:

| Token | Emits | Portable surface |
|---|---|---|
| `madgwick-ahrs` | `CONFIG_ALP_SDK_AHRS` | [`<alp/ahrs.h>`](https://docs.alplab.ai/sdk/api/ahrs) — Madgwick IMU orientation filter |
| `pid` | `CONFIG_ALP_SDK_PID` | [`<alp/pid.h>`](https://docs.alplab.ai/sdk/api/pid) — portable PID controller |

### Licence policy — copyleft is not admitted

The `license` field on every manifest is validated against a **permissive allowlist**: `Apache-2.0`, `MIT`, `BSD-2-Clause`, `BSD-3-Clause`, `Zlib`, `MIT-0`, `BSL-1.0`, `CC0-1.0`. A GPL-family or proprietary licence is rejected, so a copyleft surprise can't ride in through a `libraries:` selection. Extending that allowlist is a deliberate human legal-review decision, not a metadata edit.

:::danger[`tinygsm` and `libhelix` were removed — no compatibility alias]
A maintainer legal review dropped both curated tokens entirely: `tinygsm` (LGPL-3.0) and `libhelix` (RPSL-1.0) are copyleft / source-available licences unwanted in a SoM manufacturer's firmware distribution. Gone with them: the `west.yml` pins, the manifests and HW-backend profiles, their teaching examples, and every Kconfig / loader reference. **No ABI shim and no back-compat alias survives** — a retired curated token carries no compatibility promise. LGPL-3.0 and RPSL-1.0 are deliberately *not* on the allowlist above.

`catch2` (BSL-1.0) and `minimp3` (CC0-1.0) are permissive and **stay** — the same review added those two SPDX ids to the allowlist to accommodate them.

If you depend on `tinygsm` or `libhelix`, route it through `extra_libraries:` and own the licence obligation yourself.
:::

### `extra_libraries:` (open-set escape hatch)

`extra_libraries:` is the per-core open-set escape hatch for anything the SDK doesn't curate — one-off vendor SDKs, research-only deps, or libraries on their way into the curated set.

```yaml
libraries: [mbedtls]                    # curated — top-level

cores:
  m55_hp:
    extra_libraries:                    # non-curated — per-core
      - name: zforce                     # one-off vendor SDK, inline Kconfig path
        include_path: third_party/zforce/include
        kconfig:
          - CONFIG_ZFORCE=y
          - CONFIG_ZFORCE_I2C_ADDR=0x50

      - name: mycrypto                   # library with per-silicon backend selection
        profile: third_party/mycrypto/hw-backends.yaml
```

Each entry must declare exactly one of `kconfig:` (inline fragment) or `profile:` (path to a `hw-backends.yaml`-style file). The `include_path:` is optional and adds the directory to the slice's compile include path.

| Field      | When to use                                                                                                |
|------------|------------------------------------------------------------------------------------------------------------|
| `kconfig:` | Fast path for one-off libraries. Lines emit verbatim into the slice's `alp.conf`.                          |
| `profile:` | Library wants per-silicon backend selection consistent with the curated `libraries:` (same matcher).       |

Loader-enforced rules:

- Exactly one of `kconfig:` or `profile:` per entry.
- `name:` is globally unique across every core's `extra_libraries:`.
- `name:` must NOT collide with a curated library name — use the top-level `libraries:` for curated entries.
- `profile:` must resolve to a file (repo-relative).

## `boot:` block (MCUboot) {#boot-block}

```yaml
boot:
  method: mcuboot               # mcuboot | none (none = unverified, dev/lab only)
  signing:                      # required when method: mcuboot
    algorithm: ecdsa_p256       # ecdsa_p256 | rsa2048 | rsa3072 | ed25519
    key_file: keys/release.pub.pem
  swap_algorithm: scratch       # scratch | move | overwrite — NO fixed default; see below
  build_type: Release           # Release | Debug | MinSizeRel (propagates to MCUboot + TF-M)
```

Project-wide — the bootloader is a device-level artifact, not a per-OS choice. The loader emits a `SB_CONFIG_*` sysbuild overlay (signature type, swap algorithm). `build_type:` propagates to both the MCUboot and TF-M sysbuild child images so they ship the same flavour.

Defaults from the SoM family apply when `boot:` is omitted: AEN → MCUboot + ECDSA-P256 (swap strategy per the slot-layout rule below); V2N / V2N-M1 → `method: none` on the Zephyr slice (U-Boot owns boot on the Linux side).

### `swap_algorithm:` — no fixed default, and single-slot targets refuse it {#swap-algorithm}

The enum is `scratch` (crash-safe, needs scratch partition), `move` (more erases, no scratch), `overwrite` (no rollback). **There is no fixed schema default.** When `swap_algorithm:` is omitted, the SDK derives the default from the target's **real slot layout**:

| Target slot layout | Omitted `swap_algorithm:` resolves to |
|---|---|
| Stock two-slot AEN target | `scratch` |
| **Single-slot** target (e.g. `E1M-AEN801`, whose disjoint-slot0 `memory_map:` has no slot1/scratch region — alp-sdk #1069 / #1413) | the SDK's stock **single-app boot** instead |

:::danger[Behaviour change: setting `swap_algorithm:` on a single-slot target is now a build error]
**Setting any of the three values explicitly on a single-slot target is a build-time `OrchestratorError`** — that target has no slot1/scratch partition for any of them to swap into.

A `board.yaml` that was previously valid can trip over this: the schema used to declare `"default": "scratch"`, so `swap_algorithm: scratch` was the natural thing to write out longhand. On `E1M-AEN801` that line now fails the build. **Delete the key** and let the slot layout decide — don't switch it to `move` or `overwrite` to get past the error, because all three are refused on a single-slot target.
:::

:::info[Removed in v0.11.0: `slots:`, `scratch_size_kib:`, `anti_rollback:`]
Slot and scratch **sizes** are not configurable in `board.yaml`. MCUboot takes its slot geometry from the board DT partitions — an SDK build-policy choice, not a per-project field. Use [`storage:`](#storage-block) to declare the actual partition table.

`anti_rollback:` was removed because only **software** downgrade prevention is wired today ([`ota.rollback.min_version`](#ota-block)); the OPTIGA / OTP hardware-counter tier is unbuilt. The field promised a security guarantee the SDK did not deliver — if you relied on it, `ota.rollback.min_version` is what was actually enforcing your floor.
:::

Cross-field validator rule R2 rejects `signing.algorithm:` values not supported by the SoM family (Alif Ensemble: `ecdsa_p256` / `ed25519`; Renesas RZ/V2N and RZ/V2N + DEEPX: `ecdsa_p256` / `rsa2048` / `rsa3072`).

For `method: mcuboot`, `rsa3072` is additionally **rejected at emit time**: sysbuild's `BOOT_SIGNATURE_TYPE` choice carries no RSA key-length knob, so there is no way to express 3072 until a per-image `sysbuild/mcuboot.conf` overlay seam ships. Use `rsa2048` (mcuboot's RSA default length), `ecdsa_p256`, or `ed25519`. `rsa3072` stays load-bearing for the Renesas RZ/V2N U-Boot / FIT signing path, which doesn't go through sysbuild.

## `ota:` block {#ota-block}

```yaml
ota:
  provider: mender              # mender | hawkbit | mcumgr | none (REQUIRED)
  artifact_name: alp-v0.4-v2n101-build42
  signing_key: keys/ota.pub.pem
  server:
    url:    https://hosted.mender.io
    tenant: ${MENDER_TENANT_TOKEN}
  poll_interval_s: 1800         # SECONDS; default 1800 (30 min); min 60. hawkbit: see below
  rollback:
    enabled:     true
    retries:     3
    min_version: 100            # anti-downgrade floor
  storage:                      # Yocto/Linux-only A/B rootfs geometry
    device:        /dev/mmcblk0p
    boot_part_mb:  256
    rootfs_ab:     true
    total_size_mb: 4096
```

`ota.provider:` is **provider-driven dispatch** (ADR 0009 follow-up). The loader emits real Kconfig + machine config per provider:

| Provider  | Zephyr emit                                                                                                | Yocto emit                                                              |
|-----------|------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------|
| `mender`  | `CONFIG_MENDER_MCU_CLIENT=y` + server URL / tenant / artifact name / poll interval (Mender-MCU-client)     | `MENDER_*` weak-assignments in `local.conf` + `INHERIT += "mender-full"`|
| `hawkbit` | `CONFIG_HAWKBIT=y` + `CONFIG_HAWKBIT_SHELL=y` + `HAWKBIT_SERVER` + `HAWKBIT_POLL_INTERVAL` (Zephyr upstream) | —                                                                       |
| `mcumgr`  | `CONFIG_MCUMGR=y` + `CONFIG_MCUMGR_GRP_IMG=y` + `CONFIG_MCUMGR_GRP_OS=y` (transport selection is the app's call) | —                                                                  |
| `none`    | —                                                                                                          | —                                                                       |

:::warning[Removed in v0.17.0: `ota.server.tls_ca_bundle`]
`server:` now accepts only `url` and `tenant`; a `tls_ca_bundle:` key fails schema validation. No emitter ever read it: the Hawkbit path derives TLS solely from the scheme of `url` (`CONFIG_HAWKBIT_USE_TLS`) with no CA registration, and the Mender path emits no CA variable. The field promised a pinned trust anchor the SDK didn't deliver, so it was removed rather than kept as a silent no-op. Delete the line; if you need a pinned CA, provision it in your own application.
:::

Validator rule R1 enforces target presence per provider: `mender` accepts either a Yocto or Zephyr core; `hawkbit` / `mcumgr` require at least one Zephyr core. The `--emit west-libraries` fragment auto-adds the `mender-mcu-client` `name-allowlist:` entry when `provider: mender` is declared.

### `poll_interval_s:` — seconds here, minutes on hawkbit {#poll-interval}

`poll_interval_s:` is in **SECONDS** (`minimum: 60`, `default: 1800` — 30 min, battery-friendly; Mender's own default is 60 s).

:::warning[hawkbit rounds nothing — a non-minute value is refused at emit]
`provider: hawkbit` converts the value to `CONFIG_HAWKBIT_POLL_INTERVAL`, which **Zephyr declares in MINUTES** with `range 1 43200`. So a hawkbit project's `poll_interval_s:` **must be a whole number of minutes between 60 s and 2592000 s — anything else is refused at emit** rather than written out of range.

Concretely: `1800` (30 min) is fine; `90` is not a whole number of minutes and fails; `2592060` is above the range and fails. The constraint is scoped to `provider: hawkbit` — the other providers take the seconds value as written.
:::

`ota.storage:` is Yocto/Linux-only (the kernel-side A/B partition geometry); ignored on Zephyr where MCUboot's slot layout governs.

## `storage:` block {#storage-block}

```yaml
storage:
  - name: settings              # required; pattern ^[a-z][a-z0-9_]*$
    size_kib: 64                # required; min 4
    fs: littlefs                # littlefs | fat | ext4 | raw (default: raw)
    mount: /lfs/settings        # optional; omit to skip auto-mount
    flash_device: mram_main     # SoM memory_map: region OR on_module.ospi_memories: key.
                                # Read the resolution rules below before relying on this —
                                # no target resolves to a working DT label today.

  - name: app_data
    size_kib: 128
    fs: littlefs
    mount: /lfs/app
    flash_device: mram_main

  - name: mcuboot_scratch       # raw partition for MCUboot swap scratch
    size_kib: 32
    fs: raw
    flash_device: mram_main

  - name: legacy_blob
    size_kib: 1024
    flash_device: ospi0
    offset_kib: 4096            # explicit 4 KiB-aligned offset override
```

Schema-authoritative filesystem partitions with a deterministic flash-partition allocator. The orchestrator name-sorts entries within each `flash_device:`, page-aligns to 4 KiB, and writes byte-stable offsets across rebuilds. Blocked entries (TBD capacity, unknown device, page-misaligned offset, sibling overlap, **unresolvable Devicetree label** — see below) land in `system-manifest.yaml` with `status: blocked` so reviewers see the gap.

### `flash_device:` — what resolves, and what is refused {#flash-device}

`flash_device:` references either a SoM `memory_map:` region (e.g. `mram_main`, `ocram_low`) or an `on_module.ospi_memories:` key (e.g. `ospi0`). Both were tightened materially in v0.16.0 (alp-sdk #1484, #1556).

**A `memory_map:` region marked `carveout: false` is refused as a target** (#1484). Such a region is a partition *inside* a flash-class node, not a flash device of its own. Naming an AEN MRAM sub-region — `mcuboot`, `he_slot0`, `hp_slot0`, `reserved`, `storage`, `atoc` — resolves and decorates a Devicetree label that **does not exist on the board**; that fabrication is the defect being refused.

:::warning[No target resolves to a genuinely working Devicetree label today]
Verbatim from the schema: **"No target resolves to a genuinely working Devicetree label today."**

A `memory_map:` region's label **defaults to the region name** when the SoM preset sets no explicit `dt_label:` override — and **neither `mram_main` nor `ocram_low` carries that override**. As of **alp-sdk#1556** the resolver **refuses `status: ok`** for that case: it blocks with a reason instead of decorating an unverified, fabricated `dt_label`. So a `storage:` entry pointing at `mram_main` or `ocram_low` lands `status: blocked` in `system-manifest.yaml` rather than silently emitting a partition node under a label the board tree never defines.

An `on_module.ospi_memories:` key such as `ospi0` is **likewise unverified** against the generated board tree, but is **NOT yet gated the same way** — that is a separate follow-up. Do not read `ospi0`'s lack of a block as evidence that it resolves.
:::

**An OSPI device the chosen SKU doesn't carry is refused** (#2311, new in v0.17.0). An `on_module.ospi_memories:` key marked `assembled: false` on your SKU — a footprint designed into the PCB but not populated on that configuration — is rejected as a `flash_device:` with that reason. `E1M-AEN801` is the case to know: its `ospi0` / `ospi1` are both `assembled: false`, while `E1M-AEN803` fits the NOR. Pick a device your SKU actually carries.

The design record for the way out is **ADR 0027 (Proposed)** — *"Storage regions are declared by ROLE; `flash_device:` becomes an explicit pin"*.

Emit artefacts:

- `build/generated/dts-partitions.dtsi` — partial DTS overlay attaching a `partitions { compatible = "fixed-partitions"; … }` child node under `&<flash_device>`. Apps reach partitions via Zephyr's `FIXED_PARTITION_ID(<name>_partition)`.
- `build/generated/storage-mounts.c` — optional static `fs_mount_t alp_storage_mounts[]` table for boot-time iteration.
- Per-fs Kconfig in `alp.conf`: `CONFIG_FILE_SYSTEM=y` + the matching `CONFIG_FILE_SYSTEM_LITTLEFS=y` / `CONFIG_FAT_FILESYSTEM_ELM=y` / `CONFIG_FILE_SYSTEM_EXT4=y` + per-littlefs `CONFIG_FS_LITTLEFS_PARTITION_<NAME>=y`.

The loader rejects typoed `flash_device:` references at parse time with the list of known devices, and duplicate partition names within `storage:` error eagerly.

## `security:` block (PSA + TF-M) {#security-block}

```yaml
security:
  psa:
    persistent_slots: 16        # CONFIG_PSA_CRYPTO_PERSISTENT_SLOT_COUNT (default 16)
    its_storage:      mram_secure       # ITS backing region (SoM memory_map: name)
    ps_storage:       ospi0             # optional PS backing (e.g. OSPI EEPROM)
    tfm:              true              # enable TF-M sysbuild child image
    attestation_root: optiga_trust_m    # optiga_trust_m | tfm_internal | none (default)
```

When `security.psa.tfm: true` the loader emits a `SB_CONFIG_TFM=y` + `SB_CONFIG_TFM_BUILD_TYPE=<flavour>` overlay at `build/sysbuild/tfm/tfm.conf` (build type is inherited from `boot.build_type:`). With `tfm: false`, PSA Crypto still runs — entirely non-secure (mbedTLS-only).

`its_storage:` / `ps_storage:` reference either a SoM `memory_map:` region name (typically `mram_secure` on AEN, `ocram_secure` on V2N) or a `storage[].name` from the [`storage:` block](#storage-block). Errors point at the offending YAML path.

`attestation_root: optiga_trust_m` requires the SoM to physically ship OPTIGA Trust M. The loader rejects this value on SoMs that don't carry OPTIGA — and, as of v0.17.0 (#2316), on SKUs where the part is named but **not assembled**. `E1M-AEN801` and `E1M-AEN803` both carry the OPTIGA footprint but fit no part (`assembled: false`), so on those SKUs pick `tfm_internal` or `none`. The V2N / V2M SKUs and the other AEN SKUs populate it.

A `ps_storage:` / `its_storage:` reference to an `on_module.ospi_memories:` key that is `assembled: false` on the chosen SKU is refused the same way (#2311). On a SKU with no OSPI fitted (e.g. `E1M-AEN801`), point the backing store at `mram_main` instead.

See ADR 0013 for the M55-HP TrustZone-M trust-boundary decision.

## `cores.<id>.memory:` and `cores.<id>.power:`

```yaml
cores:
  m55_he:
    memory:
      stack_kib:     4          # CONFIG_MAIN_STACK_SIZE = 4096
      heap_kib:      16         # CONFIG_HEAP_MEM_POOL_SIZE = 16384
      isr_stack_kib: 2          # CONFIG_ISR_STACK_SIZE = 2048
    power:
      sleep_mode:     standby   # disabled | idle | standby | deep (default: disabled)
      wakeup_sources: [uart, gpio, rtc]
```

Per-core tuning that previously needed hand-written Kconfig.  Zephyr slices only — ignored on Yocto / baremetal.

`sleep_mode != disabled` emits `CONFIG_PM=y` + `CONFIG_PM_DEVICE=y` and selects the matching `PM_STATE_*` hierarchy. Each entry in `wakeup_sources:` is either a peripheral subsystem name (`uart`, `gpio`, `rtc`, `i2c`, …) or an `E1M_*` pad name. Both land in `alp.conf` as hint comments only: Zephyr has no `CONFIG_PM_DEVICE_WAKE_<SUBSYS>` symbol, so wire each wake source with the devicetree `wakeup-source;` property and a runtime `pm_device_wakeup_enable()` call.

Validator warnings:

- (W4) `inference.default_arena_kib > memory.heap_kib` — inference may OOM. Build continues; stderr `WARN: …` line emitted.
- (W5) `power.sleep_mode != disabled` with no `wakeup_sources:` declared — device will sleep but cannot wake.

## `diagnostics:` block {#diagnostics-block}

```yaml
diagnostics:
  log_level: info               # error | warn | info | debug | trace (default: info)
  last_error: true              # alp_last_error() thread-local slot (default: true)
  console: auto                 # auto | alp | uart | ram | linux | none (default: auto)
  link: auto                    # auto | itcm (default: auto) — AEN M55-HE RAM-run only
  sim_console: false            # opt-in RAM console for headless cores (default: false)
  modules:
    alp_iot:       debug        # Alp SDK module name
    alp_inference: warn
    alp_security:  "off"        # quote 'off' — bare off parses as YAML false
    i2c:           debug        # Zephyr log module the SDK wires
    net_tcp:       warn
```

`diagnostics.modules:` emits per-module `CONFIG_<MODULE>_LOG_LEVEL_<LEVEL>=y` per entry so you can dial individual subsystems up or down without flooding the console. Per-module values use the same enum as `log_level:` plus `off` (silence the module entirely). **Quote `off`** — bare `off` parses as YAML false and the loader rejects it.

**The key space is wider than the Alp SDK.** Keys are either Alp SDK module names (`alp_iot`, `alp_inference`, `alp_audio`, `alp_security`, `alp_gpio`, …) **or Zephyr log modules the SDK wires** (`i2c`, `spi`, `gpio`, `adc`, `net_tcp`, …).

Because a Zephyr module's log-level choice symbol only exists where that module is actually built, the emit is conditional: a level is written **live only where that choice symbol exists** — i.e. the module **and** `CONFIG_LOG` are both enabled on that core — and is **downgraded to a hint comment otherwise, so the fragment always configures**. Naming a module that isn't available on a core never fails the build; it also never takes effect there, so check the generated `alp.conf` if a level you set appears to be ignored.

### `console:` — the backend, not the wire

Picks the console *backend* the loader wires per slice. The board layer still owns the physical console UART (the `zephyr,console` DT chosen node + pinmux); this knob only selects the backend.

| Value | Effect |
|---|---|
| `auto` (default) | Resolve from the slice's OS and the SoM topology — see below |
| `alp` / `uart` | Zephyr UART console; printf/LOG land on the module's console UART |
| `ram` | Zephyr RAM console — read `ram_console_buf` over SWD on a serial-less bench |
| `linux` | Yocto/Ubuntu stdio/tty console |
| `none` | Emit no console Kconfig; inherit the board default |

**`auto` resolution depends on whether the core has a hardware console.** A Zephyr slice on a core the SoM topology marks `hw_console: true` resolves to `uart`; a Yocto/Ubuntu slice resolves to `linux`. But a **headless** core (`hw_console: false` — no hardware UART, e.g. the RZ/V2N M33 system-manager) resolves to **`none`**, *not* `uart`.

That last case matters: emitting `CONFIG_UART_CONSOLE=y` on a core whose board has no serial driver is an "assigned y but got n" Kconfig error and a fatal build failure. An explicit `console:` always wins over the auto path, on headless cores too.

### `link:` — link an AEN image into ITCM for a RAM-run {#diagnostics-link}

New in v0.17.0 (built by `tan build` from tan v0.7.0). Picks where the built image is linked:

| Value | Effect |
|---|---|
| `auto` (default) | Link where the board puts the image — E1M-AEN slices link into MRAM slot0 for the production flows |
| `itcm` | Link the M55-HE image into ITCM (base `0x0`, global window `0x58000000`) for a RAM-run with `tan flash --ram`, which loads it over J-Link and never writes MRAM |

With `itcm`, the planner writes an ITCM retarget Kconfig fragment and devicetree overlay beside the slice's `alp.conf` and layers them into the build. Only the M55-HE slice is retargeted, and its manifest entry carries `flash_method: ram_run_only`, so a plain `tan flash` can't write it to MRAM.

`itcm` is accepted **only** on the Alif Ensemble E8 M55-HE (`E1M-AEN801` / `E1M-AEN803`). `tan build` refuses it for any other SKU, for a project with no `os: zephyr` app on `cores.m55_he` (an M55-HP-only project included), and for a sysbuild project (one with `boot:`, `ota:` or TF-M — a RAM-run image has no MCUboot slot). The console is constrained too: `console: auto` is promoted to `ram` (read `ram_console_buf` over SWD, or with `tan flash --ram --ram-console`), `uart` / `alp` are accepted for a RAM-run UART shell, and `linux` / `none` are refused. (The schema's own description still says `uart` is refused; tan v0.7.0 accepts it.)

:::danger[An `itcm` image is not bootable from MRAM]
It is linked at `0x0`. Never use `link: itcm` for an image you intend to flash to MRAM — keep it to bench RAM-runs.
:::

`link:` is implemented by `tan build` only. The SDK's own `scripts/alp_orchestrate/` loader refuses any value other than `auto` rather than silently emitting an MRAM-linked image, so build `itcm` projects with `tan build`.

### `sim_console:` — give a headless core a console in the simulator

Opt-in. When `true`, emits `CONFIG_RAM_CONSOLE=y` for every **headless** core, so the studio hardware simulator's `uart_socket` can stream that core's boot/console output instead of sitting silent. Cores that already have a UART console are unchanged, and absent/`false` emits nothing — no RAM cost on production images.

Precedence is narrow by design: `sim_console:` only upgrades a core whose console **auto-resolved to `none`** because it's headless. An explicit `diagnostics.console:` is never overridden. The emitted Kconfig is identical to `console: ram`; only the teaching comment differs, so a reader can tell a bench SWD flow from a simulator one.

`sim_console:` is **retained** in alp-sdk v0.16.0 — schema, metadata, emitters and docs — even though Renode left the SDK with [ADR 0022](https://github.com/alplabai/alp-sdk/blob/main/docs/adr/0022-python-executor-renode-retirement.md) Amendment 2. Its consumer is **Alp Studio's hardware simulator**, which reads the RAM console out of the image bundle; it never was a `tan renode` key. There is no `tan renode` verb any more — see [the `tan` CLI page](https://docs.alplab.ai/sdk/tools/cli#renode-retired).

## Cross-field validation

`scripts/alp_orchestrate/`'s `_validate_consistency()` runs after the JSON Schema pass and the per-core loader rules. Five rules, two warnings:

| ID  | Severity | Rule                                                                                                       |
|-----|----------|------------------------------------------------------------------------------------------------------------|
| R1  | ERROR    | `ota.provider: mender` works on both Yocto + Zephyr; `hawkbit` / `mcumgr` require at least one Zephyr core. |
| R2  | ERROR    | `boot.signing.algorithm:` must match the SoM family allow-list.                                            |
| R3  | ERROR    | `cores.<id>.iot.tls: true` requires `mbedtls` or `bearssl` in the top-level `libraries:` / the core's `extra_libraries:`. |
| R4  | WARN     | `cores.<id>.inference.default_arena_kib > cores.<id>.memory.heap_kib` — inference may OOM.                 |
| R5  | WARN     | `cores.<id>.power.sleep_mode != disabled` with no `wakeup_sources:` declared.                              |

Errors fail the build with the offending YAML path; warnings emit a stderr `WARN:` line and continue.

## `ipc` block (cross-core carve-outs)

```yaml
ipc:
  - kind:         rpmsg                       # rpmsg | raw_shmem | mailbox_only (REQUIRED)
    endpoints:    [a55_cluster, m33_sm]       # ≥2 core IDs (REQUIRED)
    carve_out_kb: 512                          # KiB requested (REQUIRED)
    name:         alp_default_rpmsg            # ^[a-z][a-z0-9_]*$ (REQUIRED)
    # cacheable: true                          # raw_shmem only — rejected on rpmsg (see below)
    address:      0x10078000                   # optional — pin to an explicit base
```

Each entry declares a shared-memory region the orchestrator allocates from the SoM preset's `memory_map:` regions whose `accessible_from:` covers every listed endpoint. Addresses + endpoint IDs + mailbox channel macros are emitted into `build/generated/alp/system_ipc.h`, which both halves `#include`. App code uses [`<alp/rpc.h>`](https://docs.alplab.ai/sdk/api/rpc) — never raw addresses.

Kinds:

- `rpmsg` — OpenAMP-framed.
- `raw_shmem` — plain shared memory + customer-owned synchronisation.
- `mailbox_only` — doorbell + signal only, no shared memory.

**The carve-out is non-cacheable by default, on every silicon.** The allocator prefers a `memory_map:` region whose `cacheable:` attribute matches the entry's preference, and the preference is non-cacheable unless the entry says otherwise. The SDK performs no cache maintenance anywhere in `<alp/rpc.h>` or `<alp/mproc.h>`, so the safe default is to keep shared memory out of the D-cache entirely (below).

`cacheable: true` is accepted on `kind: raw_shmem` only, as an explicit opt-out: it declares that your application does its own cache clean/invalidate. On `kind: rpmsg` the loader **rejects** `cacheable: true` outright, because `<alp/rpc.h>` has no cache-maintenance layer behind it — remove the key (or set it to `false`).

### `raw_shmem` and `rpmsg` auto-emit `CONFIG_DCACHE=n`

Declaring an `ipc` entry with `kind: raw_shmem` or `kind: rpmsg` causes the build to emit `CONFIG_DCACHE=n` automatically for **every core named in that entry's `endpoints`**. A `raw_shmem` entry can opt out with `cacheable: true`; an `rpmsg` entry has no opt-out. It does not apply to `kind: mailbox_only`, which carries no shared memory.

```yaml
ipc:
  - { kind: raw_shmem, endpoints: [m55_hp, m55_he], carve_out_kb: 4, name: alp_shmem0 }
```

This closes a cross-core SRAM0 D-cache incoherence that produced **silent false-negative results** — one core's writes sat in its own D-cache while the peer read stale SRAM0 and saw a plausible-looking wrong answer rather than a failure.

## `peripherals` / `chips`

```yaml
cores:
  m55_hp:
    peripherals: [i2c, pwm, adc]   # per-slice

chips:
  - lsm6dso                        # project-wide chip drivers
  - ssd1306
```

The orchestrator gates each peripheral and chip driver on a Kconfig symbol so unused code doesn't cost flash. Listing a chip in `board.yaml` is equivalent to setting `CONFIG_ALP_SDK_CHIP_<NAME>=y` by hand — but with validation that the SoM actually routes the bus the chip needs.

## `cameras:` block (camera modules) {#cameras-block}

New in v0.17.0. Names the camera module fitted to each of the board's camera connectors, and the build wires the matching driver into the one core that owns it:

```yaml
som:
  sku: E1M-AEN803
preset: e1m-evk

cores:
  m55_he:
    app: ./src                         # the customer app that will own the camera

cameras:
  - connector: CAM0                    # a key of the board's camera_connectors
    module: innomaker_cam_ov9281       # metadata/camera_modules/<module>.yaml
    # core: m55_he                     # optional — see "Which core owns the camera"
```

| Field       | Required | Notes |
|-------------|----------|-------|
| `connector` | yes      | `^CAM[0-9]+$`. Must be a connector the resolved board declares under `camera_connectors:`; `CAMn` is camera index `n`. |
| `module`    | yes      | A module id with a manifest at `metadata/camera_modules/<module>.yaml`. The sensor chip is implied by the module. |
| `core`      | no       | The core that owns the camera. Omit it when exactly one core can. |

An unknown `connector` or `module` is rejected at validation.

### Camera modules

| Module id | Sensor | I2C (7-bit) | CSI-2 lanes | Zephyr shield | E1M-X EVK `CAM0` Linux fragment |
|---|---|---|---|---|---|
| `innomaker_cam_ov9281` | OV9281 (global-shutter mono) | `0x60` | 2 | `innomaker_cam_ov9281` | generated, bench-unverified |
| `innomaker_cam_imx335` | IMX335 (5 MP colour) | `0x1A` | 2 | `innomaker_cam_imx335` | generated, bench-unverified |
| `raspberry_pi_camera_module_1` | OV5647 (5 MP raw Bayer) | `0x36` | 2 | `raspberry_pi_camera_module_1` | generated, bench-unverified |
| `raspberry_pi_camera_module_2` | IMX219 (8 MP) | `0x10` | 2 | — (Linux only) | generated, bench-unverified |
| `raspberry_pi_global_shutter_camera` | IMX296LQR-C (1.58 MP global-shutter colour) | `0x1A` | 1 | `raspberry_pi_global_shutter_camera` | generated, **bench-verified** on `E1M-V2M103` |

A module manifest (schema `camera-module-v1`) carries what the sensor's own chip manifest can't know: the module's I2C strap address, its oscillator (`xclk_hz`), the lanes it routes, its Zephyr shield (when one exists), and any per-module CSI-2 host or ISP settings a Zephyr shield needs. Unless a module is marked bench-verified for Linux, its generated Linux devicetree fragment carries a `BENCH-UNVERIFIED` header line.

### Which core owns the camera

A camera belongs to **exactly one core**, and only that core's build is touched:

- **Zephyr owner** → one `-DSHIELD=<carrier shields> <module shield>` define on that slice (the carrier half from the connector's `zephyr_shields:`, the camera half from the module's `zephyr_shield:`; on a sysbuild project it is `-D<image>_SHIELD=…` so MCUboot doesn't receive it).
- **Yocto owner** → `ALP_CAMERA_CAM<n> = "<module_id>"` in that slice's `local.conf`. The kernel recipe keys a generated sensor devicetree include on that variable — today for `CAM0` only.

The candidates are the cores the **connector** supports: a Zephyr core running a customer app (never the SDK's `alp-stock-shim`) needs a connector with `zephyr_shields:` and a module with a `zephyr_shield:`; a Yocto core needs a connector with `linux: true`. Exactly one candidate → it owns the camera. None, or more than one, is an error (`tan validate` reports it as `ALP-B003`) until you set `cameras[].core`. A Zephyr owner also needs each carrier shield to ship an overlay for that core's board target, and a module shield can be used on only one connector per core.

On the stock boards today, `e1m-evk`'s `CAM0` (J5, 15-pin Raspberry-Pi CSI-2, 2 lanes) is a Zephyr connector (`e1m_evk_rpi_csi` carrier shield), and `e1m-x-evk`'s `CAM0` (J5, 2 lanes) is a Linux-only connector with no Zephyr shield.

### `camera_connectors:` — declaring connectors on a custom board

In preset mode the connectors come from the preset. In inline mode, declare them at the top level, keyed `CAM0`, `CAM1`, …. Every signal is a **reference** to a macro or E1M identifier already in your `e1m_routes:` — never a restated pad:

```yaml
camera_connectors:
  CAM0:
    refdes: J5                     # connector reference designator on your carrier
    csi:    E1M_X_CSI0             # E1M CSI-2 receiver instance (E1M_CSI<n> / E1M_X_CSI<n>)
    lanes:  2                      # data lanes the connector routes (1..4)
    i2c:    CAM_I2C_BUS            # macro of the e1m_routes `buses` entry for camera control
    select:                        # optional: GPIO levels that route a carrier CSI mux here
      - { gpio: PIN_CAM0_MUX_SEL, value: 0 }
    enable: PIN_CAM0_EN            # optional: e1m_routes gpio macro; its active_low is normative
    reset:  PIN_CAM0_RST           # optional: e1m_routes gpio macro; its active_low is normative
    supply: fixed-3v3              # optional: an always-on fixed supply pin
    lane_polarity: [1, 1, 1]       # optional: per-lane P/N inversion, clock lane first
    linux: true                    # Yocto camera path (see below)
    # zephyr_shields: [<carrier shield>]   # Zephyr carrier half, if one exists
```

- `select:` `value` is the raw pad level, unaffected by the route's `active_low`.
- For `enable:` and `reset:`, the referenced route's `active_low` **is** load-bearing: generators emit `GPIO_ACTIVE_LOW` from it. Asserted `enable` means "camera on", so an enable behind an inverting stage (e.g. an N-FET that pulls the module enable low) must carry `active_low: true`; asserted `reset` means "held in reset".
- `supply: fixed-3v3` tells the generator that the module makes its own sensor rails from an always-on 3.3 V pin, so every sensor `*-supply` binds to one fixed regulator.
- `linux: true` is allowed only on `CAM0` of an RZ/V2N-family board. `zephyr_shields:` names Zephyr carrier shields in `-DSHIELD` order; omit it when none exists (no Zephyr core can then own that connector's camera).

## `ownership:` block (per-product core ownership) {#ownership-block}

New in v0.17.0, for the RZ/V2N family. Some E1M instances can in principle be driven by either the A55 (Linux) or the M33 (Zephyr); `ownership:` names the owner per product:

```yaml
ownership:
  e1m_uart1: a55          # {<E1M instance>: a55 | m33}
```

Only the instances the SoM family declares as assignable can appear, and the core must be one of that instance's allowed candidates — the loader rejects anything else, naming the instance and the allowed cores. Omitted instances keep their default, and fixed (non-assignable) ownership can't be overridden. As of v0.17.0 the assignable V2N instances are `e1m_uart0`, `e1m_uart1`, `e1m_spi0`, `e1m_can0` and `e1m_can1`, all defaulting to `a55` with `a55` as the **only** allowed candidate — so the block is accepted, but there is no M33 hand-off you can select yet.

## `models:` block (AI model packaging) {#models-block}

Top-level optional array. Each entry names a source model the SDK compiles for **every** NPU back-end the SoM can drive (derived from `som.sku` — you don't list back-ends here) and packages into one fat [`.alpmodel`](https://docs.alplab.ai/sdk/api/inference#portable-model-packages-alpmodel) via `tan model build`.

```yaml
models:
  - name: classifier               # required; ^[A-Za-z][A-Za-z0-9_-]*$
    source: models/mobilenet.onnx  # required; path relative to board.yaml
    compile:                       # per-backend config the SDK can't derive
      deepx_dxm1:
        config:      models/mobilenet.dxcom.json # dxcom quant/compile config
        calibration: models/calib/               # PTQ calibration dataset dir
      drpai:
        input_shape: "1,3,224,224"               # NCHW, string or list → DRP-AI TVM `-s`
        input_name:  input                       # ONNX graph input tensor → `-i`
        images:      models/calib-images/        # PTQ calibration image dir → `--images`
        product:     V2N                         # optional; V2N (default) or V2H
```

| Field     | Required | Notes                                                                                                                                                                                 |
|-----------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `name`    | yes      | `^[A-Za-z][A-Za-z0-9_-]*$`. Names the output `.alpmodel`.                                                                                                                              |
| `source`  | yes      | Path (relative to `board.yaml`) to the source model. `.tflite` compiles for CPU (TFLM) + Ethos-U (Vela) out of the box; `.onnx` needs a vendor toolchain (DRP-AI / DEEPX) on the build host, else it's recorded as a coverage skip; `.pte` (ExecuTorch) passes through for CPU — see [below](#pte-executorch). |
| `spec`    | no       | `$ref` to an external model spec, for large or shared models.                                                                                                                          |
| `inputs`  | no       | App-side input hints (e.g. layout).                                                                                                                                                   |
| `compile` | no       | Per-backend compile config for NPU toolchains that need a per-model config + calibration the SDK can't derive. Keys are back-end ids; a back-end with no block is recorded as a coverage skip ("no compile config") rather than guessed. `compile.deepx_dxm1` requires `config` + `calibration`; `compile.drpai` requires `input_shape` + `input_name` + `images` (optional `product`). Paths are relative to this `board.yaml`. |

:::warning[Changed in v0.17.0: `compile.drpai.spec` is gone]
`compile.drpai:` no longer takes a `spec:` file. It now carries the three facts the DRP-AI TVM driver is invoked with directly — `input_shape` (NCHW, as `"1,3,224,224"` or `[1, 3, 224, 224]`), `input_name` (the ONNX graph input tensor), and `images` (a calibration image directory for post-training INT8 quantization) — plus an optional `product` (`V2N` or `V2H`; defaults to `V2N`). A `board.yaml` still carrying `spec:` fails schema validation.

The DRP-AI `--images` calibration path only preprocesses to the 224 × 224 ImageNet-classifier geometry, so tan v0.7.0 refuses a DRP-AI compile whose `input_shape` isn't `1,3,224,224`.
:::

### `.pte` — ExecuTorch source models are producible, not yet invocable {#pte-executorch}

`source:` accepts a third format as of v0.16.0: **`.pte`**, an ExecuTorch `torch.export` program. It **passes through for CPU** via `scripts/alp_model/adapters/executorch.py`.

:::warning[A `.pte` build succeeds and the resulting blob still cannot run on device]
**No on-device ExecuTorch runtime backend exists yet**, so the resulting blob is **producible but not yet invocable** (alp-sdk #1260). The build will not warn you at load time — the device-side rule is where it surfaces: [`ALP_INFERENCE_MODEL_EXECUTORCH = 4`](https://docs.alplab.ai/sdk/api/inference#alp_inference_model_executorch--4-is-producible-but-not-invocable) is **RESERVED**, and a blob claiming it is **rejected with `ALP_ERR_INVAL`**.

Ship `.tflite` (or `.onnx` through a vendor toolchain) for anything that has to actually execute today.
:::

Compile the packages with `tan model build` (see [Inference](https://docs.alplab.ai/sdk/api/inference#building-a-package)); load them at runtime with `alp_inference_open_alpmodel()`.

## How the orchestrator compiles the file

`scripts/alp_orchestrate/` (driven by `tan build`) reads `board.yaml`, validates against the schema, resolves the SoM SKU + board preset + per-core topology, applies overrides, runs the cross-field validator, and emits **per-slice native configs** plus **cross-slice generated artefacts**.

### Generated artefacts (deterministic, byte-stable across rebuilds)

| Path                                          | What it carries                                                                |
|-----------------------------------------------|--------------------------------------------------------------------------------|
| `build/system-manifest.yaml`                  | Per-slice status, log paths, artefact paths, boot order, blocked storage rows. |
| `build/generated/alp/system_ipc.h`            | Endpoint IDs, addresses, mailbox channel macros — shared by all slices.        |
| `build/generated/dts-reservations.dtsi`       | `reserved-memory:` carve-outs shipped into Linux + Zephyr DTs.                 |
| `build/generated/dts-partitions.dtsi`         | `fixed-partitions` overlay from the resolved `storage:` block.                 |
| `build/sysbuild/tfm/tfm.conf`                 | TF-M sysbuild child-image overlay (when `security.psa.tfm: true`).             |
| `build/<core>-zephyr/alp.conf`                | Kconfig fragment layered onto each Zephyr slice's `prj.conf`.                  |
| `build/<core>-yocto/conf/alp-generated.conf`  | `local.conf` snippet consumed by bitbake (`MACHINE=…`, `IMAGE_INSTALL`).       |

The system manifest is consumed downstream by `tan image` (assembles the bundle), `tan flash` (walks `boot_order:` per artefact), and OTA (`<alp/ota.h>`).

### Per-slice emit modes (driven manually if you bypass `tan build`)

| `--emit` mode         | Output                                                                       |
|-----------------------|------------------------------------------------------------------------------|
| `zephyr-conf`         | `alp.conf` — Kconfig fragment, layered over `prj.conf` via `OVERLAY_CONFIG`. |
| `cmake-args`          | A list of `-D` flags for plain CMake / bare-metal.                           |
| `yocto-conf`          | `local.conf` snippet (`MACHINE=…`, `IMAGE_INSTALL` deltas).                  |
| `dts-overlay`         | Zephyr DTS overlay with `alp,pin-array` + bus aliases.                       |
| `dts-partitions`      | Fixed-partitions overlay for the resolved `storage:` block.                  |
| `storage-mounts-c`    | Static `fs_mount_t alp_storage_mounts[]` table.                              |
| `tfm-sysbuild-conf`   | TF-M sysbuild child-image overlay.                                           |
| `system-manifest`     | Final system manifest YAML.                                                  |
| `ipc-contract-h`      | `<alp/system_ipc.h>`.                                                        |
| `hw-info-h`           | `<alp_hw_info_build.h>` with `ALP_HW_BUILD_*` macros.                        |
| `west-libraries`      | `west.yml` fragment pinning the libraries `board.yaml` requested.            |
| `build-plan`          | Deterministic, write-free JSON build plan (one slice per non-`off` core, sorted by `coreId`) — the contract IDE/CLI tooling consumes (ADR 0014). |
| `os-topology`         | Per-core natural-vs-effective OS facts as JSON (`core_type`, `runtime_class`, `default_os`, `effective_os`, `allowed_os`). |
| `carrier-netlist`     | Schema-versioned JSON handoff for Alp Studio — carrier-facing nets + carrier BOM. See below. |
| `linux-ownership-dts` | V2N family: the Linux devicetree fragment for this project's resolved [`ownership:`](#ownership-block). New in v0.17.0. |

There is no single `tan` verb covering the whole catalog. [`tan generate`](https://docs.alplab.ai/sdk/tools/cli) writes nine targets by default (`zephyr-conf`, `dts-overlay`, `native-sim-overlay`, `cmake-args`, `yocto-conf`, `carrier-netlist`, `west-libraries`, `hw-info-h`, `os-topology`) and three more only when named with `--target` (`zephyr-board`, `ipc-contract-h`, the demonstrator `composed-route-table`); `west alp-emit` prints the orchestrator subset (`system-manifest`, `ipc-contract-h`, `dts-reservations`, `dts-partitions`, `storage-mounts-c`, `tfm-sysbuild-conf`, `build-plan`, `kconfig`); and `linux-ownership-dts` is reachable only from `scripts/alp_project.py --emit`.

### `carrier-netlist` — Alp Studio handoff {#carrier-netlist-studio-handoff}

```bash
tan generate --target carrier-netlist
# or, driving the loader directly:
python scripts/alp_project.py --input board.yaml --emit carrier-netlist
```

Produces a **schema-versioned JSON** handoff for [Alp Studio](https://studio.alplab.ai) describing the carrier PCB's electrical interface to the SoM. Two things go in the file:

- **Carrier-facing nets** — composed from the board's `e1m_routes:` and the SoM preset's `pad_routes:`, so a net that reaches the silicon through an on-module mediator (e.g. a CC3501E or GD32 bridge) is resolved end-to-end.
- **Carrier BOM rows** — from the board's `populated:` chips plus the chip/block manifests.

It is a **netlist + BOM handoff only**. SoM internals stay excluded, and the SDK does **not** claim to emit KiCad projects, Gerbers, DRC results, or PCB layout — Studio owns the board-design surface downstream. The `generated_by` field records `scripts/alp_project.py --emit carrier-netlist` for traceability.

### Build-time hw_info header

```c
#include "alp/hw_info.h"
#include "alp_hw_info_build.h"   /* generated by --emit hw-info-h */

alp_hw_info_t info;
alp_hw_info_read(&info);
alp_hw_info_assert_matches_build(&info,
                                 ALP_HW_BUILD_SOM_SKU,
                                 ALP_HW_BUILD_SOM_HW_REV);
```

`ALP_HW_BUILD_SOM_SKU`, `ALP_HW_BUILD_SOM_FAMILY`, `ALP_HW_BUILD_SOM_HW_REV`, and (when a board is declared) `ALP_HW_BUILD_BOARD_NAME` + `ALP_HW_BUILD_BOARD_HW_REV` are all emitted per project. Per-slice `ALP_HW_BUILD_CORE_ID` + `ALP_HW_BUILD_OS` live in each slice's generated header.

## Hardware revision tracking

Every released SoM family and board carries a `hw_revisions:` table. The SDK uses it to detect "wrong firmware for this hardware" two ways:

- **Build-time** — `scripts/alp_orchestrate/loader.py`'s `load_board_yaml` resolves the `hw_revisions:` table for the SKU and refuses the build on any of three independent grounds (below).
- **Runtime** — the SDK reads the SoM's on-module 24C128 EEPROM manifest for the authoritative MPN string + hw_rev + serial + mfg date ([`alp_hw_info_read()`](https://docs.alplab.ai/sdk/api/hw-info)); a blank EEPROM reports `ALP_ERR_NOT_PROVISIONED`. Boards may additionally encode their own revision on a board-side BOARD_ID ADC divider — an independent, board-side path.

### The three build-time refusals

Checked in this order. Each is fatal, each has its own exit code from `scripts/validate_board_yaml.py`.

**1. Exists** — the value must be a declared key in the resolved `hw_revisions` table for that SoM/board. Otherwise `SdkRevisionUnknown`:

```
SoM <sku> hw_rev <value> is not a known hardware revision. Available hw_rev(s) for <sku>: <list>.
```

**2. Buildable** — the entry's `status` must be outside `{reserved, tbd}`. `status` is a **required** key on every `hw_revisions` entry (`metadata/schemas/hw-revisions-v1.schema.json`), and a **missing `status` is treated as refuse, not pass**. Otherwise `SdkRevisionNotBuildable`:

```
SoM <sku> hw_rev <value> exists but is not buildable (<status: 'reserved'> | carries no `status:` key).
```

| `status`        | Buildable? |
|-----------------|------------|
| `production`    | yes        |
| `preview`       | yes        |
| `preliminary`   | yes        |
| `deprecated`    | yes        |
| `reserved`      | **no**     |
| `tbd`           | **no**     |
| *(key absent)*  | **no**     |

**3. In SDK range** — the running SDK version must fall inside the entry's `[min_sdk_version, max_sdk_version]`. Otherwise `SdkRevisionUnsupported`:

```
SDK <version> does not support this hardware revision: <reason>. Pin an SDK inside the declared range, or set a hw_rev this SDK supports.
```

### Exit codes

`scripts/validate_board_yaml.py` returns a distinct code per refusal, so CI can branch on which one fired:

| Constant                              | Code |
|---------------------------------------|------|
| `EXIT_SDK_REVISION_UNSUPPORTED`       | `3`  |
| `EXIT_SDK_REVISION_UNKNOWN`           | `4`  |
| `EXIT_SDK_REVISION_NOT_BUILDABLE`     | `5`  |

:::warning[Behaviour change: a `board.yaml` that validated before can now be refused]
Specifically one naming an `hw_rev` whose `hw_revisions` table entry carries no `status:` key. `status` is now required, and its absence is a refusal (`SdkRevisionNotBuildable`, exit `5`) rather than a pass. If your build starts failing here, add the correct `status:` to the revision entry — don't switch `hw_rev` to hide it.
:::

## Modular SoMs: optional chip populations

The SoM YAML carries a per-chip `assembled:` flag for every entry in its `i2c_devices:` topology so the SDK can express SoMs that ship in multiple BOM variants:

| `assembled:`     | Meaning                                                              |
|------------------|----------------------------------------------------------------------|
| `true` (default) | Chip is always populated on every BOM variant of this SKU.           |
| `false`          | DNI — the chip footprint exists but is empty.                        |
| `"optional"`     | Per-BOM-variant — some units have it, some don't.                    |

Customer code that uses an optional chip MUST handle `alp_*_init` returning `ALP_ERR_NOT_READY` gracefully (skip the demo, log a clear message, fall back) instead of crashing.

## Versioning

`board.yaml` has one live shape. Breaking changes are flagged in the SDK's CHANGELOG with a migration table; every in-repo example is rewritten in the same change.

## See also

- [Heterogeneous Builds](https://docs.alplab.ai/sdk/heterogeneous-builds) — dual-OS project walkthrough
- [`<alp/rpc.h>`](https://docs.alplab.ai/sdk/api/rpc) — framed RPC over OpenAMP/RPMsg
- [`metadata/templates/board.yaml`](https://github.com/alplabai/alp-sdk/blob/main/metadata/templates/board.yaml) — the canonical commented template
- [Architecture](https://docs.alplab.ai/sdk/architecture) — how the orchestrator fits into the build
- [Quick start](https://docs.alplab.ai/sdk/quick-start) — concrete walk-through
