summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorH. Peter Anvin (Intel) <hpa@zytor.com>2019-04-24 11:14:43 -0700
committerH. Peter Anvin (Intel) <hpa@zytor.com>2019-04-24 11:14:43 -0700
commit9bb55bd1276822565f111f0bb347024b7e08df5b (patch)
tree4582a8ab5ea1dbbe5fc60484fc9518a426b29797 /doc
parent982186a1a3139763f2aa2710b32236009f64270d (diff)
parent8b262474424c0f6912b22bbf7452f26bfa4d1235 (diff)
downloadnasm-9bb55bd1276822565f111f0bb347024b7e08df5b.tar.gz
Merge branch 'evalmacro'
Resolved Conflicts: asm/preproc.c output/elf.h output/outelf.c output/outelf.h version Signed-off-by: H. Peter Anvin (Intel) <hpa@zytor.com>
Diffstat (limited to 'doc')
-rw-r--r--doc/changes.src8
-rw-r--r--doc/nasmdoc.src136
2 files changed, 98 insertions, 46 deletions
diff --git a/doc/changes.src b/doc/changes.src
index ad539676..eec64bca 100644
--- a/doc/changes.src
+++ b/doc/changes.src
@@ -18,6 +18,14 @@ since 2007.
\b Suppress nuisance "\c{label changed during code generation}" messages
after a real error.
+\b Add support for the \c{merge} and \c{strings} attributes on ELF
+sections. See \k{elfsect}.
+
+\b Add support for the \c{note}, \c{preinit_array}, \c{init_array},
+and \c{fini_array} sections type in ELF. See \k{elfsect}.
+
+\b Handle more than 32,633 sections in ELF.
+
\S{cl-2.14.02} Version 2.14.02
\b Fix crash due to multiple errors or warnings during the code
diff --git a/doc/nasmdoc.src b/doc/nasmdoc.src
index a8559d46..015dbcc2 100644
--- a/doc/nasmdoc.src
+++ b/doc/nasmdoc.src
@@ -122,15 +122,14 @@
\IR{- opunary} \c{-} operator, unary
\IR{! opunary} \c{!} operator, unary
\IR{alignment, in bin sections} alignment, in \c{bin} sections
-\IR{alignment, in elf sections} alignment, in \c{elf} sections
+\IR{alignment, in elf sections} alignment, in ELF sections
\IR{alignment, in win32 sections} alignment, in \c{win32} sections
-\IR{alignment, of elf common variables} alignment, of \c{elf} common
+\IR{alignment, of elf common variables} alignment, of ELF common
variables
\IR{alignment, in obj sections} alignment, in \c{obj} sections
\IR{a.out, bsd version} \c{a.out}, BSD version
\IR{a.out, linux version} \c{a.out}, Linux version
-\IR{autoconf} Autoconf
-\IR{bin} bin
+\IR{bin} \c{bin} output format
\IR{bitwise and} bitwise AND
\IR{bitwise or} bitwise OR
\IR{bitwise xor} bitwise XOR
@@ -150,8 +149,8 @@ variables
\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}
-\IR{common, elf extensions to} \c{COMMON}, \c{elf} extensions to
+in ELF
+\IR{common, elf extensions to} \c{COMMON}, ELF extensions to
\IR{common, obj extensions to} \c{COMMON}, \c{obj} extensions to
\IR{declaring structure} declaring structures
\IR{default-wrt mechanism} default-\c{WRT} mechanism
@@ -165,7 +164,8 @@ in \c{elf}
\IA{effective address}{effective addresses}
\IA{effective-address}{effective addresses}
\IR{elf} ELF
-\IR{elf, 16-bit code and} ELF, 16-bit code and
+\IR{elf, 16-bit code} ELF, 16-bit code
+\IR{elf, debug formats} ELF, debug formats
\IR{elf shared libraries} ELF, shared libraries
\IR{elf32} \c{elf32}
\IR{elf64} \c{elf64}
@@ -181,7 +181,7 @@ in \c{elf}
\IR{functions, pascal calling convention} functions, Pascal calling
convention
\IR{global, aoutb extensions to} \c{GLOBAL}, \c{aoutb} extensions to
-\IR{global, elf extensions to} \c{GLOBAL}, \c{elf} extensions to
+\IR{global, elf extensions to} \c{GLOBAL}, ELF extensions to
\IR{global, rdf extensions to} \c{GLOBAL}, \c{rdf} extensions to
\IR{got} GOT
\IR{got relocations} \c{GOT} relocations
@@ -238,16 +238,16 @@ convention
Object File Format
\IR{relocations, pic-specific} relocations, PIC-specific
\IA{repeating}{repeating code}
-\IR{section alignment, in elf} section alignment, in \c{elf}
+\IR{section alignment, in elf} section alignment, in ELF
\IR{section alignment, in bin} section alignment, in \c{bin}
\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, elf extensions to} \c{SECTION}, 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}
-\IR{segment, obj extensions to} \c{SEGMENT}, \c{elf} extensions to
+\IR{segment, obj extensions to} \c{SEGMENT}, ELF extensions to
\IR{segment names, borland pascal} segment names, Borland Pascal
\IR{shift command} \c{shift} command
\IA{sib}{sib byte}
@@ -259,6 +259,8 @@ Object File Format
\IR{symbols, exporting from dlls} symbols, exporting from DLLs
\IR{symbols, importing from dlls} symbols, importing from DLLs
\IR{test subdirectory} \c{test} subdirectory
+\IR{thread local storage in elf} thread local storage, in ELF
+\IR{thread local storage in mach-o} thread local storage, in \c{macho}
\IR{tlink} \c{TLINK}
\IR{underscore, in c symbols} underscore, in C symbols
\IR{unicode} Unicode
@@ -295,16 +297,16 @@ Object File Format
The Netwide Assembler, NASM, is an 80x86 and x86-64 assembler designed
for portability and modularity. It supports a range of object file
-formats, including Linux and \c{*BSD} \c{a.out}, \c{ELF}, \c{COFF},
-\c{Mach-O}, 16-bit and 32-bit \c{OBJ} (OMF) format, \c{Win32} and
-\c{Win64}. It will also output plain binary files, Intel hex and
+formats, including Linux and *BSD \c{a.out}, ELF, Mach-O, 16-bit and
+32-bit \c{.obj} (OMF) format, COFF (including its Win32 and Win64
+variants.) It can also output plain binary files, Intel hex and
Motorola S-Record formats. Its syntax is designed to be simple and
easy to understand, similar to the syntax in the Intel Software
Developer Manual with minimal complexity. It supports all currently
known x86 architectural extensions, and has strong support for macros.
-NASM also comes with a set of utilities for handling the \c{RDOFF}
-custom object-file format.
+NASM also comes with a set of utilities for handling its own RDOFF2
+object-file format.
\S{legal} \i{License} Conditions
@@ -352,7 +354,7 @@ For example,
\c nasm -f elf myfile.asm
-will assemble \c{myfile.asm} into an \c{ELF} object file \c{myfile.o}. And
+will assemble \c{myfile.asm} into an ELF object file \c{myfile.o}. And
\c nasm -f bin myfile.asm -o myfile.com
@@ -374,7 +376,7 @@ The option \c{-hf} will also list the available output file formats,
and what they are.
If you use Linux but aren't sure whether your system is \c{a.out}
-or \c{ELF}, type
+or ELF, type
\c file nasm
@@ -4298,7 +4300,7 @@ operating in 16-bit mode, 32-bit mode or 64-bit mode. The syntax is
\c{BITS XX}, where XX is 16, 32 or 64.
In most cases, you should not need to use \c{BITS} explicitly. The
-\c{aout}, \c{coff}, \c{elf}, \c{macho}, \c{win32} and \c{win64}
+\c{aout}, \c{coff}, \c{elf*}, \c{macho}, \c{win32} and \c{win64}
object formats, which are designed for use in 32-bit or 64-bit
operating systems, all cause NASM to select 32-bit or 64-bit mode,
respectively, by default. The \c{obj} object format allows you
@@ -4575,9 +4577,8 @@ refer to symbols which \e{are} defined in the same module as the
\c ; some code
\c{GLOBAL}, like \c{EXTERN}, allows object formats to define private
-extensions by means of a colon. The \c{elf} object format, for
-example, lets you specify whether global data items are functions or
-data:
+extensions by means of a colon. The ELF object format, for example,
+lets you specify whether global data items are functions or data:
\c global hashlookup:function, hashtable:data
@@ -4608,8 +4609,8 @@ at the same piece of memory.
Like \c{GLOBAL} and \c{EXTERN}, \c{COMMON} supports object-format
specific extensions. For example, the \c{obj} format allows common
-variables to be NEAR or FAR, and the \c{elf} format allows you to
-specify the alignment requirements of a common variable:
+variables to be NEAR or FAR, and the ELF format allows you to specify
+the alignment requirements of a common variable:
\c common commvar 4:near ; works in OBJ
\c common intarray 100:4 ; works in ELF: 4 byte aligned
@@ -4681,7 +4682,7 @@ For example, when mangling local symbols via the generic namespace:
This is useful when the directive is needed to be output format
agnostic.
-The example is also euquivalent to this, when the output format is \c{elf}:
+The example is also euquivalent to this, when the output format is ELF:
\c %pragma elf gprefix _
@@ -5833,8 +5834,8 @@ Format} Object Files
The \c{elf32}, \c{elf64} and \c{elfx32} output formats generate
\c{ELF32 and ELF64} (Executable and Linkable Format) object files, as
used by Linux as well as \i{Unix System V}, including \i{Solaris x86},
-\i{UnixWare} and \i{SCO Unix}. \c{elf} provides a default output
-file-name extension of \c{.o}. \c{elf} is a synonym for \c{elf32}.
+\i{UnixWare} and \i{SCO Unix}. ELF provides a default output
+file-name extension of \c{.o}. \c{elf} is a synonym for \c{elf32}.
The \c{elfx32} format is used for the \i{x32} ABI, which is a 32-bit
ABI with the CPU in 64-bit mode.
@@ -5847,8 +5848,8 @@ target operating system (OSABI). This field can be set by using the
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} 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
@@ -5873,13 +5874,52 @@ not.
\b \i\c{progbits} defines the section to be one with explicit contents
stored in the object file: an ordinary code or data section, for
-example, \i\c{nobits} defines the section to be one with no explicit
+example.
+
+\b \i\c{nobits} defines the section to be one with no explicit
contents given, such as a BSS section.
-\b \c{align=}, used with a trailing number as in \c{obj}, gives the
+\b \i\c{note} indicates that this section contains ELF notes. The
+content of ELF notes are specified using normal assembly instructions;
+it is up to the programmer to ensure these are valid ELF notes.
+
+\b \i\c{preinit_array} indicates that this section contains function
+addresses to be called before any other initialization has happened.
+
+\b \i\c{init_array} indicates that this section contains function
+addresses to be called during initialization.
+
+\b \i\c{fini_array} indicates that this section contains function
+pointers to be called during termination.
+
+\b \I{align, ELF attribute}\c{align=}, used with a trailing number as in \c{obj}, gives the
\I{section alignment, in elf}\I{alignment, in elf sections}alignment
requirements of the section.
+\b \c{byte}, \c{word}, \c{dword}, \c{qword}, \c{tword}, \c{oword},
+\c{yword}, or \c{zword} with an optional \c{*}\i{multiplier} specify
+the fundamental data item size for a section which contains either
+fixed-sized data structures or strings; it also sets a default
+alignment. This is generally used with the \c{strings} and \c{merge}
+attributes (see below.) For example \c{byte*4} defines a unit size of
+4 bytes, with a default alignment of 1; \c{dword} also defines a unit
+size of 4 bytes, but with a default alignment of 4. The \c{align=}
+attribute, if specified, overrides this default alignment.
+
+\b \I{pointer, ELF attribute}\c{pointer} is equivalent to \c{dword}
+for \c{elf32} or \c{elfx32}, and \c{qword} for \c{elf64}.
+
+\b \I{strings, ELF attribute}\c{strings} indicate that this section
+contains exclusively null-terminated strings. By default these are
+assumed to be byte strings, but a size specifier can be used to
+override that.
+
+\b \i\c{merge} indicates that duplicate data elements in this section
+should be merged with data elements from other object files. Data
+elements can be either fixed-sized objects or null-terminatedstrings
+(with the \c{strings} attribute.) A size specifier is required unless
+\c{strings} is specified, in which case the size defaults to \c{byte}.
+
\b \i\c{tls} defines the section to be one which contains
thread local variables.
@@ -5889,24 +5929,28 @@ qualifiers are:
\I\c{.text} \I\c{.rodata} \I\c{.lrodata} \I\c{.data} \I\c{.ldata}
\I\c{.bss} \I\c{.lbss} \I\c{.tdata} \I\c{.tbss} \I\c\{.comment}
-\c section .text progbits alloc exec nowrite align=16
-\c section .rodata progbits alloc noexec nowrite align=4
-\c section .lrodata progbits alloc noexec nowrite align=4
-\c section .data progbits alloc noexec write align=4
-\c section .ldata progbits alloc noexec write align=4
-\c section .bss nobits alloc noexec write align=4
-\c section .lbss nobits alloc noexec write align=4
-\c section .tdata progbits alloc noexec write align=4 tls
-\c section .tbss nobits alloc noexec write align=4 tls
-\c section .comment progbits noalloc noexec nowrite align=1
-\c section other progbits alloc noexec nowrite align=1
+\c section .text progbits alloc exec nowrite align=16
+\c section .rodata progbits alloc noexec nowrite align=4
+\c section .lrodata progbits alloc noexec nowrite align=4
+\c section .data progbits alloc noexec write align=4
+\c section .ldata progbits alloc noexec write align=4
+\c section .bss nobits alloc noexec write align=4
+\c section .lbss nobits alloc noexec write align=4
+\c section .tdata progbits alloc noexec write align=4 tls
+\c section .tbss nobits alloc noexec write align=4 tls
+\c section .comment progbits noalloc noexec nowrite align=1
+\c section .preinit_array preinit_array alloc noexec nowrite pointer
+\c section .init_array init_array alloc noexec nowrite pointer
+\c section .fini_array fini_array alloc noexec nowrite pointer
+\c section .note note noalloc noexec nowrite align=4
+\c section other progbits alloc noexec nowrite align=1
(Any section name other than those in the above table
is treated by default like \c{other} in the above table.
Please note that section names are case sensitive.)
-\S{elfwrt} \i{Position-Independent Code}\I{PIC}: \c{macho} Special
+\S{elfwrt} \i{Position-Independent Code}\I{PIC}: ELF Special
Symbols and \i\c{WRT}
Since \c{ELF} does not support segment-base references, the \c{WRT}
@@ -6044,7 +6088,7 @@ requires that it be aligned on a 4-byte boundary.
\S{elf16} 16-bit code and ELF
-\I{ELF, 16-bit code and}
+\I{ELF, 16-bit code}
The \c{ELF32} specification doesn't provide relocations for 8- and
16-bit values, but the GNU \c{ld} linker adds these as an extension.
@@ -6054,7 +6098,7 @@ be linked as ELF using GNU \c{ld}. If NASM is used with the
these relocations is generated.
\S{elfdbg} Debug formats and ELF
-\I{ELF, Debug formats and}
+\I{ELF, debug formats}
ELF provides debug information in \c{STABS} and \c{DWARF} formats.
Line number information is generated for all executable sections, but please
@@ -8142,7 +8186,7 @@ then the correct first instruction in the code section will not be
seen because the starting point skipped over it. This isn't really
ideal.
-To avoid this, you can specify a `\i\c{synchronisation}' point, or indeed
+To avoid this, you can specify a `\i{synchronisation}' point, or indeed
as many synchronisation points as you like (although NDISASM can
only handle 2147483647 sync points internally). The definition of a sync
point is this: NDISASM guarantees to hit sync points exactly during