mirror of
https://github.com/hsoft/collapseos.git
synced 2024-11-20 22:28:05 +11:00
121 lines
4.0 KiB
Markdown
121 lines
4.0 KiB
Markdown
# Writing the glue code
|
|
|
|
Collapse OS is not an OS, it's a meta OS. It supplies parts that you're expected
|
|
to glue together in a "glue code" asm file. Here is what a minimal glue code
|
|
for a shell on a Classic [RC2014][rc2014] with an ACIA link would look like:
|
|
|
|
|
|
; The RAM module is selected on A15, so it has the range 0x8000-0xffff
|
|
RAMSTART .equ 0x8000
|
|
RAMEND .equ 0xffff
|
|
ACIA_CTL .equ 0x80 ; Control and status. RS off.
|
|
ACIA_IO .equ 0x81 ; Transmit. RS on.
|
|
|
|
jr init
|
|
|
|
; interrupt hook
|
|
.fill 0x38-$
|
|
jp aciaInt
|
|
|
|
init:
|
|
di
|
|
; setup stack
|
|
ld hl, RAMEND
|
|
ld sp, hl
|
|
im 1
|
|
call aciaInit
|
|
call shellInit
|
|
ei
|
|
jp shellLoop
|
|
|
|
#include "core.asm"
|
|
ACIA_RAMSTART .equ RAMSTART
|
|
#include "acia.asm"
|
|
SHELL_RAMSTART .equ ACIA_RAMEND
|
|
.define SHELL_GETC call aciaGetC
|
|
.define SHELL_PUTC call aciaPutC
|
|
.define SHELL_IO_GETC call aciaGetC
|
|
SHELL_EXTRA_CMD_COUNT .equ 0
|
|
#include "shell.asm"
|
|
|
|
Once this is written, building it is easy:
|
|
|
|
scas -o collapseos.bin -I /path/to/parts glue.asm
|
|
|
|
## Platform constants
|
|
|
|
The upper part of the code contains platform-related constants, information
|
|
related to the platform you're targeting. You might want to put it in an
|
|
include file if you're writing multiple glue code that targets the same machine.
|
|
|
|
In all cases, `RAMSTART` are necessary. `RAMSTART` is the offset at which
|
|
writable memory begins. This is where the different parts store their
|
|
variables.
|
|
|
|
`RAMEND` is the offset where writable memory stop. This is generally
|
|
where we put the stack, but as you can see, setting up the stack is the
|
|
responsibility of the glue code, so you can set it up however you wish.
|
|
|
|
`ACIA_*` are specific to the `acia` part. Details about them are in `acia.asm`.
|
|
If you want to manage ACIA, you need your platform to define these ports.
|
|
|
|
## Header code
|
|
|
|
Then comes the header code (code at `0x0000`), a task that also is in the glue
|
|
code's turf. `jr init` means that we run our `init` routine on boot.
|
|
|
|
`jp aciaInt` at `0x38` is needed by the `acia` part. Collapse OS doesn't dictate
|
|
a particular interrupt scheme, but some parts might. In the case of `acia`, we
|
|
require to be set in interrupt mode 1.
|
|
|
|
## Includes
|
|
|
|
This is the most important part of the glue code and it dictates what will be
|
|
included in your OS. Each part is different and has a comment header explaining
|
|
how it works, but there are a couple of mechanisms that are common to all.
|
|
|
|
### Defines
|
|
|
|
Parts can define internal constants, but also often document a "Defines" part.
|
|
These are constant that are expected to be set before you include the file.
|
|
|
|
See comment in each part for details.
|
|
|
|
### RAM management
|
|
|
|
Many parts require variables. They need to know where in RAM to store these
|
|
variables. Because parts can be mixed and matched arbitrarily, we can't use
|
|
fixed memory addresses.
|
|
|
|
This is why each part that needs variable define a `<PARTNAME>_RAMSTART`
|
|
constant that must be defined before we include the part.
|
|
|
|
Symmetrically, each part define a `<PARTNAME>_RAMEND` to indicate where its
|
|
last variable ends.
|
|
|
|
This way, we can easily and efficiently chain up the RAM of every included part.
|
|
|
|
### Tables grafting
|
|
|
|
A mechanism that is common to some parts is "table grafting". If a part works
|
|
on a list of things that need to be defined by the glue code, it will place a
|
|
label at the very end of its source file. This way, it becomes easy for the
|
|
glue code to "graft" entries to the table. This approach, although simple and
|
|
effective, only works for one table per part. But it's often enough.
|
|
|
|
For example, to define extra commands in the shell:
|
|
|
|
[...]
|
|
SHELL_EXTRA_CMD_COUNT .equ 2
|
|
#include "shell.asm"
|
|
.dw myCmd1, myCmd2
|
|
[...]
|
|
|
|
### Initialization
|
|
|
|
Then, finally, comes the `init` code. This can be pretty much anything really
|
|
and this much depends on the part you select. But if you want a shell, you will
|
|
usually end it with `shellLoop`, which never returns.
|
|
|
|
[rc2014]: https://rc2014.co.uk/
|