From e55c836b5af387054cfb921f2554a1bc8657d91f Mon Sep 17 00:00:00 2001
From: "H. Peter Anvin" <hpa@zytor.com>
Date: Mon, 10 Dec 2007 15:35:28 -0800
Subject: [PATCH] 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.
---
 doc/nasmdoc.src | 18 +++++++++++++
 misc/altreg.inc | 67 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 85 insertions(+)
 create mode 100644 misc/altreg.inc

diff --git a/doc/nasmdoc.src b/doc/nasmdoc.src
index 9638c998..1a2f007b 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 00000000..91e86db6
--- /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