added section headers and other formatting to all the parts of the hex dump

Force-Push: yes
Change-Id: Ie66d85fd171dfb45d1f3b6869bf94056ec8303af

3 files changed, 72 insertions, 1 deletions

diff --git a/evoke.e b/evoke.e
index ddb6135..1e9e881 100644
--- a/evoke.e
+++ b/evoke.e
@@ -22,6 +22,7 @@ s" source-to-precompile" variable
 
   elf-file-header
   elf-program-header
+
   output-cold-start
   source-to-copy-to-log s" pyrzqxgl" output-warm-start
   source-to-precompile s" pyrzqxgl" label-transform
@@ -35,6 +36,8 @@ s" source-to-precompile" variable
   0 L!' :
   0 L!' ;
   0 L!' ;asm
+  ~ : blank-line
+  ~ : This is the end of the hex dump. Thanks for reading!
   ;
 
 ' all-contents entry-to-execution-token label-loop
diff --git a/execution.e b/execution.e
index 20064af..66f04d1 100644
--- a/execution.e
+++ b/execution.e
@@ -236,6 +236,21 @@
 ~ (output memory start, current output point
 ~  -- output memory start, current output point)
 : output-cold-start
+  ~ : blank-line
+  ~ : blank-line
+  ~ : ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+  ~ : ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+  ~ : ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+  ~ : ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+  ~ : blank-line
+  ~ :   This is the start of the cold-start routine, which is the first code
+  ~ : of any kind the executable runs. It has the responsibility of creating
+  ~ : the Forth execution environment, then invoking the warm-start routine,
+  ~ : which is defined below.
+  ~ : blank-line
+  ~ : blank-line
+  ~ : indent
+
   current-offset L' cold-start set-label
   cld                                      ~ clear the DF flag
 
@@ -389,7 +404,9 @@
   ~   We are about to set up rsi, we did rbp already, and rsp came to us
   ~ already set up. That's all that "next" needs, so take it away!
   L@' warm-start L@' origin + :rsi mov-reg64-imm64
-  pack-next ;
+  pack-next
+  ~ : deindent
+  ;
 
 
 ~ Routine warm-start
@@ -403,6 +420,35 @@
 ~ (output buffer start, output point, input string pointer, delimiter pointer
 ~  -- output buffer start, output point)
 : output-warm-start
+  ~ : blank-line
+  ~ : blank-line
+  ~ : ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+  ~ : ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+  ~ : ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+  ~ : ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+  ~ : blank-line
+  ~ :   This is the start of the warm-start routine, which is the first Forth
+  ~ : code the executable runs, after the cold-start routine has created the
+  ~ : Forth execution environment.
+  ~ :
+  ~ :   It does some initial setup here at the top; then the vast bulk of it
+  ~ : is actually the log-load routine, directly included; then finally there
+  ~ : is a small amount of finishing work done at the tail end of the
+  ~ : warm-start routine.
+  ~ :
+  ~ :   The routine's body is interpreted Forth code, meaning that it is an
+  ~ : an array of pointers to the codewords of Forth words, occasionally
+  ~ : interspersed with literal values.
+  ~ :
+  ~ :   The codeword pointers were located by using the label system, which
+  ~ : means the labels they reference must have been defined somewhere else,
+  ~ : normally by the label transform. The label-transformed code normally
+  ~ : occurs after the warm-start routine in the executable, which means these
+  ~ : are forward references to words defined far below.
+  ~ : blank-line
+  ~ : blank-line
+  ~ : indent
+
   ~   While it's not actually a requirement that codeword pointers be
   ~ word-aligned, it's highly likely that it helps performance. (Whether it
   ~ does is up to Intel's microcode.)
@@ -498,6 +544,10 @@
   log-load-transform
   ~ (output buffer start, output point)
 
+  ~ : blank-line
+  ~ :   We're now done with the log-load routine; the next little bit of code
+  ~ : here is the final bit of the warm-start routine.
+
   ~   Now everything we need has been added to the log and we're almost ready
   ~ to jump into it. It's inconvenient for code under the log-load transform
   ~ to interact with the label system, so if we want to point
@@ -511,6 +561,7 @@
   ~ Get rid of that heap pointer on the stack, we're finally done with it!
   L@' drop offset-to-target-address-space pack64
   L@' execute offset-to-target-address-space pack64
+  ~ : deindent
   ;
 
 
diff --git a/transform.e b/transform.e
index e987689..e6c4af5 100644
--- a/transform.e
+++ b/transform.e
@@ -2604,6 +2604,23 @@ allocate-transformation-state s" transformation-state" variable
 ~ (output buffer start, output point, input string pointer, delimiter pointer
 ~  -- output buffer start, output point)
 : log-load-transform
+  ~ :   This is the start of the log-load routine, which is a long block of
+  ~ : code that has been processed by the log-load transform. It is part of
+  ~ : the warm-start routine, which does other things before and after it.
+  ~ : For clarity's sake, to avoid weird nesting, the section header above
+  ~ : calls this the warm-start section of the executable, but in a sense it
+  ~ : might be more accurate to call it the log-load section.
+  ~ :
+  ~ :   The routine is interpreted Forth code, just as the warm-start routine
+  ~ : as a whole is; see above.
+  ~ :
+  ~ :   The job of the log-load routine is to create runnable code in the
+  ~ : dynamic log, at runtime. The normal way to create a Forth executable
+  ~ : is to use label-transformed code to implement a minimal set of
+  ~ : functionality needed for the log-load routine to run, then invoke the
+  ~ : log-load routine to copy a more complete set of functionality into
+  ~ : memory.
+
   main-input-buffer dup push-input-buffer
   3roll attach-string-to-input-buffer