From 8f615e1bd842523018a947fdcc83667f427988a4 Mon Sep 17 00:00:00 2001
From: Gale Faraday <k4mu1kazum4@gmail.com>
Date: Sat, 11 Oct 2025 18:32:28 -0500
Subject: [PATCH] feat(docs): update manual

---
 docs/buzbee.typ | 63 +++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 56 insertions(+), 7 deletions(-)

diff --git a/docs/buzbee.typ b/docs/buzbee.typ
index 535754b..0c7a74c 100644
--- a/docs/buzbee.typ
+++ b/docs/buzbee.typ
@@ -18,6 +18,10 @@ 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.
+
 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
@@ -29,10 +33,11 @@ MIT license.
 
 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".
+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()
 
@@ -47,6 +52,9 @@ listed in alphabetical order. Below in @if-table is a list of available IFs.
     columns: (1fr, auto),
     inset: 10pt,
     align: center,
+    fill: (_, y) =>
+      if calc.odd(y) { luma(250) }
+      else { white },
     table.header(
       [*Name* (pg. no.)], [*Description*]
     ),
@@ -149,6 +157,9 @@ BIOS routine.
   )
 )
 
+Peeking memory causes the MPU to read the requested bytes and dump them to the
+screen.
+
 #lorem(120)
 
 #pagebreak()
@@ -198,9 +209,34 @@ Some common EFs to call include the using call to reset the CHIBI PC-09 with
 = BUZBEE Reserved Memory Regions <res-mem>
 
 BUZBEE uses memory in the 0200-02FF page. A table of the layout of this memory
-is provided.
+is provided. The memory is laid out in a packed structure starting at 0200.
 
-// TODO: Provide a table of the BUZBEE memory layout.
+#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()
 
@@ -236,4 +272,17 @@ Building the documentation can also be accomplished using `make docs`, provided
 
 = BUZBEE Internals and Modding <internals>
 
-#lorem(120)
+BUZBEE's interpreter works by "compiling" textual user commands into bytecode
+for more simply passing parameters to IFs (see @if-top).
+
+BUZBEE's source, and the surrounding BIOS source is well commented, but a
+general summary of the control flow is provided here.
+
++ BUZBEE sets up the prompt and input buffer with `NEWLINE`
++ BUZBEE enters an input processing loop that works with the CHIBI PC-09's
+  serial driver.
++ If no input is provided, restart.
++ BUZBEE makes a tokenizing pass over the input buffer.
++ BUZBEE attempts to execute the tokens, which may involve leaving the BUZBEE
+  loop, or in the event the IF returns, loops around and re-enters the BUZBEE
+  loop.