From 3295f1689e7f3a96fa0a50d4ad1fcfd5d0469972 Mon Sep 17 00:00:00 2001 From: Virgil Dupras Date: Sat, 19 Sep 2020 10:32:28 -0400 Subject: [PATCH] doc: add cross.txt --- blk/260 | 2 +- blk/261 | 7 ++--- doc/bootstrap.txt | 4 +-- doc/cross.txt | 73 +++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 78 insertions(+), 8 deletions(-) create mode 100644 doc/cross.txt diff --git a/blk/260 b/blk/260 index 82592d1..7a12010 100644 --- a/blk/260 +++ b/blk/260 @@ -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 diff --git a/blk/261 b/blk/261 index e84e1be..fe70f57 100644 --- a/blk/261 +++ b/blk/261 @@ -1,9 +1,6 @@ Words overrides like ":", "IMMEDIATE" and "CODE" are not automatically shadowed to allow the harmless inclusion of this unit. This shadowing has to take place in your xcomp -configuration. +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. diff --git a/doc/bootstrap.txt b/doc/bootstrap.txt index 07ae87d..270e54e 100644 --- a/doc/bootstrap.txt +++ b/doc/bootstrap.txt @@ -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 diff --git a/doc/cross.txt b/doc/cross.txt new file mode 100644 index 0000000..4d12d7f --- /dev/null +++ b/doc/cross.txt @@ -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.