mirror/nasm
2
0
Fork 0
mirror of https://github.com/netwide-assembler/nasm.git synced 2025-01-24 16:35:40 +08:00
Code Issues Packages Projects Releases Wiki Activity

doc: update documentation for a version 2.12 release

Browse Source 
Add documentation updates for version 2.12.

Signed-off-by: H. Peter Anvin <hpa@linux.intel.com>
This commit is contained in:
H. Peter Anvin 2016-02-18 11:49:33 -08:00
parent 5f0e601f98
commit 277308f1f3
2 changed files with 85 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
doc/changes.src
View File

@ -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.

89
doc/nasmdoc.src
View File

@ -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