6.3KB
Understanding the code
One of the design goals of Collapse OS is that its code base should be easily
understandable in its entirety. Let's help with this with a little walthrough.
We use the basic rc2014 recipe as a basis for the walkthrough.
This walkthrough assumes that you know z80 assembly. It is recommended that you
read code conventions in CODE.md first.
Code snippets aren't reproduced here. You have to follow along with code listing.
Power on
You have a RC2014 classic built with an EEPROM that has the recipe's binary on it and you're linked to its serial I/O module. What happens when you power it on and press the reset button (I've always had to press the reset button for the RC2014 to power on properly. I don't know why. Must be some tricky sync issue with the components)?
A freshly booted Z80 starts executing address zero. That address is in your
glue code. The first thing it does is thus jp init. Initialization is handled
by recipes/rc2014/glue.asm.
As you can see, it's a fairly straightforward init. Stack at the end of RAM, interrupt mode 1 (which we use for the ACIA), then individual module initialization, and finally, BASIC's runloop.
ACIA init
An Asynchronous Communication Interface Adaptor allows serial communication with
another ACIA (ref http://alanclements.org/serialio.html ). The RC2014 uses a
6850 ACIA IC and Collapse OS's kernel/acia module was written to interface
with this kind of IC.
For this module to work, it needs to be wired to the z80 but in a particular
manner (which oh! surprise, the RC2014's Serial I/O module is...): It should use
two ports, R/W. One for access to its status register and one for its access to
its data register. Also, its INT line should be wired to the z80 INT line
for interrupts to work.
I won't go into much detail about the wiring: the 6850 seems to have been designed to be wired thus, so it would kind of be like stating the obvious.
aciaInit in kernel/acia is also straightforward. First, it initializes the
input buffer. This buffer is a circular buffer that is filled with high priority
during the interrupt handler at aciaInt. It's important that we process input
at high priority to be sure not to miss a byte (there is no buffer overrun
handling in acia. Unhandled data is simply lost).
That buffer will later be emptied by BASIC's main loop.
Once the input buffer is set up, all that is left is to set up the ACIA itself,
which is configurable through ACIA_CTL. Comments in the code are
self-explanatory. Make sure that you use serial config, on the other side, that
is compatible with this config there.
BASIC init
Then comes basInit at apps/basic/main. This is a bigger app, so there is
more stuff to initialize, but still, it stays straightforward. I'm not going to
explain every line, but give you a recipe for understanding. Every variable as,
above its declaration line, a comment explaining what it does. Refer to it.
This init method is the first one we see that has sub-methods in it. To quickly
find where they live, be aware that the general convention in Collapse OS code
is to prefix every label with its module name. So, for example, varInit lives
in apps/basic/var.
You can also see, in the initialization of BAS_FINDHOOK, a common idiom: the
use of unsetZ (from kernel/core) as a noop that returns an error (in this
case, it just means “command not found”).
Sending the prompt
We're now entering basStart, which simply prints Collapse OS’ prompt and then
enter its runloop. Let's examine what happens when we call printstr (from
kernel/stdio).
printstr itself is easy. It iterates over (HL) and calls STDIO_PUTC for
each char.
But what is STDIO_PUTC? It's a glue-defined routine. Let's go back to
glue.asm. You see that .equ STDIO_PUTC aciaPutC line is? Well, there you
have it. call STDIO_PUTC, in our context, is the exact equivalent of
call aciaPutC. Let's go see it.
Whew! it's straightforward! We do two things here: wait until the ACIA is ready to transmit (if it's not, it means that it's still in the process of transmitting the previous character we asked it to transmit), then send that char straight to the data port.
BASIC's runloop
Once the prompt is sent, we're entering BASIC's runloop at basLoop. This loops
forever.
The first thing it does is to wait for a line to be entered using
stdioReadLine from kernel/stdio. Let's see what this does.
Oh, this is a little less straightforward. This routine repeatedly calls
STDIO_GETC and puts the result in a stdio-specific buffer, after having echoed
back the received character so that the user sees what she types.
STDIO_GETC is blocking. It always returns a char.
As you can see in the glue unit, STDIO_GETC is mapped to aciaGetC. This
routine waits until the ACIA buffer has something in it. Once it does, it reads
one character from it and returns it.
Back to stdioReadLine, we check that we don't have special handling to do,
that is, end of line or deletion. If we don't, we echo back the char, advance
buffer pointer, wait for a new one.
If we receive a CR or LF, the line is complete, so we return to basLoop with
a null-terminated input line in (HL).
I won't cover the processing of the line by BASIC because it's a bit long and doesn't help holistic understanding very much, You can read the code.
Once the line is processed, that the associated command is found and called, we go back the the beginning of the loop for another ride.
When do we receive a character?
In the above section, we simply wait until the buffer has something in it. But
how will that happen? Through aciaInt interrupt.
When the ACIA receives a new character, it pulls the INT line low, which, in
interrupt mode 1, calls 0x38. In our glue code, we jump to aciaInt.
In aciaInt, the first thing we do is to check that we're concerned (the INT
line can be triggered by other peripherals and we want to ignore those). To do
so, we poll ACIA's status register and see if its receive buffer is full.
If yes, then we fetch that char from ACIA, put it in the buffer and return from interrupt. That's how the buffer gets full.
Conclusion
This walkthrough covers only one simple case, but I hope that it gives you keys to understanding the whole of Collapse OS. You should be able to start from any other recipe's glue code and walk through it in a way that is similar to what we've made here.