add tracing of the latest output point in packstring

this is necessary because packstring isn't implemented in terms of pack8, unlike packalign

also add a bunch more magic comments to hex.e, which would be in the wrong place without the semantic change

Force-Push: yes
Change-Id: I422b8d00a07568be5113e005fddaeab82f5ca731

2 files changed, 31 insertions, 2 deletions

diff --git a/hex.e b/hex.e
index 963b82a..ead2dc4 100644
--- a/hex.e
+++ b/hex.e
@@ -17,6 +17,7 @@
 
 ~ (buffer start, output point -- buffer start, output point)
 : output-start-routine
+  ~ : This is the start routine, the first thing that runs when the ELF loads.
   current-offset L!' cold-start
   ~   The basic registers preserved across syscalls are rbx, rsp, rbp.
   ~ To avoid redundant moves, we store the buffer pointer in rbx just once,
@@ -110,6 +111,7 @@
 ~ (output memory start, current output point
 ~  -- output memory start, current output point)
 : output-read-byte
+  ~ : This is the routine named "read-byte".
   current-offset L!' read-byte
   ~ We use self-xor as a concise way to set registers to zero.
   :rax :rax xor-reg64-reg64                 ~ syscall number for sys-read
@@ -129,6 +131,7 @@
 ~ (output memory start, current output point
 ~  -- output memory start, current output point)
 : output-decode-nibble
+  ~ : This is the routine named "decode-nibble".
   current-offset L!' decode-nibble
 
   0x30 :rax sub-reg64-imm8                  ~ ASCII zero
@@ -164,6 +167,7 @@
 ~ (output memory start, current output point
 ~  -- output memory start, current output point)
 : output-exit
+  ~ : This is the routine named "exit".
   current-offset L!' exit
   60 :rax mov-reg64-imm32                   ~ syscall number for sys-exit
   0 :rdi mov-reg64-imm32                    ~ exit code
@@ -177,6 +181,7 @@
 ~ (output memory start, current output point
 ~  -- output memory start, current output point)
 : output-error-handlers
+  ~ : These are the error handler routines.
   current-offset L!' invalid-byte
   L@' origin L@' invalid-byte-message + :rsi mov-reg64-imm64
   L@' invalid-byte-message-size :rdx mov-reg64-imm64
@@ -206,6 +211,7 @@
 ~ (output memory start, current output point
 ~  -- output memory start, current output point)
 : output-messages
+  ~ : These are the message strings.
   current-offset dup L!' invalid-byte-message 3unroll
   s" Invalid byte." packstring
   current-offset 4 roll - L!' invalid-byte-message-size
@@ -233,6 +239,8 @@
   output-decode-nibble
   output-error-handlers
   output-messages
+  ~ :   This is a buffer that's zero in the ELF, but is written to at runtime
+  ~ : and used as a variable.
   current-offset L!' buffer 0 pack64
   current-offset L!' total-size ;
 
diff --git a/transform.e b/transform.e
index 3086968..ce51255 100644
--- a/transform.e
+++ b/transform.e
@@ -2988,7 +2988,7 @@ allocate-transformation-state s" transformation-state" variable
 
         dup hex-output-metadata-entry-type @
         hex-output-metadata-entry-type-string-literal = {
-          newline
+          fresh-line
           ." ~ Null-terminated string literal: "
           0x22 value@ emitstring drop
           dup hex-output-metadata-entry-string @ emitstring
@@ -2999,7 +2999,7 @@ allocate-transformation-state s" transformation-state" variable
 
         dup hex-output-metadata-entry-type @
         hex-output-metadata-entry-type-alignment = {
-          newline
+          fresh-line
           ." ~ Alignment padding to width "
           dup hex-output-metadata-entry-string @ .
           newline
@@ -3215,6 +3215,24 @@ allocate-transformation-state s" transformation-state" variable
     s" dup" find entry-to-execution-token ,
     s" stringlen" find entry-to-execution-token ,
     s" 1+" find entry-to-execution-token ,
+    ~ (output point, string pointer, string length including terminator)
+
+    ~   Before we add the metadata entry, we also want to call hex-pack-trace
+    ~ to make sure latest-output-point gets adjusted for the string.
+    ~ Otherwise, we'd see magic comments in the wrong place.
+    s" 3roll" find entry-to-execution-token ,
+    s" dup" find entry-to-execution-token ,
+    s" lit" find entry-to-execution-token ,
+    4 ,
+    s" unroll" find entry-to-execution-token ,
+    s" swap" find entry-to-execution-token ,
+    s" dup" find entry-to-execution-token ,
+    s" 3unroll" find entry-to-execution-token ,
+    ~ (output point, string pointer, string length including terminator,
+    ~  output point, string length including terminator)
+    ' hex-pack-trace entry-to-execution-token ,
+
+    ~ (output point, string pointer, string length including terminator)
     s" swap" find entry-to-execution-token ,
     ' hex-output-metadata-entry-type-string-literal entry-to-execution-token ,
     s" swap" find entry-to-execution-token ,
@@ -3355,6 +3373,9 @@ allocate-transformation-state s" transformation-state" variable
     s" -" find entry-to-execution-token ,
     ~ (output point, alignment byte width, padding start, padding length)
 
+    ~   This would be the place to put a call to hex-pack-trace, but packalign
+    ~ is implemented using pack8, so it's not necessary.
+
     ' hex-output-metadata-entry-type-alignment entry-to-execution-token ,
     ~ (output point, alignment byte width, padding start, padding length,,
     ~  entry type)