[nasm:nasm-2.15.xx] %use masm: much better documentation

[nasm-bot for H. Peter Anvin (Intel)]

Commit-ID:  be1be3f627d82a1352738eb26c6e53281fc924cc
Gitweb:     http://repo.or.cz/w/nasm.git?a=commitdiff;h=be1be3f627d82a1352738eb26c6e53281fc924cc
Author:     H. Peter Anvin (Intel) <hpa at zytor.com>
AuthorDate: Fri, 10 Jul 2020 02:46:23 -0700
Committer:  H. Peter Anvin (Intel) <hpa at zytor.com>
CommitDate: Fri, 10 Jul 2020 02:46:23 -0700

%use masm: much better documentation

Signed-off-by: H. Peter Anvin (Intel) <hpa at zytor.com>


---
 doc/changes.src   |  3 +++
 doc/nasmdoc.src   | 56 +++++++++++++++++++++++++++++++++++++++++++++++++------
 test/masmdisp.asm |  6 +++++-
 3 files changed, 58 insertions(+), 7 deletions(-)

diff --git a/doc/changes.src b/doc/changes.src
index 3dc85deb..714299d0 100644
--- a/doc/changes.src
+++ b/doc/changes.src
@@ -27,6 +27,9 @@ in \c{%+} tokens at the beginning or end, or multiple ones in a row.
 
 \b Fix macro label capture (\c{%00}, \k{percent00}).
 
+\b Much better documentation for the MASM compatiblity package,
+\c{%use masm} (see \k{pkg_masm}).
+
 \b Portability fixes.
 
 \S{cl-2.15.02} Version 2.15.02
diff --git a/doc/nasmdoc.src b/doc/nasmdoc.src
index 26e4db27..b52f854a 100644
--- a/doc/nasmdoc.src
+++ b/doc/nasmdoc.src
@@ -4664,17 +4664,61 @@ functionality, as intended to be used primarily with machine-generated code.
 It does not include any "programmer-friendly" shortcuts, nor does it in any way
 support ASSUME, symbol typing, or MASM-style structures.
 
-Currently, the MASM compatibility package emulates only the PTR
-keyword and recognize syntax displacement[index] for memory
-operations.
 To enable the package, use the directive:
 
 \c{%use masm}
 
-In addition, NASM now natively supports the MASM \c{?} and
-\c{DUP} syntax for the \c{DB} etc data declaration directives,
-regardless of if this package is included or not. See \k{db}.
+Currently, the MASM compatibility package emulates:
 
+\b The \c{FLAT} and \c{OFFSET} keywords are recognized and ignored.
+
+\b The \c{PTR} keyword signifies a memory reference, as if the
+argument had been put in square brackets:
+
+\c      mov eax,[foo]               ; memory reference
+\c      mov eax,dword ptr foo       ; memory reference
+\c      mov eax,dowrd ptr flat:foo  ; memory reference
+\c      mov eax,offset foo          ; address
+\c      mov eax,foo                 ; address (ambiguous syntax in MASM)
+
+\b The \c{SEGMENT} ... \c{ENDS} syntax:
+
+\c    segname SEGMENT
+\c        ...
+\c    segname ENDS
+
+\b The \c{PROC} ... \c{ENDP} syntax:
+
+\c    procname PROC [FAR]
+\c         ...
+\c    procname ENDP
+
+\> \c{PROC} will also define \c{RET} as a macro expanding to either
+\c{RETF} if \c{FAR} is specified and \c{RETN} otherwise. Any keyword
+after \c{PROC} other than \c{FAR} is ignored.
+
+\b The \c{TBYTE} keyword as an alias for \c{TWORD} (see \k{qsother}).
+
+\b The \c{END} directive is ignored.
+
+\b In 64-bit mode relative addressing is the default (\c{DEFAULT REL},
+see \k{REL & ABS}).
+
+In addition, NASM now natively supports, regardless of whether this
+package is used or not:
+
+\b \c{?} and \c{DUP} syntax for the \c{DB} etc data declaration
+directives (see \k{db}).
+
+\b \c{displacement[base+index]} syntax for memory operations, instead
+of \c{[base+index+displacement]}.
+
+\b \c{seg:[addr]} instead of \c{[seg:addr]} syntax.
+
+\b A pure offset can be given to \c{LEA} without square brackets:
+
+\c      lea rax,[foo]               ; standard syntax
+\c      lea rax,foo                 ; also accepted
 
 \C{directive} \i{Assembler Directives}
 
diff --git a/test/masmdisp.asm b/test/masmdisp.asm
index 295d88d7..c5e9af4f 100644
--- a/test/masmdisp.asm
+++ b/test/masmdisp.asm
@@ -14,6 +14,7 @@ fproc	proc far
 	lea rsi,dword ptr foo
 	lea rsi,[foo]
 	lea rsi,dword [foo]
+	mov rdi,gs:[rbx]
 	ret
 fproc	endp
 
@@ -21,6 +22,8 @@ nproc	proc near
 	mov eax,dword ptr foo
 	mov rdx,offset foo
 	mov ecx,bar[rbx]
+	mov rdi,[gs:foo]
+	mov rdi,qword ptr gs:foo
 	ret
 nproc	endp
 
@@ -31,6 +34,7 @@ nxx	dd 80
 foo	dd 100
 _DATA	ends
 
-_BSS	segment nobits
+	segment _BSS nobits
 bar	resd 100
+xyzzy	dd 64 dup (?)
 _BSS	ends