feat(docs): expanded Typst doc

.editorconfig

@@ -12,7 +12,7 @@ insert_final_newline = true
 indent_style = space
 indent_size = 2
 
-[*.md]
+[*.{md,typ}]
 indent_style = space
 indent_size = 2
 max_line_length = 80

docs/buzbee.typ

@@ -50,15 +50,15 @@ listed in alphabetical order. Below in @if-table is a list of available IFs.
     table.header(
       [*Name* (pg. no.)], [*Description*]
     ),
-    [`CALL` #ref(<if-call>, form: "page")],
+    [`CALL` (#ref(<if-call>, form: "page"))],
     [Call a resident routine in the MPU's address space.],
-    [`HELP` #ref(<if-help>, form: "page")],
+    [`HELP` (#ref(<if-help>, form: "page"))],
     [Display a summary of known commands.],
-    [`PEEK` #ref(<if-peek>, form: "page")],
+    [`PEEK` (#ref(<if-peek>, form: "page"))],
     [Dumps memory from the MPU's address space to the terminal.],
-    [`POKE` #ref(<if-poke>, form: "page")],
+    [`POKE` (#ref(<if-poke>, form: "page"))],
     [Overwrites memory in the MPU's address space.],
-    [`SREC` #ref(<if-srec>, form: "page")],
+    [`SREC` (#ref(<if-srec>, form: "page"))],
     [Switches into Motorola S-Record receive mode.],
   ),
   caption: [Table of IFs],
@@ -66,10 +66,19 @@ listed in alphabetical order. Below in @if-table is a list of available IFs.
 
 In the following pages these IFs are described in specific.
 
-// TODO: Talk about how IFs are tokenized.
+IFs are tokenized from their textual form into a binary "bytecode" form. This
+bytecode is not reliably stable between versions, so it isn't described here in
+specific, but a general breakdown is provided.
+
+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,
@@ -99,7 +108,8 @@ In the following pages these IFs are described in specific.
   ),
 )
 
-#lorem(120)
+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
@@ -172,23 +182,55 @@ BIOS routine.
 
 == External Functions (EFs) <ef-top>
 
-#lorem(120)
+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 <ef-rom>
 
-#lorem(120)
+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 <res-mem>
 
-#lorem(120)
+BUZBEE uses memory in the 0200-02FF page. A table of the layout of this memory
+is provided.
+
+// TODO: Provide a table of the BUZBEE memory layout.
 
 #pagebreak()
 
 = Building CHIBI PC-09 Firmware from Source <building>
 
-#lorem(120)
+Building the CHIBI PC-09 firmware from source requires LWTOOLS
+#link("http://lwtools.ca"), a functioning C compiler (`cc`), and a POSIX Shell
+implementation (`sh`). The firmware was developed using LWTOOLS version 4.24 on
+Linux, though later versions may work as well. A GNU Make "makefile" is provided for
+building on Linux. GNU binutils' `objcopy` is also used to build the compiled
+Motorola S-Record into a raw binary. Development is tracked using Git.
+
+Using the makefile is simple. It provides facilities for easy building, and
+development.
+
+To build an S-Record of the ROM run:
+```sh
+make generate && make boot.s19
+```
+
+To build a ROM image with `objcopy` run:
+```sh
+make generate && make
+```
+
+In order to rebuild, first the generated files and existing objects must be
+cleaned. To do this a `make clean` pseudo-target is defined.
+
+Building the documentation can also be accomplished using `make docs`, provided
+`typst` is installed.
 
 #pagebreak()
 

src/buzbee.inc

@@ -5,16 +5,3 @@
 ; vim: ft=asm
 
 BUZBEE IMPORT
-
-;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
-;;
-;; BUZBEE Variables
-;;
-;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
-
-BBIN_BASE      EQU $0200
-BBIN_DEPTH     EQU $7F
-BBTOKENS_BASE  EQU $0280
-BBTOKENS_DEPTH EQU $3F
-BBTOKENS_CCH   EQU $02C0
-

src/buzbee.s

@@ -7,6 +7,26 @@
   INCLUDE "hardware.inc"
   INCLUDE "serial.inc"
 
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;;
+;; BUZBEE Variables
+;;
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
+BBIN_DEPTH     EQU $7F
+BBTOKENS_DEPTH EQU $3F
+
+  SECTION BBVARS,bss
+
+tagbbvar STRUCT
+input    rmb BBIN_DEPTH     ; Input buffer
+tokens   rmb BBTOKENS_DEPTH ; Token buffer
+cbtokens rmb 2
+  ENDSTRUCT
+
+  ORG $0200
+BBVAR tagbbvar
+
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;
 ;; BUZBEE Machine Language Monitor for CHIBI PC-09
@@ -39,7 +59,7 @@ CLRIN               ; Label to just clear input buffer without newline
   clra              ; Init A and X
   ldx #$0000
 NEXT@
-  sta BBIN_BASE,x   ; Clear input buffer
+  sta BBVAR.input,x ; Clear input buffer
   leax 1,x
   cmpx #BBIN_DEPTH
   blo NEXT@
@@ -64,7 +84,7 @@ INPLOOP
   beq FULLBUF@         ; Handle the buffer being full
 ECHO@
   jsr POUTCHAR         ; Echo char back, this includes BS chars
-  sta BBIN_BASE,y      ; Add it to the input buffer
+  sta BBVAR.input,y    ; Add it to the input buffer
   leay 1,y
 NOCHAR@
   ; Check for error condition, work based on The Serial Port release 19
@@ -96,7 +116,7 @@ HESC@
 HBACKSPC@
   clrb                 ; Clear last char
   leay -1,y
-  stb BBIN_BASE
+  stb BBVAR.input
   bra ECHO@            ; Echo the char in A
 FULLBUF@
   lda #$07             ; ASCII BEL
@@ -114,14 +134,14 @@ FULLBUF@
 ; @return A: resulting hash
 MKCMDSUM
   pshs b
-  ldb #4           ; Loop over four chars
+  ldb #4             ; Loop over four chars
-  clra             ; Initialize accumulator
+  clra               ; Initialize accumulator
 NEXTC@
-  suba BBIN_BASE,x ; Subtract current char from accumulator
+  suba BBVAR.input,x ; Subtract current char from accumulator
-  leax 1,x         ; Next char
+  leax 1,x           ; Next char
-  decb             ; Reduce count
+  decb               ; Reduce count
-  cmpb #0          ; Are we at the end?
+  cmpb #0            ; Are we at the end?
-  bne NEXTC@       ;  No? loop
+  bne NEXTC@         ;  No? loop
   rts
 
 ; Maps a command hash to a command index, and executes it
@@ -184,6 +204,7 @@ HELP_MSG
   fcc "POKE <ADDR> <BYTES> - Overwrite memory with <BYTES> starting at <BASE>."
   fcb $0D,$0A
   fcc "SREC - Enter Motorola S-Record entry mode."
+  fcb $0D,$0A
   fcb $00
 
 BBCMDPTRTBL