15 KiB
Capture logs and automate boot tests
Set up log capture as you bring up the board. Start with firmware logs, collect kernel evidence at handoff, then add persistent logs and automated reboot cycles. Use the bring-up checkpoints to identify the stage being tested.
| Stage | Required support | Saved result |
|---|---|---|
| UEFI menu | GOP display, menu input, Advanced Logger and QR plugin | Firmware .log file scanned from the screen |
| XNU entry | UART or framebuffer diagnostics | Serial log or photograph of the last checkpoint/panic |
| Storage | Reserved log region, kernel writer and a Linux or recovery reader | Kernel message buffer and diagnostic snapshots |
| Repeated tests | Working log retrieval and return to bootloader | One evidence directory per boot |
1. Include the firmware log exporter
Prepare the firmware checkout using UEFI integration.
The shared exporter is
package/UniXNUPkg/Driver/AdvancedLogDxe/AdvancedLogDxe.inf in UniXNU.
It reads the Advanced Logger memory buffer while UEFI boot services are active.
-
In the firmware DSC
[Components], add:UniXNUPkg/Driver/AdvancedLogDxe/AdvancedLogDxe.infIn the FDF's DXE firmware volume, add:
INF UniXNUPkg/Driver/AdvancedLogDxe/AdvancedLogDxe.inf -
Enable the platform's Advanced Logger producer and route the desired firmware debug output into it. The exporter dispatches after
gAdvancedLoggerProtocolGuidis installed. Its INF also requiresAdvLoggerPkg,MsGraphicsPkg,AdvancedLoggerAccessLibandQrEncoderLib. From the firmware checkout, find the library instances supplied by its Mu revision:find . -name '*AdvancedLogger*.inf' -o -name '*QrEncoder*.inf'Map the access and QR libraries in the DSC
[LibraryClasses]and include their package roots inboard.toml[firmware] packages. Initialize the submodules containing those packages if the search returns no files. Use the platform's Advanced Logger configuration for its buffer and debug-library mappings. -
Set
gUniXNUPkgTokenSpaceGuid.PcdUniXNUDeviceModelin the DSC[PcdsFixedAtBuild]to the board's ASCII name. The export filename uses this value. -
In the device's
board.toml, addtools = trueto its existing[payload]table. This adds Tools to the generated boot menu. A hand-authoredunixnu.tomluses an entry withaction = "tools". -
From the main UniXNU checkout, with the device selected and local inputs configured, run:
./unixnu firmware ./unixnu payload ./unixnu bootimg
Result: the rebuilt image contains the exporter, and Tools → Advanced Logger appears when the platform's logging protocol is available.
2. Scan the firmware log before kernel handoff
Prepare a second phone or camera device with OneSend (扫传). The exporter sends a sequence of OneSend QR frames.
-
Boot the image from the main checkout:
fastboot devices fastboot -s <serial> boot out/<device>/<os_profile>/<config>/boot/boot.img -
Stay in the UniXNU menu. Select Tools, then Advanced Logger. The plugin takes a snapshot of the current firmware log when opened. If a loader error returns you to the menu, open the plugin then to capture it before resetting the device.
-
Open OneSend's receiving scanner, allow camera access and keep the complete QR square in view. Keep scanning as frames cycle until the receiver finishes.
-
Use Down / j to slow rotation and Up / k to speed it up. The initial interval is one second; five speeds range from 5 seconds to 250 milliseconds. Boards that map volume buttons to Up/Down use those buttons. Enter or Escape returns to the menu; a board's power button works when mapped to Enter.
-
Save the received
<model>-<date>-<time>.logwith the image revision and last completed checkpoint. The filename uses the firmware clock. Check the text for the failing operation before rebuilding.
Result: a readable firmware log captured while the menu remains accessible.
XNU execution after ExitBootServices uses the capture methods in step 3.
| Symptom | Action |
|---|---|
| Tools is missing | Check [payload] tools, rebuild the payload and repack the boot image |
| Advanced Logger is missing | Check the INF in DSC/FDF, its dependencies and the platform's logger protocol |
Advanced Logger: no log |
Check the Advanced Logger producer, debug routing and buffer configuration |
| Scanner progress stops | Reduce rotation speed and keep scanning the repeating sequence |
| Firmware stops before the menu | Capture the platform UART or photograph its last visible output |
3. Capture the kernel handoff
- Save the firmware log from step 2, then start the kernel entry.
- Follow debugging to capture the board's UART or framebuffer output. For a green handoff bar, use the entry-probe procedure.
- Photograph the complete panic screen or checkpoint, including registers and the last text lines. Record the kernel arguments from the built payload.
- After changing arguments, run
./unixnu payloadand./unixnu bootimgagain. Repeat the same boot and compare the last confirmed checkpoint.
Result: evidence for the kernel stage even while storage is being adapted. Continue with persistent capture after storage verification.
4. Select a persistent log reader
A persistent reader consumes the reserved log region after the test kernel returns control. Define the region, file header, boot ID, completion marker and snapshot layout before implementing the reader. The writer, reader and decoder must use the same block units and byte ranges.
-
Reserve a log region in the target storage layout. Record its partition, offset, size and block units beside the root and Data regions. Check that the image builder, partition provider, writer and reader use the same bounds.
-
Connect the kernel writer to the storage driver's bounded read, write and sync operations. Store the kernel message buffer, diagnostic snapshots, boot ID and write status. Start the writer after the region opens.
-
Choose a reader environment that the device can boot:
Linux reader. Build a small Linux image with the target kernel, DTB, storage driver, USB device controller and CDC ACM support. Copy the region into RAM, expose a serial shell and keep source partitions read-only.
Recovery reader. Boot a compatible rooted recovery image with block access and ADB, then read the region from recovery. A TWRP-like recovery provides the reader runtime; the host only transfers the result.
adb reboot recovery adb wait-for-device adb shell id adb shell ls -l /dev/block/by-name adb shell mkdir -p /tmp/unixnu-log adb shell dd if=/dev/block/by-name/<log-partition> \\ of=/tmp/unixnu-log/log.bin bs=4M adb pull /tmp/unixnu-log/log.bin out/logs/log.binFor a region inside
userdata, use the offset and length from the device record withdd skip=<block-offset> count=<block-count>. Keep the recovery mount read-only. Record the recovery build, block path and command. -
Adapt the host decoder to the writer header and snapshot format. Select the serial device or ADB target explicitly when automatic discovery does not identify one device.
-
Implement the return path for the selected reader. Use the board's reboot reason and reset interface. Record the bootloader and recovery commands used by the manual cycle.
The reference implementation supplies a
Linux reader, a reserved userdata region and a fastboot return path. Its source
layout is a reference for package/BootLog.c, BootReset.c,
BootResetCore.h, package/linux-log/ and scripts/read-sheng-log.py. Its PMIC
addresses, watchdog calls, storage reservation and Linux image inputs belong to
that board record.
Keep each round's write small. The reference writer (header version 5) writes
the used blocks of the round's text slot and only the message-buffer blocks
that new kernel text reached, about 7 KiB/s on the reference board; a panic
flush writes the whole message area. User-space daemons log through syslog or
os_log, whose store logd bounds, not to files that grow without limit: the
reference Wi-Fi supplicant runs with -q -s.
Result: one reader environment, one matching decoder, an identified storage range and a tested route back to bootloader or recovery.
For the reference iOS 27 native source path, enable log=1 boot-ui-trace=1
when diagnosing a user-space stall. The source storage archive includes
BootProcessWorker.c, which captures process stacks separately from the log
writer so a user-page fault cannot stop log persistence. Add
boot-ui-focus3=chronod to retain its stacks alongside backboardd and SpringBoard.
The arm64e sampler strips return-address PAC before validating and encoding
frames. An empty stack section alone is not evidence that the processes stopped.
5. Complete one manual capture cycle
-
Build a test payload with logging enabled and rebuild the boot image.
-
Boot the test image and wait for the checkpoint under test.
-
Return to the selected reader environment:
fastboot -s <serial> boot <reader.img>Or boot the recovery image:
adb reboot recovery adb wait-for-device -
Run the reader, save the raw region and decoded text under a directory named with the boot ID, and confirm the header, snapshots and write status.
-
Return to the board's bootloader and confirm its identity before the next run.
The selected device repository supplies the Linux reader commands. The recovery commands above apply to any board with a compatible recovery image.
Result: one complete test, an identifiable evidence directory and a verified reader return path. A missing or stale header points to writer startup, region geometry or the selected reader command.
6. Automate the verified cycle
- Enable the board's timed return to bootloader or recovery. Set the timeout after the measured checkpoint and log synchronization time.
- Configure a host runner with the exact device identity, test image, reader image or recovery image, output directory and timeout.
- Have it boot the test image, observe the return, start the selected reader,
retrieve and decode the log, and confirm the final bootloader state.
A recovery reader uses
adb reboot recovery,adb wait-for-deviceandadb pullin the same sequence as the manual cycle. - On timeout, record the failed stage and use the board's documented bootloader or recovery entry procedure. Keep the images and partial evidence.
- Record revisions, arguments, checkpoint, reset result, reader environment, output directory and unresolved errors in the porting record.
The runner follows the same sequence as the manual cycle. A board with recovery access can use the same runner structure with ADB commands.
For recovery charging, python3 scripts/arm-sheng-recovery-return.py --serial <serial> --seconds 7200 arms a fastboot return timer. Running it again renews the monotonic deadline.
For a timed sheng macOS image, run from the device checkout:
SERIAL=<serial> READER=<sheng-linux-log.img> OUT=<capture-directory> \
scripts/run-sheng-unattended.sh <boot.img> 7500
For the first installation, add USERDATA=/path/to/userdata.sparse. The runner checks the sheng product and full-partition sparse geometry, writes userdata, then starts the timed boot and log capture. Subsequent runs use the preserved-Data image with USERDATA unset.
The runner assigns a six-character build-tag beginning with s and matches it against the captured header. The letter prefix keeps XNU's boot-argument parser in string mode. cycle.json records the expected tag, capture match, boot acknowledgement, elapsed test and reader time, the reader exit status and the final command-responsive fastboot state.
The host runner keeps the Mac awake. A two-hour session uses autoreset=7200 diag=1 diag-export=6900; the Linux reader has its own 300-second return timer. The runner refreshes the selected slot's bootability and retry budget before each RAM boot. cycle.json records the final fastboot response.
scripts/repack-sheng-boot.py INPUT OUTPUT --partition-bytes <bytes> fits a payload to the measured boot partition. Use --kernel-arg NAME=VALUE or --remove-arg NAME to change an XNU argument. The first installation uses data-reset=1; subsequent priming runs retain Data and the build-specific shader checkpoints.
scripts/make-userdata-full.py --zstd userdata-root.img.zst <partition-bytes> userdata.sparse streams the root image into Android sparse format and fills the remaining partition with zeros. Keep space for the compressed root and sparse output.
Build the arm64e Vulkan diagnostic dependencies from the main checkout with python3 scripts/build-gpu-validation-deps.py. Prepare a RAM boot from the device checkout using the matching acceptance tool's files directory:
python3 scripts/prepare-sheng-gpu-lab.py boot.img gpu-lab.img \
--tools <acceptance-files> --tools ../UniXNU/build/gpu-validation-deps/files \
--plugin ../UniXNU/build/adreno-metal-plugin-macos27
For Actions builds, scripts/fetch-actions-artifact.py OWNER/REPOSITORY RUN_ID ARTIFACT OUTPUT --file prime-list.txt --file prime-list.json retrieves selected files through HTTP byte ranges. Omit --file to retrieve the artifact's files. Downloads stream directly to the output directory and verify ZIP integrity. Artifacts up to 1 MiB are buffered in memory for quick log retrieval. Rerun with --file NAME to resume an incomplete transfer; download links are refreshed automatically.
For an installed root with unchanged OS images and policies, dispatch macos-lab.yml with root_storage=false to build boot, kernel and payload artifacts. The default also builds the userdata image.
The preparer accepts --core <resolved-tree> and uses ICD metadata from the matching Turnip build, adds signed tools and the Shader Cache app, and appends their code identities to the owner trust bundle. Use --manual-session --preserve-data --autoreset 7200 for a manual desktop session with the firmware return timer. Shader Cache is available in Applications; the user starts compilation from its window. --shader-cache-view opens that window, --graphics-view opens System Settings, and --graphics-comparison runs the fixed interaction capture.
The logical FAT is 256 MiB. With matching firmware, sheng stores it as independently compressed 1 MiB UEFI chunks (UNXNFAT1); encoded ramdisks must fit the 190 MiB board limit. UniXNURamDiskDxe exposes the logical FAT through a 1 MiB read cache.
The unattended runner confirms readiness with a bounded fastboot getvar product request. A boot acknowledgement timeout starts the image return wait; the final state requires a successful command response.
Result: each test produces an identifiable evidence directory and a recorded return path. Continue the remaining bring-up stages.