collapseos/doc/glue-code.md

# 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/