2019-05-09 12:58:41 -04:00
|
|
|
# emul
|
|
|
|
|
2019-05-20 12:11:45 -04:00
|
|
|
This folder contains a couple of tools running under the [libz80][libz80]
|
|
|
|
emulator.
|
|
|
|
|
2019-12-31 22:03:48 -05:00
|
|
|
## Not real hardware
|
|
|
|
|
|
|
|
In the few emulated apps described below, we don't try to emulate real hardware
|
|
|
|
because the goal here is to facilitate userspace development.
|
|
|
|
|
|
|
|
These apps run on imaginary hardware and use many cheats to simplify I/Os.
|
|
|
|
|
|
|
|
For real hardware emulation (which helps developing drivers), see the `hw`
|
|
|
|
folder.
|
|
|
|
|
2019-05-20 12:11:45 -04:00
|
|
|
## Build
|
|
|
|
|
|
|
|
First, make sure that the `libz80` git submodule is checked out. If not, run
|
|
|
|
`git submodule init && git submodule update`.
|
|
|
|
|
2019-12-31 13:32:09 -05:00
|
|
|
After that, you can run `make` and it builds all applications.
|
2019-05-20 12:11:45 -04:00
|
|
|
|
|
|
|
## shell
|
|
|
|
|
2019-12-11 14:05:34 -05:00
|
|
|
Running `shell/shell` runs the BASIC shell in an emulated machine. The goal of
|
|
|
|
this machine is not to simulate real hardware, but rather to serve as a
|
|
|
|
development platform. What we do here is we emulate the z80 part, the 64K
|
|
|
|
memory space and then hook some fake I/Os to stdin, stdout and a small storage
|
|
|
|
device that is suitable for Collapse OS's filesystem to run on.
|
2019-05-09 12:58:41 -04:00
|
|
|
|
|
|
|
Through that, it becomes easier to develop userspace applications for Collapse
|
|
|
|
OS.
|
|
|
|
|
2019-12-12 14:32:47 -05:00
|
|
|
By default, the shell initialized itself with a CFS device containing the
|
|
|
|
contents of `cfsin/` at launch (it's packed on the fly). You can specify an
|
|
|
|
alternate CFS device file (it has to be packaed already) through the `-f` flag.
|
|
|
|
|
|
|
|
By default, the shell runs interactively, but you can also pipe contents through
|
|
|
|
stdin instead. The contents will be interpreted exactly as if you had typed it
|
|
|
|
yourself and the result will be spit in stdout (it includes your typed in
|
|
|
|
contents because the Collapse OS console echoes back every character that is
|
|
|
|
sent to it.). This feature is useful for automated tests in `tools/tests/shell`.
|
|
|
|
|
2019-05-20 12:11:45 -04:00
|
|
|
## zasm
|
|
|
|
|
|
|
|
`zasm/zasm` is `apps/zasm` wrapped in an emulator. It is quite central to the
|
|
|
|
Collapse OS project because it's used to assemble everything, including itself!
|
|
|
|
|
|
|
|
The program takes no parameter. It reads source code from stdin and spits
|
|
|
|
binary in stdout. It supports includes and had both `apps/` and `kernel` folder
|
|
|
|
packed into a CFS that was statically included in the executable at compile
|
|
|
|
time.
|
2019-05-19 15:03:34 -04:00
|
|
|
|
2019-05-20 12:11:45 -04:00
|
|
|
The file `zasm/zasm.bin` is a compiled binary for `apps/zasm/glue.asm` and
|
|
|
|
`zasm/kernel.bin` is a compiled binary for `tools/emul/zasm/glue.asm`. It is
|
2019-05-19 15:03:34 -04:00
|
|
|
used to bootstrap the assembling process so that no assembler other than zasm
|
|
|
|
is required to build Collapse OS.
|
|
|
|
|
|
|
|
This binary is fed to libz80 to produce the `zasm/zasm` "modern" binary and
|
2019-05-20 12:11:45 -04:00
|
|
|
once you have that, you can recreate `zasm/zasm.bin` and `zasm/kernel.bin`.
|
2019-05-19 15:03:34 -04:00
|
|
|
|
|
|
|
This is why it's included as a binary in the repo, but yes, it's redundant with
|
|
|
|
the source code.
|
|
|
|
|
2019-05-20 12:11:45 -04:00
|
|
|
Those binaries can be updated with the `make updatebootstrap` command. If they
|
|
|
|
are up-to date and that zasm isn't broken, this command should output the same
|
|
|
|
binary as before.
|
2019-05-09 12:58:41 -04:00
|
|
|
|
2019-12-13 17:38:40 -05:00
|
|
|
## avra
|
|
|
|
|
|
|
|
In the `zasm` folder, there's also `avra` which is a zasm compiled as an AVR
|
|
|
|
assembler. It works the same way as zasm except it expects AVR mnemonics and
|
|
|
|
spits AVR binaries.
|
|
|
|
|
2019-05-20 12:11:45 -04:00
|
|
|
## runbin
|
2019-05-09 12:58:41 -04:00
|
|
|
|
2019-05-20 12:11:45 -04:00
|
|
|
This is a very simple tool that reads binary z80 code from stdin, loads it in
|
|
|
|
memory starting at address 0 and then run the code until it halts. The exit
|
|
|
|
code of the program is the value of `A` when the program halts.
|
2019-05-09 12:58:41 -04:00
|
|
|
|
2019-05-20 12:11:45 -04:00
|
|
|
This is used for unit tests.
|
2019-11-23 15:22:26 -05:00
|
|
|
|
2020-03-24 13:46:05 -04:00
|
|
|
## forth
|
|
|
|
|
|
|
|
Collapse OS' Forth interpreter, which will probably soon replace the whole OS.
|
|
|
|
|
|
|
|
At this point, it is not yet entirely self-hosting, but will be eventually.
|
|
|
|
Because of that aim, it currently builds in a particular manner.
|
|
|
|
|
|
|
|
There are 3 build stages.
|
|
|
|
|
|
|
|
**Stage 0**: This stage is created with zasm by assembling `forth/forth.asm`
|
|
|
|
through `stage0.asm`. This yields `forth0.bin`. We then wrap this binary with
|
|
|
|
`stage.c` to create the `stage1` binary, which allows us to get to the next
|
|
|
|
stage.
|
|
|
|
|
|
|
|
The long term goal is to gradually extract contents from `forth.asm` and have
|
|
|
|
nothing but Forth source files.
|
|
|
|
|
|
|
|
**Stage 1**: The `stage1` binary allows us to augment `forth0.bin` with
|
|
|
|
contents from `z80c.fs`, which compiles native words using Forth's Z80
|
|
|
|
assembler. This yields `z80c.bin`.
|
|
|
|
|
|
|
|
This is where there's a chiken-and-egg issue: Forth's assembler needs our full
|
|
|
|
Forth interpreter, but that interpreter needs native words from `z80c.fs`. This
|
|
|
|
is why `z80c.bin` is committed into the git repo and it's built automatically
|
|
|
|
with `make`. Updating `z80c.bin` is a specific make rule, `fbootstrap`.
|
|
|
|
|
|
|
|
Then, from there, we augment `forth0.bin` with `z80c.bin` and yield
|
|
|
|
`forth1.bin`, from which we create `stage2`.
|
|
|
|
|
|
|
|
**Stage 2**: From there, the way is clear to compile the dict of our full Forth
|
|
|
|
interpreter, which we do using `stage2` and produce `forth2.bin`, from which we
|
|
|
|
can create our final `forth` executable.
|
|
|
|
|
2019-11-23 15:22:26 -05:00
|
|
|
## Problems?
|
|
|
|
|
|
|
|
If the libz80-wrapped zasm executable works badly (hangs, spew garbage, etc.),
|
|
|
|
it's probably because you've broken your bootstrap binaries. They're easy to
|
|
|
|
mistakenly break. To verify if you've done that, look at your git status. If
|
|
|
|
`kernel.bin` or `zasm.bin` are modified, try resetting them and then run
|
|
|
|
`make clean all`. Things should go better afterwards.
|
|
|
|
|
|
|
|
If that doesn't work, there's also the nuclear option of `git reset --hard`
|
|
|
|
and `git clean -fxd`.
|
|
|
|
|
|
|
|
If that still doesn't work, it might be because the current commit you're on
|
|
|
|
is broken, but that is rather rare: the repo on Github is plugged on Travis
|
|
|
|
and it checks that everything is smooth.
|