mirror of
https://github.com/hsoft/collapseos.git
synced 2024-11-01 14:30:55 +11:00
99 lines
3.6 KiB
Plaintext
99 lines
3.6 KiB
Plaintext
# 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.
|
|
|
|
# Immediate compiling words trickyness
|
|
|
|
When using an immediate compiling word such as "IF" during
|
|
xcomp, things are a bit tricky for two reasons:
|
|
|
|
1. Immediates used during xcomp are from the host system.
|
|
2. The reference of the word(s) they compile is for the host
|
|
system.
|
|
|
|
Therefore, unless the compiled word (for example (?br) compiled
|
|
by IF) has exactly the same address in both the host and guest,
|
|
the resulting binary will be broken.
|
|
|
|
For this reason, we re-implement many of those compiling words
|
|
in xcomp overrides, hacking our way through, so that those
|
|
compiling words compile proper guest references. We don't do
|
|
this for all compiling words though. This means that some words
|
|
can't be used in core and drivers, for example, ABORT" and .".
|
|
|
|
How to know whether a word can be used?
|
|
|
|
1. If it's not an immediate compiling word, it's fine.
|
|
2. If its overriden in B270, it's fine.
|
|
3. Otherwise, you can't cross-compile it.
|