Add a reviewed Board package

Use this guide when the exact SoC already has a maintained provider. A Board adds PCB facts and reviewed bindings; it does not copy a vendor SDK or authorize every silicon route. Actual unobserved PCB revision, bridges and voltage stay unknown.

Prepare the fixed source and recursive dependencies before using the resolver or build commands below.

Gather the minimum facts

Record the full part, package, source document revision and retained provenance. Record oscillator values, supply conditions, SWD reservations, pins, active levels, jumper conditions and safe initial outputs. Distinguish document defaults from an observation of your particular board. Start with one LED and one console route.

Choose a maintained fixed clock profile matching those oscillator facts. A new Board oscillator value does not synthesize an arbitrary PLL, power, Flash wait-state or peripheral kernel-clock plan. Add and verify an exact SoC profile before authorizing a new combination; parsing success does not measure clocks or establish electrical qualification.

The following is a complete maintained Board file, including soc_family:

Source-reviewed Qiming V3.1 facts; physical PCB revision remains unknown.
{
  "schema_version": 1,
  "id": "stm32f407zg-qiming-v31",
  "soc": "STM32F407ZGT6",
  "soc_family": "stm32f407",
  "source_revision": "V3.1",
  "physical_pcb_revision": null,
  "clocks": {
    "hse_hz": 8000000
  },
  "bindings": [
    {
      "id": "led0",
      "controller": "GPIOE",
      "route": "gpio-pe3",
      "initial": 8,
      "mask": 8
    },
    {
      "id": "led1",
      "controller": "GPIOE",
      "route": "gpio-pe4",
      "initial": 16,
      "mask": 16
    },
    {
      "id": "led2",
      "controller": "GPIOG",
      "route": "gpio-pg9",
      "initial": 512,
      "mask": 512
    },
    {
      "id": "uart1",
      "controller": "USART1",
      "route": "usart1-pa9-pa10"
    },
    {
      "id": "flash0",
      "controller": "FLASH",
      "route": "flash-internal"
    },
    {
      "id": "iwdg0",
      "controller": "IWDG",
      "route": "iwdg"
    },
    {
      "id": "can1",
      "controller": "CAN1",
      "route": "can1-pa11-pa12"
    },
    {
      "id": "can2",
      "controller": "CAN2",
      "route": "can2-pb12-pb13"
    }
  ],
  "reserved_resources": [
    "PA13",
    "PA14"
  ],
  "unknowns": [
    "Physical PCB revision and fitted options not inspected",
    "SPI/I2C/PWM/ADC/EXTI external wiring not bound or physically qualified",
    "CAN optional fitted transceivers, termination and jumper positions not inspected; software pad routes only, physical CAN qualification not executed"
  ],
  "provenance": [
    {
      "url": "https://github.com/petercwq/STM32407/blob/master/启明欣欣407开发板(高配版)V3.1例程使用手册.pdf",
      "scope": "V3.1 LED identities and low-active behavior"
    },
    {
      "repository": "https://github.com/petercwq/STM32407",
      "tree": "08c5f513f1677388fcacaa519dca0c9ef00b6d2e",
      "led_header_blob": "63ed6144e8d33f947fbe2784a9962d2913028ac8",
      "led_source_blob": "4adeb6f04323f6c8ae4eabf3308334e3e6910277",
      "clock_source_blob": "e99736d005f731db67300447d77ce96901d4c3ec",
      "uart_source_blob": "e0f9a0fdf6633de6ef5f1c451c2966f22dae204b",
      "scope": "LED pins and inactive initialization; HSE_VALUE 8 MHz with PLL_M 8 / PLL_N 336 / PLL_P 2; USART1 PA9/PA10 AF7"
    },
    {
      "repository": "https://github.com/petercwq/STM32407",
      "tree": "08c5f513f1677388fcacaa519dca0c9ef00b6d2e",
      "scope": "CAN1 sample blob 8731616cf0d5bf02917c76463c49e722b39eb415 PA11/PA12 AF9; CAN2 blob ef8da679c5e7c7163fe2a48a80b6ce8f9d6ecfaa PB12/PB13 AF9. Fitted transceiver options and jumper positions require commissioning inspection."
    }
  ]
}

The integration contract owns field and resource requirements. Keep your Board package in its external product repository when it describes private PCB data. Public reusable packages live under boards/; ordinary packages require only board.json and a README. Add bounded neutral Board hooks only for electrical actions not expressible by maintained data.

Validate through the actual resolver

From the Nexus repository root, inspect a known-good reference before authoring:

python tools/configure/configure.py list-bindings     --assembly tools/configure/assemblies/qiming-baremetal-uart.toml
python tools/configure/configure.py check     --assembly tools/configure/assemblies/qiming-baremetal-uart.toml
python tools/configure/configure.py explain     --assembly tools/configure/assemblies/qiming-baremetal-uart.toml

For your package, select board_package in an external complete assembly and run those same commands with its absolute path. Relative package paths resolve from the authored assembly. A JSON syntax check alone cannot prove SoC identity, clock, route or resource compatibility. Unknown fields and unreviewed routes must reject.

To create an assembly from a reviewed private package, explicitly select its clock and binding. The following is a command template: replace package, clock and binding with your package’s reviewed facts before running it.

python tools/configure/configure.py init \
    --board-package /path/to/private-board --backend baremetal \
    --clock REVIEWED_CLOCK --profile gpio --binding REVIEWED_BINDING \
    --instance led --output /path/to/product/assembly.toml
python tools/configure/configure.py provider-check \
    --assembly /path/to/product/assembly.toml --json

Exactly one of --board and --board-package is required. The CLI package path resolves from the working directory; the generated TOML stores it relative to its own directory. The resolver rejects symlinked package paths. It allows ordinary parent-directory references, so a private Board and product configuration can move together without placing private facts in Nexus.

provider-check resolves the same typed IR and emits the real static bundle into a temporary directory. Its report records family, part, Board, backend, selected controllers, configuration-module paths, fact-input identities, and generated-file hashes. Optional --expect-family and --expect-part reject an unexpected selection. resolved_typed_ir and static_bundle_emitted are generation checks; they do not establish compilation, instance behavior or physical qualification. Add same-family instances through reviewed routes and the existing provider; maintain a new family implementation only when the actual SoC requires it.

Build and record the selected scope

Configure your external consumer using its assembly and the locked ARM toolchain. Keep baremetal and FreeRTOS in separate output roots. Check resolved claims, vector/startup, strong handlers, ELF/BIN/map and every physical RAM/Flash budget. Factory lookup must be pure before start and instance state must remain isolated. Use a software Board fixture for model/link testing; label its wiring accordingly.

Prepare HIL plans without equipment. Physical qualification requires a separately reviewed station, observed Board/part/UID/probe/wiring, exact image and real raw measurements. Source-reviewed pads never establish connector continuity, immunity or safe electrical behavior.