OS 3.2 Boot Process¶

In AmigaOS 3.2 the boot shell no longer finishes building the system. A separate ROM module, system-startup (formerly wbfind, then bootstrap), takes over as soon as dos.library has initialised itself: it mounts the boot partitions, starts the file systems, replaces ROM modules with newer disk-based ones, optionally starts the syslog module, and only then launches the boot shell. The boot menu and syscheck set flags that control this process, and SetPatch still runs from the Startup-Sequence to repair what can only be fixed at run time.

This article follows the boot sequence from a developer's point of view, using the NDK 3.2 release notes and the system-startup and syslog autodocs. The step-by-step list of what system-startup does is in the system-startup reference and in AmigaDOS Library Internals; this page explains the history, the rules and the consequences for programs.

From dos.library to system-startup¶

dos.library version	Change (DOS-RelNotes)
47.5	"In case the dos.library finds the bootstrap module, it will start this instead of the shell, and it does not attempt to find any other modules then. Creating the runtime environment is then up to bootstrap."
47.8	`CliInitNewCli()` and `CliInit()` end in a dead-end alert. "The dos.library init code no longer falls back to the legacy init method, it requires now system-startup to take over."
47.9	"The dos.library startup code no longer mounts the boot point mounts from expansion. This is now handed over to system-startup." dos requesters open intuition.library instead of using the copy in the GlobVec, "This allows easier relocation of Intuition."

The shell start-up protocol is now reduced to CliInitRun(). The bootstrap 47.1 note puts it this way: "all what is left is CliInitRun(), making shell design by about 67% easier as there is no longer a need to check the packet type and dispatch according to the flags in the startup packet." The boot shell is started with System(), which since dos 47.3 can create a new shell from a command stream (SYS_CmdStream, SYS_Asynch).

The module's history¶

Release	Name	Role
3.1.4, 45.2	`wbfind`	"a short workbench loader that can go into ROM": a bogus library that loads the real workbench.library/icon.library from `LIBS:` or any inserted disk. Unlike the A4000T module it does not patch `OpenLibrary()`.
45.3–45.5	`wbfind`	Checks that candidate segments are resident modules of an acceptable version; shows a volume requester if none is found (suppressed for `LIBS:` to avoid endless requesters; honours `pr_WindowPtr`).
3.2, 47.1	`bootstrap`	Adds "loader hooks" for `audio.device`, `mathffp.library` and `mathieeesingbas.library`. Started by dos instead of the boot shell. Uses disk-based `L:Ram-Handler`, `L:Con-Handler` and `L:Shell-Seg` instead of the ROM versions.
47.6	`system-startup`	Renamed. Searches `LIBS:` and `DEVS:` for devices not yet initialised and replaces the ROM versions.
47.7		Mounting the devices from the expansion boot-point list moved here.
47.8–47.11		Hot-patching of intuition; module upgrade rules (below).
47.12		Creates the entry for `PIPE:`.
47.13		Honours expansion flags that disable module upgrades, shell debug and interactive shell.
47.14		syslog support.
47.21		Failsafe boot flag: boots `:S/Startup-Failsafe` instead of `:S/Startup-Sequence`.

Requirements for replaceable handlers¶

L:Ram-Handler, L:Con-Handler and L:Shell-Seg are only used if they are modules: "all three require a 'resident' structure, i.e. they need to be a 'module' in addition to a 'handler'." To please Version, bootstrap 47.2 creates a $VER: tag in the dummy startup segment of loaded modules. The aux-handler stub (47.2) finds the con-handler segment on the dos resident list "where it is always put", because the con-handler is not necessarily a resident module any more.

ROM-Updates: replacing modules from disk¶

The rules accumulated in the system-startup release notes and autodoc:

Rule	Source
A ROM module is replaced only by a disk version with a strictly larger version: "A ROM revision can only be replaced by a RAM version larger than the ROM version, similar to LoadModule."	47.10
`intuition` is the exception: it may be downgraded to V40. A V40 intuition is only loaded from the boot volume; upgrades are searched on all volumes.	47.10, 47.17
All volumes are scanned, not only the boot volume.	47.15
A dummy file (e.g. an empty file) of the right name in the right place on the boot volume prevents the upgrade.	47.18
ROM modules already present are optional: no requester if no update is found.	47.16
Module updates are disabled when booting without Startup-Sequence, "probably helpful for desaster recovery in case one of the modules runs berzerk".	47.8
The boot menu can disable ROM-Updates through a flag in `ExpansionBase`.	autodoc
A later FFS found on disk also replaces the root file system. The autodoc adds that the file system is upgraded from the RDB, "not upgraded from file".	47.3, autodoc

The autodoc lists the upgradable modules: filesystem (from the RDB), con-handler, ram-handler, shell/BootShell/CLI (L:Shell-Seg), intuition, console.device, gadtools.library, syslog, mathffp.library, mathieeesingbas.library, audio.device, and workbench/icon.library. See the system-startup reference for the table.

Hot-patching intuition¶

system-startup 47.8 added "a logic to hotpatch a new intuition version into the system". Conditions and mechanics from 47.8–47.12:

It "depends on no other module having opened intuition as well, and no BCPL file handler being mounted."
Because intuition overrides the default monitor from graphics, the monitor is saved first, intuition is opened, and then intuition may be "enlightened" (the viewport patched to enable the new graphics modes). The boot menu 47.1 opens intuition only if its GUI is needed, so this "may have to be delayed up to system-startup".
"The LVOs of the dead copy of intuition are now replaced to jump to a function that displays an Alert."
47.9 removes the loaded intuition with Expunge() so a V47+ intuition can be replaced by V40. 47.12 restores the open count if a V40 intuition could not be removed.

Consequences for code that runs before or during boot (file systems, handlers, boot-time resident modules):

Do not cache IntuitionBase from an early OpenLibrary(); dos.library itself stopped doing so in 47.9.
A BCPL-style handler mounted early blocks the intuition upgrade.

Boot flags¶

system-startup reads flags left in ExpansionBase by the boot menu. The public libraries/expansionbase.h only defines the classic Flags bits (EBF_CLOGGED, EBF_SHORTMEM, EBF_BADMEM, EBF_DOSFLAG, EBF_KICKBACK33, EBF_KICKBACK36, EBF_SILENTSTART, EBF_START_CC0); the V47 boot flags are not part of the public includes. What the notes and autodoc describe:

Flag (boot menu)	Effect in system-startup
Disable module upgrades	ROM-Updates skipped
Shell debug	`debug` shell variable set; with syslog, boot shell activity is logged
Interactive shell	`interactive` shell variable set
System log / Debug	syslog module loaded and initialised
Silent start (`EBF_SILENTSTART`)	Boot console not forced open; it opens on first output
Failsafe	Boots `:S/Startup-Failsafe` instead of `:S/Startup-Sequence`

The shell's debug variable "pushes executed commands through the serial output" (shell 47.23); interactive single-steps scripts. Both are described in The AmigaDOS Shell.

Changes to the boot menu relevant to developers:

Version	Change
45.1	All models get a diagnostic screen; AA models get DblPAL/DblNTSC monitors in the VGA-only variant; syscheck factored out.
45.2	Dbl modes only with a HIRES Denise or better ("a HIRES Agnus is not good enough by itself"). The default monitor is set only if it can be made available.
45.4	Dbl modes removed for ECS ("ECS cannot display a 640x200/640x256 screen in 31kHz").
45.6	Boards shut up by autoconfig are listed as "disabled", not "defective"; the menu appears (grey, not red) when boards were disabled for lack of autoconfig space.
47.1	Opens intuition only when the GUI is needed.
47.3	Wakes up input.device itself so it can read qualifiers (the boot order changed).
47.4	Additional boot flags; either ALT key enables debugging of the boot shell.
47.5	GUI and options to enable the system log.
47.6–47.7	Expansion Board Diagnostic page shows board address, size and type columns.
47.8	Failsafe boot flag.
47.9–47.11	Keyboard shortcuts for sub-pages and boot device selection; main page shows the Kickstart release version and the soft-kicked exec version, if present.

syscheck¶

syscheck "still depends on the bootmenu" but is a separate module "that (of course) just calls into the bootmenu with appropriate options" (45.1). It is the screen that appears when expansion boards had to be shut up; 47.1 is a version bump only.

syslog¶

syslog (47.1) is "a simple system logger writing serial output to RAM:syslog. It is triggered by System-Startup by a flag that is set by the boot menu." From the autodoc:

It is a ROM module activated "whenever the user selects the Debug option in the boot menu".
It collects "information that would otherwise go through the serial port at 9600-8N1". Many debugging tools use this serial protocol, so their output ends up in RAM:syslog too.
System-Startup also sets $DEBUG to 1, so boot shell activity is logged.
RAM:syslog "is opened only when extending the log"; it can be deleted and is re-created when new data arrives.

For a developer this means serial debug output from drivers and handlers can be read back after boot without a serial cable: select Debug in the boot menu, boot, and inspect RAM:syslog. See Amiga Debugging Tools.

SetPatch¶

SetPatch still runs early in the Startup-Sequence. Its 3.1.4/3.2 release notes show which jobs moved elsewhere and which patches remain.

Options¶

Option	Since	Effect
`CONTENTS/S`	47.4	List all patches contained in this SetPatch release.

SetPatch 45.25 added "an option to turn off the patch that disables the drive LED patch"; the release note does not name the keyword.

What SetPatch no longer does¶

Removed	Replacement given in the notes
NSDPatch	Not needed for working devices; FFS gained TD64 support instead. NSDPatch is available separately on Aminet.
ROMUpdates	"users replace it by a separate invocation by `LoadModule AUTO`, or by a custom ROM." In 3.2, system-startup's ROM-Updates covers module replacement.
Shell-Seg replacement by a V47+ shell	47.3: "no longer replaced by a V47 or later shell because this requires a later dos.library anyhow."

CPU and math libraries¶

SetPatch first tries to load 680x0.library, "the generic CPU dispatcher"; if it is already loaded, the CPU-specific libraries are not started (45.2, 45.3). On a 68020 it also looks for 68020.library.
With a 68060 but no 68060.library, SetPatch fixes UMult64/SMult64 of utility V40 so that Workbench runs (45.10). UMult64/SMult64 are patched after a test of the function result (45.8).
With a 68040 or 68060, math libraries older than V45 are removed so they re-run FPU detection; the matching trans library is removed together with its core library (45.11, 45.12).
AFF_FPGA (exec/execbase.h, bit 10 of AttnFlags) is honoured (47.2), "there is currently no CPU support library for this flag."
Patch for mathieeesingbas.library V37–40, originating from OS 3.5 (47.4).

Other patches and fixes listed in the notes¶

Area	Patch
graphics	`Draw()` FRST_DOT handling with partially obscured lines; `BltMaskBitMapRastPort()` (minterms fixed in 45.9); `EraseRect()`
cardres	`CardForceChange()`
exec	Alert 0x0100000f (bad memory release in pools: a register not restored); kickstart software version adjusted for a LoadModule'd exec; `AllocEntry()` workaround for programs that test the result for NULL instead of negative (47.1)
dos	`ExAll()` did not load A2 with the file system task before `ErrorReport` (45.13); handler stack check now treats BCPL handler stacks (Port-Handler) as LONGs (45.19)
expansion	A3000 superkickstart: code that wrongly assumed an active 030 MMU stole 512K, "rendering LoadModule and other reset-resident programs useless"; the patch hooks the reset process and restores the missing modules and memory (45.22, 45.23)
scsi.device	Experimental DASP-driven drive LED (45.6)
audio.device	A newer `audio.device` in `DEVS:` is loaded (45.16)
Shell	A newer shell in `L:` replaces Shell, CLI and the boot shell, and the dos root node pointers are adjusted (45.16, 45.17, 45.24)

If SetPatch itself fails, "the current shell needs to be shut down hard to stop it from executing the rest of the startup-sequence" (45.21).

Developer checklist¶

Handlers that should be replaceable from L: need a Resident structure.
Don't cache IntuitionBase in code that starts before the Startup-Sequence; system-startup may expunge and replace intuition.
Avoid BCPL-style handlers in the boot path: they block the intuition upgrade, and their stack is counted in LONGs.
To stop a specific module from being upgraded on a system, place an empty file of the module's name in its location on the boot volume.
For boot-time diagnostics, enable the system log in the boot menu and read RAM:syslog.
Use CliInitRun()-based shell start-up only; CliInit() and CliInitNewCli() alert in V47.

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search