#set document(
  title: "BUZBEE Manual",
  author: "Gale Faraday",
  description: "CHIBI PC-09 machine language monitor BUZBEE technical and user manual",
)

#import "style.typ": conf
#show: conf.with(
  title: [BUZBEE User Manual and Technical Reference],
  subtitle: [A CHIBI PC-09 Machine Language Monitor],
  author: [Gale Faraday],
)

= Introduction <intro>

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 <bbfunc>

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) <if-top>

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(<if-call>, form: "page"))],
    [Call a resident routine in the MPU's address space.],
    [`HELP` (#ref(<if-help>, form: "page"))],
    [Display a summary of known commands.],
    [`PEEK` (#ref(<if-peek>, form: "page"))],
    [Dumps memory from the MPU's address space to the terminal.],
    [`POKE` (#ref(<if-poke>, form: "page"))],
    [Overwrites memory in the MPU's address space.],
    [`SREC` (#ref(<if-srec>, form: "page"))],
    [Switches into Motorola S-Record receive mode.],
  ),
  caption: [Table of IFs],
) <if-table>

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 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,
  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` <if-call>

#_ifpagehead(
  desc: "Calls a resident routine in the MPU's address space.",
  syntax: [`CALL <PTR>`],
  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` <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` <if-peek>

#_ifpagehead(
  desc: "Dumps memory from the MPU's address space to the terminal.",
  syntax: [`PEEK <BASE> [<HIGH>]`],
  params: (
    base: [
      The address of the byte to dump or the base (lower bound) address of the
      byte to start dumping from if `<HIGH>` is specified.
    ],
    high: [
      An optional operand given as the upper bound of the range to dump. Forms
      a range together with `<BASE>`.
    ],
  )
)

#lorem(120)

#pagebreak()

=== IF: `POKE` <if-poke>

#_ifpagehead(
  desc: "Writes values to the MPU's address space.",
  syntax: [`POKE <ADDR> <BYTES>`],
  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` <if-srec>

#_ifpagehead(
  desc: "Switches into Motorola S-Record receive mode.",
  syntax: [`SREC`],
  params: (),
)

#lorem(120)

#pagebreak()

== External Functions (EFs) <ef-top>

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>

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>

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>

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()

= BUZBEE Internals and Modding <internals>

#lorem(120)