docs(bios): revised manual to cover all firmware topics
This commit is contained in:
307
docs/firmware.typ
Normal file
307
docs/firmware.typ
Normal file
@@ -0,0 +1,307 @@
|
||||
#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.
|
||||
Reference in New Issue
Block a user