chibi-firmware/docs/firmware.typ

#set document(
  title: "CHIBI PC-09 Firmware Manual",
  author: "Gale Faraday",
  description: "CHIBI PC-09 Firmware: BIOS, CHIBIO, and BUZBEE documentation",
)

#import "style.typ": conf
#show: conf.with(
  title: [CHIBI PC-09 Firmware Manual and Technical Reference],
  subtitle: [A Complete Firmware Package for the CHIBI PC-09],
  author: [Gale Faraday],
)

= Introduction <intro>

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
copyright 2025 Gale Faraday. All CHIBI PC-09 components are licensed under the
MIT license.

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

= Programs in ROM <programs>

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 <chibio-intro>

#lorem(120)

#pagebreak()

= BUZBEE Machine Language Monitor <bb-intro>

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

#_ifpagehead(
  desc: "Dumps memory from the MPU's address space to the terminal.",
  syntax: [`PEEK <BASE> [<HIGH>]`],
  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 `<HIGH>` is specified.
    ],
    high: [
      An optional operand given as the upper bound of the range to dump. Forms
      a range together with `<BASE>`. (two bytes)
    ],
  )
)

Peeking memory causes the MPU to read the requested bytes and dump them to the
screen.

#pagebreak()

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

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

#pagebreak()

==== IF: `SREC` <bbif-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) <bbef-top>

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 <res-mem>

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

BUZBEE's interpreter works by "compiling" textual user commands into bytecode
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.

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.