# The roadmap to version 1
[docs/milestones.md](milestones.md) says what Burnout does and why.
This file says in what order to build it.
Each phase has a goal, the work in it, and an exit test.
Do not start a phase until the phase it depends on passes its exit test.
The sizes are relative: S is a day or two, M is a week, L is longer, and XL is
the one that needs a plan of its own.
P0 to P7 are done. Raw mode and Windows mode write a drive on all three
hosts, and a drive from each host installs Windows 11.
v0.3.0 is the first release, and it holds P0 to P6. v1.0.0 holds P7. v0.1
and v0.2 were planned, and nobody cut them.
P8, Legacy BIOS boot, is done, and v1.1.0 holds it.
Burnout reads an ISO itself, and `burnout write` uses the reader to choose the
mode.
---
## The order, and the reason for it
Two rules set the order.
**Risk first.**
The layout that Windows mode writes rested on two claims that nobody had
tested.
If they were wrong, the layout changed, and any Windows code written before
then was wasted.
So the test came before the code, and it needed no code. P0 ran it.
**Useful early.**
Raw mode is one code path, it exercises the whole device layer on three hosts,
and it writes a Linux drive.
That is a tool somebody can use, and it arrives long before Windows mode.
Ship it.
```mermaid
flowchart LR
P0([P0 prove the layout]) -.gates.-> P6
P1[P1 device layer] --> P2[P2 raw mode]
P2 --> P3[P3 MBR and FAT32]
P3 --> P4[P4 exFAT]
P4 --> P6[P6 Windows mode]
P5[P5 read an ISO] --> P6
P6 --> P7[P7 the edges]
P7 --> P8[P8 Legacy BIOS]
P7 --> P9[P9 one partition]
P5 --> P10[P10 read a WIM]
P10 --> P11[P11 NTFS]
P11 --> P12[P12 Windows To Go]
P8 --> P12
P12 --> P13[P13 a graphical interface]
```
P0 and P5 do not wait for anything.
Start P0 now, because it can send P3 and P4 back to the drawing board.
| | Phase | Size | Release |
| --- | --- | --- | --- |
| P0 | Prove the layout | S | **done** |
| P1 | The skeleton and the device layer | L | **done** |
| P2 | Raw mode | M | **done** |
| P3 | The partition table and FAT32 | M | **done** |
| P4 | The exFAT writer | XL | **done** |
| P5 | Reading an ISO | L | **done** |
| P6 | Windows mode | L | **v0.3.0** |
| P7 | The edges | M | **v1.0.0** |
| P8 | Legacy BIOS boot | M | **v1.1.0** |
| P9 | A write to one partition | S to M | **v2.0.0** |
| P10 | Read a WIM file | L | **v2.1.0 and v2.2.0** |
| P11 | Write an NTFS volume | XL | **v2.3.0** |
| P12 | Windows To Go | L | **v3.0.0** |
| P13 | A graphical interface | L | in progress |
---
## P0. Prove the layout
**Size S. Done. [The result is here](spike-layout.md).**
Both questions are answered. Windows PE reads exFAT, and Setup does **not**
find the image across the partition boundary, so `autounattend.xml` with an
`InstallFrom` path is required on every Windows drive.
Build the two-partition drive by hand, with whatever tools your machine has.
This is an experiment and not a product, so `diskutil`, `mkfs` and `dd` are
all allowed here.
They are not allowed in the code.
The work:
1. Make an MBR drive with a FAT32 partition of about 1 GB and an exFAT
partition for the rest.
2. Copy every file of a Windows 11 ISO to partition 1, except
`sources/install.wim`.
3. Copy `sources/install.wim` to partition 2, keeping the `sources` directory.
4. Start it on real firmware in UEFI mode.
5. Repeat with an `autounattend.xml` that names the image in
``, and again without it.
**The exit test.** Two questions have written answers in
`docs/spike-layout.md`:
- Does Windows PE read exFAT?
- Does Setup find the install image on the second partition, with the
`InstallFrom` path and without it?
**If exFAT fails**, the fallback is FAT32 on both partitions and a WIM splitter
written in Rust.
That keeps the MIT licence, it does not solve an oversized `install.esd`, and
it adds a phase the size of P4.
Better to learn it in an afternoon than in month three.
---
## P1. The skeleton and the device layer
**Size L. Done.**
`burnout list` names every drive on Windows, on macOS and on Linux, gives the
size to the byte, and marks the drive that the running system starts from. It
needs no privilege. `burnout-core` carries no dependency at all.
The five operations that the operating system owns, and nothing above them.
The work:
- A Cargo workspace. `burnout-core` holds everything that is not
host-specific, and takes any target that reads, writes and seeks, so a test
gives it a file. `burnout` is the command line on top.
- The device layer, in two traits and one handle. `DriveList` lists the
drives and needs no drive and no handle. `DriveAccess` unmounts the volumes
of one drive and opens it. The open handle reads, writes, seeks and flushes.
Close is the drop of the handle.
One trait cannot hold all five, because `flush` belongs to an open handle
and `list` belongs to the host. One trait would make the write path of P2
take the host as well as the target, and
[CONTRIBUTING.md](../CONTRIBUTING.md) says the write path takes a source, a
target handle and a progress callback, and nothing else.
- Linux: read `/sys/block` for the size, the model, the vendor and the
removable flag. Unmount through the `umount2` system call.
`umount` is a program, and this file says below that a tool of the host is
not allowed. `umount2` is the peer of `DADiskUnmount` and
`FSCTL_DISMOUNT_VOLUME`: three calls, and no subprocess. It also returns an
error number rather than a sentence in the language of the host.
- macOS: IOKit for the list, Disk Arbitration for the unmount. Write to
`/dev/rdiskN` and never `/dev/diskN`, because the raw node skips the buffer
cache and is about ten times faster.
- Windows: SetupAPI for the list, `IOCTL_STORAGE_QUERY_PROPERTY` for the
details, `FSCTL_LOCK_VOLUME` and `FSCTL_DISMOUNT_VOLUME` before the write.
- Find the disk the running system starts from, on each host, and mark it.
- Handle a logical sector size of 4096 as well as 512. A raw device refuses a
write that its sector size does not divide.
- `burnout list`, with a stable index.
- GitHub Actions on Windows, macOS and Ubuntu, from the first commit.
An operating system API is not a tool of the host.
IOKit, Disk Arbitration and SetupAPI are how you open a device, so they are
fine.
`diskutil`, `mkfs` and `format` do the work that Burnout must do itself, so
they are not.
**The exit test.** `burnout list` names every drive correctly on all three
hosts, gives the size to the byte, and marks the system disk. It runs with no
privilege. CI is green on all three.
**Two claims that CI cannot answer.** Both are closed by hand.
*No privilege on Windows.* The GitHub runner signs in as an Administrator, so
a pass there says nothing. A clean Windows 11 ARM64 install in a virtual
machine carries a standard account, which is not in Administrators, holds the
Medium integrity level `S-1-16-8192`, and gets `Access is denied` from
`net session`. That account ran the list:
1 QEMU NVMe Ctrl 25.8 GB (25,769,803,776 bytes) NVMe no (system disk)
2 QEMU HARDDISK 12.9 GB (12,884,901,888 bytes) USB yes
The two image files behind those drives are 25,769,803,776 and
12,884,901,888 bytes on the host, so both sizes are correct to the byte, the
bus is right for each, and the disk the machine started from carries the mark.
The run also found a fault that no host here could show: the binary linked the
Microsoft C runtime and stopped before it ran one line. The build now links
that runtime in.
*A 4Kn drive.* No drive here reports a 4096-byte sector, so `scsi_debug` made
one on Fedora ARM64:
modprobe scsi_debug sector_size=4096 dev_size_mb=64
`/sys/block/sdb/size` read 131072 and `queue/logical_block_size` read 4096.
The list reported 67,108,864 bytes, which is 131072 x 512. The trap below
gives 536,870,912, which is eight times too large. The user id was 1000, so
this also shows the list needs no privilege on Linux.
---
## P2. Raw mode
**Size M. Depends on P1. Done. Planned for v0.1, and shipped in v0.3.0.**
**v0.1 needs the release workflow, so that work moves here from P7.**
The decision below puts build provenance on every release artifact, and P7
scheduled the workflow that makes it. A release at v0.1 cannot satisfy both,
and a first release without provenance would break the promise on the first
day it applies. The workflow builds each host, publishes a SHA256 for each
binary, attests each one, and opens a draft release that a person publishes.
The first thing a person can use.
The work:
- Read the image, write it to the device, in aligned blocks.
- Progress that reports what the code proves, and completion only after the
flush returns. A byte count that reached the size of the source is not a
finished write, because the operating system still holds a cache.
- Verify: read the device back and compare a hash against the source.
- The confirmation prompt, and the refusals: no system disk ever, no fixed
disk unless forced, and no target that the person did not name.
- `--force` for a fixed disk. The person types the model and the size of the
drive back, and not a letter and not the word yes. A prompt that takes one
keystroke is one that people learn to answer without reading.
- Elevation. Restart through `sudo`, with the `BURNOUT_ELEVATED` guard against
an endless loop. On Windows, print how to fix it and stop.
- `--no-elevate`, and no elevation attempt when the input is not a terminal.
**The exit test.** A drive written on each of the three hosts starts Ubuntu on
real hardware. The hash of the device matches the hash of the ISO. Every test
in the suite runs against a file, and none opens a device.
**It passed in virtual machines first.**
A 2,689,781,760 byte Fedora ARM64 image went onto a drive from each host, and
each of the three drives then started Fedora in a machine that had that drive
and nothing else. No install medium, no second disk.
| Host | The drive it wrote | What it printed |
| --- | --- | --- |
| macOS 26 | a 4 GB image attached with `hdiutil` | `162ba3c5...999933ef` |
| Fedora 44 ARM64 | a 3 GB virtual USB disk | `162ba3c5...999933ef` |
| Windows 11 ARM64 | a 3 GB virtual USB disk | `162ba3c5...999933ef` |
One digest from three hosts, and it is the digest that `shasum -a 256` gives
for the file on the host.
The Linux run also shows the restart, in the title of its window:
sudo -- /tmp/b write /dev/sr0 2 --elevated
Two dashes before the path, the arguments carried across, and the guard added
on the end.
**Three things the first run did not touch, now run.**
*An unmount that had something to unmount.* The first run wrote to blank
disks, so the unmount had nothing to do on any host. Each host now writes over
a drive that the host itself had mounted.
| Host | Before the write | After it |
| --- | --- | --- |
| macOS | `/Volumes/TESTVOL`, and `/dev/rdisk5` answered `Resource busy` | the volume is gone and the write verified |
| Linux | `/dev/sda1` at `/run/media/liveuser/XFER` | the write verified |
| Windows | `G:` labelled TESTOL, with a file on it | the write verified |
*The write path at a 4096-byte sector.* `scsi_debug sector_size=4096` makes a
drive that refuses a write the sector size does not divide. An image of
5,000,003 bytes, which 4096 does not divide, went onto it whole and read back
with the digest that `sha256sum` gives for the file. That is the padding
proved against a device and not against a test double.
*The options nobody had typed.* `--force` prints the model and the size, takes
them back in any case and spacing, and refuses one wrong digit. A pipe with no
terminal behind it refuses to ask for a password and says to use `sudo`. Half
a yes is not a yes. Each refusal leaves the drive alone and exits 1.
**What a virtual drive still does not prove.** A QEMU USB disk is not a USB
stick. It has no controller of its own, it never fails in the middle of a
write, and it arrives with no descriptors of its own. The other half of this
exit test needs a stick that can be erased.
**The real stick, on one Mac.** A Samsung Flash Drive of 128.3 GB, with a
USB 3 controller of its own. An Apple M5 cannot start a Linux stick, so UTM
passed the stick itself through to a VM, and a VM start counts as the start on
real hardware. That leaves the firmware of a physical PC unproved, and the list
under "Not run yet" below has the other gaps.
| Host | How it reached the stick | What it printed |
| --- | --- | --- |
| macOS 26 | `/dev/rdisk5`, 55 MB/s, read back at 125 MB/s | `162ba3c5...999933ef` |
| Fedora 44 ARM64, a VM | the stick passed through, `/dev/sdb`, 48 MB/s, read back at 88 MB/s | `162ba3c5...999933ef` |
| Windows 11 ARM64, a VM | the stick passed through, `\\.\PhysicalDrive2`, 37 MB/s, read back at 87 MB/s | `162ba3c5...999933ef` |
The same digest as the ISO, from each of the three hosts. The stick that
macOS wrote then started Fedora in a VM that had no disk of its own, and so did
the stick that Windows wrote. The boot order of that VM named no disk, so its
firmware stopped at the UEFI shell, and the shell started
`\EFI\BOOT\BOOTAA64.EFI` from the stick. The media check of the initramfs,
`checkisomd5`, then read the image back from the first byte of the stick and
passed each time. That is a check of the write that Burnout did not make.
**Three faults that only the real stick found.**
- **Linux refused the stick as the system disk.** The VM started from its
disc, and the stick in the port held the same image, which the desktop had
mounted. The live-USB rule found the image on one drive, because it did not
count the disc, and no option overrides that refusal. It now counts the disc,
so a stick and a disc that hold the same image mark neither, and the write
asks for the model and the size.
- **The rate of a write divided the bytes by the flush alone.** Linux takes
the image into its page cache first, and the write and the flush both said
303.1 MB/s for a stick that reads back at 27.1 MB/s. Each step now keeps its
own clock, and the flush carries no rate. On macOS the same fault showed as
a write with no rate at all.
- **`--device /dev/disk5` named no drive on macOS,** because Burnout writes
`/dev/rdisk5`. The name under `/dev` now counts.
On Linux the stick answered for itself as well. After the write, the guest
dropped its caches and read the first 2,689,781,760 bytes of `/dev/sdb` in
22.1 seconds, and `sha256sum` gave the digest above. That read came off the
drive and not out of a cache.
**Four faults that only Windows and the real stick found.**
- **Windows refused the first write with "Incorrect function".** Partition 1
of the Fedora image has the GPT attribute read-only. Windows refuses each
write that reaches such a partition, even when its volume is locked and
dismounted. A write past every partition went through.
- **Windows read the new table during the write.** With the old table zeroed,
the first 4 MiB block put the Fedora table back, and the next write failed
the same way.
- **Windows changed the stick after the write.** For a GPT that ends before
the drive does, Windows moves the backup to the end of the drive and
rewrites 12 bytes of the primary header. The check failed at byte 528. The
ISO with those 12 bytes in it hashes to what the drive held, so the rest of
the write was whole. The same 12 bytes also fail the media check of Fedora.
Its MD5, computed the way `checkisomd5` computes it, matches the image as
published and not the image with those 12 bytes.
- **An offline drive still changed after the check.** The check read the whole
image back and matched it, and a minute later those 12 bytes were the ones
of Windows again, with the drive offline the whole time.
The first three go when the first write takes the drive offline. An offline
drive has no partitions for Windows to apply. Offline, a write into the old
read-only partition went through, and the new header held after the write,
after the flush and after the handle closed. Online again, Windows rewrote it
within three seconds. A second write while the drive is offline passes too.
The fourth needs more: a read-only drive refuses the write that Windows makes.
The handle that wrote marks the drive read-only when it goes, which is after
the last write and before the check, and the check only reads. The next write
takes the mark off again. Measured: with the mark, the header held across the
close of the handle, a drive query and thirty seconds, and again across a
whole write, its check and the minute after it. The last line of a write says
that the drive is offline and read-only.
The first write also zeroes the MBR and both GPT copies, and the first block
of the image goes on last. So no stale backup stays at the end of the drive,
and a write that stops leaves no table.
Neither mark outlives the drive or the machine. Measured: the stick came out
and went back in, and Windows reported both flags gone and had changed the 12
bytes again within 20 seconds. A restart of Windows clears both marks as well,
measured with the stick still in the port. The media check of Fedora then
fails on that drive.
The first failure also showed a fault of the terminal: the error printed on the
end of the progress line. The line now ends before an error prints.
Each host above wrote the stick with the code as it stands, and each check
passed. **One claim is still open: the firmware of a physical PC.** A VM start
stands for it.
**Two faults that only a real run could find.**
- `fsync` on `/dev/rdiskN` answers `ENOTTY`, because the raw node holds no
buffer of the operating system. The drive holds one of its own, so the flush
is `DKIOCSYNCHRONIZECACHE`. Before the fix the bytes reached the medium and
the command reported a failure.
- The Windows binary linked the Microsoft C runtime, so it stopped on a clean
install before it ran one line. The build now links that runtime in.
- **Burnout offered to erase the live USB it was running from.** A live system
reaches its root through a loop device: the medium holds one large file, the
loop presents that file as a block device, and the root is an overlay on top
of it. Nothing in that chain names the drive, so the drive carried no mark
and no refusal. Found by booting a machine from a drive that Burnout had
written. It now follows every mounted loop device to the drive that carries
its backing file, and when it cannot name the system disk at all the
confirmation asks for the model and the size rather than one word.
**Three measurements.** In a release build on an Apple M-series machine, a
2.7 GB write and its 2.7 GB read back take 22 seconds together, which is about
245 MB/s. The same work in a debug build takes 295 seconds, so measure the
build that ships. The hash is not the part that waits: a USB 3 stick writes at
30 to 150 MB/s.
---
## P3. The partition table and FAT32
**Size M. Depends on P2. Done.**
The first half of the Windows layout.
The work:
- Write an MBR: the boot signature, one entry per partition, the right type
bytes, and CHS fields that are wrong in the way every tool writes them wrong.
- Format a FAT32 volume with the `fatfs` crate, which is MIT and works over
anything that reads, writes and seeks.
- Put a sector adapter under it. `fatfs` writes a FAT32 entry as four bytes at
`cluster * 4`, and a directory entry as 32 bytes, and a raw device refuses
any write that its sector size does not divide. Measured in the 0.3.6
source, and the `fatfs` README says to wrap the storage. The adapter reads a
partial sector, changes it and writes it back, and passes whole sectors
straight through. It lives in `burnout-core`, which keeps no dependency.
- Write a directory tree into it.
- Repair two faults in the directories that `fatfs` 0.3.6 writes. The next
part of this section gives them.
- The layout lives in a new crate, `burnout-layout`, which is the only crate
that depends on `fatfs`. P4 puts the exFAT writer beside it.
**The exit test.** A drive partitioned and filled by Burnout mounts on
Windows, on macOS and on Linux, and every file reads back with the hash it
went in with. The same code, run against an image file, passes in CI.
**It passes on the three hosts, and CI runs it on each push.**
The example `layout_image` writes the table, formats partition 1, copies a
sample tree of 207 files onto it and checks each file through a new mount.
The tree holds files at several depths, a file of no bytes, long names, the
name `Überprüfung.txt`, an empty directory, and a directory of 200 files that
fills more than one cluster. Each host then mounts the image with its own
mechanism, checks it with its own tool, and reads each file back through its
own FAT driver.
| Host | How it mounts the image | Its check tool | Files that match |
| --- | --- | --- | --- |
| macOS 26 | `hdiutil`, `mount -t msdos` | `fsck_msdos -n`, exit 0 | 207 of 207 |
| Fedora 44 ARM64, 512-byte sectors | `losetup` | `fsck.fat -n`, no fault | 207 of 207 |
| Fedora 44 ARM64, 4096-byte sectors | `losetup --sector-size 4096` | `fsck.fat -n`, no fault | 207 of 207 |
| Windows Server 2025, in CI | a VHD, `Mount-DiskImage -Access ReadOnly` | `chkdsk`, "found no problems" | 207 of 207 |
The `layout` job of CI runs the same checks on `ubuntu-latest`,
`macos-latest` and `windows-latest`, and its first run passed on each. Fedora
also ran them in a virtual machine here. The Windows machine here asks for an
administrator password before it mounts a VHD, and this work does not type
one, so the Windows answer is the runner of CI, which is an administrator.
The `same-image` job compares the image that each host built. The first run
got one digest from three hosts, `8da7a714...daadcf0ae`, and it is the digest
of the image built on macOS here. The same tree gives the same bytes on each
host, which is the promise of this project in its smallest form.
**Four faults that no test of this crate found, and the host tools did.**
- `fatfs` 0.3.6 writes a long-name entry before `.` and before `..` in each
new directory, and gives `..` the cluster of the root, where FAT32 asks for
0. `fsck_msdos -n` exits 206 and names every directory. The source of
`fatfs` fixes both, and no release carries the fix: 0.3.6, of January 2023,
is the last. A git or a patched dependency would stop `cargo install` from
crates.io, so Burnout reads the volume after `fatfs` unmounts it and writes
the two entries again. A test fails on the day a release of `fatfs` stops
writing the old shape, and the repair can go then.
- `fatfs` without `chrono` writes a date of zero, which is not a date, and
macOS shows each entry as 1970. Every entry now carries 1980-01-01 at
midnight, the first second that FAT holds. One fixed time also keeps one
tree one image.
- Linux could not find `Überprüfung.txt` until the mount had the `utf8`
option. Without it, the kernel gives each name in its default character set.
The volume was right, and macOS read the name.
- A test that changed one byte on the drive found the change in another file.
The generator of the test bytes repeated a run of one file inside another,
and the test searched for the run. The bytes now come from a generator
that gives each file a stream of its own.
**What this does not prove.** Every write went to an image file. A raw device
is proven only through `StrictTarget`, which refuses what a device refuses.
P6 writes the layout to a device, and that is where the device half closes.
---
## P4. The exFAT writer
**Size XL. Depends on P3. Done. Planned for v0.2, and shipped in v0.3.0.**
The one piece with no crate behind it, and the reason macOS can take part at
all.
Microsoft published the exFAT specification in 2019, so this is documented
work and not archaeology.
That public specification is also the reason exFAT beat NTFS and APFS for
partition 2.
The work:
- The boot sector and its backup, with the checksum sector.
- The FAT.
- The allocation bitmap.
- The upcase table.
- Directory entries: the file entry, the stream extension, and the name
entries, with the name hash and the checksum over the whole entry set.
- Large files, which is the entire point, so a file over 4 GiB is the first
test and not the last.
**How the writer works.** These are the decisions, and the reason for each.
- **One pass, with the whole tree.** Burnout knows every file before it
writes the first byte. So the writer plans the whole volume first, and then
writes it. Each file and each directory gets one run of clusters, and its
entry says so with the NoFatChain flag, as Windows does. The FAT holds a
chain only for the allocation bitmap, the up-case table and the root
directory, because the specification asks for a chain there.
- **The clusters go in the order of the tree.** The bitmap takes cluster 2,
the up-case table comes next, and the root directory comes after them, as
the specification recommends. Every directory and every file follows in the
order of `TreePath`, so one tree gives one volume.
- **The cluster size is the one that Windows picks.** It is 4 KiB up to
256 MiB, 32 KiB up to 32 GiB, and 128 KiB above that, and never less than
one sector. The FAT starts 1 MiB into the volume, and the clusters start on
the next whole mebibyte. That is the alignment of the partitions, for the
same reason.
- **The boot regions go last.** The writer puts every other byte on the
volume first. A drive that stops half way then holds nothing that a host
mounts.
- **The up-case table is the one that the specification recommends.** It is
2,918 entries in compressed form, and its checksum is E619D30Dh. The source
holds it as a table whose lines match Table 25 of the specification, and a
test checks the checksum.
- **Every timestamp is 1980-01-01 at midnight, in local time,** as on
partition 1. One tree then gives one volume, to the byte.
- **Each file and each directory fills whole clusters, and the rest of its
last cluster is zero.** Old data on a drive then cannot show through, and
the same tree gives the same bytes on a device too.
- **The check reads the volume with a reader of its own.** It shares only
the checksums and the up-case table with the writer, and no cache. It
checks the boot region, its checksum and
its copy, the checksum of each entry set and the hash of each name. It
checks that the bitmap marks each cluster that the volume uses and no other.
Then it reads each file and compares its digest with the one it went in
with. The host tools check the same volume in CI.
- **The code lives in `burnout-layout`, beside FAT32.** It takes no
dependency.
**The exit test.** A volume that Burnout formats mounts on Windows, on macOS
and on Linux. A 6 GiB file written into it reads back with the same hash on
all three. The host's own check tool reports no error.
**It passes on the three hosts, and CI runs it on each push.**
The example `layout_image` now also writes partition 2 as exFAT. It holds the
same tree of 207 files and one more: `sources/install.wim` of 6,442,463,289
bytes, which is 6 GiB and 12,345 bytes. Its bytes come from a generator, so no
host holds a file of that size. The example checks both partitions with its
own readers. Each host then mounts the image with its own mechanism, checks
each partition with its own tool, and reads each file back through its own
driver.
| Host | How it mounts the image | Its exFAT check tool | Files of partition 2 that match |
| --- | --- | --- | --- |
| macOS 26 | `hdiutil`, `mount -t exfat` | `fsck_exfat -n`, "appears to be OK" | 208 of 208 |
| Fedora 44 ARM64, 512-byte sectors | `losetup` | `fsck.exfat -n` of exfatprogs 1.3.2, "clean" | 208 of 208 |
| Fedora 44 ARM64, 4096-byte sectors | `losetup --sector-size 4096` | the same | 208 of 208 |
| Ubuntu 24.04 in CI, at both sizes | `losetup` | `fsck.exfat -n` of exfatprogs 1.2.2, "clean" | 208 of 208 |
| Windows Server 2025, in CI | a VHD, `Mount-DiskImage -Access ReadOnly` | `chkdsk`, "found no problems" | 208 of 208 |
Partition 1 passes on each host too, with 207 of 207 files, as in P3. The
large file has the SHA-256 `9f122a80...b7b8fa6d20` on each host, which is the
digest it went in with. The `same-image` job got one digest of the whole
image from the three hosts, `0b3d05d3...c536408dc`, and it is the digest of
the image built on macOS here.
**What the host tools found.** Nothing in the volume. Each check tool passed
the first volume that the writer made. Two things around it:
- The Linux runner of CI, Ubuntu 24.04 with the kernel 6.17.0-1022-azure,
had no exFAT driver. `fsck.exfat` passed the volume, and `mount -t exfat`
said that it does not know the file system. The driver is in
`linux-modules-extra` of that kernel, and CI now installs it when
`modprobe exfat` finds no module.
- macOS shows each time on both partitions as 23:00 on 31 December 1979, in
the zone of the Mac here, which is one hour ahead of UTC in January. The
entries hold midnight on 1 January 1980. The two partitions agree, because
the exFAT entries hold no offset from UTC, which the specification allows,
and which means local time, as FAT keeps it.
**The checksums are the ones that macOS writes.** The tests hold entry sets,
entries of the root and a boot region from a volume that macOS 26 formatted.
The writer gives the same bytes and the same checksums. The reader also reads
that volume of macOS whole, bitmap and all.
**What this does not prove.** Every write went to an image file. A raw device
is proven only through `StrictTarget`, which refuses what a device refuses.
P6 writes the layout to a device, and that is where the device half closes.
The Windows machine here asks for an administrator password before it mounts
a VHD, so the Windows answer is the runner of CI, as in P3.
---
## P5. Reading an ISO
**Size L. Depends on nothing. Done.**
Burnout has to read the image itself, for the same reason it writes the
filesystem itself: a mount through the host is three different behaviours.
**This phase is larger than the milestones document assumed.**
A Windows ISO is UDF, not ISO 9660.
ISO 9660 stores an extent length in 32 bits, so it cannot hold a file of 4 GiB
or more, and a current `install.wim` is exactly that.
[The spike](spike-layout.md) measured both.
So reading a Windows ISO needs a UDF reader, and Burnout writes one.
The work:
- ISO 9660, with Joliet and Rock Ridge, for a Linux ISO.
- **UDF, read only**: the anchor descriptor, the logical volume and partition
descriptors, the file set, file entries, directory descriptors, and plain
extents. No compression, no encryption, no write path. This is decided, and
the reason is below.
- Detect the mode from the first 512 bytes and from what is inside.
- Refuse a macOS installer by name, and say `createinstallmedia`.
**What the two ISOs hold.** Measured on Windows 11 25H2 and Ubuntu 26.04.1
before the design.
- The Windows ISO has no boot table in its first sector. Its ISO 9660 tree
holds one file, `README.TXT`, and the real tree is in UDF 1.02. That UDF
uses file entries with short allocation descriptors, one partition of
type 1, whose number is 0BADh and not 0, and extended attributes on the
root. `install.wim` is eight extents of 1,023 MiB, one after the other.
- The Ubuntu ISO has a boot table, so it goes to raw mode. Its ISO 9660 tree
carries Rock Ridge, with names, links and continuation areas, and a Joliet
copy of the names.
**How the reader works.** These are the decisions, and the reason for each.
- **The reader lives in a new crate, `burnout-iso`.** It depends on
`burnout-core` alone. The tree of files moves from `burnout-layout` into
`burnout-core` first, so the reader and the writers share one tree and no
crate depends on another for it.
- **UDF wins when an image has it.** A Windows ISO keeps its real tree there.
Without UDF, the reader takes Rock Ridge, then Joliet, then plain ISO 9660,
because each of them holds more of a name than the next. Rock Ridge comes
first only when it gives names. `hdiutil` writes Rock Ridge with modes and
times and no names, and then Joliet holds more of each name.
- **The reader checks what it reads.** Each UDF descriptor has to carry its
own checksum, its CRC and its own location. A fault is an error that names
the image, and the reader does not guess past it.
- **It reads what a Windows ISO uses, and it refuses the rest by name.**
That is type 1 partitions, file entries and extended file entries, short
and long allocation descriptors and data inside the entry, and names in
8-bit and 16-bit form. A virtual, sparable or metadata partition, and
zisofs compression, give an error that says what is missing.
- **A link is listed and not copied.** Rock Ridge keeps links, and a FAT or
an exFAT volume cannot hold one. A Windows ISO has none.
- **The mode comes from the image.** A boot table in the first sector is raw
mode. An `.app` bundle, an installer package or a compressed `.dmg` is macOS
media, and Burnout refuses it and names `createinstallmedia`. A `.dmg`
counts as compressed when its trailer describes more sectors than its data
holds, which is true of each compressed and read-only format that
`hdiutil` makes and of no raw one. An image with `sources/install.wim` or
`sources/install.esd` is Windows mode. Anything else fits neither mode, and
`burnout write` stops and says what it found, as the README says. A
compressed image, such as an `.img.xz`, is one of these.
- **`burnout write` refuses a Windows ISO until P6.** A byte copy of one
starts nothing on most machines. `--mode raw` makes the copy anyway, of a
Windows ISO and of an image that fits neither mode.
- **Each test builds its own image.** A small ISO 9660 builder and a small UDF
builder live beside the tests. Each check that the reader makes has a test
that breaks it.
- **The gate reads an ISO that each host makes.** macOS makes UDF 1.02, UDF
1.50, and ISO 9660 with Joliet, with `hdiutil makehybrid`. Linux makes Rock
Ridge with Joliet, Joliet alone, and a file past 4 GiB, with `xorriso`.
Windows makes UDF at the revisions 1.02 to 2.01, and ISO 9660 with Joliet,
with its own IMAPI2. Burnout reads each one and compares every file with the
tree it came from, and each ISO has to read as the file system that the
reader has to choose. UDF 2.50 from IMAPI2 keeps its tree in a metadata
partition, and it has to give the refusal by name.
**The exit test.** Burnout lists the contents of a Windows 11 ISO and a Ubuntu
ISO, and extracts `install.wim` from the first with the hash that the host's
own mount gives for the same file.
**The exit test passes here.** The example `iso_tree` is the reader of
Burnout. It lists an ISO, extracts one file, writes a manifest in the form of
`sha256sum`, and compares an ISO with a directory.
| Image | The tree that the reader takes | What it is checked against | What agrees |
| --- | --- | --- | --- |
| Windows 11 25H2 x64 | UDF, 976 files | the macOS mount, with `shasum -a 256 -c` on the manifest | 976 of 976 files, and the mount holds no other |
| Windows 11 25H2 Arm64 | UDF, 962 files | the same | 962 of 962 files, and the mount holds no other |
| Windows 10 22H2 x64 | UDF, 906 files | the macOS mount, the path, the type and the size of each entry | 991 of 991 entries |
| Ubuntu 26.04.1 server | Rock Ridge, 834 files and 3 links | libarchive 3.7.4: its list, and each file that it extracts | 991 of 991 entries, and 834 of 834 files |
| Lubuntu 26.04.1, and Fedora 44 for x86_64 and aarch64 | Rock Ridge | libarchive 3.7.4, the path, the type, the size and the link of each entry | 775, 355 and 440 entries |
`iso_tree extract` gives `sources/install.wim` of the x64 ISO as
7,578,075,168 bytes, with the SHA-256 `93ee38f5...babd9809d0`. `shasum` gives
the same digest for the file of the macOS mount. The Ubuntu ISO carries an MD5
of 831 of its files too, and each file that the reader gives agrees with it.
**macOS mounts no file system of a hybrid Linux ISO.** `hdiutil attach` sees
the GPT of the Ubuntu ISO and says that it holds no file system that it can
mount. So the Ubuntu ISO is checked against libarchive, the reader behind
`bsdtar` on macOS, and against its own list of MD5 digests. The plan said to
mount it in the Fedora VM as well. That step is dropped: xorriso 1.5.6 made
the Ubuntu ISO, and the Linux job of the gate reads an ISO that xorriso makes,
on each push.
**What the real media and the tools found.**
- `hdiutil` pads a directory record to an even length with one zero byte, and
can put a padding entry of Rock Ridge after it. The reader took that byte
for the start of an entry, and refused the record. A zero byte where an
entry starts now ends the area, as in the reader of Linux.
- `hdiutil` writes Rock Ridge with no names. The reader took it over Joliet,
and gave the short names of ISO 9660, in upper case and without the
characters that are not ASCII. It now takes Rock Ridge only when the root
gives names.
- The plan said that an image with no boot table and no install image is raw
mode with a warning. The README says that Burnout stops, and the code now
does. The `.img.xz` of Raspberry Pi OS on the drive here is one of these.
- The Windows ISOs use less of UDF than the reader reads. In the three of
them, each of the 3,119 file entries and each of the 3,391 file identifiers
passes the four checks of its tag. Each file entry uses strategy 4 and short
descriptors, and holds 56 bytes of extended attributes. No ISO holds an
extended file entry, data inside an entry, an area of more descriptors, a
hidden file or a deleted one. The tests build each of those.
**The gate passes on the three hosts, and CI runs it on each push.** Each
host makes the ISOs of the sample tree with its own tool. The reader gives
the tree back from each one, byte for byte, as the file system that it has to
choose.
| Host | Tool | ISO | What the reader gives |
| --- | --- | --- | --- |
| macOS 26.6 in CI, and macOS 26 here | `hdiutil makehybrid` | UDF 1.02, UDF 1.50, and ISO 9660 with Joliet | the 8 directories and 207 files of the tree, from each |
| Ubuntu 24.04 in CI | xorriso 1.5.6 | Rock Ridge with Joliet, and Joliet alone | the same, from each |
| | | Rock Ridge with one file of 4 GiB, 5 MiB and 7 bytes, which ISO 9660 keeps in more than one extent | the file |
| Windows Server 2025 in CI | IMAPI2 | UDF 1.02, 1.50, 2.00 and 2.01, and ISO 9660 with Joliet | the tree, from each |
| | | UDF 2.50 | the refusal of its metadata partition, by name |
**What the first run of the gate found.** Two faults, both in the gate:
- xorriso writes Rock Ridge unless it gets `--norock`. The gate made its
Joliet ISO with `-J` alone, the reader took the Rock Ridge in it, as it has
to, and the check that it takes Joliet failed. The gate now gives
`--norock`.
- The runner of CI takes the exit code of the last program in a PowerShell
step as the result of the step. The refusal of UDF 2.50 left its exit code
there, so the step failed after the check passed. The check now sets the
exit code back.
**What this does not prove.** The reader reads an image file. P6 copies its
files onto a drive, and that is where the tree meets a device.
---
## P6. Windows mode
**Size L. Depends on P0, P4 and P5. Done. Shipped as v0.3.0.**
Put the four pieces together.
The work:
- Plan the layout, then write it: MBR, FAT32 of about 1 GB, exFAT for the rest.
- Copy every boot file to partition 1 and the install image to partition 2.
- Generate `autounattend.xml`: the `LabConfig` keys for the hardware checks,
a local account for the Microsoft account step, and the `InstallFrom` path
if P0 says it is needed. Write only the entries that the person asks for,
and leave the rest of Setup interactive.
- Per-file verification, and a report that names the check it ran. A hash of
the whole device proves nothing here, because Burnout built a filesystem
that the source never had.
**What is there, and what P6 adds.** P3 and P4 write the table, FAT32 and
exFAT into an image file, and check each file through a new mount. P5 reads
the ISO and chooses the mode. P6 joins them in `burnout write`, writes the
file that Setup needs, and runs the same code on a drive.
**What the three Windows ISOs hold.** Measured before the design.
| ISO | Boot files, in clusters of 4 KiB | `install.wim` | Editions | Index 1 | Pro |
| --- | --- | --- | --- | --- | --- |
| Windows 11 25H2 x64 | 975 files, 849 MiB | 7.06 GiB | 11 | Home | index 6 |
| Windows 11 25H2 Arm64 | 961 files, 873 MiB | 6.59 GiB | 3 | Home | index 3 |
| Windows 10 22H2 x64 | 905 files, 912 MiB | 4.83 GiB | 11 | Home | index 6 |
The image lists its editions in XML, in UTF-16 and not compressed, at a place
that its header gives. Each edition names its architecture: 9 is x64, and 12
is Arm64.
**How Windows mode works.** These are the decisions, and the reason for each.
- **The tree splits in two.** Partition 2 holds `sources/install.wim` or
`sources/install.esd` alone. Partition 1 holds every other file, and
`autounattend.xml`.
- **Partition 1 holds the boot files and 256 MiB more.** Each file counts in
whole clusters of 4 KiB. A fixed 1 GiB leaves Windows 10 about 100 MiB, and
the next ISO can hold more. The room that is left takes a driver that a
person adds later.
- **The drive has to hold both partitions, and Burnout checks that first.**
The check runs before the privilege and before the confirmation, and a
drive that is too small is refused with the size it needs.
- **`autounattend.xml` goes on every drive, and it holds what the spike
measured.** The search that pins the install volume to `W:`, and the
`InstallFrom` path that uses it. Each component names the architecture of
the image, because Setup ignores a component for another one. The options
add the rest, and nothing else: `--skip-hardware-checks` adds the five
`LabConfig` keys, and `--no-microsoft-account` takes away the step of the
Microsoft account. That option writes two things: `HideOnlineAccountScreens`,
and the `BypassNRO` key in the specialize pass, which lets the first-run
setup go on with no network. The empty product key stays out, because Setup
is to ask for the key.
- **Burnout does not choose the edition.** Index 1 is Home on each ISO above.
The spike gave index 1, and a person who wanted Pro got Home. With the
`InstallFrom` path and no index, Setup shows the list of editions, and the
person chooses one. So Burnout writes no index.
- **The check reads the drive again through a new handle.** The write ends
with a flush, the drive opens again, and each file is read back through a
new mount of its volume, as raw mode reads the drive again. The report says
that it checked each file against the SHA-256 that it went in with.
- **The labels come from the ISO.** Partition 1 takes the label of the ISO,
cut to what FAT32 holds, and partition 2 is `INSTALL`. The search in the
file finds the volume by its content, so no label is part of the layout.
- **`--mode windows` forces the layout** on an image that carries a boot table
and an install image, which some tools make.
- **The code that writes the drive lives in `burnout-layout`.** It works on
any target, so an example writes an image file with it, and CI checks that
image on each host with the tools of the host.
**What the VM measured.** Two questions decided the options, and a VM
answered both before the command line changed. The VM is aarch64 with UEFI,
no TPM, a blank NVMe disk, no network adapter, and a drive image from the
example as a USB disk. It ran Windows 11 25H2, build 26200.8037.
1. **Does Setup take `InstallFrom` with no index?** Yes. Setup shows "Select
Image" with the three editions of the Arm64 image: Home, Home Single
Language and Pro. So `burnout write` has no `--edition`, and Burnout does
not read the editions out of the image. The library can still write an
index, and the example takes `--edition` for it.
P10 reads the editions, so `burnout write` takes `--edition` since then,
as an option. With no option, Setup still asks. Measured on 2026-11-11
with the Arm64 ISO and `--edition pro` in the same VM: Setup went from
the product key page to its check of the hardware, and showed no "Select
Image" page.
2. **Does `HideOnlineAccountScreens` alone skip the Microsoft account on
25H2?** No. With no network, the first-run setup stops at "Let's connect
you to a network", and that page has no way on. With the `BypassNRO` key
from the file too, the page shows "I don't have internet". The next page
asks for the name of a local account, and the page after it asks for its
password. So Burnout holds no password. This ran on Home.
The five `LabConfig` keys work too: Setup shows no refusal on the VM with no
TPM.
**The exit test.** A drive made on each of the three hosts installs Windows 11
on a machine with no TPM, with no Microsoft account step, from an ISO whose
`install.wim` is over 4 GiB.
Here that is the Arm64 ISO, whose `install.wim` is 6.59 GiB, on the Samsung
drive, in the VM above. macOS writes the drive on this Mac. Fedora and Windows
write it in their VMs, with the drive passed through. An emulated x64 machine
cannot run a current Windows image, and [the spike](spike-layout.md) measured
why.
**The exit test, run.** Each host wrote the Samsung drive from
`Win11_25H2_English_Arm64_v2.iso` with `--skip-hardware-checks` and
`--no-microsoft-account`. Each write put 963 files of 7,988,543,418 bytes on
the drive, and checked each file against its SHA-256. The drive then started
the VM above, and Windows installed to the desktop.
| Host | How it reached the drive | Write | Check | Disk signature |
| --- | --- | --- | --- | --- |
| macOS 26 | `/dev/rdisk5` | 38.9 MB/s | 78.7 MB/s | `0x09381FF3` |
| Fedora 44 ARM64, a VM | the drive passed through, `/dev/sdb` | 54.7 MB/s | 224.9 MB/s | `0x110C19AC` |
| Windows 11 ARM64, a VM | the drive passed through, `\\.\PhysicalDrive1` | 8.8 MB/s | 11.0 MB/s | `0x8C36F180` |
Each write gives the drive a new disk signature, and the UEFI shell of the VM
prints it, so each install shows which host wrote the drive. Each install went
the same way:
- The drive arrived after the VM started, so the firmware stopped at the UEFI
shell, and the shell started `\EFI\BOOT\BOOTAA64.EFI` from partition 1.
- Setup showed the three editions, and Home was chosen. No page refused the
VM for its missing TPM.
- The disk page selected partition 2 of the drive, said that Windows cannot go
there, and kept Next off. The blank NVMe disk was selected by hand.
- The first-run setup offered "I don't have internet", and then asked for the
name and the password of a local account. In the VM the password stayed
empty, and each privacy setting went off.
- `winver` showed Windows 11 Home, version 25H2, OS build 26200.8037.
Fedora checked at 224.9 MB/s. In the same VM, `dd iflag=direct` read 2 GB of
the drive at 220 MB/s. So the drive itself reads that fast, and the speed of
the check does not show a read out of the page cache.
**Two faults that only the real drive found.** Both are fixed, and the macOS
write passed on its third run.
- **macOS mounted the new volumes when the handle that wrote closed.** The
open for the check then failed with `EBUSY`. The check now takes the volumes
off before each open, and tries again for ten seconds while the drive is
busy.
- **Spotlight wrote to a volume before the check read it.** The check found
`.Spotlight-V100` on partition 1 and refused the drive, which is its job. On
macOS, Burnout now refuses each mount of a volume of the drive, through the
mount approval of Disk Arbitration, from the first unmount until the check
ends.
**Two items that the exit test left open, now fixed.** The same macOS write,
run again with both fixes on the same drive, passed.
- **The host wrote to the drive after Burnout ended.** When the drive came
back to the Mac, macOS mounted it, and Spotlight wrote 16,584 KiB to
partition 1 and 11,904 KiB to partition 2, as `du` counts them. On macOS,
Burnout now ejects the drive when the check ends, while the mounts are
still refused. After the run the drive stayed on the USB bus with no disk
and no mount. It was then connected again with each mount refused, and its
two volumes were mounted read-only. They held the 962 files of the ISO,
each with the SHA-256 of its copy in the ISO, and `autounattend.xml`, and
nothing else: no `.Spotlight-V100` and no `.fseventsd`. Windows Setup still
writes `System Volume Information` when it installs from the drive, and
that is Setup.
- **Partition 1 went to the drive in writes of 4 KiB.** `fatfs` writes one
cluster at a time, and `SectorIo` sent each cluster on by itself. Through
the USB pass-through of the Windows VM that part ran at 0.5 to 1.3 MB/s.
`SectorIo` now sends whole sectors that follow one another in one write of
up to 1 MiB. On macOS the write reached 803.4 MB at 31.8 MB/s, where it was
at 12.7 MB/s near 997 MB before, and the whole write ran at 50.9 MB/s
against 38.9 MB/s. A Windows 11 VM then wrote the same drive twice, first
with the binary of the commit before the change, and then with v0.3.0.
After 30 seconds the old binary had written 125.4 MB at 4.2 MB/s, and
v0.3.0 767.0 MB at 25.4 MB/s. The whole write ran at 22.0 MB/s and then at
37.6 MB/s, and the check at 35.6 MB/s both times. That VM is not the
Windows VM of the exit test, which has a slower USB path: there the old
binary wrote at 8.8 MB/s. So only two runs in the same VM compare.
The VM stopped at "Start boot option" after a warm restart twice, in the
install from the drive that Windows wrote, and in its first run with a drive
image. A cold stop and start went on each time, so the fault is in that VM
and not in the drive. The VM was made for this test, and it is gone.
**What is still open.** x64 and the firmware of a physical PC are not run.
The drive started in an Arm64 VM on this Mac.
---
## P7. The edges, and version 1
**Size M. Depends on P6. Done. Shipped as v1.0.0.**
The work that turns a program that works into one somebody else can use.
- One error message for every refusal, in Simplified Technical English, that
names the fix.
- `--json` for the list and for progress, so a script can read it.
- Resume nothing and promise nothing about a stopped write. Say that the drive
is now unusable, because it is.
- Build provenance is in place from v0.1, because it moved to P2. This phase
checks that it still holds for every artifact and every host.
- The macOS and Windows download warning, and the way past it, in the README.
- `install.esd` alongside `install.wim` everywhere.
- The README stops saying that nothing is built.
- winget and Scoop, with a manifest for each release. The decision on
distribution below says why they wait until here.
**What is done.**
- The error messages. Each one says what went wrong, and then what to do
about it, and a test holds every kind of error to one form. A busy drive
gives one error on every host. Measured on macOS with a disk image: the
unmount of a volume with a file open on it answers `0x0000c010`, which is
`unix_err(EBUSY)`, and an eject while a program reads the raw node answers
busy too. Measured on Linux in the Fedora VM: the unmount of a volume with a
file open on it gives the error with the mount point. Measured on Windows in
a test VM: the lock of a volume with a file open on it gives the error for a
volume of the drive. A code of the system with one cause, such as `EIO`,
carries its fix.
- An image that ends before its own ISO 9660 volume is refused in each mode,
before the mode check reads it. Raw mode wrote such a file, and the check
passed, because the check compares the drive with the same short file.
Measured on the twelve ISOs of the test set: each file is exactly as long as
its volume.
- A drive that takes no write, such as an SD card with its lock switch on,
is marked `(read only)` in the list, and the write refuses it before the
privilege, with the lock switch as the fix. Before this, macOS answered the
probe for a write with `EACCES`, and Burnout asked for a password that
cannot help. macOS reads `Writable` from the registry, Linux reads
`/sys/block//ro`, and Windows asks `IOCTL_DISK_IS_WRITABLE`.
Windows also answers write-protected for the read-only mark that a write of
Burnout leaves on the drive, and the next write takes that mark off. So
Windows refuses only a drive that answers write-protected with no mark.
Measured with diskpart: a medium that QEMU gives read only says "Current
Read-only State: Yes" and "Read-only: No", and a drive that Burnout wrote
says yes to both. Measured on macOS with a disk image attached read only,
and on Linux and on Windows with a drive that QEMU gives read only: the
list marks it, and the write refuses it. On Windows a second write to the
drive that Burnout wrote goes through.
- A write that stops says what the drive holds. After an error, one line
follows the error. Ctrl-C, SIGTERM and SIGHUP on Linux and macOS end with
128 and the number of the signal, and a signal that the parent ignores
stays ignored, so `nohup` still works. Ctrl-C, Ctrl-Break and the close of
the console on Windows end with 130. Burnout resumes nothing. Measured on
macOS with a disk image: a stop at the confirmation, during the write, and
during the check. Measured on Linux in the Fedora VM: SIGINT ends with 130,
SIGTERM with `--json` ends with 143 and the stopped event, a write under
`nohup` goes on to its end through SIGHUP, and Ctrl-C from the keyboard
ends the progress line and prints the stop. Measured on Windows in the test
VM: Ctrl-C from the keyboard in PowerShell prints the stop and ends with
130.
- `--json`. `list` prints one object, and `write` prints one object on a line
for the confirmation, each step, the result, an error and a stop. Each kind
of error has a name that a script tests. Measured on macOS: a raw write of a
disk image, and a Windows write of the Windows 11 Arm64 ISO onto a 16 GB
disk image.
- The warning of a download, and the way past it, is in the README, for
macOS and for Windows.
- winget and Scoop. `scripts/winget-manifest.sh` and `scripts/scoop-manifest.sh`
write each manifest from the `SHA256SUMS` of a release, and
[releasing.md](releasing.md) says when to run them. Nothing publishes them
before version 1. Both manifests parse, and `winget validate` in Windows 11
25H2 says "Manifest validation succeeded."
- The README says that both modes are built, and its release badge reads the
latest release.
- `install.esd`. Measured in the Windows test VM: DISM exported image 1 of the
`install.wim` of Windows 11 25H2 Arm64, with recovery compression, into an
`install.esd` of 5,271,324,480 bytes. `scripts/make-iso.ps1` made an ISO of
6,188,892,160 bytes from that tree. Burnout on macOS wrote the ISO onto a
16 GB disk image in 44 seconds, with `sources/install.esd` on partition 2,
and the check passed. Setup started from that drive and installed onto a
blank disk. Its log says
`Applying WIM file: W:\sources\install.esd, index 1`, and the first page of
the first-run setup showed less than six and a half minutes after the click
on Next.
- The build provenance of v1.0.0. `gh attestation verify` passes for each of
the six binaries. Each digest is a subject of one attestation, which
`release.yml` made at `refs/tags/v1.0.0`, commit `2bdd517`. Each digest also
matches `SHA256SUMS`.
- Version 1.0.0 is out: the release, the four crates on crates.io, and the
formula in the tap. `brew install stiven-gjekaj/tap/burnout` installed
1.0.0 on the Mac.
- Scoop and winget. The bucket
[Stiven-Gjekaj/scoop-bucket](https://github.com/Stiven-Gjekaj/scoop-bucket)
holds the manifest of 1.0.0. It validates against the schema of Scoop, and
each download matches its hash. The winget manifest went to winget-pkgs in
[pull request 441640](https://github.com/microsoft/winget-pkgs/pull/441640),
in schema 1.12.0, which the template of winget-pkgs asks for. It validates
against the JSON schemas of 1.12.0, and each download matches its hash.
**What is open.**
- Microsoft reviews the winget pull request. The person who owns the project
signs the Contributor License Agreement of Microsoft in it first.
**The exit test, dropped.** The first plan was this: somebody who has never
seen the project writes a Windows drive and a Linux drive, on a host you did
not choose, without asking you a question. The person who owns the project
dropped it on 2026-09-26. The exit tests of P2 and P6 already wrote a Linux
drive and a Windows drive from each of the three hosts, and each drive started
its system. So for a release of P7, the exit test that
[releasing.md](releasing.md) asks for is those two, and both passed. No test
put the tool in the hands of a person who is new to it, and no test started a
drive on the firmware of a physical PC.
---
## P8. Legacy BIOS boot
**Size M. Depends on P7. Done. Ships as v1.1.0.**
A Windows drive from Burnout starts a PC with UEFI firmware only. P8 makes the
same drive start a PC with BIOS firmware, or with UEFI in its compatibility
mode. Raw mode needs nothing here, because a hybrid image carries its own boot
code.
The layout does not change. Partition 1 stays FAT32 and active, and partition
2 stays exFAT. The MBR was chosen so that this phase fits with no change to
anything that exists.
**The plan changed: Burnout writes the boot code itself.** The first plan
was to download grub4dos at run time. A look at it on 2026-11-11 found three
costs. Its releases on GitHub are builds for UEFI in `.7z` archives, and its
builds for a BIOS are archives on another server. A download needs an HTTPS
library and an archive reader, in a tool that has almost no dependencies.
grub4dos is GPL. The source of grub4dos shows the one thing that a loader
must do for `BOOTMGR`: load the whole file at `2000:0000`, keep the boot
sector of the partition at `0000:7C00` with the first sector of the partition
in its BPB, and jump with the drive in `DL`. That is a small loader, so
Burnout has its own, under the MIT licence:
- `boot/mbr.asm` of `burnout-layout`, the code of the MBR. It reads the first
sector of the active partition by LBA, and starts it.
- `boot/fat32.asm`, the code of the FAT32 volume, in two parts of 512 bytes.
Part 1 goes into the boot sector and its copy, around the BPB that the
format wrote. Part 2 goes into reserved sector 2, which nothing else uses.
It walks the root directory, loads `BOOTMGR`, and starts it.
- Burnout includes the bytes that `nasm` builds, and `scripts/boot-code.sh`
builds them again in CI and compares them.
Both decisions of the first plan fall away. There is no download, so there
is no network code and no copy for a computer with no network. The code costs
nothing on a UEFI start, so it is not an option: each Windows drive carries
it.
**What is done.**
- The boot code, in the MBR and in the FAT32 volume, on every Windows write.
The check after the write reads the MBR back with its code.
- A test in QEMU with SeaBIOS, in CI on each push:
`scripts/bios-boot-test.sh`. A drive image with a probe of 409,600 bytes as
`bootmgr`, behind 300 files with long names, starts as an IDE disk and as a
USB stick on xHCI and on EHCI. Measured on macOS with QEMU 11.1.3 and
SeaBIOS 1.17.0, all three print
`PROBE cs=2000 dl=80 bpb-dl=80 hidden=00000800 signature=ok end=ok`: the
probe runs at `2000:0000`, with the drive in `DL` and in the BPB, with the
first sector of partition 1 in the BPB, and with the last bytes of the file
in memory.
- An image with no `bootmgr` stops with "Burnout: the volume holds no
BOOTMGR" on the screen. `fsck_msdos -n` on macOS finds the volume clean
with the boot code in it.
- CI on Windows mounts and checks a FAT32 volume that carries the boot code,
in the jobs "layout" and "windows mode".
**The exit test, run.** `windows_image` wrote `Win10_22H2_English_x64v1.iso`
into a drive image of 6,410,993,664 bytes, with 907 files checked against
their SHA-256. QEMU 11.1.3 started it:
| Firmware | What it showed |
| --- | --- |
| SeaBIOS 1.17.0 | The logo of Windows after 1 minute, and the first page of Setup |
| OVMF of QEMU 11.1.3 | The first page of Setup |
The Fedora 44 x86_64 ISO, as a USB stick that QEMU opened read only, started
with SeaBIOS (GRUB started its first entry) and with OVMF (the boot screen of
Fedora). Raw mode writes the ISO byte for byte, so the ISO is the drive.
**A fault that the exit test found, and fixed.** The first run stopped at
"Windows cannot read the setting from the unattend answer file",
with SeaBIOS and with OVMF alike. Windows 10 Setup reads the key from the
answer file once the file names the image, and the file held none. Windows 11
asks for the key itself, so the tests of P6 never met it, and v1.0.0 has it
for each Windows 10 ISO. `autounattend.xml` now gives an empty key that Setup
always asks for. The run after the fix reached the first page of Setup with
both firmwares.
Windows 11 with the new answer file: a drive image from
`Win11_25H2_English_Arm64_v2.iso` started in QEMU on this Mac with HVF and
OVMF for Arm64, and Setup showed its first page and then its usual page for
the product key, with "I don't have a product key" on it.
v1.1.0 shipped all of this: the release, the four crates, the formula in the
tap, the manifest in the bucket, and a pull request to winget-pkgs. Each of
the six binaries passes `gh attestation verify` at `refs/tags/v1.1.0`, and
`brew install stiven-gjekaj/tap/burnout` installed 1.1.0.
**What is open.**
- A drive with sectors of 4096 bytes. The code reads each number from the
BPB, but SeaBIOS 1.17.0 cannot read sector 0 of such a drive at all, so
QEMU cannot test it. A USB stick has sectors of 512 bytes.
**Measured, to size it.** Burnout holds 25,138 lines of Rust, and the exFAT
writer of P4 holds 3,645 of them. The code of P8 is 199 lines of Rust with
its tests (190 in `boot.rs` and 9 in the MBR and the format), 459 lines of
assembly in the MBR and the volume, a probe of 154 lines, and two scripts of
102 lines. That is far less than the estimate of 1,000 to 1,500 lines,
because no download and no archive reader came in.
**The test runs in emulation only.** The project has no x64 PC, and the
person who owns it said so on 2026-10-01. This Arm Mac emulates x86 in QEMU:
SeaBIOS for a BIOS start, and OVMF for a UEFI start. Windows 11 x64 stops
during its start under emulation, so the test goes as far as the first screen
of Setup. Windows 10 x64 needs no TPM, so it shows the boot chain alone.
**The exit test.** A drive that Burnout writes from
`Win10_22H2_English_x64v1.iso` reaches the first screen of Setup in an
emulated x86 VM with SeaBIOS, and again with OVMF. A drive from a Linux x86_64
ISO starts in both.
**What stays unproved.** The firmware of a physical PC, in BIOS mode and in
UEFI mode, as after P2 and P6. A full install on x64.
---
## P9. A write to one partition
**Size S to M. Depends on P7. Done. Ships as v2.0.0.**
`burnout write --partition ` copies the image byte for byte
into partition `n` and leaves the rest of the drive as it is. The person who
owns the project asked for it on 2026-11-11, and it left "Later, maybe".
The risk is a wrong partition beside data that a person keeps. So most of the
phase is safety:
- **The table comes from the drive.** Burnout reads the first 1 MiB of the
drive after it has the privilege, and reads an MBR or a GPT from it. It
checks the CRC-32 of the GPT header and of its entries, and refuses a table
whose partitions overlap or go past the end of the drive.
- **The confirmation names the partition.** It shows the number, the size,
the first byte and the type, and says that the other partitions stay as
they are.
- **The table is read again after the confirmation.** A partition that moved
or changed size between the two reads stops the write with
`partition_changed`.
- **The write cannot leave the partition.** Each write and each read of the
check go through a window on the drive that starts at the first byte of the
partition and ends at its last byte.
- **A Windows ISO is refused.** Windows mode writes a whole drive. An image
that a whole drive does not take, such as a file system, goes on.
- An extended MBR partition, a number that is not in the table, an image
larger than the partition and a drive with no table are refused, each with
its own error kind.
**Measured, to size it.** 924 lines came in: 595 in `partitions.rs` with its
tests, 202 in the write command, 135 for seven new error kinds, and 13 in the
CLI and the exports. That is size S to M, as estimated.
**The exit test, measured on macOS with disk images on 2026-11-11.** A write
into partition 2 of a GPT image left the GPT and partition 1 with the same
SHA-256 before and after, and partition 1 still mounted with its file. A
write into partition 2 of an MBR image passed its check. A missing number, a
partition too small, a drive with no table and a Windows ISO were refused. The
JSON confirm event carried the partition, and the result named it.
**What stays unproved.** A write to one partition on Windows and on Linux. CI
runs the unit tests on both, but no person ran the command there.
---
## Windows To Go: P10 to P12, toward version 3
**Done for UEFI in version 3.0.0. The person who owns the project asked for
it on 2026-11-11.**
Windows To Go puts a Windows system that runs from the USB drive onto it, in
place of an installer. So it is a third write mode, and not an option on
Windows mode. It needs three large parts that Burnout does not have, and it
avoided two of them on purpose.
| Part | The reference, measured on 2026-09-26 | An estimate in Rust |
| --- | --- | --- |
| A WIM reader: resources, XPRESS, LZX and LZMS, extraction | wimlib, about 350 KB of C in those files | 5,000 to 7,000 lines |
| An NTFS writer: MFT, attributes, indexes, security, log file | ntfs-3g, about 754 KB of C in those files | 8,000 to 12,000 lines |
| A BCD store, which is a registry hive | none measured | 1,500 to 2,000 lines |
That is 15,000 to 20,000 lines, four to six times the exFAT writer, and most
of the size of Burnout today.
- Windows needs hard links, reparse points, extended attributes and large
directory indexes on its system volume. Setup applies the image with
extended attributes, and its log says so.
- wimlib is LGPL or GPL, so a WIM reader in Burnout must be new code to stay
under the MIT licence.
- Microsoft took Windows To Go out of Windows itself.
- Each test applies an image of 5 to 10 GB and then starts Windows.
So the work goes in three phases, and each one ships what it can show a
person on its own, as a minor release of version 2. Version 3 is the release
that writes a drive that Windows starts from.
### P10. Read a WIM file
**Size L. Depends on P5. Done, with LZMS since 2026-11-13.**
The crate `burnout-wim` reads a WIM or ESD file from inside an ISO, through
`IsoSource::open_file`, which seeks.
1. **The header and the editions.** Done, and shipped as `burnout info`. The
XML is not compressed, so no decompressor was needed. Measured on
2026-11-11: the Windows 10 22H2 x64 and the Windows 11 25H2 x64 ISOs list
11 editions each, and the Windows 11 25H2 Arm64 ISO lists 3, as P6
counted. Each run took less than a quarter of a second.
2. **The offset table and the resources.** Done. Each stream, by its SHA-1,
with its place, its size and its chunks.
3. **The decompressors.** LZX and XPRESS are done. Each one is new code from
a public description: the LZX of the Cabinet SDK, and LZ77+Huffman in
[MS-XCA]. Four WIM files that wimlib made are test data in CI, and each
of their streams decompresses to its SHA-1. Measured on 2026-11-11 with
the example `wim_check`: each stream of the three install images matched
its SHA-1. That is 71,824 streams and 11.5 GB for Windows 10 22H2 x64,
95,219 streams and 16.4 GB for Windows 11 25H2 x64, and 90,772 streams
and 15.2 GB for Windows 11 25H2 Arm64, at about 200 MB/s on one core of
this Mac. A resource streams one chunk at a time, so its size does not
matter.
4. **The metadata resource.** Done. The security descriptors and the tree of
directory entries of one edition, with hard links, reparse points and
extra streams. Measured on 2026-11-11 with the example `wim_tree`: for
each of the 25 editions of the three ISOs, the counts of directories and
of files equal the ones in the XML, and each file with data names a
stream of the offset table. The XML counts a directory that is a
reparse point as a file. Windows 11 25H2 x64 Pro holds 32,610
directories, 143,888 files, 470 security descriptors, 2 reparse points,
no named stream, and 45,176 names that are hard links to another file.
5. **The exit test.** Met for WIM files: each stream comes out with its
SHA-1, and each file of each edition names one of those streams.
**LZMS, done on 2026-11-13.** An ESD file and a solid resource use LZMS.
Microsoft publishes no description of LZMS. The public decoders are in
wimlib, whose `lzms_decompress.c` is LGPL 2.1 or later, and in 7-Zip, which
is LGPL too. On 2026-11-12 the owner of the project asked Eric Biggers, the
author of wimlib, for the MIT licence on a Rust port of his decoder, and on
2026-11-13 he said yes. The port is now `burnout-wim/src/lzms`, and its
header records the permission.
- Chunked LZMS and solid resources read, with two test files that wimlib
made, one with chunks of 32 KiB and one solid with chunks of 64 KiB.
- A stream in a solid resource gives its place in the bytes of all solid
resources of the file, one after the other. The `install.esd` of the Media
Creation Tool showed it: its 10 solid resources hold 11,161,438,137 bytes,
and its streams run from place 0 to that number. Its table lists the
streams in that order, and the entry of a resource can come after the
first stream in it.
- Measured on 2026-11-13 with `wim_check`: each of the 75,934 streams of
the `install.esd` of Windows 10 22H2 x64, build 19045.3803 (4,164,077,935
bytes, its SHA-1 as the catalog of the Media Creation Tool gives it),
matched its SHA-1. That is 11.4 GB in 114 s.
- `to_go_image` wrote Windows 10 Pro of that `install.esd` into a disk
image of 40 GiB: 101,926 files and directories, 30,021 hard links, 9.6 GB
of streams and 127 boot files, in 108 s, and checked each of them in
155 s. That drive has not started in a VM yet.
- `burnout info` lists the editions of an ISO, and not of a bare WIM or ESD
file. That is still to do.
### P11. Write an NTFS volume
**Size XL. Depends on P10. Started.**
An NTFS writer that takes the tree of P10: the MFT and its mirror, the
attributes, the B+ tree indexes of large directories, the security
descriptors, hard links, reparse points and extended attributes, and a clean
log file. A drive image goes to Windows in a VM, and `chkdsk` finds no fault.
**How it is tested.** Windows PE, from the Windows 11 25H2 Arm64 ISO in
QEMU, runs `diskpart` and `chkdsk` on a disk image that the Mac writes.
`diskpart` can take the disk offline, the Mac changes the image, and the disk
comes online again, so one start of the VM tests many images. First, `format`
of Windows wrote a volume of 256 MiB, and the Mac read it, as the reference
for each structure. No code of Windows comes in: the reference gives the
values of the format, and the tests compare bytes.
Done, in `crates/burnout-layout/src/ntfs/`, measured on 2026-11-11:
1. **The parts.** The run lists, the file records with their fixups, the boot
sector, `$STANDARD_INFORMATION` and `$FILE_NAME`, the B-tree of an index,
and the descriptors of the system files. `$AttrDef` and `$SDS` are the same
bytes that Windows wrote, and so are the descriptors 256 and 257.
2. **An empty volume.** Records 0 to 15, and `$Quota`, `$ObjId` and `$Reparse`
in `$Extend`. Windows mounts it as NTFS, and `chkdsk` says that it found no
problems. Windows accepts a `$LogFile` of 0xFF bytes, as on its own volume.
The first image did not mount: a run of `$Bad` gave its length with the
high bit set, and NTFS reads the length as signed. Swapping the parts of
Burnout into the volume of Windows, one group at a time, found it.
3. **`$UpCase`.** Burnout writes the table of its exFAT writer. It differs from
the table of Windows 11 in 109 of the 65,536 units, and Windows takes it,
because each volume carries its own table.
4. **Files and directories.** Each new file gets a record from record 27 on
and a run of its own clusters, and each directory an index, in blocks
when its root does not hold it. A volume with 309 files in nested
directories, 301 of them in one directory, and a name outside ASCII:
`chkdsk` found no problems, `dir` listed each name and size, and the
content read back. A name that DOS can hold goes in both namespaces, and
a long one in POSIX: with Win32 names alone, `chkdsk` found a "minor file
name error" in each file.
5. **Hard links and reparse points.** A file with three names in three
directories, and the junction `Documents and Settings` to `C:\Users`.
`chkdsk` found no problems, `dir` showed the junction and its target,
`fsutil hardlink list` gave the three names, and the content read back
through each name.
6. **Descriptors and named streams.** 500 descriptors, so that `$SDH` and
`$SII` need blocks, and a stream `Zone.Identifier`. `chkdsk` found no
problems, `icacls` showed the descriptor of a file, and the stream read
back.
7. **A whole edition of Windows.** The example `wim_ntfs` of `burnout-wim`
applied Windows 11 25H2 Pro of the Arm64 ISO to a disk image of 32 GiB:
127,048 files and directories, 43,485 more names and 15.1 GB of data in
64 s. `chkdsk` said that Windows found no problems, after 168,192 file
records, 1,413 records with attribute lists, 231,634 index entries and 2
reparse records, and `cmd.exe` of the volume ran in Windows PE. Two faults
came out on the way, and each has its test now: an index node with its
end entry alone, and a hard-linked file with a name in both namespaces.
8. **The Pro edition of each ISO.** The same check with Windows 11 25H2 Pro
of the x64 ISO, 131,322 files and directories and 14.4 GB in 59 s, and
Windows 10 22H2 Pro of the x64 ISO, 100,491 files and directories and
9.5 GB in 40 s. `chkdsk` found no problems in each.
9. **Windows starts from it.** On 2026-11-11 the example applied Windows 11
25H2 Pro of the Arm64 ISO to a disk image with a GPT: an EFI system
partition from 1 MiB and the NTFS partition from 512 MiB. Windows PE
formatted the EFI partition and ran `bcdboot`. QEMU then started the disk
alone with UEFI: the boot manager, `winload`, the kernel and the drivers
came from the volume of Burnout, the specialize pass ran, and Windows
showed the first page of its first-run setup. With an MBR, the
specialize pass stopped with "Failed to get system partition", also with
partition type 0xEF, so a drive of Windows To Go for UEFI takes a GPT.
Next: P12. Burnout writes the EFI partition, the boot files and the BCD
store itself, in the place of `bcdboot`, and the store that `bcdboot`
wrote is the reference.
### P12. Windows To Go
**Size L. Depends on P8, P10 and P11. Done for UEFI in version 3.0.0, and for a BIOS after it.**
`burnout write --to-go --edition ` lays out the drive with
an EFI system partition and an NTFS partition, applies the edition, and writes
a BCD store and the boot files for UEFI. The exit test is a drive image that
starts Windows to its first-run setup in a VM.
What was built, each step in its own commit:
1. `burnout_layout::hive` writes and reads a registry hive, the format of a
BCD store: regf version 1.3, with lh lists and one security cell.
2. `burnout_layout::bcd` builds the store: the boot manager, the loader of
Windows, the resume loader and the seven objects of settings that
`bcdboot` wrote. A device element names a partition of a GPT disk by
the GUID of the partition and of the disk, in 88 bytes. A test compares
each element with the store that `bcdboot` wrote, when that store is at
hand.
3. `burnout_layout::gpt` writes a GPT: a protective MBR, the header and its
128 entries, and the copy of both at the end of the disk.
4. `burnout::to_go` plans the drive, writes it on any block target, and
reads it back. The boot files are `Windows\Boot\EFI` and
`Windows\Boot\Fonts` of the edition, as `bcdboot` copies them, and
`bootmgfw.efi` again as `EFI\Boot\BOOTAA64.EFI` or `BOOTX64.EFI`.
5. `write --to-go` takes `--edition`, and refuses `--partition`, `--mode`
and the options of Setup.
Measured on 2026-11-11:
1. The store that Burnout built went in the place of the store of
`bcdboot`, on a drive that `bcdboot` had made. Windows started to its
first-run setup.
2. The example `wim_ntfs` made a whole drive with no program of Windows:
the GPT, the EFI system partition, the boot files, the store and NTFS.
QEMU started the image alone, and Windows came to its first-run setup.
3. `burnout write --to-go --edition 3` wrote Windows 11 25H2 Pro of the
Arm64 ISO to a disk image of 40 GiB, attached with `hdiutil`, in 121 s
with the check. Random bytes filled its first 2 GiB and its last MiB
before the write, as on a used drive. QEMU started it alone, and Windows
came to its first-run setup.
**A BIOS, after version 3.0.0.** `write --to-go --bios` makes the drive for
a BIOS. Windows starts from a BIOS only on an MBR disk, so the table is an
MBR with the boot code of P8, and the FAT32 system partition is active. The
FAT32 code of P8 loads `bootmgr`, so no NTFS boot code is necessary.
1. The reference: in Windows PE, `bcdboot C:\Windows /s S: /f BIOS` wrote
the store and the files for an MBR disk with an active FAT32 partition
at 1 MiB and Windows 11 Pro x64 at 512 MiB. An MBR partition device is
the 88 bytes of a GPT one, with the first byte of the partition at byte
32, the style 1 at byte 52 and the disk signature at byte 56. The
loaders are `.exe` files, the boot manager has no path, and the memory
test is a tool of the boot manager.
2. `burnout_layout::bcd` builds that store. Each object and each element is
the same as the one of `bcdboot`, and a test compares them when the
reference is at hand.
3. `mbr_with` writes an MBR with the boot code of Burnout and any
partitions.
4. `to_go::plan` takes the firmware. For a BIOS it copies
`Windows\Boot\PCAT`, `Fonts` and `Resources` to `\Boot`, with `bootmgr`
and `BOOTNXT` at the root, as `bcdboot` did. The first and the last MiB
of the drive go to zero, so no old GPT stays.
Measured on 2026-11-11: `burnout write --to-go --bios --edition Pro` put
Windows 11 25H2 Pro of the x64 ISO onto a disk image of 40 GiB and checked it
in 124 s. QEMU with SeaBIOS started the image alone as a SATA disk, with
x64 emulated in TCG. The Windows logo came in 30 s, and the first-run setup
in about 37 minutes.
**x64 through UEFI, measured on 2026-11-11.** The example `to_go_image`
wrote Windows 11 25H2 Pro of the x64 ISO into a disk image of 40 GiB. QEMU
with OVMF started it alone as an NVMe disk, with x64 emulated in TCG, and
Windows came to its first-run setup in about 45 minutes. On a PC with
Windows, `burnout write --to-go` of the same edition wrote a VHDX in about
3.5 minutes, and Hyper-V started it in a VM of generation 2 with Secure
Boot on. At 5 minutes Windows answered the heartbeat of Hyper-V; the screen
was not captured.
**On a PC with Windows, measured on 2026-11-11.** Each drive was a VHDX
that `diskpart` attached, and Hyper-V started it in a VM of generation 2
with Secure Boot on, 4 processors and 4 GB.
- `burnout list` showed the VHDX as `Msft Virtual Disk 42.9 GB Virtual`.
Without `--force`, Burnout refused it. With `--force`, it asked for the
model and the size. It then wrote Windows 11 Pro, build 26300.9457: 140,067
files and directories and 15.5 GB of streams. The first-run setup came
within 5 minutes.
- The ISO of the Media Creation Tool for Windows 10 holds `install.esd`.
`burnout write --to-go --edition Pro` refused it with the kind
`lzms_image`, and printed the DISM command for index 6, which is Pro. The
command ran, and `--to-go --edition 1` wrote the WIM file that came out:
101,926 entries and 9.6 GB of streams. Windows 10 came to its first-run
setup within 5 minutes.
- An ESD that DISM made with `/Compress:recovery` went the same way, and
Windows 11 came to its first-run setup.
- Windows mode on a VHDX of 16 GB: 977 files on FAT32 and `install.wim` on
exFAT, checked by SHA-256. Windows 11 Setup started.
- `--to-go --bios` on a VHDX: QEMU with SeaBIOS 1.17.0 started it as a SATA
disk, and Windows ran. As an NVMe disk, SeaBIOS said "could not read the
boot disk". A drive for a BIOS needs a firmware that reads the bus of the
drive, and SeaBIOS does not read NVMe.
- An `install.esd` goes through the export to a WIM file. Burnout does not
read LZMS itself, as P10 says.
- A drive with sectors of 4096 bytes was refused on that day. The next
paragraph but one says what changed.
**One drive for a BIOS and for UEFI, measured on 2026-11-12.** UEFI starts
Windows from an MBR disk, so `--bios` now puts the boot files and the store
for UEFI on partition 1 too, beside those for a BIOS. The store for UEFI
names the partitions of the MBR, as the store for a BIOS does. The example
`to_go_image` wrote Windows 11 25H2 Pro of the x64 ISO into a disk image of
40 GiB: 219 boot files. QEMU with OVMF started one copy of the image as an
NVMe disk, and QEMU with SeaBIOS started another copy as a SATA disk. Each
came to its first-run setup, with x64 emulated in TCG.
**A drive with sectors of 4096 bytes, measured on 2026-11-12.** Windows
Setup 10.0.26100 formatted a disk with sectors of 4096 bytes in a VM, and
its NTFS gave the fields that Burnout now writes on such a drive:
- 4096 bytes in a sector, and 1 sector in a cluster.
- 256 hidden sectors, for a partition at LBA 256.
- The total sectors are 1 less than the sectors of the partition. The
backup boot sector is in the last sector of 4096 bytes.
- A file record is 1024 bytes and an index buffer is 1 cluster. The update
sequence array has 3 entries, at a stride of 512 bytes.
- The GPT has its entries at LBA 2 and its first usable sector at LBA 6.
The example `to_go_image` with `4096` wrote Windows 11 25H2 Pro of the x64
ISO into a disk image of 40 GiB: 136 boot files, written in 63 s and checked
in 102 s. QEMU with OVMF started it as an NVMe disk with
`logical_block_size=4096`, and Windows came to its first-run setup within
20 minutes, with x64 emulated in TCG. A BIOS starts no drive with such
sectors, so `--bios` refuses it with the kind `bios_sector_size`.
---
## P13. A graphical interface
**Size L. Depends on P12. In progress: the spike passed on the three hosts,
and `burnout` has the two changes that it asked for. The person who owns the
project chose it on 2026-11-12, and it left "Later, maybe".**
A program with windows that writes a drive, for a person who does not use a
terminal. It is a second program on the same crates, and it adds no write
mode. The command line stays the reference: each thing that the program does,
`burnout` does too.
### The shape: the program does not write
The program has no privilege, and it does not open a drive for a write. It
starts `burnout write ... --json` as a child with the privilege, reads the
events, and shows them. The confirmation, the refusal of the system disk, the
check of a fixed disk and the check after the write stay in one binary, which
the tests already cover.
- `burnout list --json` gives the drives. It needs no privilege.
- The `confirm` event names the drive and the answer that it `expects`. The
program shows the drive, and the person types that answer. The program
sends it to the child. It never makes the answer itself.
- `start`, `progress` and `done` give the progress bar. `result`, `error`
and `stopped` end the write.
- A cancel sends the child the same signal as Ctrl+C, so the drive ends in
the same state as a stop on the command line.
So the program holds no code that can erase a drive. A fault in it can show
the wrong thing, and it cannot write the wrong thing past the confirmation.
### Scope
In: raw mode and Windows mode, with the choice of the image, the drive and the
edition, the progress, the cancel and the result.
Out of the first release: `--to-go`, `--partition`, `--bios` and the options
of Setup. They stay on the command line, and the program says so.
### Risk first: the privilege on each host
The program cannot ask for a password through `sudo`, because it has no
terminal. Each host needs its own path, and none of the three is measured:
| Host | The path to try first | What can go wrong |
| --- | --- | --- |
| macOS | `authopen` | `authopen` gives a file descriptor, so `burnout` must take a drive that is already open. A helper through `SMAppService` needs a signed app, and decision 2 below rules it out. |
| Windows | `ShellExecuteEx` with `runas`, which shows the UAC prompt | A child started that way has no pipe for its output, so the events need a named pipe or a file. |
| Linux | `pkexec burnout write ...` | `pkexec` passes the output through. A desktop with no polkit agent cannot ask. |
**macOS, measured on 2026-11-12.** A process with no root started
`/usr/libexec/authopen -stdoutpipe -o 2 /dev/rdiskN` on a socket pair, and
got a file descriptor for read and write back through `SCM_RIGHTS`.
- On a USB stick of 125.8 GB that root owns, a plain open was refused.
`authopen` showed the dialog of macOS, the person typed the password, and
the process wrote a sector back unchanged through the descriptor.
- While a volume of the stick was mounted, the person authorized the open and
`authopen` still gave no descriptor. After an unmount it gave one in 2.5 s
with no second dialog, because macOS keeps the right for a short time. So
`burnout` unmounts first, and asks `authopen` after that.
- On a disk image that the person attached, `authopen` gave the descriptor
with no dialog.
So on macOS `burnout` itself can ask `authopen` for the drive, in the place
of a restart through `sudo`. The program then starts `burnout` with no
privilege, and macOS asks for the password in its own dialog.
**Linux, measured on 2026-11-12** in the Fedora 44 live VM (aarch64,
GNOME), on a disk image of 300 MiB that QEMU gave as a USB disk.
- `burnout write --json` with no privilege stopped with the kind
`needs_privilege`, and wrote nothing.
- `pkexec burnout write ... --json` showed the dialog of GNOME, and the
person of the session authenticated in it. `pkexec` passed the input and
the output through. All 11 events came as lines, and the exit code was 0.
Burnout wrote 8 MiB and checked it byte for byte.
- The live system does not say which disk it starts from, so the `confirm`
event asked for the model and the size, and a plain `yes` was refused with
`not_confirmed`. The program must send the answer that the event names in
`expects`, after the person types it.
**Windows, measured on 2026-11-12** in the Windows 11 VM (Arm64), on a disk
image of 280 MiB that QEMU gave as a USB disk. A test program with no
privilege made a named pipe with `PIPE_REJECT_REMOTE_CLIENTS`, and started
itself again through `ShellExecuteEx` with `runas` and
`SEE_MASK_NOCLOSEPROCESS`.
- UAC showed its prompt, with "unknown publisher" for the program that no
certificate signs. The account was an administrator, so the prompt asked
for a yes and no password.
- The elevated child opened the pipe, found the one drive of 280 MiB, and
wrote a sector of it back unchanged through `\\.\PhysicalDrive2`.
- Its lines came through the pipe as it wrote them, one second apart. Its
exit code came to the parent through the handle of the process.
- A program that the MSVC runtime does not link in stopped with
`0xC0000135`, a DLL not found. The release links it in, so the program must
do the same.
So on Windows `burnout` needs one change: an option that names a pipe for
the events, because a child that UAC starts has no output of its own.
So the first step is a spike, as P0 was. On each host it starts `burnout
list --json` and then a write to a disk image with the privilege, from a
program that a person opens with a double-click, and records what works. The
spike can change `burnout`, for example with an option for a named pipe. Do
not write the windows before the spike passes on all three hosts.
**The two changes to `burnout`, made on 2026-11-12.**
- macOS: with no terminal, `write` asks `/usr/libexec/authopen` for the drive
after the unmount, in the place of a restart through `sudo`. Measured on a
disk image of 64 MiB with its write bit taken away, so that a plain open
was refused. `burnout write --json` ran with no terminal, macOS showed its
dialog, and the person typed the password. The dialog took 32 s. Then
`burnout` wrote 8 MiB through the descriptor, checked it byte for byte,
and exited with 0. `--partition` reads the table of the drive before it
asks, so with no terminal it stops and says to use a terminal. The unmount
of a volume that root mounted is not measured with a USB stick yet:
`DADiskUnmount` with no root answered `0xf8da0009` for such a volume.
- Windows: `write --json --pipe NAME` uses `\\.\pipe\NAME.out` for its events
and `\\.\pipe\NAME.in` for its answer. Measured in the Windows 11 VM
(Arm64) on a disk image of 400 MiB that QEMU gave as a USB disk. A test
program with no privilege made the two pipes, started `burnout` through
UAC, and sent the answer that the `confirm` event named. `burnout` wrote
200 MiB, checked it, and exited with 0 after 13.3 s, and each event came
through the pipe as it happened. In a second run the program wrote `stop`
at the first progress of the write. `burnout` sent `stopped` with
`reached` `writing`, and exited with 130. A UAC prompt that nobody answers
closes after about 2 minutes, and `ShellExecuteEx` then fails with 1223,
the error of a cancel. The program shows that as a cancel.
**The write from the program, measured on 2026-11-13.** Each run wrote the
same image of 200 MiB to a disk image of 400 MiB, through the windows of
`burnout-gui`, and each drive held the SHA-256 of the image after it.
- macOS: the person chose the image and the drive. `burnout` showed the
confirmation, macOS asked for the drive in its dialog, and the person gave
a fingerprint. The program showed the write, the check and the eject.
- Linux, in the Fedora 44 live VM: pkexec showed the dialog of polkit for
`burnout write ... --json --stop-on-input`. The live system does not name
its system disk, so the program asked for the model and the size, and
`burnout` took them. The binary was built on the Mac with `cargo zigbuild`
and the `libfontconfig.so` of the Fedora package.
- Windows, in the Windows 11 VM: the program started `burnout` through UAC.
Nobody answered the first prompt, and after about 2 minutes the program
showed "Cancelled". On a later run the person answered yes, and the
confirmation, the progress and the result came through the two pipes.
- The table of drives had no action of accessibility that selects a row. A
list of its own replaced it: each row is a list item with a label and a
default action that selects it, and the arrow keys move the selection.
Measured on macOS through the accessibility interface.
- The window draws no picture for a capture of macOS while it renders through
OpenGL. The software renderer of Slint draws one, so a test sets
`SLINT_BACKEND=winit-software`.
**The release.** Each release builds `burnout-gui` for the six hosts beside
`burnout`. On Linux it builds against glibc on Ubuntu 22.04, because a static
binary cannot load the libraries of a desktop. The tap, the bucket and winget
get a package of their own for it, which depends on the package of `burnout`.
[releasing.md](releasing.md) has the steps. The macOS package is a command and
not an app bundle, so the first release opens it from a terminal or from a
link that a person makes.
### Decisions, made on 2026-11-12
1. **The toolkit is Slint.** It is native Rust, it runs on the three hosts,
and its binaries are small. Its free licence for a desktop program asks
for an attribution in the program, so the program shows it. Read the
licence again before the first release.
2. **No code signing.** "Version 1 buys no certificate" stays. The program
ships through Homebrew, Scoop and winget, as `burnout` does, and the
release documents the warning for a download in a browser. So a helper
through `SMAppService` is out, because it needs a Developer ID. The spike
on macOS tries `authopen` first. It also checks whether a Homebrew cask
sets the quarantine mark on the app.
3. **A package of its own.** The program is the crate `burnout-gui` in this
workspace, with the binary `burnout-gui`. It goes out in the same release
as `burnout`, with the same version. Its formula, its Scoop manifest and
its winget package depend on the package of `burnout`, so the package of
`burnout` does not change and a person who uses the command line gets no
more than before. The program finds `burnout` beside itself or on the
path, and refuses a `burnout` of another version, because the events of
`--json` are the contract between the two.
### The exit test
On macOS, on Windows and on Linux, a person opens the program with a
double-click, and not from a terminal:
- The system disk is not in the list, or it is shown and cannot be chosen.
- A fixed disk needs its model and its size typed back, as on the command
line.
- The program writes a Linux ISO and a Windows 11 ISO to a USB drive, and each
drive starts on a PC.
- A cancel during the write stops the child, and the program shows the state
of the drive that `burnout` reports.
- The program starts after the download path that the release documents.
---
## Later, maybe
Not planned. Each one changes what Burnout is, so it needs a phase of its own
in this roadmap before work starts. The person who owns the project moved them
here from "out for good" on 2026-11-11. The sizes are estimates from the code
as it stands, and nothing measured them.
| Feature | Size | What it costs |
| --- | --- | --- |
| A drive that holds many images | XL | A boot menu that loads an ISO from a data partition, for BIOS and for UEFI, with Secure Boot. Much of what such a tool gives comes from years of fixes for one ISO after another. |
| macOS install media | XL | Apple ships no ISO, and `createinstallmedia` runs on macOS only. Burnout would build the installer from the packages that Apple ships, in a format that Apple does not document and changes each year. |
A write to one partition left this list as P9, and a graphical interface
left it as P13.
---
## The decisions that were open
All four are settled. The reasons are here so that a later reader can reopen
one with an argument rather than a preference.
### A fixed disk can be a target, and it costs two steps
Every drive in a desktop computer reports as fixed, so a refusal by that test
alone stops somebody writing an internal disk on purpose.
An easy yes stops nobody writing the wrong one by accident.
So `--force` allows a fixed disk, **and the person types the model and the
size of the drive back before the write starts**.
Not a letter, and not the word yes.
A prompt that takes one keystroke is a prompt that people learn to answer
without reading.
**The system disk is refused under every flag.** There is no escape for it,
and that is what [SECURITY.md](../SECURITY.md) already promises.
### Burnout reads UDF itself
A Windows ISO keeps `install.wim` in UDF, because ISO 9660 holds an extent
length in 32 bits and cannot address a file of 4 GiB or more.
[The spike](spike-layout.md) measured both facts.
Burnout gets a read-only UDF reader, scoped to what a Windows ISO uses: the
anchor descriptor, the logical volume and partition descriptors, the file set,
file entries, directory descriptors, and plain extents.
No compression, no encryption, and no write path.
Three reasons. It keeps the rule that Burnout never delegates to the host, so
one ISO reads the same way on three operating systems. ECMA-167 and the UDF
specification are public, so this is documented work. And it runs against a
file, so every test of it obeys the rule that no test opens a device.
Read the licence and the coverage of any crate before counting on it, but do
not plan around one.
**The fallback stays on the shelf:** take an extracted folder instead of an
ISO. It is honest and nearly free, and it makes the tool worse at the one
thing it exists to do.
### A crate and a tap now, and winget and Scoop at version 1
From v0.3, Burnout reaches people in three ways.
- **The binaries of the release.** Six binaries, `SHA256SUMS` and an
attestation, as [releasing.md](releasing.md) says.
- **crates.io.** `cargo install burnout` builds on the machine, so nothing
carries the quarantine mark. The four crates go up in the order of their
dependencies: `burnout-core`, `burnout-iso`, `burnout-layout`, and then
`burnout`. The three libraries go up only because the binary needs them,
and their interface is not stable. A version on crates.io can be yanked,
and never deleted.
- **A Homebrew tap of the project.** `brew install stiven-gjekaj/tap/burnout`
installs the binary of the release, for macOS on each chip and for Linux.
Homebrew downloads with curl, so the Gatekeeper warning never shows.
homebrew-core asks for a project that people already know, and this one is
not known yet.
Two rules hold for all of them.
- **Nothing goes out before a person publishes the draft.** After that, a
person publishes the crates from a clean checkout of the tag, on a machine
where `cargo login` holds the token. No token of crates.io is stored on
GitHub.
- **A person writes each commit.** No bot pushes to the tap. After the
release, a script writes the formula from the `SHA256SUMS` of the release,
and a person commits it.
winget and Scoop wait for version 1. Both download with no Mark of the Web,
so SmartScreen shows no warning, as Homebrew shows no Gatekeeper warning.
They wait because Rufus already serves Windows, and the people who need
Burnout most are on macOS and on Linux. homebrew-core, the AUR, COPR and Nix
wait for users. The static binaries already run on any Linux.
### Version 1 buys no certificate
A code signing certificate matters for a binary that somebody **downloads**,
not one that a package manager installs.
- macOS applies Gatekeeper to a file that carries `com.apple.quarantine`,
which a browser sets. Homebrew fetches with curl and does not set it.
`cargo install` compiles on the machine, so there is nothing to quarantine.
- Windows SmartScreen keys off the Mark of the Web, which a browser sets.
- Linux never expected it. A distribution signs with its own key.
Apple silicon does need every binary to carry a signature, and an ad hoc one
counts. The Rust linker applies that already.
So the path that a certificate would help is one person downloading a built
binary from a release page in a browser. That is real, and it is not worth
several hundred a year for a project with no users yet.
**Instead, every release carries build provenance.**
`actions/attest-build-provenance` signs each artifact through Sigstore, and
anybody can check it with `gh attestation verify`.
A certificate proves that somebody paid a fee.
An attestation proves that this binary came from this commit through this
workflow, which is the stronger claim for a tool that asks for root.
Publish a SHA256 for each artifact as well, and document the warning and the
way past it for anybody who downloads one directly.
---
## What version 1 is not
Legacy BIOS boot, Windows To Go, a drive that holds many images, a write to a
single partition, a graphical interface, and macOS install media.
[The milestones](milestones.md) say why for each one.
Legacy BIOS boot is now P8, a write to one partition is P9, and Windows To Go
is P10 to P12. The other three are in [Later, maybe](#later-maybe).