From 7a0a28f4d8b738d305b826b5464b27255dd7def3 Mon Sep 17 00:00:00 2001
From: Irene Knapp <ireneista@irenes.space>
Date: Thu, 10 Sep 2026 06:41:22 -0700
Subject: add some magic comment commands to reorder subitems more generally

these are all fully working and debugged.

they have been used in a principled attempt to get all the parameter orders in amd64.e correct, but that effort needs to be verified carefully, which it hasn't been, yet.

a couple of missing magic comments in elf.e and execution.e were also added.

Force-Push: yes
Change-Id: Id4c48b121a71b4f945ee3718e14a06f07afd7304
---
 amd64.e | 49 +++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 45 insertions(+), 4 deletions(-)

(limited to 'amd64.e')

diff --git a/amd64.e b/amd64.e
index ba78bc4..1a5df04 100644
--- a/amd64.e
+++ b/amd64.e
@@ -518,10 +518,24 @@ s" :cc-greater" keyword
     0 4 :rsp reg64 sib
     ~ : drop-subitem
   } if
+
   ~ The displacement byte.
+  ~
+  ~   When addressing-disp8-reg64 references a source, as in
+  ~ lea-reg64-disp8-reg64, the first two parameters of the assembly word
+  ~ calling it are the source register and the source displacement value. When
+  ~ it references a target or destination, as in mov-disp8-reg64-reg64, the
+  ~ LAST two parameters are the target registera and target displacement
+  ~ value.
+  ~
+  ~   In both cases, the register comes first and the displacement value
+  ~ comes second. When these are used in a comment template without any other
+  ~ rearranging going on, whichever is on the top of the stack will be popped
+  ~ off first. So, we swap them here, thus putting the register on the top.
   swap
   ~ : 1 adjust-length
   ~ : provide-hex8
+  ~ : swap-subitems
   pack8 ;
 
 ~ (output point, reg/op field value, reg/mem field register,
@@ -538,10 +552,13 @@ s" :cc-greater" keyword
     0 4 :rsp reg64 sib
     ~ : drop-subitem
   } if
-  ~ The displacement value.
+
+  ~   The displacement value. This is subject to the same considerations as in
+  ~ addressing-disp8-reg64.
   swap
   ~ : 4 adjust-length
   ~ : provide-hex32
+  ~ : swap-subitems
   pack32 ;
 
 ~ (output point, reg/op field value,
@@ -552,7 +569,17 @@ s" :cc-greater" keyword
   dup :rbp != {
     ~ Reg/mem value 4 means to use an SIB byte (at least, with this mode).
     5 roll 0 6 roll 4 modrm 4 unroll
-    reg64 3unroll reg64 3unroll scalefield 3unroll sib
+    reg64 3unroll reg64 3unroll scalefield 3unroll
+    ~   We want the scale factor to show after the registers, so we put it
+    ~ last on the stack. We also want the base register to show before the
+    ~ index register, so the base comes first.
+    ~
+    ~   Importantly, we have to do this before the sib so it'll count as being
+    ~ inside the span the assembly word's description attaches to.
+    ~
+    ~ : -3 roll-subitems
+    ~ : swap-subitems
+    sib
     exit
   } if
   ." Base parameter to addressing-indexed-reg64 is :rbp." 1 sys-exit ;
@@ -568,7 +595,21 @@ s" :cc-greater" keyword
   swap
   ~ : 1 adjust-length
   ~ : provide-hex8
-  pack8 ;
+  ~
+  ~   We want the parameters to be shown in the order:
+  ~
+  ~ base register, index register, index scale factor, displacement
+  ~
+  ~   So, we put them on the stack in the opposite of that order.
+  ~
+  ~   Importantly, we have to do this before the pack8 so it'll count as being
+  ~ inside the span the assembly word's description attaches to.
+  ~
+  ~ : -4 roll-subitems
+  ~ : -3 roll-subitems
+  ~ : swap-subitems
+  pack8
+  ;
 
 
 ~ Easy instructions
@@ -687,7 +728,7 @@ s" :cc-greater" keyword
 
 ~ (output point, source register, target register -- output point)
 : mov-reg64-reg64
-  ~ : 1 #swap # # mov-reg64-reg64
+  ~ : 1 # # mov-reg64-reg64
   3roll rex-w 0x89 pack8 3unroll
   swap reg64 swap addressing-reg64 ;
 : mov-indirect-reg64-reg64
-- 
cgit 1.4.1