doc: update documentation for a version 2.12 release

Add documentation updates for version 2.12.

Signed-off-by: H. Peter Anvin <hpa@linux.intel.com>

2 files changed, 85 insertions, 24 deletions

diff --git a/doc/changes.src b/doc/changes.src
index eab8439d..94ddb9c9 100644
--- a/doc/changes.src
+++ b/doc/changes.src
@@ -9,12 +9,15 @@ since 2007.
 
 \S{cl-2.12} Version 2.12
 
-\b Huge rework of \c{macho} backend (\k{Mach-O}), internal unification
-   of 32 and 64 bit formats and make NASM to handle section
-   alignment properly.
+\b Major fixes to the \c{macho} backend (\k{machofmt}); earlier versions
+   would produce invalid symbols and relocations on a regular basis.
+
+\b Support for thread-local storage in Mach-O.
+
+\b Support for arbitrary sections in Mach-O.
 
 \b Fix wrong negative size treated as a big positive value passed into
-   backend causing nasm to crash.
+   backend causing NASM to crash.
 
 \b Fix handling of zero-extending unsigned relocations, we have been printing
    wrong message and forgot to assign segment with predefined value before
@@ -25,16 +28,19 @@ since 2007.
 
 \b Portability fixes for building NASM with LLVM compiler.
 
-\b Add support of Codeview (\c{cv8}) debug format for \c{win32} and \c{win64}
-   formats in the \c{COFF} backend (\k{coff}).
+\b Add support of Codeview version 8 (\c{cv8}) debug format for
+   \c{win32} and \c{win64} formats in the \c{COFF} backend,
+   see \k{codeview}.
 
 \b Allow 64-bit outputs in 16/32-bit only backends.  Unsigned 64-bit
    relocations are zero-extended from 32-bits with a warning
-   (suppressible via \c{}); signed 64-bit relocations are an arror.
+   (suppressible via \c{-w-zext-reloc}); signed 64-bit relocations are
+   an arror.
 
 \b Line numbers in list files now correspond to the lines in the source
    files, instead of simply being sequential.
 
+
 \S{cl-2.11.09} Version 2.11.09
 
 \b Fix potential stack overwrite in \c{macho32} backend.
diff --git a/doc/nasmdoc.src b/doc/nasmdoc.src
index 00a1a14b..23a273b3 100644
--- a/doc/nasmdoc.src
+++ b/doc/nasmdoc.src
@@ -140,6 +140,7 @@ variables
 \IA{case-sensitive}{case sensitive}
 \IA{case-insensitive}{case sensitive}
 \IA{character constants}{character constant}
+\IR{codeview} CodeView debugging format
 \IR{common object file format} Common Object File Format
 \IR{common variables, alignment in elf} common variables, alignment
 in \c{elf}
@@ -187,7 +188,8 @@ convention
 \IR{logical or} logical OR
 \IR{logical xor} logical XOR
 \IR{mach object file format} Mach, object file format
-\IR{mach-o} Mach-O
+\IA{mach-o}{macho}
+\IR{mach-o} Mach-O, object file format
 \IR{macho32} \c{macho32}
 \IR{macho64} \c{macho64}
 \IR{macos x} MacOS X
@@ -232,6 +234,7 @@ Object File Format
 \IR{section alignment, in obj} section alignment, in \c{obj}
 \IR{section alignment, in win32} section alignment, in \c{win32}
 \IR{section, elf extensions to} \c{SECTION}, \c{elf} extensions to
+\IR{section, macho extensions to} \c{SECTION}, \c{macho} extensions to
 \IR{section, win32 extensions to} \c{SECTION}, \c{win32} extensions to
 \IR{segment alignment, in bin} segment alignment, in \c{bin}
 \IR{segment alignment, in obj} segment alignment, in \c{obj}
@@ -336,7 +339,7 @@ distribution archive, for the license conditions under which you may
 use NASM.  NASM is now under the so-called 2-clause BSD license, also
 known as the simplified BSD license.
 
-Copyright 1996-2011 the NASM Authors - All rights reserved.
+Copyright 1996-2016 the NASM Authors - All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are
@@ -4395,6 +4398,9 @@ output format defaults to 16-bit mode in anticipation of it being
 used most frequently to write DOS \c{.COM} programs, DOS \c{.SYS}
 device drivers and boot loader software.
 
+The \c{BITS} directive can also be used to generate code for a
+different mode than the standard one for the output format.
+
 You do \e{not} need to specify \c{BITS 32} merely in order to use
 32-bit instructions in a 16-bit DOS program; if you do, the
 assembler will generate incorrect code because it will be writing
@@ -5428,6 +5434,14 @@ data for "safe exception handler table" causes no backward
 incompatibilities and "safeseh" modules generated by NASM 2.03 and
 later can still be linked by earlier versions or non-Microsoft linkers.
 
+\S{codeview} Debugging formats for Windows
+\I{Windows debugging formats}
+
+The \c{win32} and \c{win64} formats support the Microsoft CodeView
+debugging format.  Currently CodeView version 8 format is supported
+(\i\c{cv8}), but newer versions of the CodeView debugger should be
+able to handle this format as well.
+
 
 \H{win64fmt} \i\c{win64}: Microsoft Win64 Object Files
 
@@ -5695,12 +5709,58 @@ the \c{info} section type are not supported.
 
 \H{machofmt} \I{Mach-O}\i\c{macho32} and \i\c{macho64}: \i{Mach Object File Format}
 
-The \c{macho32} and \c{macho64} output formts produces \c{Mach-O}
+The \c{macho32} and \c{macho64} output formts produces Mach-O
 object files suitable for linking with the \i{MacOS X} linker.
 \i\c{macho} is a synonym for \c{macho32}.
 
 \c{macho} provides a default output file-name extension of \c{.o}.
 
+\S{machosect} \c{macho} extensions to the \c{SECTION} Directive
+\I{SECTION, macho extensions to}
+
+The \c{macho} output format specifies section names in the format
+"\e{segment}\c{,}\e{section}".  No spaces are allowed around the
+comma.  The following flags can also be specified:
+
+\b \c{data} - this section contains initialized data items
+
+\b \c{text} - this section contains code exclusively
+
+\b \c{mixed} - this section contains both code and data
+
+\b \c{bss} - this section is uninitialized and filled with zero
+
+\b \c{align=}\e{alignment} - specify section alignment
+
+The default is \c{data}, unless the section name is \c{__text} or
+\c{__bss} in which case the default is \c{text} or \c{bss},
+respectively.
+
+For compatibility with other Unix platforms, the following standard
+names are also supported:
+
+\c .text    = __TEXT,__text  text
+\c .rodata  = __DATA,__const data
+\c .data    = __DATA,__data  data
+\c .bss     = __DATA,__bss   bss
+
+If the \c{.rodata} section contains no relocations, it is instead put
+into the \c{__TEXT,__const} section unless this section has already
+been specified explicitly.  However, it is probably better to specify
+\c{__TEXT,__const} and \c{__DATA,__const} explicitly as appropriate.
+
+\S{machotls} \i{Thread Local Storage in Mach-O}\I{TLS}: \c{macho} special
+symbols and \i\c{WRT}
+
+Mach-O defines the following special symbols that can be used on the
+right-hand side of the \c{WRT} operator:
+
+\b \c{..tlvp} is used to specify access to thread-local storage.
+
+\b \c{..gotpcrel} is used to specify references to the Global Offset
+   Table.  The GOT is supported in the \c{macho64} format only.
+
+
 \H{elffmt} \i\c{elf32}, \i\c{elf64}, \i\c{elfx32}: \I{ELF}\I{linux, elf}\i{Executable and Linkable
 Format} Object Files
 
@@ -5715,13 +5775,14 @@ ABI with the CPU in 64-bit mode.
 
 \S{abisect} ELF specific directive \i\c{osabi}
 
-The ELF header specifies the application binary interface for the target operating system (OSABI).
-This field can be set by using the \c{osabi} directive with the numeric value (0-255) of the target
- system. If this directive is not used, the default value will be "UNIX System V ABI" (0) which will work on
- most systems which support ELF.
+The ELF header specifies the application binary interface for the
+target operating system (OSABI).  This field can be set by using the
+\c{osabi} directive with the numeric value (0-255) of the target
+system. If this directive is not used, the default value will be "UNIX
+System V ABI" (0) which will work on most systems which support ELF.
 
-\S{elfsect} \c{elf} Extensions to the \c{SECTION}
-Directive\I{SECTION, elf extensions to}
+\S{elfsect} \c{elf} extensions to the \c{SECTION} Directive
+\I{SECTION, elf extensions to}
 
 Like the \c{obj} format, \c{elf} allows you to specify additional
 information on the \c{SECTION} directive line, to control the type
@@ -5779,15 +5840,9 @@ qualifiers are:
  Please note that section names are case sensitive.)
 
 
-\S{elfwrt} \i{Position-Independent Code}\I{PIC}: \c{elf} Special
+\S{elfwrt} \i{Position-Independent Code}\I{PIC}: \c{macho} Special
 Symbols and \i\c{WRT}
 
-The \c{ELF} specification contains enough features to allow
-position-independent code (PIC) to be written, which makes \i{ELF
-shared libraries} very flexible. However, it also means NASM has to
-be able to generate a variety of ELF specific relocation types in ELF
-object files, if it is to be an assembler which can write PIC.
-
 Since \c{ELF} does not support segment-base references, the \c{WRT}
 operator is not used for its normal purpose; therefore NASM's
 \c{elf} output format makes use of \c{WRT} for a different purpose,
@@ -5836,7 +5891,7 @@ peculiarity of the dynamic linker.
 A fuller explanation of how to use these relocation types to write
 shared libraries entirely in NASM is given in \k{picdll}.
 
-\S{elftls} \i{Thread Local Storage}\I{TLS}: \c{elf} Special
+\S{elftls} \i{Thread Local Storage in ELF}\I{TLS}: \c{elf} Special
 Symbols and \i\c{WRT}
 
 \b In ELF32 mode, referring to an external or global symbol using