diff options
author | H. Peter Anvin <hpa@linux.intel.com> | 2016-02-18 11:49:33 -0800 |
---|---|---|
committer | H. Peter Anvin <hpa@linux.intel.com> | 2016-02-18 11:49:33 -0800 |
commit | 277308f1f3cbd6dba09e560998f7dca7fa7aeaf3 (patch) | |
tree | 06ebe1652cf8e3893ff5576729d9aff096cfab41 | |
parent | 5f0e601f9890e4dc85245c2f2b4178e051c97ea5 (diff) | |
download | nasm-277308f1f3cbd6dba09e560998f7dca7fa7aeaf3.tar.gz |
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>
-rw-r--r-- | doc/changes.src | 20 | ||||
-rw-r--r-- | doc/nasmdoc.src | 89 |
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 |