Document naming of registers in 64-bit mode

Intel's docs diverge from AMD's docs (MASM follow AMD's docs);
formally document what we're doing and include a file of macros in
case someone wants to use alternate names.

2 files changed, 85 insertions, 0 deletions

diff --git a/doc/nasmdoc.src b/doc/nasmdoc.src
index 9638c99..1a2f007 100644
--- a/doc/nasmdoc.src
+++ b/doc/nasmdoc.src
@@ -6376,6 +6376,24 @@ loading a value into a 32-bit register (but not an 8- or 16-bit
 register), the upper 32 bits of the corresponding 64-bit register are
 set to zero.
 
+\H{reg64} Register names in 64-bit mode
+
+NASM uses the following names for general-purpose registers in 64-bit
+mode, for 8-, 16-, 32- and 64-bit references, respecitively:
+
+\c      AL/AH, CL/CH, DL/DH, BL/BH, SPL, BPL, SIL, DIL, R8B-R15B
+\c      AX, CX, DX, BX, SP, BP, SI, DI, R8W-R15W
+\c      EAX, ECX, EDX, EBX, ESP, EBP, ESI, EDI, R8D-R15D
+\c      RAX, RCX, RDX, RBX, RSP, RBP, RSI, RDI, R8-R15
+
+This is consistent with the AMD documentation and most other
+assemblers.  The Intel documentation, however, uses the names
+\c{R8L-R15L} for 8-bit references to the higher registers.  It is
+possible to use those names by definiting them as macros; similarly,
+if one wants to use numeric names for the low 8 registers, define them
+as macros.  See the file \i\c{altreg.inc} in the \c{misc} directory of
+the NASM source distribution.
+
 \H{id64} Immediates and displacements in 64-bit mode
 
 In 64-bit mode, immediates and displacements are generally only 32
diff --git a/misc/altreg.inc b/misc/altreg.inc
new file mode 100644
index 0000000..91e86db
--- /dev/null
+++ b/misc/altreg.inc
@@ -0,0 +1,67 @@
+;;
+;; altreg.inc
+;;
+;; Alternate register names for 64-bit mode
+;;
+
+;;
+;; Intel documents R8L-R15L instead of R8B-R15B
+;; (Warning: this may confuse people with an AT&T-style assembly
+;; background, where "r8l" means R8D, etc.)
+;;
+%idefine r8l  r8b
+%idefine r9l  r9b
+%idefine r10l r10b
+%idefine r11l r11b
+%idefine r12l r12b
+%idefine r13l r13b
+%idefine r14l r14b
+%idefine r15l r15b
+
+;;
+;; Numeric register names for the lower 8 registers
+;;
+%idefine r0  rax
+%idefine r1  rcx
+%idefine r2  rdx
+%idefine r3  rbx
+%idefine r4  rsp
+%idefine r5  rbp
+%idefine r6  rsi
+%idefine r7  rdi
+
+%idefine r0d eax
+%idefine r1d ecx
+%idefine r2d edx
+%idefine r3d ebx
+%idefine r4d esp
+%idefine r5d ebp
+%idefine r6d esi
+%idefine r7d edi
+
+%idefine r0w ax
+%idefine r1w cx
+%idefine r2w dx
+%idefine r3w bx
+%idefine r4w sp
+%idefine r5w bp
+%idefine r6w si
+%idefine r7w di
+
+%idefine r0b al
+%idefine r1b cl
+%idefine r2b dl
+%idefine r3b bl
+%idefine r4b spl
+%idefine r5b bpl
+%idefine r6b sil
+%idefine r7b dil
+
+%idefine r0l al
+%idefine r1l cl
+%idefine r2l dl
+%idefine r3l bl
+%idefine r4l spl
+%idefine r5l bpl
+%idefine r6l sil
+%idefine r7l dil