From e71c23da39dfddf2ab12139b8a0a68f9ca64f388 Mon Sep 17 00:00:00 2001 From: Gale Faraday Date: Sun, 19 Oct 2025 19:10:02 -0500 Subject: [PATCH] docs(bios): revised manual to cover all firmware topics --- docs/{buzbee.typ => firmware.typ} | 470 +++++++++++++++--------------- makefile | 2 +- 2 files changed, 243 insertions(+), 229 deletions(-) rename docs/{buzbee.typ => firmware.typ} (75%) diff --git a/docs/buzbee.typ b/docs/firmware.typ similarity index 75% rename from docs/buzbee.typ rename to docs/firmware.typ index 5d8896a..4a8e0a2 100644 --- a/docs/buzbee.typ +++ b/docs/firmware.typ @@ -1,26 +1,22 @@ #set document( - title: "BUZBEE Manual", + title: "CHIBI PC-09 Firmware Manual", author: "Gale Faraday", - description: "CHIBI PC-09 machine language monitor BUZBEE technical and user manual", + description: "CHIBI PC-09 Firmware: BIOS, CHIBIO, and BUZBEE documentation", ) #import "style.typ": conf #show: conf.with( - title: [BUZBEE User Manual and Technical Reference], - subtitle: [A CHIBI PC-09 Machine Language Monitor], + title: [CHIBI PC-09 Firmware Manual and Technical Reference], + subtitle: [A Complete Firmware Package for the CHIBI PC-09], author: [Gale Faraday], ) = Introduction -BUZBEE is a "machine language monitor" styled after Steve Wozniak's WOZMON for -the CHIBI PC-09 hobby computer platform. It is the stock bootloader and -interface for the PC-09. This manual goes over the usage of BUZBEE, and some of -the technical internals of how it works and how to hack on it. - -BUZBEE was created primarily to debug prototype versions of the CHIBI PC-09. -BUZBEE will grow alongside the CHIBI PC-09 project. It also functions as a -reference implementation of an OS using the CHIBI PC-09 BIOS. +This is the complete, stock firmware package for Amber Zeller's CHIBI PC-09 +hobby computer. Featuring Gale Faraday's BUZBEE machine language monitor +(@bb-intro), the CHIBI/O BIOS interface (@chibio-intro), and several inbuilt +programs (@programs). The CHIBI PC-09 name and platform is copyright 2024-2025 Amber Zeller. The CHIBI PC-09 BIOS is copyright 2024-2025 Gale Faraday and Amber Zeller. BUZBEE is @@ -29,220 +25,6 @@ MIT license. #pagebreak() -= BUZBEE Functions - -BUZBEE is at its core a chain loader or bootloader. This means that most of the -functionality of the CHIBI starts with using BUZBEE. BUZBEE functions are broken -into two categories: _Internal Functions_ or "IFs" defined in @if-top, and -_External Functions_ or "EFs" in @ef-top. IFs are native routines mapped to -textual commands entered at the BUZBEE prompt. EFs are native routines called -through IFs. EFs can either be any user supplied code, or one of a set of -routines in the BIOS/BUZBEE ROM or "firmware". - -#pagebreak() - -== Internal Functions (IFs) - -Internal Functions are the textual commands that BUZBEE interprets from the -command line to execute the user's wish. Internal Functions are canonically -listed in alphabetical order. Below in @if-table is a list of available IFs. - -#figure( - table( - columns: (auto, auto, 1fr), - inset: 10pt, - align: center, - fill: (_, y) => - if calc.odd(y) { luma(250) } - else { white }, - table.header( - [*Name* (pg. no.)], [*Command Token*], [*Description*] - ), - [`CALL` (#ref(, form: "page"))], - [`$00`], - [Call a resident routine in the MPU's address space.], - [`HELP` (#ref(, form: "page"))], - [`$01`], - [Display a summary of known commands.], - [`PEEK` (#ref(, form: "page"))], - [`$02`], - [Dumps memory from the MPU's address space to the terminal.], - [`POKE` (#ref(, form: "page"))], - [`$03`], - [Overwrites memory in the MPU's address space.], - [`SREC` (#ref(, form: "page"))], - [`$04`], - [Switches into Motorola S-Record receive mode.], - ), - caption: [Table of IFs], -) - -In the following pages these IFs are described in specific. - -IFs are tokenized from their textual form into a binary "bytecode" form. This -bytecode is described in @internals. - -First the text command name (eg. `CALL`) is hashed in some way into a token. -Then conditional processing on the remainder of the line occurs. Values given in -hex are encoded as their corresponding bytes directly. The token buffer -mechanics are described more in @internals. Subcommands are also hashed into -tokens. - -#pagebreak() - -// Function for creating IF page headers -#let _ifpagehead( - desc: none, - syntax: none, - params: (), -) = { - smallcaps[#desc] - parbreak() - [Syntax: #syntax] - parbreak() - [Parameters: ] - if params.len() > 0 { - for (param, desc) in params [ - - #raw("<" + upper(param) + ">"): #desc - ] - } else { - text(style: "italic")[N/A] - } -} - -=== IF: `CALL` - -#_ifpagehead( - desc: "Calls a resident routine in the MPU's address space.", - syntax: [`CALL `], - params: ( - ptr: "An absolute pointer to a position in the 6309 MPU's memory map.", - ), -) - -Call takes an absolute pointer into the MPU's address space to call as if it -were a subroutine using `JSR`. - -// TODO: For when CHIBI PC-09 Prototype #2 comes out or whenever we get banking -// add it here "Special care must be taken to properly bank in the correct -// memory banks before executing this command." yadda yadda - -#pagebreak() - -=== IF: `HELP` - -#_ifpagehead( - desc: "Displays a summary of available IFs.", - syntax: [`HELP`], - params: () -) - -`HELP` does what it says on the tin. It should be noted that between Git tags of -the firmware the message displayed by this may be incomplete or innaccurate. -Internally all this does is print a string with the UART using the `POUTZSTR` -BIOS routine. - -#pagebreak() - -=== IF: `PEEK` - -#_ifpagehead( - desc: "Dumps memory from the MPU's address space to the terminal.", - syntax: [`PEEK []`], - params: ( - base: [ - The address (two bytes) of the byte to dump or the base (lower bound) - address of the byte to start dumping from if `` is specified. - ], - high: [ - An optional operand given as the upper bound of the range to dump. Forms - a range together with ``. (two bytes) - ], - ) -) - -Peeking memory causes the MPU to read the requested bytes and dump them to the -screen. - -#pagebreak() - -=== IF: `POKE` - -#_ifpagehead( - desc: "Writes values to the MPU's address space.", - syntax: [`POKE `], - params: ( - addr: "The base (low) address (two bytes) to start writing bytes from.", - bytes: "The bytes to write into memory separated by whitespace.", - ) -) - -Poking memory causes the MPU to overwrite the bytes at `` with the bytes -given in ``. - -#pagebreak() - -=== IF: `SREC` - -#_ifpagehead( - desc: "Switches into Motorola S-Record receive mode.", - syntax: [`SREC`], - params: (), -) - -Motorola S-Record mode is currently a stub. - -#pagebreak() - -== External Functions (EFs) - -External functions are any native user code that can be called with `CALL` (see -@if-call). This mechanism is usable to run any code or routine in memory as -though interactively using the MPU's `JSR` instruction. - -=== EFs in ROM - -Some common EFs to call include the using call to reset the CHIBI PC-09 with -`CALL 8000`. - -// TODO: Talk about memory test and BIOS interface - -#pagebreak() - -= BUZBEE Reserved Memory Regions - -BUZBEE uses memory in the 0200-02FF page. A table of the layout of this memory -is provided. The memory is laid out in a packed structure starting at 0200. - -#table( - columns: (auto, 1fr, auto), - inset: 10pt, - align: center, - fill: (_, y) => - if calc.odd(y) { luma(250) } - else { white }, - table.header( - [*Internal Name*], [*Size (Bytes)*], [*Description*] - ), - [`input`], - [128], - [Text input buffer], - [`cchinput`], - [2], - [Text input buffer character count], - [`tokens`], - [64], - [BUZBEE token buffer], - [`cbtokens`], - [2], - [Count of bytes in `tokens`], - [`scratch`], - [2], - [Internal scratch word used for some operations], -) - -#pagebreak() - = Building CHIBI PC-09 Firmware from Source Building the CHIBI PC-09 firmware from source requires LWTOOLS @@ -273,10 +55,242 @@ Building the documentation can also be accomplished using `make docs`, provided #pagebreak() -= BUZBEE Internals and Modding += Programs in ROM + +Some simple programs are included in the CHIBI PC-09's firmware ROM and can be +called through BUZBEE's `CALL` command. Soft reseting the CHIBI PC-09 is also +handled through this interface by calling `$8000` or the ROM entrypoint. + +A simple memory test based on ROBIT-2 for the SWTPC is included at `$9000`. + +#pagebreak() + += CHIBI/O BIOS Interface + +#lorem(120) + +#pagebreak() + += BUZBEE Machine Language Monitor + +BUZBEE is a "machine language monitor" styled after Steve Wozniak's WOZMON for +the CHIBI PC-09 computer platform. It is the stock bootloader and +interface for the PC-09. This chapter goes over the usage of BUZBEE, and some of +the technical internals of how it works and how to use it. + +BUZBEE was created primarily to debug prototype versions of the CHIBI PC-09. +BUZBEE will grow alongside the CHIBI PC-09 project. It also functions as a +reference implementation of an OS using the CHIBI PC-09 BIOS. + +#pagebreak() + +== BUZBEE Functions + +BUZBEE is at its core a chain loader or bootloader. This means that most of the +functionality of the CHIBI starts with using BUZBEE. BUZBEE functions are called +_Internal Functions_ or "IFs". These are documented in @bbif-top. BUZBEE +functions are native functions mapped to textual commands entered at the BUZBEE +prompt. + +#pagebreak() + +== Internal Functions (IFs) + +Internal Functions are the textual commands that BUZBEE interprets from the +command line to execute the user's wish. Internal Functions are canonically +listed in alphabetical order. Below in @bbif-table is a list of available IFs. + +#figure( + table( + columns: (auto, auto, 1fr), + inset: 10pt, + align: center, + fill: (_, y) => + if calc.odd(y) { luma(250) } + else { white }, + table.header( + [*Name* (pg. no.)], [*Command Token*], [*Description*] + ), + [`CALL` (#ref(, form: "page"))], + [`$00`], + [Call a resident routine in the MPU's address space.], + [`HELP` (#ref(, form: "page"))], + [`$01`], + [Display a summary of known commands.], + [`PEEK` (#ref(, form: "page"))], + [`$02`], + [Dumps memory from the MPU's address space to the terminal.], + [`POKE` (#ref(, form: "page"))], + [`$03`], + [Overwrites memory in the MPU's address space.], + [`SREC` (#ref(, form: "page"))], + [`$04`], + [Switches into Motorola S-Record receive mode.], + ), + caption: [Table of IFs], +) + +In the following pages these IFs are described in specific. + +IFs are tokenized from their textual form into a binary "bytecode" form. This +bytecode is described in @bbinternals. + +First the text command name (eg. `CALL`) is hashed in some way into a token. +Then conditional processing on the remainder of the line occurs. Values given in +hex are encoded as their corresponding bytes directly. The token buffer +mechanics are described more in @bbinternals. Subcommands are also hashed into +tokens. + +#pagebreak() + +// Function for creating IF page headers +#let _ifpagehead( + desc: none, + syntax: none, + params: (), +) = { + smallcaps[#desc] + parbreak() + [Syntax: #syntax] + parbreak() + [Parameters: ] + if params.len() > 0 { + for (param, desc) in params [ + - #raw("<" + upper(param) + ">"): #desc + ] + } else { + text(style: "italic")[N/A] + } +} + +==== IF: `CALL` + +#_ifpagehead( + desc: "Calls a resident routine in the MPU's address space.", + syntax: [`CALL `], + params: ( + ptr: "An absolute pointer to a position in the 6309 MPU's memory map.", + ), +) + +Call takes an absolute pointer into the MPU's address space to call as if it +were a subroutine using `JSR`. + +// TODO: For when CHIBI PC-09 Prototype #2 comes out or whenever we get banking +// add it here "Special care must be taken to properly bank in the correct +// memory banks before executing this command." yadda yadda + +#pagebreak() + +==== IF: `HELP` + +#_ifpagehead( + desc: "Displays a summary of available IFs.", + syntax: [`HELP`], + params: () +) + +`HELP` does what it says on the tin. It should be noted that between Git tags of +the firmware the message displayed by this may be incomplete or innaccurate. +Internally all this does is print a string with the UART using the `POUTZSTR` +BIOS routine. + +#pagebreak() + +==== IF: `PEEK` + +#_ifpagehead( + desc: "Dumps memory from the MPU's address space to the terminal.", + syntax: [`PEEK []`], + params: ( + base: [ + The address (two bytes) of the byte to dump or the base (lower bound) + address of the byte to start dumping from if `` is specified. + ], + high: [ + An optional operand given as the upper bound of the range to dump. Forms + a range together with ``. (two bytes) + ], + ) +) + +Peeking memory causes the MPU to read the requested bytes and dump them to the +screen. + +#pagebreak() + +==== IF: `POKE` + +#_ifpagehead( + desc: "Writes values to the MPU's address space.", + syntax: [`POKE `], + params: ( + addr: "The base (low) address (two bytes) to start writing bytes from.", + bytes: "The bytes to write into memory separated by whitespace.", + ) +) + +Poking memory causes the MPU to overwrite the bytes at `` with the bytes +given in ``. + +#pagebreak() + +==== IF: `SREC` + +#_ifpagehead( + desc: "Switches into Motorola S-Record receive mode.", + syntax: [`SREC`], + params: (), +) + +Motorola S-Record mode is currently a stub. + +#pagebreak() + +=== External Functions (EFs) + +External functions are any native user code that can be called with `CALL` (see +@bbif-call). This mechanism is usable to run any code or routine in memory as +though interactively using the MPU's `JSR` instruction. + +== BUZBEE Reserved Memory Regions + +BUZBEE uses memory in the 0200-02FF page. A table of the layout of this memory +is provided. The memory is laid out in a packed structure starting at 0200. + +#table( + columns: (auto, 1fr, auto), + inset: 10pt, + align: center, + fill: (_, y) => + if calc.odd(y) { luma(250) } + else { white }, + table.header( + [*Internal Name*], [*Size (Bytes)*], [*Description*] + ), + [`input`], + [128], + [Text input buffer], + [`cchinput`], + [2], + [Text input buffer character count], + [`tokens`], + [64], + [BUZBEE token buffer], + [`cbtokens`], + [2], + [Count of bytes in `tokens`], + [`scratch`], + [2], + [Internal scratch word used for some operations], +) + +#pagebreak() + +== BUZBEE Internals and Modding BUZBEE's interpreter works by "compiling" textual user commands into bytecode -for more simply passing parameters to IFs (see @if-top). The way that works is +for more simply passing parameters to IFs (see @bbif-top). The way that works is the implementation dependent, but each hash is one byte (1B) in size, and corresponds to an IF token, which is the index of the hash. diff --git a/makefile b/makefile index d3f0b44..96a28ce 100644 --- a/makefile +++ b/makefile @@ -34,7 +34,7 @@ LDFLAGS := -f srec -m map.txt -s linkscript # ------------------------------------------------------------------------------ docs: docs/*.typ - typst compile docs/buzbee.typ + typst compile docs/firmware.typ all: $(TARGROM)