mirror of
https://github.com/hsoft/collapseos.git
synced 2024-11-05 17:30:55 +11:00
74 lines
2.7 KiB
Markdown
74 lines
2.7 KiB
Markdown
# emul
|
|
|
|
This folder contains a couple of tools running under the [libz80][libz80]
|
|
emulator.
|
|
|
|
## 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.
|
|
|
|
## Build
|
|
|
|
First, make sure that the `libz80` git submodule is checked out. If not, run
|
|
`git submodule init && git submodule update`.
|
|
|
|
After that, you can run `make` and it builds all applications.
|
|
|
|
## forth
|
|
|
|
Collapse OS' Forth interpreter, which is in the process of replacing the
|
|
zasm-based project.
|
|
|
|
The Forth interpreter is entirely self-hosting, that is, it assembles its
|
|
binary with itself.
|
|
|
|
There are 3 build stages.
|
|
|
|
**Stage 0**: At this stage, all we have are our bootstrap binaries, `boot.bin`
|
|
and `z80c.bin`. We concatenate them into `forth0.bin` ans then wrap the
|
|
emulator around it which is named `stage1` (because it builds the stage 1) to
|
|
have a barebone forth interpreter.
|
|
|
|
**Stage 1**: The `stage1` binary allows us to augment `forth0.bin` with
|
|
the compiled dictionary of a full Forth interpreter. We feed it with
|
|
`$(FORTHSRCS)` and then dump the resulting compiled dict.
|
|
|
|
From there, we can create `forth1.bin`, which is wrapped by both the `forth`
|
|
and `stage2` executables. `forth` is the interpreter you'll use.
|
|
|
|
**Stage 2**: `stage2` is used to resolve the chicken-and-egg problem and use
|
|
the power of a full Forth intepreter, including an assembler, to assemble
|
|
`z80c.bin`. This is a manual step executed through `make updatebootstrap`.
|
|
|
|
Normally, running this step should yield the exact same `boot.bin` and
|
|
`z80c.bin` as before, unless of course you've changed the source.
|
|
|
|
## runbin
|
|
|
|
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.
|
|
|
|
This is used for unit tests.
|
|
|
|
## 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
|
|
`boot.bin` or `z80c.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.
|