-
Notifications
You must be signed in to change notification settings - Fork 8
Thistle Boot ROM Manual
The Thistle boot ROM is an environment for live-writing 6502 programs that isn't as painful as trying to type them in as hex dumps, and does not require using any external programs, though is arguably more painful than writing them using an external assembler.
If any unmanaged disk is present, it will boot from that.
If managed disks are present, for each, it attempts to load and run a file called "Thistle/boot" or "Thistle" (checked in that order), which contains raw assembled 6502 code, at $0200.
If it hasn't managed to boot anything, it provides a prompt.
The prompt maintains a current "writing pointer", shown as $0200 > on startup.
(If reading the boot ROM, see the label commands.)
Typing a 6502 instruction (such as LDA #$00) writes it and advances the writing pointer.
The commands the boot ROM does provide allow for loading and saving memory.
These operate on the last filesystem shown in the "Checking filesystems..." display.
ls/list [dir]: Lists the contents of a directory (if not provided, the root) of the first filesystem.
load [name]: Loads a file and resets the writing pointer to $0200.
save [name]: Saves a file with a given name based on memory content up to the writing pointer.
run: Runs the code at $0200.
In later versions of the boot ROM (>= aeb675b), additional commands are available:
fs [uuid]: Sets the filesystem. Useful if the default filesystem is incorrect (for example, tmpfs). The UUID must be written in full.
at [addr]: Sets the writing pointer. For example, at 0200 returns the prompt to showing $0200 >.
db [byte]: Writes a byte as-is. For example, db 60 is equivalent to RTS.
(Note that in versions of the boot ROM before this, it's not possible to move the writing pointer arbitrarily without modifying the boot ROM directly or writing a sequence of instructions first to add commands.)
Entering the following into the prompt on startup (i.e. when $0200 > is shown) will write 'A' on the terminal.
LDA #$41
STA $E003
LDA #$0A
STA $E003
RTS
run
Commented, the code is:
LDA #$41 ; 'A'
STA $E003 ; E003 is the terminal output (see General IO)
LDA #$0A ; newline
STA $E003
RTS
Relative branch instructions are based around relative offsets.
The assembler can't translate these from absolute addresses automatically.
Instead, the instruction formats used for these are of the form 0x?? / -0x??. These contain the offset in hexadecimal (positive and negative respectively, though a positive offset above 0x7F overflows to a negative offset, and a negative offset above 0x80 underflows to a positive offset)
For example, 0x05 (skip forward 5 bytes after the end of the instruction), and -0x05 (skip backwards 5 bytes before the end - yes, the end - of the instruction).
So BRA -0x02 is an infinite loop with no instructions in the middle.