docs(bios): revised manual to cover all firmware topics
This commit is contained in:
@@ -1,26 +1,22 @@
|
||||
#set document(
|
||||
title: "BUZBEE Manual",
|
||||
title: "CHIBI PC-09 Firmware Manual",
|
||||
author: "Gale Faraday",
|
||||
description: "CHIBI PC-09 machine language monitor BUZBEE technical and user manual",
|
||||
description: "CHIBI PC-09 Firmware: BIOS, CHIBIO, and BUZBEE documentation",
|
||||
)
|
||||
|
||||
#import "style.typ": conf
|
||||
#show: conf.with(
|
||||
title: [BUZBEE User Manual and Technical Reference],
|
||||
subtitle: [A CHIBI PC-09 Machine Language Monitor],
|
||||
title: [CHIBI PC-09 Firmware Manual and Technical Reference],
|
||||
subtitle: [A Complete Firmware Package for the CHIBI PC-09],
|
||||
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.
|
||||
|
||||
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.
|
||||
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
|
||||
@@ -29,220 +25,6 @@ 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" 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()
|
||||
|
||||
== 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: (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(<if-call>, form: "page"))],
|
||||
[`$00`],
|
||||
[Call a resident routine in the MPU's address space.],
|
||||
[`HELP` (#ref(<if-help>, form: "page"))],
|
||||
[`$01`],
|
||||
[Display a summary of known commands.],
|
||||
[`PEEK` (#ref(<if-peek>, form: "page"))],
|
||||
[`$02`],
|
||||
[Dumps memory from the MPU's address space to the terminal.],
|
||||
[`POKE` (#ref(<if-poke>, form: "page"))],
|
||||
[`$03`],
|
||||
[Overwrites memory in the MPU's address space.],
|
||||
[`SREC` (#ref(<if-srec>, form: "page"))],
|
||||
[`$04`],
|
||||
[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 described in @internals.
|
||||
|
||||
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 (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` <if-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` <if-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) <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. 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()
|
||||
|
||||
= Building CHIBI PC-09 Firmware from Source <building>
|
||||
|
||||
Building the CHIBI PC-09 firmware from source requires LWTOOLS
|
||||
@@ -273,10 +55,242 @@ Building the documentation can also be accomplished using `make docs`, provided
|
||||
|
||||
#pagebreak()
|
||||
|
||||
= BUZBEE Internals and Modding <internals>
|
||||
= 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 @if-top). The way that works is
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user