|
- # 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.
|