Re: Build failures for Atari ramdisk images

[Izumi Tsutsui <tsutsui%ceres.dti.ne.jp@localhost>]

Just FYI, here is a dumb README.md (draft) "to prepare ustarfs based
bootable floppies for NetBSD/atari" (assisted by ChatGPT 5):

---

# README - TT030 TOS Floppy Boot (for NetBSD/atari boot)

This note explains how the Atari TT030 TOS (Atari native OS on the ROM)
decides to boot from a floppy, and what a floppy must contain to be
considered "bootable" by TOS.

This note is written for people maintaining the NetBSD/atari boot code
(e.g., `sys/arch/atari/stand/xxboot` and friends).

---

## 1) How the TT030 ROM TOS boots from a floppy

### What "bootable" means to TOS

* On cold boot, TOS selects a boot device (floppy, hard disk, etc.) and
  examines sector 0 (the boot sector).
* If the boot sector passes TOS's "executable boot sector" test,
  TOS jumps to the 680x0 code in that sector.
* If it does not pass, TOS continues to start the TOS desktop
  (and/or checks other devices depending on setup).

### The executable-boot-sector test (TOS convention)

* Size: exactly 512 bytes (one sector).
* CPU code: starts with valid 68k instructions
  (conventionally a short `BRA` at offset 0).
* Checksum rule: interpret the entire sector as 256 big-endian 16-bit words;
  the uint16_t sum of all words (including the checksum word itself)
  must equal `0x1234`.
  The usual practice is to compute the sum over the first 255 words and
  choose the last word so the final sum becomes `0x1234`.
  https://github.com/NetBSD/src/blob/edfd29f0/sys/arch/atari/stand/installboot/installboot.c#L520-L530

### Operator actions & machine settings that affect boot

* Keyboard override: On many TOS 2.x/3.x systems (including TT030),
  holding `Alt` during reset/power-on suppresses hard-disk autoboot
  and lets TOS try the floppy first.
  (Exact behavior can vary with the installed HDD driver;
   `Alt` is the commonly used "prefer floppy" hint.)
* NVRAM boot preference (TT030 only): The TT has NVRAM that can bias
  which device class TOS prefers first (floppy vs. SCSI/ACSI).
  If floppy boot appears to be skipped, check NVRAM settings.
  The `Alt` override typically still forces a floppy probe.

---

## 2) Making a floppy "bootable" for TOS

### A. Stock TOS method: place an auto-executed boot sector

At minimum you must provide a TOS-style executable boot sector in
sector 0. From there, your sector-0 code may use BIOS/XBIOS to load
more sectors and continue your own bootstrap (NetBSD's approach).

#### TOS boot sector content (sector 0)

* 680x0 code, typically beginning with a short branch (`BRA`) to
  your real entry (`main`).
* Optional fake BPB area: TOS will tolerate arbitrary bytes following
  the branch; you don't need a valid FAT BPB if your code doesn't
  rely on GEMDOS. NetBSD's tiny loaders deliberately fill those bytes
  so TOS won't try to mount it as a normal filesystem.
* Checksum word at the end adjusted so the 16-bit sum is `0x1234`
  (see above).

Your boot sector code may (and in NetBSD's case does) call BIOS
(`trap #13`) and XBIOS (`trap #14`) services - for floppies the
relevant call is `Floprd` - to pull additional sectors into RAM.

#### NetBSD/atari's floppy boot layout (what our code expects)

NetBSD/atari uses a fixed 8 KB "boot block" immediately at the
start of the disk (as other ports); TOS executes sector 0
(our 1st-stage), which then reads the remaining part of this block
and chains to the 2nd-stage.

```
LBA 0   ( 512 B):   1st-stage floppy loader = fdboot (TOS boot sector)
LBA 1..2 (1024 B)   4 byte magic `NBDAMAGIC` (NBDA) or `AHDIMAGIC` (AHDI)
                     + 1020 byte disklabel (see <machine/disklabel.h>)
LBA 3..15 (6656 B)  2nd-stage loader (bootxx)
LBA 16+             Free for filesystems or data
```

* `fdboot` (1st-stage) lives entirely in sector 0, satisfies
  the TOS checksum rule, and:

  * probes the floppy geometry (sectors/track * sides),
  * reads LBA 1..15 via XBIOS `Floprd` into RAM,
  * jumps into the 2nd stage (`bootxx`) and passes it three parameters:

    1. a function pointer for sector reads (`readsector`),
    2. pointer to the disklabel area (if relevant),
    3. an autoboot flag. (determined by pressed keys)

* `bootxx` (2nd stage) then interprets whatever filesystem it supports 
  (traditionally ffsv1 on atari), finds `/boot` (the 3rd stage, `bootxxx`)
  and chains to it. From there `bootxxx` loads the kernel.

* Notes for maintainers:

  * The 8 KB split and symbol offsets are defined in the `xxboot` headers;
    the 2nd-stage start offset and label location are fixed so `fdboot`
    and `bootxx` agree on where to find each other.
  * The sector size is 512 bytes; code assumes big-endian 16-bit
    arithmetic for the TOS checksum.
  * For diagnostics, `fdboot` uses BIOS console calls (`Bconout`, `Bconin`)
    to print short messages and to pause on error.

---

(but there are many other work, of course)

---
Izumi Tsutsui