Skip to main content

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​

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)​

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​

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.

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

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.

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:

FamilyMPNs
Alif EnsembleE1M-AEN301, AEN401, AEN501, AEN601, AEN701, AEN801, AEN803
Renesas RZ/V2NE1M-V2N101, V2N102, V2N103
RZ/V2N + DEEPXE1M-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​

PresetForm factorHosts
e1m-evk35 × 35E1M-AEN family
e1m-x-evk45 × 65E1M-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​

FieldRequiredWhat it picks
somyesSoM SKU (+ optional hw_rev). Silicon-level facts live in the SKU preset and are NOT customer-tunable here.
nameinline*Board name (^[A-Za-z][A-Za-z0-9_-]*$) — required in inline mode, forbidden when using preset:. Used in alp_<name>_routes.h.
descriptionnoFree-form one-line description.
hw_revnoBoard hardware revision. Defaults to the preset's default_hw_rev (preset mode) or unrevisioned (inline).
populatedinline*Chips populated on this board. Each true → CONFIG_ALP_SDK_{CHIP,BLOCK}_<name>=y. Mutually exclusive with preset:.
e1m_routesinline*E1M-pad → board-side macro routing. Read by gen_board_header.py → include/alp/boards/alp_<name>_routes.h. Mutually exclusive with preset:.
presetpreset*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_connectorsnoInline mode only. The camera connectors your board exposes, keyed CAM0, CAM1, … See cameras:.
camerasnoCamera modules fitted to the board's camera connectors. See cameras:.
ownershipnoPer-product core-ownership override for assignable E1M instances (V2N family). See ownership:.
supported_boardsnoBoard 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.
pinsnoOptional array naming the E1M pads the project actively uses. Validated against the resolved board's e1m_routes:.
coresyesPer-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.
ipcnoCross-core IPC carve-outs (rpmsg / raw_shmem / mailbox_only).
bootnoMCUboot + image-signing configuration (project-wide). See Boot block.
otanoOTA provider + server config (project-wide). Mender / Hawkbit / MCUmgr emit on Zephyr; Mender server-mode on Yocto. See OTA block.
storagenoFilesystem partitions. Deterministic flash-partition allocator + DTS/Kconfig emit. See Storage block.
securitynosecurity.psa: — PSA Crypto + optional TF-M sysbuild child image. See Security block.
chipsnoProject-wide chip-driver opt-ins (each → CONFIG_ALP_SDK_CHIP_<NAME>=y).
modelsnoAI models to compile + package into .alpmodel (silicon-agnostic; back-ends derived from som.sku). See models: block.
diagnosticsnolast_error, default log_level, console backend, link target, and per-module log levels under diagnostics.modules: (Alp SDK and wired Zephyr log modules).
featuresnoFree-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​

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.

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:

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:

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.

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:

SectionPadsNotes
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:

FieldRequiredValuesNotes
e1myesE1M pad nameValidated against the pad class for the enclosing section.
macroyes^[A-Z_][A-Z0-9_]*$Uppercase C identifier emitted into alp_<name>_routes.h.
docnostringOne-line Doxygen @brief documenting what the pad is wired to.
active_lownoboolBoard convention — pressed/asserted = 0 V. Documentation only; <alp/peripheral.h> has no active-low flag, so the app inverts the level itself.
pullnoup / down / nonePhysical 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_msnointeger (≥0)RC-debounce time constant in milliseconds for hardware debounce (buttons mostly). Documentation hint; the app may add software debounce on top.
board_aliasno^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.
mux_selectno{ 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:

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)​

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:

FieldValuesNotes
oszephyr / yocto / baremetal / offOptional — 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.
appPath to the app source directoryOptional — 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:.
imageYocto image recipe nameYocto 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.
recipeYocto bitbake recipe nameRequired for an app-only os: yocto slice (app: set, no image:) — see below.
toolchainToolchain 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.
peripheralsEnum subsetPer-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_librariesList 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:

ClassPortable surfaceNotes
dac<alp/dac.h>Analog output. Pads are declared under e1m_routes.dac: (E1M_DAC<N>).
i3c<alp/i3c.h>MIPI I3C bus. Pads are declared under e1m_routes.buses: (E1M_I3C<N>).

Which cores does my SoM expose?​

SoM familyA-classM-classHeterogeneous?
AEN E3/E4—m55_hp, m55_he (Zephyr)No — RTOS-only
AEN E5..E8a32_cluster (Yocto)m55_hp, m55_he (Zephyr)Yes
V2N / V2N-M1a55_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:​

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

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)​

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

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:

TokenEmitsPortable surface
madgwick-ahrsCONFIG_ALP_SDK_AHRS<alp/ahrs.h> — Madgwick IMU orientation filter
pidCONFIG_ALP_SDK_PID<alp/pid.h> — 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.

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.

FieldWhen 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:
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​

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 layoutOmitted swap_algorithm: resolves to
Stock two-slot AEN targetscratch
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: to declare the actual partition table.

anti_rollback: was removed because only software downgrade prevention is wired today (ota.rollback.min_version); 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:
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:

ProviderZephyr emitYocto emit
menderCONFIG_MENDER_MCU_CLIENT=y + server URL / tenant / artifact name / poll interval (Mender-MCU-client)MENDER_* weak-assignments in local.conf + INHERIT += "mender-full"
hawkbitCONFIG_HAWKBIT=y + CONFIG_HAWKBIT_SHELL=y + HAWKBIT_SERVER + HAWKBIT_POLL_INTERVAL (Zephyr upstream)—
mcumgrCONFIG_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_s: is in SECONDS (minimum: 60, default: 1800 — 30 min, battery-friendly; Mender's own default is 60 s).

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:
- 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: 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.

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 &. 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:
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. 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:​

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:
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.

ValueEffect
auto (default)Resolve from the slice's OS and the SoM topology — see below
alp / uartZephyr UART console; printf/LOG land on the module's console UART
ramZephyr RAM console — read ram_console_buf over SWD on a serial-less bench
linuxYocto/Ubuntu stdio/tty console
noneEmit 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.

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

ValueEffect
auto (default)Link where the board puts the image — E1M-AEN slices link into MRAM slot0 for the production flows
itcmLink 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 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.

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:

IDSeverityRule
R1ERRORota.provider: mender works on both Yocto + Zephyr; hawkbit / mcumgr require at least one Zephyr core.
R2ERRORboot.signing.algorithm: must match the SoM family allow-list.
R3ERRORcores.<id>.iot.tls: true requires mbedtls or bearssl in the top-level libraries: / the core's extra_libraries:.
R4WARNcores.<id>.inference.default_arena_kib > cores.<id>.memory.heap_kib — inference may OOM.
R5WARNcores.<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)​

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> — 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.

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​

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)​

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:

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"
FieldRequiredNotes
connectoryes^CAM[0-9]+$. Must be a connector the resolved board declares under camera_connectors:; CAMn is camera index n.
moduleyesA module id with a manifest at metadata/camera_modules/<module>.yaml. The sensor chip is implied by the module.
corenoThe core that owns the camera. Omit it when exactly one core can.

An unknown connector or module is rejected at validation.

Camera modules​

Module idSensorI2C (7-bit)CSI-2 lanesZephyr shieldE1M-X EVK CAM0 Linux fragment
innomaker_cam_ov9281OV9281 (global-shutter mono)0x602innomaker_cam_ov9281generated, bench-unverified
innomaker_cam_imx335IMX335 (5 MP colour)0x1A2innomaker_cam_imx335generated, bench-unverified
raspberry_pi_camera_module_1OV5647 (5 MP raw Bayer)0x362raspberry_pi_camera_module_1generated, bench-unverified
raspberry_pi_camera_module_2IMX219 (8 MP)0x102— (Linux only)generated, bench-unverified
raspberry_pi_global_shutter_cameraIMX296LQR-C (1.58 MP global-shutter colour)0x1A1raspberry_pi_global_shutter_cameragenerated, 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:

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)​

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:

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)​

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 via tan model build.

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
FieldRequiredNotes
nameyes^[A-Za-z][A-Za-z0-9_-]*$. Names the output .alpmodel.
sourceyesPath (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.
specno$ref to an external model spec, for large or shared models.
inputsnoApp-side input hints (e.g. layout).
compilenoPer-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​

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 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); 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)​

PathWhat it carries
build/system-manifest.yamlPer-slice status, log paths, artefact paths, boot order, blocked storage rows.
build/generated/alp/system_ipc.hEndpoint IDs, addresses, mailbox channel macros — shared by all slices.
build/generated/dts-reservations.dtsireserved-memory: carve-outs shipped into Linux + Zephyr DTs.
build/generated/dts-partitions.dtsifixed-partitions overlay from the resolved storage: block.
build/sysbuild/tfm/tfm.confTF-M sysbuild child-image overlay (when security.psa.tfm: true).
build/<core>-zephyr/alp.confKconfig fragment layered onto each Zephyr slice's prj.conf.
build/<core>-yocto/conf/alp-generated.conflocal.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 modeOutput
zephyr-confalp.conf — Kconfig fragment, layered over prj.conf via OVERLAY_CONFIG.
cmake-argsA list of -D flags for plain CMake / bare-metal.
yocto-conflocal.conf snippet (MACHINE=…, IMAGE_INSTALL deltas).
dts-overlayZephyr DTS overlay with alp,pin-array + bus aliases.
dts-partitionsFixed-partitions overlay for the resolved storage: block.
storage-mounts-cStatic fs_mount_t alp_storage_mounts[] table.
tfm-sysbuild-confTF-M sysbuild child-image overlay.
system-manifestFinal system manifest YAML.
ipc-contract-h<alp/system_ipc.h>.
hw-info-h<alp_hw_info_build.h> with ALP_HW_BUILD_* macros.
west-librarieswest.yml fragment pinning the libraries board.yaml requested.
build-planDeterministic, write-free JSON build plan (one slice per non-off core, sorted by coreId) — the contract IDE/CLI tooling consumes (ADR 0014).
os-topologyPer-core natural-vs-effective OS facts as JSON (core_type, runtime_class, default_os, effective_os, allowed_os).
carrier-netlistSchema-versioned JSON handoff for Alp Studio — carrier-facing nets + carrier BOM. See below.
linux-ownership-dtsV2N family: the Linux devicetree fragment for this project's resolved ownership:. New in v0.17.0.

There is no single tan verb covering the whole catalog. tan generate 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​

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 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​

#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()); 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).
statusBuildable?
productionyes
previewyes
preliminaryyes
deprecatedyes
reservedno
tbdno
(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:

ConstantCode
EXIT_SDK_REVISION_UNSUPPORTED3
EXIT_SDK_REVISION_UNKNOWN4
EXIT_SDK_REVISION_NOT_BUILDABLE5
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.
falseDNI — 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​

Questions about this page? Email contact@alplab.ai