0 Fork 0

Files

T

UniXNU Docs 5c92d4048f docs: add the VitePress documentation site

Add English and Simplified Chinese documentation under docs/, covering the boot chain, build, boot, debugging, porting, drivers, XNU 4 KiB pages, macOS and device notes. Add the Pages workflow and CNAME. Rename the boot manager from CrabApple to UniXNU across the package, symbols, paths, configuration file and logs. Update README with the documentation badge and CONTRIBUTING link.

2026-10-19 22:10:43 +08:00

2.8 KiB

Raw Blame History

Userdata layout

The userdata partition carries the Darwin root file system. UniXNU keeps the original disk images unchanged and adds a manifest that maps each image to a window in the partition.

Manifest

struct shngroot_header {
  char     magic[8];        /* "SHNGROOT" */
  uint32_t version;         /* 1 */
  uint32_t count;           /* window count */
  uint64_t image_bytes;     /* total image size */
  struct {
    char     name[32];
    uint64_t offset;
    uint64_t size;
    uint32_t block_size;    /* 512 */
    uint32_t flags;         /* bit 0: read-only */
    uint8_t  sha256[32];
    uint8_t  reserved[40];
  } window[count];
  uint8_t  reserved[32];
  uint8_t  manifest_sha256[32];
};

The header occupies 4096 bytes and is zero padded to 1 MiB. The first window starts at 0x100000. Every window is aligned to 1 MiB.

Windows

Window	IPSW component	Contents
`OS`	`OS`	The system volume
`SystemOS`	`Cryptex1,SystemOS`	The cryptex system volume

The images are copied byte for byte from the disk images in the IPSW. The userdata step attaches each disk image read-only with hdiutil and reads the raw device.

Capacity

The partition capacity is:

(last_lba - first_lba + 1) * lba_bytes

The step refuses an image larger than the capacity. The report records the capacity and the image size.

Root matching

XNU selects the root volume through /chosen/root-matching:

<dict>
  <key>IOProviderClass</key><string>IOMedia</string>
  <key>IOPropertyMatch</key>
  <dict>
    <key>UUID</key><string>00000000-0000-0000-0000-000000000000</string>
  </dict>
</dict>

The UUID is the volume UUID of the OS window. The native block driver publishes the userdata partition, the partition scheme publishes the volumes, and XNU matches the UUID.

Data volume

The writable Data volume is separate from the userdata image. It comes from the Data ramdisk seed in the payload. The seed is an input to the payload step, and the payload report records its hash.

--skip-setup writes a copy of the seed with the Setup preferences marked as done. The copy is cached by the seed hash.

Report

userdata-root.json records:

Field	Meaning
`image_bytes`	Total image size
`image_sha256`	Image hash
`manifest_sha256`	Manifest hash
`windows`	Name, offset, size and hash of each window
`userdata_bytes`	Partition capacity
`flash_command`	`fastboot flash userdata <image>`
`source`	Local or remote IPSW
`hardware_tested`	Qualification state

Next steps

Userdata image describes the build and flash commands.
Device configuration lists the [userdata] keys.
Boot chain describes how the volume is mounted.

2.8 KiB Raw Blame History