Files
UniXNU/docs/porting/records.md

8.9 KiB

Device porting records

Format 2 device repositories maintain porting.toml. Maintainers and agents update this record throughout development. The documentation site generates device pages from its pinned source snapshots.

Procedure

  1. Create the record from examples/device/porting.toml, or edit the existing device record. Match its identity to board.toml.
  2. Fill each required area using the record fields. Include selected components, board-package code, inputs and ordered operations.
  3. Assign a completion level supported by the source, host or device evidence. Record missing inputs and the next concrete action.
  4. Run the checker in Change workflow. Resolve the reported identity, coverage and evidence errors.
  5. Publish the device commit and follow Publishing and reuse. Confirm the generated page links to the published revision.

Required areas

Each area records inputs, configuration, procedure, development findings, completion criteria, current limits, next action, and evidence.

Area Required technical detail
Configuration SoC and OS profiles, source pins, component choices, array replacements, defconfig and patch order
Firmware and boot Boot format, firmware revision, PSCI, framebuffer and memory handoff
CPU and interrupts CPU affinities, enabled cores, GIC ranges, timer rate, interrupts and IPIs
Memory and DMA DRAM, reservations, address translation, DMA widths, cache policy and SMMU ownership
Storage and root Host, PHY, clocks, resets, power, SMMU stream, DMA, LUNs, GPT, root and persistent Data
Display Controller or GOP, panel, stride, format, timing, backlight and presentation
Input Bus, sensor protocol, pins, interrupts, firmware, contact IDs and coordinate mapping
GPU GPU/GMU generation, firmware, votes, SMMU, submission, fences, frontend ABI and presentation
Network Bus, firmware, interrupts, DMA, OS interface, association and packet transfer
Cellular Modem firmware and EFS/NV, QRTR/QMI, SIM identity, network registration, IPA/QMAP, data sessions and reset; use not-applicable on boards without a modem
Audio DSP, codec, clocks, firmware services, routes and playback/capture
Power Regulators, clocks, battery units, firmware ownership and supported transitions
Image assembly XNU and IPSW versions, ABI inputs, patch order, ADT, payload and boot-image format
Diagnostics Log transport, checkpoints, recovery, commands and image/source revisions

Add areas for other peripherals. Every selected component and its catalog dependencies belong to an area. Use not-applicable with a reason in limits for a function outside the board's scope. Use planned for unfinished work.

Record format

Copy examples/device/porting.toml. Its device name, SoC and OS profile must match board.toml. A board that serves several OS profiles keeps one record under its default profile; results for another profile, such as macOS, go into the same areas and name that profile and build. Each [[area]] contains:

Field Content
id Stable area identifier
status Completion level from the table below
components Canonical component IDs, including dependencies
paths Repository-relative file patterns owned by this area
inputs Hardware resources, external inputs and dependencies
configuration Actual TOML keys, DTS properties and kernel flags
procedure Ordered operations and commands
findings Observation, established cause, implementation decision and conditions for reuse
completion Observable result required at each milestone
limits Current implementation scope and unresolved inputs
next_action Concrete next measurement or implementation step
evidence Source, host or device records with references and results

Write findings as technical facts. For example: an idle UFS AHB clock branch can report CLK_OFF while hardware gating is enabled, so the probe checks branch enable and gating together. Link the implementation or captured register record. When the cause is unknown, record the symptom and the next measurement.

Completion levels

Status Required evidence
planned Required inputs and next action
implemented Source reference and implementation scope
host-verified Host command, full source commit, result and accessible log
device-verified Device command, full source commit, result and accessible log identifying the device, firmware and image
not-applicable Scope explanation in limits, with an empty component list

Each evidence entry has kind, reference, and result. Host and device entries also have command and a full 40-character revision. References use HTTPS or a committed file relative to the device repository. Store large logs as linked release or CI artifacts. Record unavailable inputs in limits and the measurement needed to resolve them in next_action.

Change workflow

  1. Read the device record and the relevant common guide before implementation.
  2. Identify the affected areas and their existing components.
  3. Update the implementation and each affected area's findings or evidence.
  4. Update configuration, procedure and completion criteria when the interface changes.
  5. Run the record checker and the existing checks for the changed implementation.
  6. Publish code and documentation through the repository's workflow. Separately published records include host or device evidence for the source revision they validate.
  7. Publish the device change. The catalog workflow refreshes its source revision and generated page.
python3 scripts/porting-record.py check --device /path/to/device
python3 scripts/porting-record.py check --device /path/to/device --base origin/main

Run the second command on the proposed device branch. It compares committed changes against the base. Every changed code path needs an owning area; each matching area needs updated findings or evidence, or published validation from an ancestor revision whose affected source files match the proposed branch. Markdown edits use the documentation review workflow. porting.toml is the authoritative device record.

The device template includes .github/workflows/porting-record.yml. Official device branches require its Porting record check. Reviewers verify hardware facts, evidence quality, component reuse and the stated completion level.

Publishing and reuse

Complete the repository publication steps, including the unixnu GitHub topic.

The catalog workflow runs at 00:00 and 12:00 UTC. It searches public repositories in the UniXNU organization, with the unixnu topic, or with UniXNU in their name or description. It reads root board.toml and porting.toml files at a fixed commit.

board.toml uses schema_version = 2; the record uses schema_version = 1. The workflow checks identity, required areas, component coverage and evidence. Valid records generate English and Chinese pages, the device index and navigation. Format 2 pages with missing or invalid records link to the repository and identify the required record work. Existing legacy pages keep their authored content. New legacy entries contain a repository link.

devices.toml stores repository identities, routes and source revisions. docs/.vitepress/device-records/ stores the source records. Site builds render these committed snapshots. Both languages use the same record text. Write the record in concise English. Site sources and deployment remain in UniXNU.

To request a scan immediately:

gh workflow run sync-devices.yml --repo UniXNU/UniXNU

To scan locally, sign in with gh auth login or set GITHUB_TOKEN, then run from the UniXNU checkout:

python3 scripts/sync-devices.py
npm --prefix docs run build

The workflow builds the site before committing generated changes and publishing that commit through the Docs workflow. Source errors appear in the workflow summary. Correct the device record and publish it before the next scan.

For a local preview:

python3 scripts/porting-record.py site --local myboard=/path/to/device
cd docs
npx vitepress build

Move a reusable procedure into the relevant common guide after checking its hardware and ABI assumptions. Keep the device's values and evidence in its record, and link the guide from that section. The README carries the device's scope, dependencies, build entry points and link to this record. AGENTS.md points to the same required reading.

Use the driver adaptation checklist to fill the procedure and completion criteria for display, brightness, input, GPU, Wi-Fi, DSP, audio and power.