doc: add cross.txt

This commit is contained in:
Virgil Dupras 2020-09-19 10:32:28 -04:00
parent 6d180f737a
commit 3295f1689e
4 changed files with 78 additions and 8 deletions

View File

@ -1,7 +1,7 @@
Cross compilation program
This programs allows cross compilation of boot binary and
icore. Run "262 LOAD" right before your cross compilation and
core. Run "262 LOAD" right before your cross compilation and
then "270 LOAD" to apply xcomp overrides.
This unit depends on a properly initialized z80a with ORG and

View File

@ -3,7 +3,4 @@ automatically shadowed to allow the harmless inclusion of
this unit. This shadowing has to take place in your xcomp
configuration.
See example in /emul/xcomp.fs
Why limit ourselves to icore? Oh, I've tried cross-compiling
the whole shebang. I tried. And failed. Too dynamic.
See /doc/cross.txt for details.

View File

@ -1,7 +1,7 @@
# Bootstrap guide
You want to deploy Collapse OS on a new system? Read usage.txt
and impl.txt, then continue here.
You want to deploy Collapse OS on a new system? Read usage.txt,
impl.txt, cross.txt, then continue here.
What is Collapse OS? It is a binary placed either in ROM on
in RAM by a bootloader. That binary, when executed, initializes

73
doc/cross.txt Normal file
View File

@ -0,0 +1,73 @@
# Cross-compilation
When Forth words are compiled, they are compiled for the system
currently running. Those compiled words are tricky to relocate
because their wordrefs reference offsets within the running
system.
If you want to deploy to a new system, you need tricks, and
those tricks are located at B260, the cross-compilation toolset.
The mechanism is simple: override ":" so that it adds an offset
to every wordrefs it compiles.
What should that offset be? the beginning of the binary being
built. That offset if the value in the ORG variable, supplied
by the assembler. It's logical: every binary begins with a bit
of assembler, which makes every following Forth word aligned
with this value.
# Dual-CURRENT
Although the principle behind cross-compilation is simple, the
devil's in the details. While building our new binary, we still
need access to a full-fledged Forth interpreter. To allow this,
we'll maintain two CURRENT: the regular one and XCURRENT, the
CURRENT value of the cross-compiled binary.
XCURRENT's value is a *host* address, not a cross one. For
example, if our cross binary begins at offset 0x1000 and the
last word added to it was at offset 0x234, then XCURRENT is
0x1234.
During cross compilation, we constantly switch CURRENT (through
the CURRENT* sysvar, see impl.txt) between the host's and
XCURRENT.
As a general rule, switching happens this way: When interpret-
ing, we're in host mode. When compiling, we're in XCURRENT mode.
When we encounter an IMMEDIATE during compilation, we execute
the *host* version of that word. The reason for this is simple:
any word freshly cross-compiled is utterly un-runable because
its wordrefs are misaligned under the current host.
# xcomp unit
Cross-compilation is achieved through the writing of a cross-
compilation unit of code, xcomp unit for short.
The xcomp toolset at B260 alters core words in a deep way, so
ordering is important. First, we load our tools. Assembler,
xcomp toolset, etc. The xcomp toolset is designed to not over-
shadow core words directly, so initial loading, B262, is harm-
less.
Now is also the time to define some support words that will not
be part of our resulting binary, but will be used during xcomp,
for example, declarations units and macros.
Then, we load B270 to apply xcomp overrides. From this point on.
every defining word is messed up and will produce offsetted
binaries.
At this point, it's critical to set ORG before spitting any-
thing. Boot binaries will usually take care of this, so you
don't have to do it yourself. You just have to make sure that
you load the boot binary right after loading B270.
Then, you spit your content following instructions in
bootstrap.txt.
After you're done, you can run EMPTY to go back to a usable
system.