838 lines
46 KiB
HTML
838 lines
46 KiB
HTML
<html><head><title>NASM Manual</title></head>
|
|
<body><h1 align=center>The Netwide Assembler: NASM</h1>
|
|
|
|
<p align=center><a href="nasmdoc7.html">Next Chapter</a> |
|
|
<a href="nasmdoc5.html">Previous Chapter</a> |
|
|
<a href="nasmdoc0.html">Contents</a> |
|
|
<a href="nasmdoci.html">Index</a>
|
|
<h2><a name="chapter-6">Chapter 6: Output Formats</a></h2>
|
|
<p>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 <code><nobr>-f</nobr></code> option on
|
|
the NASM command line. Each of these formats, along with its extensions to
|
|
the base NASM syntax, is detailed in this chapter.
|
|
<p>As stated in <a href="nasmdoc2.html#section-2.1.1">section 2.1.1</a>,
|
|
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
|
|
extension (<code><nobr>.asm</nobr></code>, <code><nobr>.s</nobr></code>, 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.
|
|
<h3><a name="section-6.1">6.1 <code><nobr>bin</nobr></code>: Flat-Form Binary Output</a></h3>
|
|
<p>The <code><nobr>bin</nobr></code> 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: <code><nobr>.COM</nobr></code>
|
|
executables and <code><nobr>.SYS</nobr></code> device drivers are pure
|
|
binary files. Pure binary output is also useful for operating system and
|
|
boot loader development.
|
|
<p>The <code><nobr>bin</nobr></code> format supports multiple section
|
|
names. For details of how nasm handles sections in the
|
|
<code><nobr>bin</nobr></code> format, see <a href="#section-6.1.3">section
|
|
6.1.3</a>.
|
|
<p>Using the <code><nobr>bin</nobr></code> format puts NASM by default into
|
|
16-bit mode (see <a href="nasmdoc5.html#section-5.1">section 5.1</a>). In
|
|
order to use <code><nobr>bin</nobr></code> to write 32-bit code such as an
|
|
OS kernel, you need to explicitly issue the
|
|
<code><nobr>BITS 32</nobr></code> directive.
|
|
<p><code><nobr>bin</nobr></code> 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
|
|
<code><nobr>binprog.asm</nobr></code> into a binary file called
|
|
<code><nobr>binprog</nobr></code>.
|
|
<h4><a name="section-6.1.1">6.1.1 <code><nobr>ORG</nobr></code>: Binary File Program Origin</a></h4>
|
|
<p>The <code><nobr>bin</nobr></code> format provides an additional
|
|
directive to the list given in <a href="nasmdoc5.html">chapter 5</a>:
|
|
<code><nobr>ORG</nobr></code>. The function of the
|
|
<code><nobr>ORG</nobr></code> directive is to specify the origin address
|
|
which NASM will assume the program begins at when it is loaded into memory.
|
|
<p>For example, the following code will generate the longword
|
|
<code><nobr>0x00000104</nobr></code>:
|
|
<p><pre>
|
|
org 0x100
|
|
dd label
|
|
label:
|
|
</pre>
|
|
<p>Unlike the <code><nobr>ORG</nobr></code> 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
|
|
<code><nobr>ORG</nobr></code> does exactly what the directive says:
|
|
<em>origin</em>. 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
|
|
<a href="nasmdo10.html#section-10.1.3">section 10.1.3</a> for further
|
|
comments.
|
|
<h4><a name="section-6.1.2">6.1.2 <code><nobr>bin</nobr></code> Extensions to the <code><nobr>SECTION</nobr></code> Directive</a></h4>
|
|
<p>The <code><nobr>bin</nobr></code> output format extends the
|
|
<code><nobr>SECTION</nobr></code> (or <code><nobr>SEGMENT</nobr></code>)
|
|
directive to allow you to specify the alignment requirements of segments.
|
|
This is done by appending the <code><nobr>ALIGN</nobr></code> qualifier to
|
|
the end of the section-definition line. For example,
|
|
<p><pre>
|
|
section .data align=16
|
|
</pre>
|
|
<p>switches to the section <code><nobr>.data</nobr></code> and also
|
|
specifies that it must be aligned on a 16-byte boundary.
|
|
<p>The parameter to <code><nobr>ALIGN</nobr></code> 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.
|
|
<h4><a name="section-6.1.3">6.1.3 <code><nobr>Multisection</nobr></code> support for the BIN format.</a></h4>
|
|
<p>The <code><nobr>bin</nobr></code> format allows the use of multiple
|
|
sections, of arbitrary names, besides the "known"
|
|
<code><nobr>.text</nobr></code>, <code><nobr>.data</nobr></code>, and
|
|
<code><nobr>.bss</nobr></code> names.
|
|
<ul>
|
|
<li>Sections may be designated <code><nobr>progbits</nobr></code> or
|
|
<code><nobr>nobits</nobr></code>. Default is
|
|
<code><nobr>progbits</nobr></code> (except <code><nobr>.bss</nobr></code>,
|
|
which defaults to <code><nobr>nobits</nobr></code>, of course).
|
|
<li>Sections can be aligned at a specified boundary following the previous
|
|
section with <code><nobr>align=</nobr></code>, or at an arbitrary
|
|
byte-granular position with <code><nobr>start=</nobr></code>.
|
|
<li>Sections can be given a virtual start address, which will be used for
|
|
the calculation of all memory references within that section with
|
|
<code><nobr>vstart=</nobr></code>.
|
|
<li>Sections can be ordered using
|
|
<code><nobr>follows=</nobr></code><code><nobr><section></nobr></code>
|
|
or
|
|
<code><nobr>vfollows=</nobr></code><code><nobr><section></nobr></code>
|
|
as an alternative to specifying an explicit start address.
|
|
<li>Arguments to <code><nobr>org</nobr></code>,
|
|
<code><nobr>start</nobr></code>, <code><nobr>vstart</nobr></code>, and
|
|
<code><nobr>align=</nobr></code> are critical expressions. See
|
|
<a href="nasmdoc3.html#section-3.8">section 3.8</a>. E.g.
|
|
<code><nobr>align=(1 << ALIGN_SHIFT)</nobr></code> -
|
|
<code><nobr>ALIGN_SHIFT</nobr></code> must be defined before it is used
|
|
here.
|
|
<li>Any code which comes before an explicit
|
|
<code><nobr>SECTION</nobr></code> directive is directed by default into the
|
|
<code><nobr>.text</nobr></code> section.
|
|
<li>If an <code><nobr>ORG</nobr></code> statement is not given,
|
|
<code><nobr>ORG 0</nobr></code> is used by default.
|
|
<li>The <code><nobr>.bss</nobr></code> section will be placed after the
|
|
last <code><nobr>progbits</nobr></code> section, unless
|
|
<code><nobr>start=</nobr></code>, <code><nobr>vstart=</nobr></code>,
|
|
<code><nobr>follows=</nobr></code>, or <code><nobr>vfollows=</nobr></code>
|
|
has been specified.
|
|
<li>All sections are aligned on dword boundaries, unless a different
|
|
alignment has been specified.
|
|
<li>Sections may not overlap.
|
|
<li>Nasm creates the
|
|
<code><nobr>section.<secname>.start</nobr></code> for each section,
|
|
which may be used in your code.
|
|
</ul>
|
|
<h4><a name="section-6.1.4">6.1.4 Map files</a></h4>
|
|
<p>Map files can be generated in <code><nobr>-f bin</nobr></code> format by
|
|
means of the <code><nobr>[map]</nobr></code> option. Map types of
|
|
<code><nobr>all</nobr></code> (default), <code><nobr>brief</nobr></code>,
|
|
<code><nobr>sections</nobr></code>, <code><nobr>segments</nobr></code>, or
|
|
<code><nobr>symbols</nobr></code> may be specified. Output may be directed
|
|
to <code><nobr>stdout</nobr></code> (default),
|
|
<code><nobr>stderr</nobr></code>, or a specified file. E.g.
|
|
<code><nobr>[map symbols myfile.map]</nobr></code>. No "user form" exists,
|
|
the square brackets must be used.
|
|
<h3><a name="section-6.2">6.2 <code><nobr>obj</nobr></code>: Microsoft OMF Object Files</a></h3>
|
|
<p>The <code><nobr>obj</nobr></code> file format (NASM calls it
|
|
<code><nobr>obj</nobr></code> rather than <code><nobr>omf</nobr></code> for
|
|
historical reasons) is the one produced by MASM and TASM, which is
|
|
typically fed to 16-bit DOS linkers to produce
|
|
<code><nobr>.EXE</nobr></code> files. It is also the format used by OS/2.
|
|
<p><code><nobr>obj</nobr></code> provides a default output file-name
|
|
extension of <code><nobr>.obj</nobr></code>.
|
|
<p><code><nobr>obj</nobr></code> is not exclusively a 16-bit format,
|
|
though: NASM has full support for the 32-bit extensions to the format. In
|
|
particular, 32-bit <code><nobr>obj</nobr></code> format files are used by
|
|
Borland's Win32 compilers, instead of using Microsoft's newer
|
|
<code><nobr>win32</nobr></code> object file format.
|
|
<p>The <code><nobr>obj</nobr></code> format does not define any special
|
|
segment names: you can call your segments anything you like. Typical names
|
|
for segments in <code><nobr>obj</nobr></code> format files are
|
|
<code><nobr>CODE</nobr></code>, <code><nobr>DATA</nobr></code> and
|
|
<code><nobr>BSS</nobr></code>.
|
|
<p>If your source file contains code before specifying an explicit
|
|
<code><nobr>SEGMENT</nobr></code> directive, then NASM will invent its own
|
|
segment called <code><nobr>__NASMDEFSEG</nobr></code> for you.
|
|
<p>When you define a segment in an <code><nobr>obj</nobr></code> 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:
|
|
<p><pre>
|
|
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
|
|
</pre>
|
|
<p>The <code><nobr>obj</nobr></code> format also enables the use of the
|
|
<code><nobr>SEG</nobr></code> and <code><nobr>WRT</nobr></code> operators,
|
|
so that you can write code which does things like
|
|
<p><pre>
|
|
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
|
|
</pre>
|
|
<h4><a name="section-6.2.1">6.2.1 <code><nobr>obj</nobr></code> Extensions to the <code><nobr>SEGMENT</nobr></code> Directive</a></h4>
|
|
<p>The <code><nobr>obj</nobr></code> output format extends the
|
|
<code><nobr>SEGMENT</nobr></code> (or <code><nobr>SECTION</nobr></code>)
|
|
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,
|
|
<p><pre>
|
|
segment code private align=16
|
|
</pre>
|
|
<p>defines the segment <code><nobr>code</nobr></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.
|
|
<p>The available qualifiers are:
|
|
<ul>
|
|
<li><code><nobr>PRIVATE</nobr></code>, <code><nobr>PUBLIC</nobr></code>,
|
|
<code><nobr>COMMON</nobr></code> and <code><nobr>STACK</nobr></code>
|
|
specify the combination characteristics of the segment.
|
|
<code><nobr>PRIVATE</nobr></code> segments do not get combined with any
|
|
others by the linker; <code><nobr>PUBLIC</nobr></code> and
|
|
<code><nobr>STACK</nobr></code> segments get concatenated together at link
|
|
time; and <code><nobr>COMMON</nobr></code> segments all get overlaid on top
|
|
of each other rather than stuck end-to-end.
|
|
<li><code><nobr>ALIGN</nobr></code> is used, as shown above, to specify how
|
|
many low bits of the segment start address must be forced to zero. The
|
|
alignment value given may be any power of two from 1 to 4096; in reality,
|
|
the only values supported are 1, 2, 4, 16, 256 and 4096, so if 8 is
|
|
specified it will be rounded up to 16, and 32, 64 and 128 will all be
|
|
rounded up to 256, and so on. Note that alignment to 4096-byte boundaries
|
|
is a PharLap extension to the format and may not be supported by all
|
|
linkers.
|
|
<li><code><nobr>CLASS</nobr></code> can be used to specify the segment
|
|
class; this feature indicates to the linker that segments of the same class
|
|
should be placed near each other in the output file. The class name can be
|
|
any word, e.g. <code><nobr>CLASS=CODE</nobr></code>.
|
|
<li><code><nobr>OVERLAY</nobr></code>, like
|
|
<code><nobr>CLASS</nobr></code>, is specified with an arbitrary word as an
|
|
argument, and provides overlay information to an overlay-capable linker.
|
|
<li>Segments can be declared as <code><nobr>USE16</nobr></code> or
|
|
<code><nobr>USE32</nobr></code>, which has the effect of recording the
|
|
choice in the object file and also ensuring that NASM's default assembly
|
|
mode when assembling in that segment is 16-bit or 32-bit respectively.
|
|
<li>When writing OS/2 object files, you should declare 32-bit segments as
|
|
<code><nobr>FLAT</nobr></code>, which causes the default segment base for
|
|
anything in the segment to be the special group
|
|
<code><nobr>FLAT</nobr></code>, and also defines the group if it is not
|
|
already defined.
|
|
<li>The <code><nobr>obj</nobr></code> file format also allows segments to
|
|
be declared as having a pre-defined absolute segment address, although no
|
|
linkers are currently known to make sensible use of this feature;
|
|
nevertheless, NASM allows you to declare a segment such as
|
|
<code><nobr>SEGMENT SCREEN ABSOLUTE=0xB800</nobr></code> if you need to.
|
|
The <code><nobr>ABSOLUTE</nobr></code> and <code><nobr>ALIGN</nobr></code>
|
|
keywords are mutually exclusive.
|
|
</ul>
|
|
<p>NASM's default segment attributes are <code><nobr>PUBLIC</nobr></code>,
|
|
<code><nobr>ALIGN=1</nobr></code>, no class, no overlay, and
|
|
<code><nobr>USE16</nobr></code>.
|
|
<h4><a name="section-6.2.2">6.2.2 <code><nobr>GROUP</nobr></code>: Defining Groups of Segments</a></h4>
|
|
<p>The <code><nobr>obj</nobr></code> 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
|
|
<code><nobr>GROUP</nobr></code> directive, whereby you can code
|
|
<p><pre>
|
|
segment data
|
|
|
|
; some data
|
|
|
|
segment bss
|
|
|
|
; some uninitialised data
|
|
|
|
group dgroup data bss
|
|
</pre>
|
|
<p>which will define a group called <code><nobr>dgroup</nobr></code> to
|
|
contain the segments <code><nobr>data</nobr></code> and
|
|
<code><nobr>bss</nobr></code>. Like <code><nobr>SEGMENT</nobr></code>,
|
|
<code><nobr>GROUP</nobr></code> causes the group name to be defined as a
|
|
symbol, so that you can refer to a variable <code><nobr>var</nobr></code>
|
|
in the <code><nobr>data</nobr></code> segment as
|
|
<code><nobr>var wrt data</nobr></code> or as
|
|
<code><nobr>var wrt dgroup</nobr></code>, depending on which segment value
|
|
is currently in your segment register.
|
|
<p>If you just refer to <code><nobr>var</nobr></code>, however, and
|
|
<code><nobr>var</nobr></code> is declared in a segment which is part of a
|
|
group, then NASM will default to giving you the offset of
|
|
<code><nobr>var</nobr></code> from the beginning of the <em>group</em>, not
|
|
the <em>segment</em>. Therefore <code><nobr>SEG var</nobr></code>, also,
|
|
will return the group base rather than the segment base.
|
|
<p>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.
|
|
<p>A group does not have to contain any segments; you can still make
|
|
<code><nobr>WRT</nobr></code> references to a group which does not contain
|
|
the variable you are referring to. OS/2, for example, defines the special
|
|
group <code><nobr>FLAT</nobr></code> with no segments in it.
|
|
<h4><a name="section-6.2.3">6.2.3 <code><nobr>UPPERCASE</nobr></code>: Disabling Case Sensitivity in Output</a></h4>
|
|
<p>Although NASM itself is case sensitive, some OMF linkers are not;
|
|
therefore it can be useful for NASM to output single-case object files. The
|
|
<code><nobr>UPPERCASE</nobr></code> 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.
|
|
<p><code><nobr>UPPERCASE</nobr></code> is used alone on a line; it requires
|
|
no parameters.
|
|
<h4><a name="section-6.2.4">6.2.4 <code><nobr>IMPORT</nobr></code>: Importing DLL Symbols</a></h4>
|
|
<p>The <code><nobr>IMPORT</nobr></code> 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
|
|
<code><nobr>EXTERN</nobr></code> as well as using the
|
|
<code><nobr>IMPORT</nobr></code> directive.
|
|
<p>The <code><nobr>IMPORT</nobr></code> 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:
|
|
<p><pre>
|
|
import WSAStartup wsock32.dll
|
|
</pre>
|
|
<p>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:
|
|
<p><pre>
|
|
import asyncsel wsock32.dll WSAAsyncSelect
|
|
</pre>
|
|
<h4><a name="section-6.2.5">6.2.5 <code><nobr>EXPORT</nobr></code>: Exporting DLL Symbols</a></h4>
|
|
<p>The <code><nobr>EXPORT</nobr></code> 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
|
|
<code><nobr>GLOBAL</nobr></code> as well as using the
|
|
<code><nobr>EXPORT</nobr></code> directive.
|
|
<p><code><nobr>EXPORT</nobr></code> 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 <em>external</em> 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.
|
|
<p>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:
|
|
<ul>
|
|
<li><code><nobr>resident</nobr></code> indicates that the exported name is
|
|
to be kept resident by the system loader. This is an optimisation for
|
|
frequently used symbols imported by name.
|
|
<li><code><nobr>nodata</nobr></code> indicates that the exported symbol is
|
|
a function which does not make use of any initialised data.
|
|
<li><code><nobr>parm=NNN</nobr></code>, where <code><nobr>NNN</nobr></code>
|
|
is an integer, sets the number of parameter words for the case in which the
|
|
symbol is a call gate between 32-bit and 16-bit segments.
|
|
<li>An attribute which is just a number indicates that the symbol should be
|
|
exported with an identifying number (ordinal), and gives the desired
|
|
number.
|
|
</ul>
|
|
<p>For example:
|
|
<p><pre>
|
|
export myfunc
|
|
export myfunc TheRealMoreFormalLookingFunctionName
|
|
export myfunc myfunc 1234 ; export by ordinal
|
|
export myfunc myfunc resident parm=23 nodata
|
|
</pre>
|
|
<h4><a name="section-6.2.6">6.2.6 <code><nobr>..start</nobr></code>: Defining the Program Entry Point</a></h4>
|
|
<p><code><nobr>OMF</nobr></code> 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 <code><nobr>..start</nobr></code> at the point where you
|
|
wish execution to begin.
|
|
<h4><a name="section-6.2.7">6.2.7 <code><nobr>obj</nobr></code> Extensions to the <code><nobr>EXTERN</nobr></code> Directive</a></h4>
|
|
<p>If you declare an external symbol with the directive
|
|
<p><pre>
|
|
extern foo
|
|
</pre>
|
|
<p>then references such as <code><nobr>mov ax,foo</nobr></code> will give
|
|
you the offset of <code><nobr>foo</nobr></code> from its preferred segment
|
|
base (as specified in whichever module <code><nobr>foo</nobr></code> is
|
|
actually defined in). So to access the contents of
|
|
<code><nobr>foo</nobr></code> you will usually need to do something like
|
|
<p><pre>
|
|
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
|
|
</pre>
|
|
<p>This is a little unwieldy, particularly if you know that an external is
|
|
going to be accessible from a given segment or group, say
|
|
<code><nobr>dgroup</nobr></code>. So if <code><nobr>DS</nobr></code>
|
|
already contained <code><nobr>dgroup</nobr></code>, you could simply code
|
|
<p><pre>
|
|
mov ax,[foo wrt dgroup]
|
|
</pre>
|
|
<p>However, having to type this every time you want to access
|
|
<code><nobr>foo</nobr></code> can be a pain; so NASM allows you to declare
|
|
<code><nobr>foo</nobr></code> in the alternative form
|
|
<p><pre>
|
|
extern foo:wrt dgroup
|
|
</pre>
|
|
<p>This form causes NASM to pretend that the preferred segment base of
|
|
<code><nobr>foo</nobr></code> is in fact <code><nobr>dgroup</nobr></code>;
|
|
so the expression <code><nobr>seg foo</nobr></code> will now return
|
|
<code><nobr>dgroup</nobr></code>, and the expression
|
|
<code><nobr>foo</nobr></code> is equivalent to
|
|
<code><nobr>foo wrt dgroup</nobr></code>.
|
|
<p>This default-<code><nobr>WRT</nobr></code> 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
|
|
<a href="#section-6.2.8">section 6.2.8</a>.
|
|
<h4><a name="section-6.2.8">6.2.8 <code><nobr>obj</nobr></code> Extensions to the <code><nobr>COMMON</nobr></code> Directive</a></h4>
|
|
<p>The <code><nobr>obj</nobr></code> 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
|
|
<p><pre>
|
|
common nearvar 2:near ; `nearvar' is a near common
|
|
common farvar 10:far ; and `farvar' is far
|
|
</pre>
|
|
<p>Far common variables may be greater in size than 64Kb, and so the OMF
|
|
specification says that they are declared as a number of <em>elements</em>
|
|
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.
|
|
<p>Some <code><nobr>OMF</nobr></code> 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:
|
|
<p><pre>
|
|
common c_5by2 10:far 5 ; two five-byte elements
|
|
common c_2by5 10:far 2 ; five two-byte elements
|
|
</pre>
|
|
<p>If no element size is specified, the default is 1. Also, the
|
|
<code><nobr>FAR</nobr></code> 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
|
|
<p><pre>
|
|
common c_5by2 10:5 ; two five-byte elements
|
|
common c_2by5 10:2 ; five two-byte elements
|
|
</pre>
|
|
<p>In addition to these extensions, the <code><nobr>COMMON</nobr></code>
|
|
directive in <code><nobr>obj</nobr></code> also supports
|
|
default-<code><nobr>WRT</nobr></code> specification like
|
|
<code><nobr>EXTERN</nobr></code> does (explained in
|
|
<a href="#section-6.2.7">section 6.2.7</a>). So you can also declare things
|
|
like
|
|
<p><pre>
|
|
common foo 10:wrt dgroup
|
|
common bar 16:far 2:wrt data
|
|
common baz 24:wrt data:6
|
|
</pre>
|
|
<h3><a name="section-6.3">6.3 <code><nobr>win32</nobr></code>: Microsoft Win32 Object Files</a></h3>
|
|
<p>The <code><nobr>win32</nobr></code> 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
|
|
use <code><nobr>obj</nobr></code> instead (see
|
|
<a href="#section-6.2">section 6.2</a>).
|
|
<p><code><nobr>win32</nobr></code> provides a default output file-name
|
|
extension of <code><nobr>.obj</nobr></code>.
|
|
<p>Note that although Microsoft say that Win32 object files follow the
|
|
<code><nobr>COFF</nobr></code> (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
|
|
<code><nobr>coff</nobr></code> output format; conversely, the
|
|
<code><nobr>coff</nobr></code> format does not produce object files that
|
|
Win32 linkers can generate correct output from.
|
|
<h4><a name="section-6.3.1">6.3.1 <code><nobr>win32</nobr></code> Extensions to the <code><nobr>SECTION</nobr></code> Directive</a></h4>
|
|
<p>Like the <code><nobr>obj</nobr></code> format,
|
|
<code><nobr>win32</nobr></code> allows you to specify additional
|
|
information on the <code><nobr>SECTION</nobr></code> 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 <code><nobr>.text</nobr></code>, <code><nobr>.data</nobr></code> and
|
|
<code><nobr>.bss</nobr></code>, but may still be overridden by these
|
|
qualifiers.
|
|
<p>The available qualifiers are:
|
|
<ul>
|
|
<li><code><nobr>code</nobr></code>, or equivalently
|
|
<code><nobr>text</nobr></code>, defines the section to be a code section.
|
|
This marks the section as readable and executable, but not writable, and
|
|
also indicates to the linker that the type of the section is code.
|
|
<li><code><nobr>data</nobr></code> and <code><nobr>bss</nobr></code> define
|
|
the section to be a data section, analogously to
|
|
<code><nobr>code</nobr></code>. Data sections are marked as readable and
|
|
writable, but not executable. <code><nobr>data</nobr></code> declares an
|
|
initialised data section, whereas <code><nobr>bss</nobr></code> declares an
|
|
uninitialised data section.
|
|
<li><code><nobr>rdata</nobr></code> declares an initialised data section
|
|
that is readable but not writable. Microsoft compilers use this section to
|
|
place constants in it.
|
|
<li><code><nobr>info</nobr></code> defines the section to be an
|
|
informational section, which is not included in the executable file by the
|
|
linker, but may (for example) pass information <em>to</em> the linker. For
|
|
example, declaring an <code><nobr>info</nobr></code>-type section called
|
|
<code><nobr>.drectve</nobr></code> causes the linker to interpret the
|
|
contents of the section as command-line options.
|
|
<li><code><nobr>align=</nobr></code>, used with a trailing number as in
|
|
<code><nobr>obj</nobr></code>, gives the alignment requirements of the
|
|
section. The maximum you may specify is 64: the Win32 object file format
|
|
contains no means to request a greater section alignment than this. If
|
|
alignment is not explicitly specified, the defaults are 16-byte alignment
|
|
for code sections, 8-byte alignment for rdata sections and 4-byte alignment
|
|
for data (and BSS) sections. Informational sections get a default alignment
|
|
of 1 byte (no alignment), though the value does not matter.
|
|
</ul>
|
|
<p>The defaults assumed by NASM if you do not specify the above qualifiers
|
|
are:
|
|
<p><pre>
|
|
section .text code align=16
|
|
section .data data align=4
|
|
section .rdata rdata align=8
|
|
section .bss bss align=4
|
|
</pre>
|
|
<p>Any other section name is treated by default like
|
|
<code><nobr>.text</nobr></code>.
|
|
<h3><a name="section-6.4">6.4 <code><nobr>coff</nobr></code>: Common Object File Format</a></h3>
|
|
<p>The <code><nobr>coff</nobr></code> output type produces
|
|
<code><nobr>COFF</nobr></code> object files suitable for linking with the
|
|
DJGPP linker.
|
|
<p><code><nobr>coff</nobr></code> provides a default output file-name
|
|
extension of <code><nobr>.o</nobr></code>.
|
|
<p>The <code><nobr>coff</nobr></code> format supports the same extensions
|
|
to the <code><nobr>SECTION</nobr></code> directive as
|
|
<code><nobr>win32</nobr></code> does, except that the
|
|
<code><nobr>align</nobr></code> qualifier and the
|
|
<code><nobr>info</nobr></code> section type are not supported.
|
|
<h3><a name="section-6.5">6.5 <code><nobr>elf</nobr></code>: Executable and Linkable Format Object Files</a></h3>
|
|
<p>The <code><nobr>elf</nobr></code> output format generates
|
|
<code><nobr>ELF32</nobr></code> (Executable and Linkable Format) object
|
|
files, as used by Linux as well as Unix System V, including Solaris x86,
|
|
UnixWare and SCO Unix. <code><nobr>elf</nobr></code> provides a default
|
|
output file-name extension of <code><nobr>.o</nobr></code>.
|
|
<h4><a name="section-6.5.1">6.5.1 <code><nobr>elf</nobr></code> Extensions to the <code><nobr>SECTION</nobr></code> Directive</a></h4>
|
|
<p>Like the <code><nobr>obj</nobr></code> format,
|
|
<code><nobr>elf</nobr></code> allows you to specify additional information
|
|
on the <code><nobr>SECTION</nobr></code> 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
|
|
<code><nobr>.text</nobr></code>, <code><nobr>.data</nobr></code> and
|
|
<code><nobr>.bss</nobr></code>, but may still be overridden by these
|
|
qualifiers.
|
|
<p>The available qualifiers are:
|
|
<ul>
|
|
<li><code><nobr>alloc</nobr></code> defines the section to be one which is
|
|
loaded into memory when the program is run.
|
|
<code><nobr>noalloc</nobr></code> defines it to be one which is not, such
|
|
as an informational or comment section.
|
|
<li><code><nobr>exec</nobr></code> defines the section to be one which
|
|
should have execute permission when the program is run.
|
|
<code><nobr>noexec</nobr></code> defines it as one which should not.
|
|
<li><code><nobr>write</nobr></code> defines the section to be one which
|
|
should be writable when the program is run.
|
|
<code><nobr>nowrite</nobr></code> defines it as one which should not.
|
|
<li><code><nobr>progbits</nobr></code> defines the section to be one with
|
|
explicit contents stored in the object file: an ordinary code or data
|
|
section, for example, <code><nobr>nobits</nobr></code> defines the section
|
|
to be one with no explicit contents given, such as a BSS section.
|
|
<li><code><nobr>align=</nobr></code>, used with a trailing number as in
|
|
<code><nobr>obj</nobr></code>, gives the alignment requirements of the
|
|
section.
|
|
</ul>
|
|
<p>The defaults assumed by NASM if you do not specify the above qualifiers
|
|
are:
|
|
<p><pre>
|
|
section .text progbits alloc exec nowrite align=16
|
|
section .rodata progbits alloc noexec nowrite align=4
|
|
section .data progbits alloc noexec write align=4
|
|
section .bss nobits alloc noexec write align=4
|
|
section other progbits alloc noexec nowrite align=1
|
|
</pre>
|
|
<p>(Any section name other than <code><nobr>.text</nobr></code>,
|
|
<code><nobr>.rodata</nobr></code>, <code><nobr>.data</nobr></code> and
|
|
<code><nobr>.bss</nobr></code> is treated by default like
|
|
<code><nobr>other</nobr></code> in the above code.)
|
|
<h4><a name="section-6.5.2">6.5.2 Position-Independent Code: <code><nobr>elf</nobr></code> Special Symbols and <code><nobr>WRT</nobr></code></a></h4>
|
|
<p>The <code><nobr>ELF</nobr></code> specification contains enough features
|
|
to allow position-independent code (PIC) to be written, which makes ELF
|
|
shared libraries very flexible. However, it also means NASM has to be able
|
|
to generate a variety of strange relocation types in ELF object files, if
|
|
it is to be an assembler which can write PIC.
|
|
<p>Since <code><nobr>ELF</nobr></code> does not support segment-base
|
|
references, the <code><nobr>WRT</nobr></code> operator is not used for its
|
|
normal purpose; therefore NASM's <code><nobr>elf</nobr></code> output
|
|
format makes use of <code><nobr>WRT</nobr></code> for a different purpose,
|
|
namely the PIC-specific relocation types.
|
|
<p><code><nobr>elf</nobr></code> defines five special symbols which you can
|
|
use as the right-hand side of the <code><nobr>WRT</nobr></code> operator to
|
|
obtain PIC relocation types. They are <code><nobr>..gotpc</nobr></code>,
|
|
<code><nobr>..gotoff</nobr></code>, <code><nobr>..got</nobr></code>,
|
|
<code><nobr>..plt</nobr></code> and <code><nobr>..sym</nobr></code>. Their
|
|
functions are summarised here:
|
|
<ul>
|
|
<li>Referring to the symbol marking the global offset table base using
|
|
<code><nobr>wrt ..gotpc</nobr></code> will end up giving the distance from
|
|
the beginning of the current section to the global offset table.
|
|
(<code><nobr>_GLOBAL_OFFSET_TABLE_</nobr></code> is the standard symbol
|
|
name used to refer to the GOT.) So you would then need to add
|
|
<code><nobr>$$</nobr></code> to the result to get the real address of the
|
|
GOT.
|
|
<li>Referring to a location in one of your own sections using
|
|
<code><nobr>wrt ..gotoff</nobr></code> will give the distance from the
|
|
beginning of the GOT to the specified location, so that adding on the
|
|
address of the GOT would give the real address of the location you wanted.
|
|
<li>Referring to an external or global symbol using
|
|
<code><nobr>wrt ..got</nobr></code> causes the linker to build an entry
|
|
<em>in</em> the GOT containing the address of the symbol, and the reference
|
|
gives the distance from the beginning of the GOT to the entry; so you can
|
|
add on the address of the GOT, load from the resulting address, and end up
|
|
with the address of the symbol.
|
|
<li>Referring to a procedure name using <code><nobr>wrt ..plt</nobr></code>
|
|
causes the linker to build a procedure linkage table entry for the symbol,
|
|
and the reference gives the address of the PLT entry. You can only use this
|
|
in contexts which would generate a PC-relative relocation normally (i.e. as
|
|
the destination for <code><nobr>CALL</nobr></code> or
|
|
<code><nobr>JMP</nobr></code>), since ELF contains no relocation type to
|
|
refer to PLT entries absolutely.
|
|
<li>Referring to a symbol name using <code><nobr>wrt ..sym</nobr></code>
|
|
causes NASM to write an ordinary relocation, but instead of making the
|
|
relocation relative to the start of the section and then adding on the
|
|
offset to the symbol, it will write a relocation record aimed directly at
|
|
the symbol in question. The distinction is a necessary one due to a
|
|
peculiarity of the dynamic linker.
|
|
</ul>
|
|
<p>A fuller explanation of how to use these relocation types to write
|
|
shared libraries entirely in NASM is given in
|
|
<a href="nasmdoc8.html#section-8.2">section 8.2</a>.
|
|
<h4><a name="section-6.5.3">6.5.3 <code><nobr>elf</nobr></code> Extensions to the <code><nobr>GLOBAL</nobr></code> Directive</a></h4>
|
|
<p><code><nobr>ELF</nobr></code> 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
|
|
<code><nobr>GLOBAL</nobr></code> directive, allowing you to specify these
|
|
features.
|
|
<p>You can specify whether a global variable is a function or a data object
|
|
by suffixing the name with a colon and the word
|
|
<code><nobr>function</nobr></code> or <code><nobr>data</nobr></code>.
|
|
(<code><nobr>object</nobr></code> is a synonym for
|
|
<code><nobr>data</nobr></code>.) For example:
|
|
<p><pre>
|
|
global hashlookup:function, hashtable:data
|
|
</pre>
|
|
<p>exports the global symbol <code><nobr>hashlookup</nobr></code> as a
|
|
function and <code><nobr>hashtable</nobr></code> as a data object.
|
|
<p>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:
|
|
<p><pre>
|
|
global hashtable:data (hashtable.end - hashtable)
|
|
|
|
hashtable:
|
|
db this,that,theother ; some data here
|
|
.end:
|
|
</pre>
|
|
<p>This makes NASM automatically calculate the length of the table and
|
|
place that information into the <code><nobr>ELF</nobr></code> symbol table.
|
|
<p>Declaring the type and size of global symbols is necessary when writing
|
|
shared library code. For more information, see
|
|
<a href="nasmdoc8.html#section-8.2.4">section 8.2.4</a>.
|
|
<h4><a name="section-6.5.4">6.5.4 <code><nobr>elf</nobr></code> Extensions to the <code><nobr>COMMON</nobr></code> Directive </a></h4>
|
|
<p><code><nobr>ELF</nobr></code> 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:
|
|
<p><pre>
|
|
common dwordarray 128:4
|
|
</pre>
|
|
<p>This declares the total size of the array to be 128 bytes, and requires
|
|
that it be aligned on a 4-byte boundary.
|
|
<h4><a name="section-6.5.5">6.5.5 16-bit code and ELF </a></h4>
|
|
<p>The <code><nobr>ELF32</nobr></code> specification doesn't provide
|
|
relocations for 8- and 16-bit values, but the GNU
|
|
<code><nobr>ld</nobr></code> linker adds these as an extension. NASM can
|
|
generate GNU-compatible relocations, to allow 16-bit code to be linked as
|
|
ELF using GNU <code><nobr>ld</nobr></code>. If NASM is used with the
|
|
<code><nobr>-w+gnu-elf-extensions</nobr></code> option, a warning is issued
|
|
when one of these relocations is generated.
|
|
<h3><a name="section-6.6">6.6 <code><nobr>aout</nobr></code>: Linux <code><nobr>a.out</nobr></code> Object Files</a></h3>
|
|
<p>The <code><nobr>aout</nobr></code> format generates
|
|
<code><nobr>a.out</nobr></code> object files, in the form used by early
|
|
Linux systems (current Linux systems use ELF, see
|
|
<a href="#section-6.5">section 6.5</a>.) These differ from other
|
|
<code><nobr>a.out</nobr></code> object files in that the magic number in
|
|
the first four bytes of the file is different; also, some implementations
|
|
of <code><nobr>a.out</nobr></code>, for example NetBSD's, support
|
|
position-independent code, which Linux's implementation does not.
|
|
<p><code><nobr>a.out</nobr></code> provides a default output file-name
|
|
extension of <code><nobr>.o</nobr></code>.
|
|
<p><code><nobr>a.out</nobr></code> is a very simple object format. It
|
|
supports no special directives, no special symbols, no use of
|
|
<code><nobr>SEG</nobr></code> or <code><nobr>WRT</nobr></code>, and no
|
|
extensions to any standard directives. It supports only the three standard
|
|
section names <code><nobr>.text</nobr></code>,
|
|
<code><nobr>.data</nobr></code> and <code><nobr>.bss</nobr></code>.
|
|
<h3><a name="section-6.7">6.7 <code><nobr>aoutb</nobr></code>: NetBSD/FreeBSD/OpenBSD <code><nobr>a.out</nobr></code> Object Files</a></h3>
|
|
<p>The <code><nobr>aoutb</nobr></code> format generates
|
|
<code><nobr>a.out</nobr></code> object files, in the form used by the
|
|
various free <code><nobr>BSD Unix</nobr></code> clones,
|
|
<code><nobr>NetBSD</nobr></code>, <code><nobr>FreeBSD</nobr></code> and
|
|
<code><nobr>OpenBSD</nobr></code>. For simple object files, this object
|
|
format is exactly the same as <code><nobr>aout</nobr></code> except for the
|
|
magic number in the first four bytes of the file. However, the
|
|
<code><nobr>aoutb</nobr></code> format supports position-independent code
|
|
in the same way as the <code><nobr>elf</nobr></code> format, so you can use
|
|
it to write <code><nobr>BSD</nobr></code> shared libraries.
|
|
<p><code><nobr>aoutb</nobr></code> provides a default output file-name
|
|
extension of <code><nobr>.o</nobr></code>.
|
|
<p><code><nobr>aoutb</nobr></code> supports no special directives, no
|
|
special symbols, and only the three standard section names
|
|
<code><nobr>.text</nobr></code>, <code><nobr>.data</nobr></code> and
|
|
<code><nobr>.bss</nobr></code>. However, it also supports the same use of
|
|
<code><nobr>WRT</nobr></code> as <code><nobr>elf</nobr></code> does, to
|
|
provide position-independent code relocation types. See
|
|
<a href="#section-6.5.2">section 6.5.2</a> for full documentation of this
|
|
feature.
|
|
<p><code><nobr>aoutb</nobr></code> also supports the same extensions to the
|
|
<code><nobr>GLOBAL</nobr></code> directive as <code><nobr>elf</nobr></code>
|
|
does: see <a href="#section-6.5.3">section 6.5.3</a> for documentation of
|
|
this.
|
|
<h3><a name="section-6.8">6.8 <code><nobr>as86</nobr></code>: Minix/Linux <code><nobr>as86</nobr></code> Object Files</a></h3>
|
|
<p>The Minix/Linux 16-bit assembler <code><nobr>as86</nobr></code> has its
|
|
own non-standard object file format. Although its companion linker
|
|
<code><nobr>ld86</nobr></code> produces something close to ordinary
|
|
<code><nobr>a.out</nobr></code> binaries as output, the object file format
|
|
used to communicate between <code><nobr>as86</nobr></code> and
|
|
<code><nobr>ld86</nobr></code> is not itself
|
|
<code><nobr>a.out</nobr></code>.
|
|
<p>NASM supports this format, just in case it is useful, as
|
|
<code><nobr>as86</nobr></code>. <code><nobr>as86</nobr></code> provides a
|
|
default output file-name extension of <code><nobr>.o</nobr></code>.
|
|
<p><code><nobr>as86</nobr></code> is a very simple object format (from the
|
|
NASM user's point of view). It supports no special directives, no special
|
|
symbols, no use of <code><nobr>SEG</nobr></code> or
|
|
<code><nobr>WRT</nobr></code>, and no extensions to any standard
|
|
directives. It supports only the three standard section names
|
|
<code><nobr>.text</nobr></code>, <code><nobr>.data</nobr></code> and
|
|
<code><nobr>.bss</nobr></code>.
|
|
<h3><a name="section-6.9">6.9 <code><nobr>rdf</nobr></code>: Relocatable Dynamic Object File Format</a></h3>
|
|
<p>The <code><nobr>rdf</nobr></code> output format produces
|
|
<code><nobr>RDOFF</nobr></code> object files.
|
|
<code><nobr>RDOFF</nobr></code> (Relocatable Dynamic Object File Format) is
|
|
a home-grown object-file format, designed alongside NASM itself and
|
|
reflecting in its file format the internal structure of the assembler.
|
|
<p><code><nobr>RDOFF</nobr></code> is not used by any well-known operating
|
|
systems. Those writing their own systems, however, may well wish to use
|
|
<code><nobr>RDOFF</nobr></code> as their object format, on the grounds that
|
|
it is designed primarily for simplicity and contains very little
|
|
file-header bureaucracy.
|
|
<p>The Unix NASM archive, and the DOS archive which includes sources, both
|
|
contain an <code><nobr>rdoff</nobr></code> subdirectory holding a set of
|
|
RDOFF utilities: an RDF linker, an <code><nobr>RDF</nobr></code>
|
|
static-library manager, an RDF file dump utility, and a program which will
|
|
load and execute an RDF executable under Linux.
|
|
<p><code><nobr>rdf</nobr></code> supports only the standard section names
|
|
<code><nobr>.text</nobr></code>, <code><nobr>.data</nobr></code> and
|
|
<code><nobr>.bss</nobr></code>.
|
|
<h4><a name="section-6.9.1">6.9.1 Requiring a Library: The <code><nobr>LIBRARY</nobr></code> Directive</a></h4>
|
|
<p><code><nobr>RDOFF</nobr></code> contains a mechanism for an object file
|
|
to demand a given library to be linked to the module, either at load time
|
|
or run time. This is done by the <code><nobr>LIBRARY</nobr></code>
|
|
directive, which takes one argument which is the name of the module:
|
|
<p><pre>
|
|
library mylib.rdl
|
|
</pre>
|
|
<h4><a name="section-6.9.2">6.9.2 Specifying a Module Name: The <code><nobr>MODULE</nobr></code> Directive</a></h4>
|
|
<p>Special <code><nobr>RDOFF</nobr></code> header record is used to store
|
|
the name of the module. It can be used, for example, by run-time loader to
|
|
perform dynamic linking. <code><nobr>MODULE</nobr></code> directive takes
|
|
one argument which is the name of current module:
|
|
<p><pre>
|
|
module mymodname
|
|
</pre>
|
|
<p>Note that when you statically link modules and tell linker to strip the
|
|
symbols from output file, all module names will be stripped too. To avoid
|
|
it, you should start module names with <code><nobr>$</nobr></code>, like:
|
|
<p><pre>
|
|
module $kernel.core
|
|
</pre>
|
|
<h4><a name="section-6.9.3">6.9.3 <code><nobr>rdf</nobr></code> Extensions to the <code><nobr>GLOBAL</nobr></code> directive</a></h4>
|
|
<p><code><nobr>RDOFF</nobr></code> global symbols can contain additional
|
|
information needed by the static linker. You can mark a global symbol as
|
|
exported, thus telling the linker do not strip it from target executable or
|
|
library file. Like in <code><nobr>ELF</nobr></code>, you can also specify
|
|
whether an exported symbol is a procedure (function) or data object.
|
|
<p>Suffixing the name with a colon and the word
|
|
<code><nobr>export</nobr></code> you make the symbol exported:
|
|
<p><pre>
|
|
global sys_open:export
|
|
</pre>
|
|
<p>To specify that exported symbol is a procedure (function), you add the
|
|
word <code><nobr>proc</nobr></code> or <code><nobr>function</nobr></code>
|
|
after declaration:
|
|
<p><pre>
|
|
global sys_open:export proc
|
|
</pre>
|
|
<p>Similarly, to specify exported data object, add the word
|
|
<code><nobr>data</nobr></code> or <code><nobr>object</nobr></code> to the
|
|
directive:
|
|
<p><pre>
|
|
global kernel_ticks:export data
|
|
</pre>
|
|
<h3><a name="section-6.10">6.10 <code><nobr>dbg</nobr></code>: Debugging Format</a></h3>
|
|
<p>The <code><nobr>dbg</nobr></code> output format is not built into NASM
|
|
in the default configuration. If you are building your own NASM executable
|
|
from the sources, you can define <code><nobr>OF_DBG</nobr></code> in
|
|
<code><nobr>outform.h</nobr></code> or on the compiler command line, and
|
|
obtain the <code><nobr>dbg</nobr></code> output format.
|
|
<p>The <code><nobr>dbg</nobr></code> 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.
|
|
<p>For simple files, one can easily use the <code><nobr>dbg</nobr></code>
|
|
format like this:
|
|
<p><pre>
|
|
nasm -f dbg filename.asm
|
|
</pre>
|
|
<p>which will generate a diagnostic file called
|
|
<code><nobr>filename.dbg</nobr></code>. 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
|
|
<code><nobr>dbg</nobr></code> format. Therefore it can be useful to run
|
|
NASM twice, in order to do the preprocessing with the native object format
|
|
selected:
|
|
<p><pre>
|
|
nasm -e -f rdf -o rdfprog.i rdfprog.asm
|
|
nasm -a -f dbg rdfprog.i
|
|
</pre>
|
|
<p>This preprocesses <code><nobr>rdfprog.asm</nobr></code> into
|
|
<code><nobr>rdfprog.i</nobr></code>, keeping the
|
|
<code><nobr>rdf</nobr></code> object format selected in order to make sure
|
|
RDF special directives are converted into primitive form correctly. Then
|
|
the preprocessed source is fed through the <code><nobr>dbg</nobr></code>
|
|
format to generate the final diagnostic output.
|
|
<p>This workaround will still typically not work for programs intended for
|
|
<code><nobr>obj</nobr></code> format, because the
|
|
<code><nobr>obj</nobr></code> <code><nobr>SEGMENT</nobr></code> and
|
|
<code><nobr>GROUP</nobr></code> directives have side effects of defining
|
|
the segment and group names as symbols; <code><nobr>dbg</nobr></code> will
|
|
not do this, so the program will not assemble. You will have to work around
|
|
that by defining the symbols yourself (using
|
|
<code><nobr>EXTERN</nobr></code>, for example) if you really need to get a
|
|
<code><nobr>dbg</nobr></code> trace of an
|
|
<code><nobr>obj</nobr></code>-specific source file.
|
|
<p><code><nobr>dbg</nobr></code> accepts any section name and any
|
|
directives at all, and logs them all to its output file.
|
|
<p align=center><a href="nasmdoc7.html">Next Chapter</a> |
|
|
<a href="nasmdoc5.html">Previous Chapter</a> |
|
|
<a href="nasmdoc0.html">Contents</a> |
|
|
<a href="nasmdoci.html">Index</a>
|
|
</body></html>
|