zig

commit f7e0ff8a5fb3e8426e8f64bba271eae358d123b4 (tree)
parent b0f222777c38088d90041ba1f28bfb1341cc76c6
Author: mlugg <mlugg@mlugg.co.uk>
Date:   Sat, 20 Sep 2025 15:16:42 +0100

std: clarify cpu_context register order rationale

Diffstat:
M
lib/std/debug/cpu_context.zig
 | 
9
++++++---

1 file changed, 6 insertions(+), 3 deletions(-)
diff --git a/lib/std/debug/cpu_context.zig b/lib/std/debug/cpu_context.zig
@@ -225,8 +225,9 @@ pub fn fromWindowsContext(ctx: *const std.os.windows.CONTEXT) Native {
 }
 
 pub const X86 = struct {
-    /// The first 8 registers here intentionally match the order of registers pushed
-    /// by PUSHA, which is also the order used by the DWARF register mappings.
+    /// The first 8 registers here intentionally match the order of registers in the x86 instruction
+    /// encoding. This order is inherited by the PUSHA instruction and the DWARF register mappings,
+    /// among other things.
     pub const Gpr = enum {
         // zig fmt: off
         eax, ecx, edx, ebx,
@@ -283,7 +284,9 @@ pub const X86 = struct {
 };
 
 pub const X86_64 = struct {
-    /// MLUGG TODO: explain this order. why does DWARF have this?
+    /// The order here intentionally matches the order of the DWARF register mappings. It's unclear
+    /// where those mappings actually originated from---the ordering of the first 4 registers seems
+    /// quite unusual---but it is currently convenient for us to match DWARF.
     pub const Gpr = enum {
         // zig fmt: off
         rax, rdx, rcx, rbx,