diff --git a/.gitignore b/.gitignore index 1873f4c..6f0d903 100644 --- a/.gitignore +++ b/.gitignore @@ -7,6 +7,7 @@ build/ map.txt bbmkhash +*.pdf # Build system generated files src/version.s diff --git a/docs/buzbee.pdf b/docs/buzbee.pdf deleted file mode 100644 index ada463c..0000000 Binary files a/docs/buzbee.pdf and /dev/null differ diff --git a/docs/buzbee.typ b/docs/buzbee.typ index 7737bf7..0c36439 100644 --- a/docs/buzbee.typ +++ b/docs/buzbee.typ @@ -11,26 +11,187 @@ author: [Gale Faraday], ) -= Introduction -#lorem(120) += 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. + +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 +copyright 2025 Gale Faraday. All CHIBI PC-09 components are licensed under the +MIT license. + #pagebreak() -= BUZBEE Functions -#lorem(120) += 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," and _External Functions_ or +"EFs." 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) -#lorem(120) +== 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: (1fr, auto), + inset: 10pt, + align: center, + table.header( + [*Name* (pg. no.)], [*Description*] + ), + [`CALL` #ref(, form: "page")], + [Call a resident routine in the MPU's address space.], + [`HELP` #ref(, form: "page")], + [Display a summary of known commands.], + [`PEEK` #ref(, form: "page")], + [Dumps memory from the MPU's address space to the terminal.], + [`POKE` #ref(, form: "page")], + [Overwrites memory in the MPU's address space.], + [`SREC` #ref(, form: "page")], + [Switches into Motorola S-Record receive mode.], + ), + caption: [Table of IFs], +) + +In the following pages these IFs are described in specific. + +// TODO: Talk about how IFs are tokenized. + #pagebreak() -== External Functions (EFs) & User Programs +#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.", + ), +) + #lorem(120) + +// 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() -= BUZBEE Reserved Memory Regions -#lorem(120) +=== 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() -= Building BUZBEE +=== IF: `PEEK` + +#_ifpagehead( + desc: "Dumps memory from the MPU's address space to the terminal.", + syntax: [`PEEK []`], + params: ( + base: [ + The address 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 ``. + ], + ) +) + #lorem(120) +#pagebreak() + +=== IF: `POKE` + +#_ifpagehead( + desc: "Writes values to the MPU's address space.", + syntax: [`POKE `], + params: ( + addr: "The base (low) address to start writing bytes from.", + bytes: "The bytes to write into memory separated by whitespace.", + ) +) + +#lorem(120) + +#pagebreak() + +=== IF: `SREC` + +#_ifpagehead( + desc: "Switches into Motorola S-Record receive mode.", + syntax: [`SREC`], + params: (), +) + +#lorem(120) + +#pagebreak() + +== External Functions (EFs) + +#lorem(120) + +=== EFs in ROM + +#lorem(120) + +#pagebreak() + += BUZBEE Reserved Memory Regions + +#lorem(120) + +#pagebreak() + += Building CHIBI PC-09 Firmware from Source + +#lorem(120) + +#pagebreak() + += BUZBEE Internals and Modding + +#lorem(120) diff --git a/docs/style.typ b/docs/style.typ index 933cc82..5fbbd09 100644 --- a/docs/style.typ +++ b/docs/style.typ @@ -9,7 +9,7 @@ // Global page format set page( paper: "us-letter", - header: align(right, text(9pt, weight: "light")[#title]), + header: align(right, text(10pt, weight: "light")[#title]), numbering: "1", ) @@ -28,13 +28,17 @@ // Heading numbering set heading(numbering: "1.1") + // Show table captions above tables + show figure.where(kind: table): set figure.caption(position: top) + // Title page and TOC page(header: none, footer: none)[ // Emit title and subtitle page #block(height: 60%)[ #align(center + horizon, block(text(22pt)[#title]) + - block(above: 2em)[#smallcaps[#subtitle]] + block(above: 2em)[#smallcaps[#subtitle]] + + block[Written by #author], ) ] // Emit TOC diff --git a/makefile b/makefile index 119fe66..d3f0b44 100644 --- a/makefile +++ b/makefile @@ -1,6 +1,6 @@ # Makefile for CHIBI PC-09 Firmware -.PHONY: generate all clean +.PHONY: generate all clean docs .IGNORE: clean .DEFAULT_GOAL := all @@ -33,6 +33,9 @@ LDFLAGS := -f srec -m map.txt -s linkscript # Rules and Phony Targets # ------------------------------------------------------------------------------ +docs: docs/*.typ + typst compile docs/buzbee.typ + all: $(TARGROM) # Fix srec into flashable bin file