NASM - The Netwide Assembler (original) (raw)

Chapter 9: Output Formats

NASM is a portable assembler, designed to be able to compile on any ANSI C-supporting platform and produce output to run on a variety of Intel x86 operating systems. For this reason, it has a large number of available output formats, selected using the -f option on the NASM command line. Each of these formats, along with its extensions to the base NASM syntax, is detailed in this chapter.

As stated in section 2.1.1, NASM chooses a default name for your output file based on the input file name and the chosen output format. This will be generated by removing the filename extension (.asm, .s, or whatever you like to use) from the input file name, and substituting an extension defined by the output format. The extensions are given with each format below.

9.1. bin: Flat-Form Binary Output

The bin format does not produce object files: it generates nothing in the output file except the code you wrote. Such `pure binary' files are used by MS-DOS: .COM executables and.SYS device drivers are pure binary files. Pure binary output is also useful for operating system and boot loader development.

The bin format supports multiple section names. For details of how NASM handles sections in the bin format, seesection 9.1.3.

Using the bin format puts NASM by default into 16-bit mode (see section 8.1). In order to usebin to write 32-bit or 64-bit code, such as an OS kernel, you need to explicitly issue the BITS 32 or BITS 64directive.

bin has no default output file name extension: instead, it leaves your file name as it is once the original extension has been removed. Thus, the default is for NASM to assemble binprog.asminto a binary file called binprog.

It is extremely important to understand that the binary output format is simply nothing other than _a linker built into the NASM executable._As such, NASM behaves just as it does when producing any other output format: notably the list file reflects the code output _before_relocation, and the addresses in the list file are addresses relative to the start of the current output section.

9.1.1. ORG: Binary File Program Origin

The bin format provides an additional directive to the list given in chapter 8: ORG. The function of the ORG directive is to specify the origin address which NASM will assume the program begins at when it is loaded into memory.

For example, the following code will generate the longword0x00000104:

    org     0x100 
    dd      label

label:

Unlike the ORG directive provided by MASM-compatible assemblers, which allows you to jump around in the object file and overwrite code you have already generated, NASM's ORG does exactly what the directive says: origin. Its sole function is to specify one offset which is added to all internal address references within the section; it does not permit any of the trickery that MASM's version does. See section 14.1.3 for further comments.

9.1.2. bin Extensions to the SECTION Directive

The bin output format extends the SECTION (orSEGMENT) directive to allow you to specify the alignment requirements of segments. This is done by appending the ALIGNqualifier to the end of the section-definition line. For example,

section .data align=16

switches to the section .data and also specifies that it must be aligned on a 16-byte boundary.

The parameter to ALIGN specifies how many low bits of the section start address must be forced to zero. The alignment value given may be any power of two.

9.1.3. Multisection Support for the bin Format

The bin format allows the use of multiple sections, of arbitrary names, besides the "known" .text,.data, and .bss names.

9.1.4. Map Files

Map files can be generated in -f bin format by means of the[map] option. Map types of all (default),brief, sections, segments, orsymbols may be specified. Output may be directed tostdout (default), stderr, or a specified file. E.g. [map symbols myfile.map]. No "user form" exists, the square brackets must be used.

9.2. ith: Intel Hex Output

The ith file format produces Intel hex-format files. Just as the bin format, this is a flat memory image format with no support for further relocation or linking. It is usually used with ROM programmers and similar utilities.

From a programmer point of view, this behaves identically to the.bin format; the only difference is the encoding of the output. All extensions supported by the bin file format is also supported by the ith file format.

ith provides a default output file-name extension of.ith.

9.3. srec: Motorola S-Records Output

The srec file format produces Motorola S-records files. Just as the bin format, this is a flat memory image format with no support for relocation or linking. It is usually used with ROM programmers and similar utilities.

From a programmer point of view, this behaves identically to the.bin format; the only difference is the encoding of the output. All extensions supported by the bin file format is also supported by the srec file format.

srec provides a default output file-name extension of.srec.

9.4. obj: Microsoft OMF Object Files

The obj file format (NASM calls it obj rather than omf for historical reasons) is the one produced by MASM and TASM, which is typically fed to 16-bit DOS linkers to produce.EXE files. It is also the format used by OS/2.

obj provides a default output file-name extension of.obj.

obj is not exclusively a 16-bit format, though; NASM has full support for the 32-bit extensions to the format. In particular, 32-bitobj format files are used by Borland's Win32 compilers, instead of using Microsoft's newer win32 object file format.

The obj format does not define any special segment names: you can call your segments anything you like. Typical names for segments inobj format files are CODE, DATA andBSS.

If your source file contains code before specifying an explicitSEGMENT directive, then NASM will invent its own segment called __NASMDEFSEG for you.

When you define a segment in an obj file, NASM defines the segment name as a symbol as well, so that you can access the segment address of the segment. So, for example:

segment data

dvar: dw 1234

segment code

function: mov ax,data ; get segment address of data mov ds,ax ; and move it into DS inc word [dvar] ; now this reference will work ret

The obj format also enables the use of the SEGand WRT operators, so that you can write code which does things like

extern foo 

  mov   ax,seg foo            ; get preferred segment of foo 
  mov   ds,ax 
  mov   ax,data               ; a different segment 
  mov   es,ax 
  mov   ax,[ds:foo]           ; this accesses `foo' 
  mov   [es:foo wrt data],bx  ; so does this

9.4.1. obj Extensions to the SEGMENT Directive

The obj output format extends the SEGMENT (orSECTION) directive to allow you to specify various properties of the segment you are defining. This is done by appending extra qualifiers to the end of the segment-definition line. For example,

segment code private align=16

defines the segment code, but also declares it to be a private segment, and requires that the portion of it described in this code module must be aligned on a 16-byte boundary.

The available qualifiers are:

NASM's default segment attributes are PUBLIC,ALIGN=1, no class, no overlay, and USE16.

9.4.2. GROUP: Defining Groups of Segments

The obj format also allows segments to be grouped, so that a single segment register can be used to refer to all the segments in a group. NASM therefore supplies the GROUP directive, whereby you can code

segment data 

    ; some data

segment bss 

    ; some uninitialized data

group dgroup data bss

which will define a group called dgroup to contain the segments data and bss. Like SEGMENT,GROUP causes the group name to be defined as a symbol, so that you can refer to a variable var in the datasegment as var wrt data or as var wrt dgroup, depending on which segment value is currently in your segment register.

If you just refer to var, however, and var is declared in a segment which is part of a group, then NASM will default to giving you the offset of var from the beginning of the_group_, not the segment. Therefore SEG var, also, will return the group base rather than the segment base.

NASM will allow a segment to be part of more than one group, but will generate a warning if you do this. Variables declared in a segment which is part of more than one group will default to being relative to the first group that was defined to contain the segment.

A group does not have to contain any segments; you can still makeWRT references to a group which does not contain the variable you are referring to. OS/2, for example, defines the special groupFLAT with no segments in it.

GROUP is cumulative. The above example can be done like this:

group dgroup data group dgroup bss

9.4.3. UPPERCASE: Disabling Case Sensitivity in Output

Although NASM itself is case sensitive, some OMF linkers are not; therefore it can be useful for NASM to output single-case object files. TheUPPERCASE format-specific directive causes all segment, group and symbol names that are written to the object file to be forced to upper case just before being written. Within a source file, NASM is still case-sensitive; but the object file can be written entirely in upper case if desired.

UPPERCASE is used alone on a line; it requires no parameters.

9.4.4. IMPORT: Importing DLL Symbols

The IMPORT format-specific directive defines a symbol to be imported from a DLL, for use if you are writing a DLL's import library in NASM. You still need to declare the symbol as EXTERN as well as using the IMPORT directive.

The IMPORT directive takes two required parameters, separated by white space, which are (respectively) the name of the symbol you wish to import and the name of the library you wish to import it from. For example:

import  WSAStartup wsock32.dll

A third optional parameter gives the name by which the symbol is known in the library you are importing it from, in case this is not the same as the name you wish the symbol to be known by to your code once you have imported it. For example:

import  asyncsel wsock32.dll WSAAsyncSelect

9.4.5. EXPORT: Exporting DLL Symbols

The EXPORT format-specific directive defines a global symbol to be exported as a DLL symbol, for use if you are writing a DLL in NASM. You still need to declare the symbol as GLOBAL as well as using the EXPORT directive.

EXPORT takes one required parameter, which is the name of the symbol you wish to export, as it was defined in your source file. An optional second parameter (separated by white space from the first) gives the external name of the symbol: the name by which you wish the symbol to be known to programs using the DLL. If this name is the same as the internal name, you may leave the second parameter off.

Further parameters can be given to define attributes of the exported symbol. These parameters, like the second, are separated by white space. If further parameters are given, the external name must also be specified, even if it is the same as the internal name. The available attributes are:

For example:

export  myfunc 
export  myfunc TheRealMoreFormalLookingFunctionName 
export  myfunc myfunc 1234  ; export by ordinal 
export  myfunc myfunc resident parm=23 nodata

9.4.6. ..start: Defining the Program Entry Point

OMF linkers require exactly one of the object files being linked to define the program entry point, where execution will begin when the program is run. If the object file that defines the entry point is assembled using NASM, you specify the entry point by declaring the special symbol ..start at the point where you wish execution to begin.

9.4.7. obj Extensions to the EXTERN Directive

If you declare an external symbol with the directive

extern  foo

then references such as mov ax,foo will give you the offset of foo from its preferred segment base (as specified in whichever module foo is actually defined in). So to access the contents of foo you will usually need to do something like

    mov     ax,seg foo      ; get preferred segment base 
    mov     es,ax           ; move it into ES 
    mov     ax,[es:foo]     ; and use offset `foo' from it

This is a little unwieldy, particularly if you know that an external is going to be accessible from a given segment or group, saydgroup. So if DS already containeddgroup, you could simply code

    mov     ax,[foo wrt dgroup]

However, having to type this every time you want to accessfoo can be a pain; so NASM allows you to declarefoo in the alternative form

extern  foo:wrt dgroup

This form causes NASM to pretend that the preferred segment base offoo is in fact dgroup; so the expressionseg foo will now return dgroup, and the expression foo is equivalent to foo wrt dgroup.

This default-WRT mechanism can be used to make externals appear to be relative to any group or segment in your program. It can also be applied to common variables: see section 9.4.8.

9.4.8. obj Extensions to the COMMON Directive

The obj format allows common variables to be either near or far; NASM allows you to specify which your variables should be by the use of the syntax

common nearvar 2:near ; nearvar' is a near common common farvar 10:far ; and farvar' is far

Far common variables may be greater in size than 64Kb, and so the OMF specification says that they are declared as a number of _elements_of a given size. So a 10-byte far common variable could be declared as ten one-byte elements, five two-byte elements, two five-byte elements or one ten-byte element.

Some OMF linkers require the element size, as well as the variable size, to match when resolving common variables declared in more than one module. Therefore NASM must allow you to specify the element size on your far common variables. This is done by the following syntax:

common c_5by2 10:far 5 ; two five-byte elements common c_2by5 10:far 2 ; five two-byte elements

If no element size is specified, the default is 1. Also, theFAR keyword is not required when an element size is specified, since only far commons may have element sizes at all. So the above declarations could equivalently be

common c_5by2 10:5 ; two five-byte elements common c_2by5 10:2 ; five two-byte elements

In addition to these extensions, the COMMON directive inobj also supports default-WRT specification likeEXTERN does (explained in section 9.4.7). So you can also declare things like

common foo 10:wrt dgroup common bar 16:far 2:wrt data common baz 24:wrt data:6

9.4.9. Embedded File Dependency Information

Since NASM 2.13.02, obj files contain embedded dependency file information. To suppress the generation of dependencies, use

%pragma obj nodepend

9.5. obj2: OS/2 32-bit OMF Object Files

The obj2 output format is the same as objexcept:

The defaults assumed by NASM if you do not specify the qualifiers are:

SECTION .text ALIGN=16 USE32 CLASS=CODE FLAT SECTION .rodata ALIGN=16 USE32 CLASS=CONST FLAT SECTION .data ALIGN=16 USE32 CLASS=DATA FLAT SECTION .bss ALIGN=16 USE32 CLASS=BSS FLAT SECTION CODE ALIGN=16 USE32 CLASS=CODE FLAT SECTION TEXT ALIGN=16 USE32 CLASS=CODE FLAT SECTION CONST ALIGN=16 USE32 CLASS=CONST FLAT SECTION DATA ALIGN=16 USE32 CLASS=DATA FLAT SECTION BSS ALIGN=16 USE32 CLASS=BSS FLAT SECTION STACK ALIGN=16 USE32 CLASS=STACK FLAT SECTION CODE32 ALIGN=16 USE32 CLASS=CODE FLAT SECTION TEXT32 ALIGN=16 USE32 CLASS=CODE FLAT SECTION CONST32 ALIGN=16 USE32 CLASS=CONST FLAT SECTION DATA32 ALIGN=16 USE32 CLASS=DATA FLAT SECTION BSS32 ALIGN=16 USE32 CLASS=BSS FLAT SECTION STACK32 ALIGN=16 USE32 CLASS=STACK FLAT

9.6. win32: Microsoft Win32 Object Files

The win32 output format generates Microsoft Win32 object files, suitable for passing to Microsoft linkers such as Visual C++. Note that Borland Win32 compilers do not use this format, but useobj instead (see section 9.4).

win32 provides a default output file-name extension of.obj.

Note that although Microsoft say that Win32 object files follow theCOFF (Common Object File Format) standard, the object files produced by Microsoft Win32 compilers are not compatible with COFF linkers such as DJGPP's, and vice versa. This is due to a difference of opinion over the precise semantics of PC-relative relocations. To produce COFF files suitable for DJGPP, use NASM's coff output format; conversely, the coff format does not produce object files that Win32 linkers can generate correct output from.

9.6.1. win32 Extensions to the SECTION Directive

Like the obj format, win32 allows you to specify additional information on the SECTION directive line, to control the type and properties of sections you declare. Section types and properties are generated automatically by NASM for the standard section names .text, .data and .bss, but may still be overridden by these qualifiers.

The available qualifiers are:

The "selection" number should be one of theIMAGE_COMDAT_SELECT_* constants fromCOFF format specification; this value controls if the linker allows multiply defined symbols and how it handles them.

The name is the "COMDAT symbol" – basically a new name for the section. So even though you have one section given by the main name (e.g..text), it can actually consist of hundreds of COMDAT sections having their own name (and alignment).

When the "selection" is IMAGE_COMDAT_SELECT_ASSOCIATIVE (5), the following name is the "COMDAT symbol" of the associated COMDAT section; this way you can link a piece of code or data only when another piece of code or data gets actually linked.

The defaults assumed by NASM if you do not specify the above qualifiers are:

section .text code align=16 section .data data align=4 section .rdata rdata align=8 section .bss bss align=4

The win64 format also adds:

section .pdata rdata align=4 section .xdata rdata align=8

Any other section name is treated by default like .text.

9.6.2. win32: Safe Structured Exception Handling

Among other improvements in Windows XP SP2 and Windows Server 2003, Microsoft has introduced the concept of "safe structured exception handling." The general idea is to collect handlers' entry points in a designated read-only table and have SEH entry points verified against this table before exception control is passed to the corresponding handler. In order for an executable module to be equipped with this read-only table, all object modules on linker command line have to comply with certain criteria. If even a single module among them does not, then the table in question is omitted and above mentioned run-time checks will not be performed for the application in question. Table omission is silent by default and therefore can be easily missed. One can instruct the linker to refuse to produce binary without such table by passing the/safeseh command line option.

Without regard to this run-time check, it's natural to expect NASM to be capable of generating modules suitable for /safeseh linking. From the developer's viewpoint the problem is two-fold:

The former can be easily achieved with any NASM version by adding the following line to the source code:

$@feat.00 equ 1

As of version 2.03 NASM adds this absolute symbol automatically, if it is not already present (in which case the developer can choose to assign another value, if desired, for whatever reason).

Registering a custom exception handler on the other hand requires certain "magic." As of version 2.03, an additional safesehdirective is implemented, which instructs the assembler to produce appropriately formatted input data for the above-mentioned "safe exception handler table." Its typical use would be:

section .text extern _MessageBoxA@16 %if ?NASM_VERSION_ID? >= 0x02030000 safeseh handler ; register handler as "safe handler" %endif handler: push DWORD 1 ; MB_OKCANCEL push DWORD caption push DWORD text push DWORD 0 call _MessageBoxA@16 sub eax,1 ; incidentally suits as return value ; for exception handler ret global _main _main: push DWORD handler push DWORD [fs:0] mov DWORD [fs:0],esp ; engage exception handler xor eax,eax mov eax,DWORD[eax] ; cause exception pop DWORD [fs:0] ; disengage exception handler add esp,4 ret text: db 'OK to rethrow, CANCEL to generate core dump',0 caption:db 'SEGV',0

section .drectve info db '/defaultlib:user32.lib /defaultlib:msvcrt.lib '

As you might imagine, it's perfectly possible to produce an .exe binary with the "safe exception handler table" and yet invoke an unregistered exception handler. A handler is invoked by manipulating [fs:0]at run-time, something the linker has no power over. It is therefore important to note that such failure to register a handler's entry point with the safeseh directive will have undesired side effects at run-time. If an exception is raised and an unregistered handler is to be executed, the application is abruptly terminated without any notification whatsoever. One can argue that the system should at least log some kind of "non-safe exception handler in x.exe at address n" message in the event log, but unfortunately the user is left without any clue as to what might have caused the crash.

Finally, all mentions of linker in this paragraph refer to Microsoft linker version 7.x and later. Presence of @feat.00 symbol and input 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.

9.6.3. Debugging formats for Windows

The win32 and win64 formats support the Microsoft CodeView debugging format. Currently CodeView version 8 format is supported (cv8), but newer versions of the CodeView debugger should be able to handle this format as well.

9.7. win64: Microsoft Win64 Object Files

The win64 output format generates Microsoft Win64 object files, which is nearly 100% identical to the win32 object format (section 9.6) with the exception that it is meant to target 64-bit code and the x86-64 platform altogether. This object file is used exactly the same as the win32 object format (section 9.6), in NASM, with regard to this exception.

9.7.1. win64: Writing Position-Independent Code

While REL takes good care of RIP-relative addressing, there is one aspect that is easy to overlook for a Win64 programmer: indirect references. Consider a switch dispatch table:

    jmp     qword [dsptch+rax*8] 
    ...

dsptch: dq case0 dq case1 ...

Even a novice Win64 assembler programmer will soon realize that the code is not 64-bit savvy. Most notably the linker will refuse to link it, showing:

'ADDR32' relocation to '.text' invalid without /LARGEADDRESSAWARE:NO

So [s]he will have to split jmp instruction as following:

    lea     rbx,[rel dsptch] 
    jmp     qword [rbx+rax*8]

What happens behind the scenes is that the effective address inlea is encoded relative to instruction pointer, in a perfectly position-independent manner. But this is only part of the problem! The issue is that in a .dll context, the caseN relocations will make their way to the final module and might have to be adjusted at .dll load time (specifically, when it can't be loaded at the preferred address). When this occurs, pages with such relocations will be rendered private to current process, which kind of undermines the idea of a shared .dll. But not to worry, it's trivial to fix:

    lea     rbx,[rel dsptch] 
    add     rbx,[rbx+rax*8] 
    jmp     rbx 
    ...

dsptch: dq case0-dsptch dq case1-dsptch ...

NASM version 2.03 and later provides another alternative,wrt ..imagebase operator, which returns an offset from base address of the current image, be it .exe or .dll module, hence the name. For those acquainted with PE-COFF format, this base address denotes the start of the IMAGE_DOS_HEADER structure. Here is how to implement a switch statement with these image-relative references:

    lea     rbx,[rel dsptch] 
    mov     eax,[rbx+rax*4] 
    sub     rbx,dsptch wrt ..imagebase 
    add     rbx,rax 
    jmp     rbx 
    ...

dsptch: dd case0 wrt ..imagebase dd case1 wrt ..imagebase

That said, the snippet before last works just fine with any NASM version and is not even Windows specific, which makes this operator unnecessary in this case. The real reason for the wrt ..imagebase operator will become apparent in the next section.

It should be noted that wrt ..imagebase is defined as 32-bit operand only:

    dd      label wrt ..imagebase           ; ok 
    dq      label wrt ..imagebase           ; bad 
    mov     eax,label wrt ..imagebase       ; ok 
    mov     rax,label wrt ..imagebase       ; bad

9.7.2. win64: Structured Exception Handling

Structured exception handing in Win64 is completely different compared to Win32. When an exception occurs, the program counter is noted, and a linker-generated table containing start and end addresses of all the functions (in a given executable module) is traversed and compared to the saved program counter. This is used to identify the correspondingUNWIND_INFO structure. If missing, then the offending subroutine is assumed to be "leaf" and this lookup procedure is instead attempted for its caller. In Win64, a leaf function is a function that does not call any other functions nor modifies any Win64 non-volatile registers, including the stack pointer. The latter ensures that it's possible to identify a leaf function's caller by simply pulling the value from the top of the stack.

While the majority of subroutines written in assembler are not calling any other functions, they may not qualify as "leaf" functions in the Win64 sense. The requirement for non-volatile registers to be unchanged leaves the developer with not more than 7 registers and no stack frame, which is not necessarily what they counted on. Customarily one would meet this requirement by saving non-volatile registers on stack and restoring them upon return. However, if (and only if) an exception is raised at run-time and no UNWIND_INFO structure is associated with such a "leaf" function, the stack unwind procedure will expect to find the caller's return address on the top of the stack immediately followed by its frame. Given that the developer pushed the caller's non-volatile registers onto the stack, the value on top will no longer point to the right place. The developer can attempt to copy the caller's return address to the top of stack, which would work in some very specific circumstances. But unless the developer can guarantee that these circumstances are always met, it's more appropriate to assume the worst, i.e. the stack unwind procedure goes berserk, abruptly terminating without any notification whatsoever (just like in the the Win32 case).

Now that we understand significance of the UNWIND_INFOstructure, let us discuss what is in it and how it is processed. First, it is checked for the presence of a reference to a custom language-specific exception handler. If there is one, then it is invoked. Depending on the return value, execution flow is resumed (exception is said to be "handled"), or the rest of the UNWIND_INFO structure is processed as follows. Aside from an optional reference to a custom handler, it carries information about the current callee's stack frame and where non-volatile registers are saved. The information is detailed enough to be able to reconstruct the contents of the caller's non-volatile registers on entry to the current callee. And so the caller's context is reconstructed, at which point the unwind procedure is repeated, using theUNWIND_INFO structure associated with the caller's instruction pointer. The procedure is repeated recursively until the exception is handled. As a last resort, the system "handles" it by generating a memory dump and terminating the application.

As of this writing, NASM unfortunately does not facilitate generation of above mentioned detailed information about stack frame layout. But as of version 2.03, it implements building blocks for generating structures involved in stack unwinding. Here is a simple example showing how to deploy a custom exception handler for a leaf function:

default rel section .text extern MessageBoxA handler: sub rsp,40 mov rcx,0 lea rdx,[text] lea r8,[caption] mov r9,1 ; MB_OKCANCEL call MessageBoxA sub eax,1 ; incidentally suits as return value ; for exception handler add rsp,40 ret global main main: xor rax,rax mov rax,QWORD[rax] ; cause exception ret main_end: text: db 'OK to rethrow, CANCEL to generate core dump',0 caption:db 'SEGV',0

section .pdata rdata align=4 dd main wrt ..imagebase dd main_end wrt ..imagebase dd xmain wrt ..imagebase section .xdata rdata align=8 xmain: db 9,0,0,0 dd handler wrt ..imagebase section .drectve info db '/defaultlib:user32.lib /defaultlib:msvcrt.lib '

What you see is that the .pdata section contains a single-element table, containing function start and end addresses, along with references to associated UNWIND_INFO structures (only one in this case). The .xdata section contains the referencedUNWIND_INFO structure, describing a function with no frame, but with a designated exception handler. These references are_required_ to be image-relative, which is the real reason for implementing the wrt ..imagebase operator). It should be noted that rdata align=n, as well as wrt ..imagebase, are actually optional in the context of these two segments (they apply even when omitted); all 32-bit references placed into these two segments will be image-relative. This is important to understand, as the developer is allowed to append handler-specific data to theUNWIND_INFO structure, and any 32-bit references that are added may require adjustment to obtain the real pointer.

As already mentioned, in Win64 terms, a leaf function is one that neither calls any other function nor modifies any non-volatile registers, including the stack pointer. But it is not uncommon for the programmer to intend to utilize every single register and sometimes even have a variable stack frame, requiring a more complicatedUNWIND_INFO structure than in the example above. Is there anything one can do with these simpler building blocks, and avoid manually composing fully-fledged UNWIND_INFO structures, which would surely be considered error-prone? Yes, there is. Recall that an exception handler is called first, before the stack layout is analyzed. As it turns out, it is perfectly possible to manipulate current callee's context in a custom handler in a manner that permits further stack unwinding. The general idea is that handler would not actually "handle" the exception, but instead restore the callee's context (restore to state at entry point) and thus mimic a Win64 leaf function. In other words, the handler would effectively undertake part of the unwinding procedure. Consider the following example:

function: mov rax,rsp ; copy rsp to volatile register push r15 ; save non-volatile registers push rbx push rbp mov r11,rsp ; prepare variable stack frame sub r11,rcx and r11,-64 mov QWORD[r11],rax ; check for exceptions mov rsp,r11 ; allocate stack frame mov QWORD[rsp],rax ; save original rsp value magic_point: ... mov r11,QWORD[rsp] ; pull original rsp value mov rbp,QWORD[r11-24] mov rbx,QWORD[r11-16] mov r15,QWORD[r11-8] mov rsp,r11 ; destroy frame ret

The key is that until magic_point, the originalrsp value remains in the chosen volatile register, and no non-volatile register except for rsp is modified. Aftermagic_point, rsp remains constant till the very end of the function. In this case a custom language-specific exception handler would look like this:

EXCEPTION_DISPOSITION handler (EXCEPTION_RECORD *rec,ULONG64 frame, CONTEXT *context,DISPATCHER_CONTEXT *disp) { ULONG64 *rsp; if (context->Rip<(ULONG64)magic_point) rsp = (ULONG64 *)context->Rax; else { rsp = ((ULONG64 **)context->Rsp)[0]; context->Rbp = rsp[-3]; context->Rbx = rsp[-2]; context->R15 = rsp[-1]; } context->Rsp = (ULONG64)rsp; 

memcpy (disp->ContextRecord,context,sizeof(CONTEXT)); 
RtlVirtualUnwind(UNW_FLAG_NHANDLER,disp->ImageBase, 
    dips->ControlPc,disp->FunctionEntry,disp->ContextRecord, 
    &disp->HandlerData,&disp->EstablisherFrame,NULL); 
return ExceptionContinueSearch;

}

As this custom handler allows the example function to mimic a Win64 leaf function, the corresponding UNWIND_INFO structure does not need to contain any information about the stack frame and its layout.

9.8. coff: Common Object File Format

The coff output type produces COFF object files suitable for linking with the DJGPP linker.

coff provides a default output file-name extension of.o.

The coff format supports the same extensions to theSECTION directive as win32 does, except that thealign qualifier and the info section type are not supported.

9.9. macho32 and macho64: Mach Object File Format

The macho32 and macho64 output formts produces Mach-O object files suitable for linking with the MacOS X linker.macho is a synonym for macho32.

macho provides a default output file-name extension of.o.

9.9.1. macho extensions to the SECTION Directive

The macho output format specifies section names in the format "segment,section". No spaces are allowed around the comma. The following flags can also be specified:

The default is data, unless the section name is__text or __bss in which case the default istext or bss, respectively.

For compatibility with other Unix platforms, the following standard names are also supported:

.text = __TEXT,__text text .rodata = __DATA,__const data .data = __DATA,__data data .bss = __DATA,__bss bss

If the .rodata section contains no relocations, it is instead put into the __TEXT,__const section unless this section has already been specified explicitly. However, it is probably better to specify __TEXT,__const and__DATA,__const explicitly as appropriate.

9.9.2. Thread Local Storage in Mach-O: macho special symbols and WRT

Mach-O defines the following special symbols that can be used on the right-hand side of the WRT operator:

9.9.3. macho specific directive subsections_via_symbols

The directive subsections_via_symbols sets theMH_SUBSECTIONS_VIA_SYMBOLS flag in the Mach-O header, that effectively separates a block (or a subsection) based on a symbol. It is often used for eliminating dead codes by a linker.

This directive takes no arguments.

This is a macro implemented as a %pragma. It can also be specified in its %pragma form, in which case it will not affect non-Mach-O builds of the same source code:

 %pragma macho subsections_via_symbols

9.9.4. macho specific directive no_dead_strip

The directive no_dead_strip sets the Mach-OSH_NO_DEAD_STRIP section flag on the section containing a a specific symbol. This directive takes a list of symbols as its arguments.

This is a macro implemented as a %pragma. It can also be specified in its %pragma form, in which case it will not affect non-Mach-O builds of the same source code:

 %pragma macho no_dead_strip symbol...

9.9.5. macho specific extensions to the GLOBAL Directive: private_extern

The directive extension to GLOBAL marks the symbol with limited global scope. For example, you can specify the global symbol with this extension:

global foo:private_extern foo: ; codes

Using with static linker will clear the private extern attribute. But linker option like -keep_private_externs can avoid it.

9.9.6. macho specific directive build_version

The directive build_version generates aLC_BUILD_VERSION load command in the Mach-O header, which allows specifying a target platform, minimum OS version and optionally SDK version. Newer Xcode linker versions warn if this is not present in object files.

This directive takes the target platform name and minimum OS version as arguments, in this form:

build_version macos,10,7

Platform names that make sense for x86 code are macos,iossimulator, tvossimulator andwatchossimulator.

Optionally, a trailing version number and minimum SDK version can also be specified with this syntax:

build_version macos, 10, 14, 0 sdk_version 10, 14, 0

This is a macro implemented as a %pragma. It can also be specified in its %pragma form, in which case it will not affect non-Mach-O builds of the same source code:

 %pragma macho build_version ...

This latter form is also useful on the command line when using the--pragma command-line switch:

 nasm -f macho64 --pragma "macho build_version macos,10,9" ...

9.10. elf32, elf64, elfx32: Executable and Linkable Format Object Files

The elf32, elf64 and elfx32output formats generate ELF32 and ELF64(Executable and Linkable Format) object files, as used by Linux as well as Unix System V, including Solaris x86, UnixWare and SCO Unix. ELF provides a default output file-name extension of .o. elf is a synonym for elf32.

The elfx32 file format is an ELF32 file containing 64-bit x86 code, and is used for the x32 ABI, which runs the CPU in 64-bit mode while using 32-bit values for pointers to reduce memory footprint. Thus, code intended to be used with the x32 ABI should be assembled withBITS 64.

9.10.1. ELF specific directive osabi

The ELF header specifies the application binary interface for the target operating system (OSABI). This field can be set by using theosabi 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.

9.10.2. ELF extensions to the SECTION Directive

Like the obj format, elf allows you to specify additional information on the SECTION directive line, to control the type and properties of sections you declare. Section types and properties are generated automatically by NASM for the standard section names, but may still be overridden by these qualifiers.

The available qualifiers are:

The defaults assumed by NASM if you do not specify the above qualifiers are:

section .text progbits alloc exec nowrite align=16 section .rodata progbits alloc noexec nowrite align=4 section .lrodata progbits alloc noexec nowrite align=4 section .data progbits alloc noexec write align=4 section .ldata progbits alloc noexec write align=4 section .bss nobits alloc noexec write align=4 section .lbss nobits alloc noexec write align=4 section .tdata progbits alloc noexec write align=4 tls section .tbss nobits alloc noexec write align=4 tls section .comment progbits noalloc noexec nowrite align=1 section .preinit_array preinit_array alloc noexec nowrite pointer section .init_array init_array alloc noexec nowrite pointer section .fini_array fini_array alloc noexec nowrite pointer section .note note noalloc noexec nowrite align=4 section other progbits alloc noexec nowrite align=1

(Any section name other than those in the above table is treated by default like other in the above table. Please note that section names are case sensitive.)

9.10.3. Position-Independent Code: ELF Special Symbols and WRT

Since ELF does not support segment-base references, theWRT operator is not used for its normal purpose; therefore NASM's elf output format makes use of WRT for a different purpose, namely the PIC-specific relocation types.

elf defines five special symbols which you can use as the right-hand side of the WRT operator to obtain PIC relocation types. They are ..gotpc, ..gotoff,..got, ..plt and ..sym. Their functions are summarized here:

A fuller explanation of how to use these relocation types to write shared libraries entirely in NASM is given insection 11.2.

9.10.4. Thread Local Storage in ELF: elf Special Symbols and WRT

9.10.5. elf Extensions to the GLOBAL Directive

ELF object files can contain more information about a global symbol than just its address: they can contain the size of the symbol and its type as well. These are not merely debugger conveniences, but are actually necessary when the program being written is a shared library. NASM therefore supports some extensions to the GLOBALdirective, allowing you to specify these features.

You can specify whether a global variable is a function or a data object by suffixing the name with a colon and the word function ordata. (object is a synonym fordata.) For example:

global hashlookup:function, hashtable:data

exports the global symbol hashlookup as a function andhashtable as a data object.

Optionally, you can control the ELF visibility of the symbol. Just add one of the visibility keywords: default,internal, hidden, or protected. The default is default of course. For example, to makehashlookup hidden:

global hashlookup:function hidden

Since version 2.15, it is possible to specify symbols binding. The keywords are: weak to generate weak symbol orstrong. The default is strong.

You can also specify the size of the data associated with the symbol, as a numeric expression (which may involve labels, and even forward references) after the type specifier. Like this:

global hashtable:data (hashtable.end - hashtable)

hashtable: db this,that,theother ; some data here .end:

This makes NASM automatically calculate the length of the table and place that information into the ELF symbol table.

Declaring the type and size of global symbols is necessary when writing shared library code. For more information, seesection 11.2.4.

9.10.6. elf Extensions to the EXTERN Directive

Since version 2.15 it is possible to specify keyword weakto generate weak external reference. Example:

extern weak_ref:weak

9.10.7. elf Extensions to the COMMON Directive

ELF also allows you to specify alignment requirements on common variables. This is done by putting a number (which must be a power of two) after the name and size of the common variable, separated (as usual) by a colon. For example, an array of doublewords would benefit from 4-byte alignment:

common dwordarray 128:4

This declares the total size of the array to be 128 bytes, and requires that it be aligned on a 4-byte boundary.

9.10.8. 16-bit code and ELF

Older versions of the ELF32 specification did not provide relocations for 8- and 16-bit values. It is now part of the formal specification, and any new enough linker should support them.

ELF has currently no support for segmented programming.

9.10.9. Debug formats and ELF

ELF provides debug information in STABS andDWARF formats. Line number information is generated for all executable sections, but please note that only the ".text" section is executable by default.

9.11. aout: Linux a.out Object Files

The aout format generates a.out object files, in the form used by early Linux systems (current Linux systems use ELF, seesection 9.10.) These differ from othera.out object files in that the magic number in the first four bytes of the file is different; also, some implementations ofa.out, for example NetBSD's, support position-independent code, which Linux's implementation does not.

a.out provides a default output file-name extension of.o.

a.out is a very simple object format. It supports no special directives, no special symbols, no use of SEG orWRT, and no extensions to any standard directives. It supports only the three standard section names .text,.data and .bss.

9.12. aoutb: NetBSD/FreeBSD/OpenBSD a.out Object Files

The aoutb format generates a.out object files, in the form used by the various free BSD Unix clones,NetBSD, FreeBSD and OpenBSD. For simple object files, this object format is exactly the same asaout except for the magic number in the first four bytes of the file. However, the aoutb format supports position-independent code in the same way as the elf format, so you can use it to write BSD shared libraries.

aoutb provides a default output file-name extension of.o.

aoutb supports no special directives, no special symbols, and only the three standard section names .text,.data and .bss. However, it also supports the same use of WRT as elf does, to provide position-independent code relocation types. Seesection 9.10.3 for full documentation of this feature.

aoutb also supports the same extensions to theGLOBAL directive as elf does: seesection 9.10.5 for documentation of this.

9.13. as86: Minix/Linux as86 Object Files

The Minix/Linux 16-bit assembler as86 has its own non-standard object file format. Although its companion linkerld86 produces something close to ordinary a.outbinaries as output, the object file format used to communicate betweenas86 and ld86 is not itself a.out.

NASM supports this format, just in case it is useful, asas86. as86 provides a default output file-name extension of .o.

as86 is a very simple object format (from the NASM user's point of view). It supports no special directives, no use ofSEG or WRT, and no extensions to any standard directives. It supports only the three standard section names.text, .data and .bss. The only special symbol supported is ..start.

9.14. dbg: Debugging Format

The dbg format does not output an object file as such; instead, it outputs a text file which contains a complete list of all the transactions between the main body of NASM and the output-format back end module. It is primarily intended to aid people who want to write their own output drivers, so that they can get a clearer idea of the various requests the main program makes of the output driver, and in what order they happen.

For simple files, one can easily use the dbg format like this:

nasm -f dbg filename.asm

which will generate a diagnostic file called filename.dbg. However, this will not work well on files which were designed for a different object format, because each object format defines its own macros (usually user-level forms of directives), and those macros will not be defined in the dbg format. Therefore it can be useful to run NASM twice, in order to do the preprocessing with the native object format selected:

nasm -e -f elf32 -o elfprog.i elfprog.asm nasm -a -f dbg elfprog.i

This preprocesses elfprog.asm into elfprog.i, keeping the elf32 object format selected in order to make sure ELF special directives are converted into primitive form correctly. Then the preprocessed source is fed through the dbg format to generate the final diagnostic output.

This workaround will still typically not work for programs intended forobj format, because the obj SEGMENTand GROUP directives have side effects of defining the segment and group names as symbols; dbg will not do this, so the program will not assemble. You will have to work around that by defining the symbols yourself (using EXTERN, for example) if you really need to get a dbg trace of an obj–specific source file.

dbg accepts any section name and any directives at all, and logs them all to its output file.

dbg accepts and logs any %pragma, but the specific %pragma:

 %pragma dbg maxdump <size>

where <size> is either a number orunlimited, can be used to control the maximum size for dumping the full contents of a rawdata output object.