019d05f64c
That's my mega-commit you've all been waiting for. The code for the shell share more routines with userspace apps than with kernel units, because, well, its behavior is that of a userspace app, not a device driver. This created a weird situation with libraries and jump tables. Some routine belonging to the `kernel/` directory felt weird there. And then comes `apps/basic`, which will likely share even more code with the shell. I was seeing myself creating huge jump tables to reuse code from the shell. It didn't feel right. Moreover, we'll probably want basic-like apps to optionnally replace the shell. So here I am with this huge change in the project structure. I didn't test all recipes on hardware yet, I will do later. I might have broken some... But now, the structure feels better and the line between what belongs to `kernel` and what belongs to `apps` feels clearer.
2.7 KiB
Code conventions
The code in this project follow certain project-wide conventions, which are
described here. Kernel code and userspace code follow additional conventions
which are described in kernel/README.md and apps/README.md.
Defines
Each unit can have its own constants, but some constant are made to be defined externally. We already have some of those external definitions in platform includes, but we can have more defines than this.
Many units have a "DEFINES" section listing the constant it expects to be defined. Make sure that you have these constants defined before you include the file.
Variable management
Each unit can define variables. These variables are defined as addresses in
RAM. We know where RAM start from the RAMSTART constant in platform includes,
but because those parts are made to be glued together in no pre-defined order,
we need a system to align variables from different modules in RAM.
This is why each unit that has variable expect a <PREFIX>_RAMSTART
constant to be defined and, in turn, defines a <PREFIX>_RAMEND constant to
carry to the following unit.
Thus, code that glue parts together could look like:
MOD1_RAMSTART .equ RAMSTART
#include "mod1.asm"
MOD2_RAMSTART .equ MOD1_RAMEND
#include "mod2.asm"
Stack management
Keeping the stack "balanced" is a big challenge when writing assembler code. Those push and pop need to correspond, otherwise we end up with completely broken code.
The usual "push/pop" at the beginning and end of a routine is rather easy to manage, nothing special about them.
The problem is for the "inner" push and pop, which are often necessary in routines handling more data at once. In those cases, we walk on eggshells.
A naive approach could be to indent the code between those push/pop, but indent level would quickly become too big to fit in 80 chars.
I've tried ASCII art in some places, where comments next to push/pop have "|" indicating the scope of the push/pop. It's nice, but it makes code complicated to edit, especially when dense comments are involved. The pipes have to go through them.
Of course, one could add descriptions next to each push/pop describing what is being pushed, and I do it in some places, but it doesn't help much in easily tracking down stack levels.
So, what I've started doing is to accompany each "non-routine" (at the beginning and end of a routine) push/pop with "--> lvl X" and "<-- lvl X" comments. Example:
push af ; --> lvl 1
inc a
push af ; --> lvl 2
inc a
pop af ; <-- lvl 2
pop af ; <-- lvl 1
I think that this should do the trick, so I'll do this consistently from now on. [zasm]: ../apps/zasm/README.md