mirror of
https://github.com/hsoft/collapseos.git
synced 2024-11-01 23:30:56 +11:00
128 lines
5.1 KiB
Markdown
128 lines
5.1 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.
|
|
|
|
## shell
|
|
|
|
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.
|
|
|
|
Through that, it becomes easier to develop userspace applications for Collapse
|
|
OS.
|
|
|
|
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`.
|
|
|
|
## 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.
|
|
|
|
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
|
|
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
|
|
once you have that, you can recreate `zasm/zasm.bin` and `zasm/kernel.bin`.
|
|
|
|
This is why it's included as a binary in the repo, but yes, it's redundant with
|
|
the source code.
|
|
|
|
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.
|
|
|
|
## 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.
|
|
|
|
## 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.
|
|
|
|
## 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`
|
|
and `z80c.bin` 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.
|
|
|
|
`z80c.bin` is a "chicken-and-egg" typf of binary that is committed in the repo.
|
|
It is the result of compiling `z80c.fs`, but this needs stage2.
|
|
|
|
**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 fbootstrap`.
|
|
|
|
Normally, running this step should yield the exact same `z80c.bin` as before,
|
|
unless of course you've changed the source.
|
|
|
|
## 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.
|