4.4 KiB
Device agent guide
This repository owns the board DTS, peripheral wiring, component selections, firmware inputs, partition layout, and packaging.
Read first
Read this README and the following UniXNU documentation before changing the port:
| Task | Required reading |
|---|---|
| Every port | Porting, device repository, component catalog, UniXNU components.toml |
| Hardware | Device tree, matching, selected SoC README, AGENTS, soc.toml and DTSI |
| Component | Its site page, README, catalog build command, dependencies and source |
| Kernel | Source and patches, patch reference, selected OS profile |
| Images | Prelink, payload, UEFI |
| Verification | Building, bring-up |
| Migration | Migration |
Work
Search the catalog and inspect existing component interfaces before adding code. Match hardware scope, OS ABI, and board dependencies. Shared SoC resources and operations belong in the selected SoC repository. Reusable drivers and libraries belong in their component repositories. Use canonical component IDs and preserve runtime identifiers recorded in the catalog.
Replace every REQUIRED_ value, set the board name and firmware paths, and select
the complete dependency set. Verify memory ranges, CPU affinities, interrupts,
firmware hashes, and partition geometry from board evidence. Set example = false
after completing the inputs. Pin the SoC commit and inspect resolved profiles.
Run from UniXNU, replacing the device path and defconfig:
./unixnu defconfig example_defconfig -D ../UniXNU-example
./unixnu fetch
./unixnu status --json
./unixnu tree
./unixnu build kernel
./unixnu build package
./unixnu build firmware --uefi ../uefi-example
./unixnu build payload --unique-chip-id <hex> --trust-cache <bundle> --data-ramdisk <seed>
./unixnu bootimg --uefi ../uefi-example --dtb <firmware.dtb>
For a Mu-Silicium initrd payload, include UniXNURamDiskDxe, DiskIoDxe and
FAT support in the firmware DSC and FDF. Follow
required firmware integration
before building the firmware and boot image.
Record commands, revisions, output paths, results, and unresolved inputs.
Report hardware boot, storage, display, input, and GPU results separately.
Finish both new ports and migrations with the same
repository checklist.
Follow publication, add
the unixnu GitHub topic, and update the device revision in UniXNU's
devices.toml. Keep this README concise.
Porting record
Read the device's porting.toml and the
record guide before implementation.
For storage, also read the UFS guide.
Update each affected area's findings or evidence with its code change.
The documentation site renders this same record. Follow its schema and
completion levels for both maintainer and agent work.
Local builds and boot diagnosis
Copy unixnu.example.toml to unixnu.local.toml in the main checkout and fill
in device inputs using the configuration reference.
Read boot arguments
before changing the command line. Rebuild the payload and boot image after
argument changes. Use the green-bar diagnosis
for stalls at loader handoff. Record the last confirmed stage and relevant logs.
Hardware adaptation
Follow Port a device in order. Read the driver adaptation checklist before selecting components. Follow each subsystem guide for board inputs, implementation paths, archive integration and expected results. Include board-package services such as brightness, buttons, Wi-Fi, DSP, battery and CPU frequency in the porting record.