Sophie: nasm-doc-1:2.07-1mdv2010.0 x86

nasm-doc-2.07-1mdv2010.0.x86_64.rpm

<html><head><title>NASM Manual</title></head>
<body><h1 align=center>The Netwide Assembler: NASM</h1>

<p align=center><a href="nasmdoca.html">Next Chapter</a> |
<a href="nasmdo11.html">Previous Chapter</a> |
<a href="nasmdoc0.html">Contents</a> |
<a href="nasmdoci.html">Index</a>
<h2><a name="chapter-12">Chapter 12: Troubleshooting</a></h2>
<p>This chapter describes some of the common problems that users have been
known to encounter with NASM, and answers them. It also gives instructions
for reporting bugs in NASM if you find a difficulty that isn't listed here.
<h3><a name="section-12.1">12.1 Common Problems</a></h3>
<h4><a name="section-12.1.1">12.1.1 NASM Generates Inefficient Code</a></h4>
<p>We sometimes get `bug' reports about NASM generating inefficient, or
even `wrong', code on instructions such as
<code><nobr>ADD ESP,8</nobr></code>. This is a deliberate design feature,
connected to predictability of output: NASM, on seeing
<code><nobr>ADD ESP,8</nobr></code>, will generate the form of the
instruction which leaves room for a 32-bit offset. You need to code
<code><nobr>ADD ESP,BYTE 8</nobr></code> if you want the space-efficient
form of the instruction. This isn't a bug, it's user error: if you prefer
to have NASM produce the more efficient code automatically enable
optimization with the <code><nobr>-O</nobr></code> option (see
<a href="nasmdoc2.html#section-2.1.22">section 2.1.22</a>).
<h4><a name="section-12.1.2">12.1.2 My Jumps are Out of Range</a></h4>
<p>Similarly, people complain that when they issue conditional jumps (which
are <code><nobr>SHORT</nobr></code> by default) that try to jump too far,
NASM reports `short jump out of range' instead of making the jumps longer.
<p>This, again, is partly a predictability issue, but in fact has a more
practical reason as well. NASM has no means of being told what type of
processor the code it is generating will be run on; so it cannot decide for
itself that it should generate <code><nobr>Jcc NEAR</nobr></code> type
instructions, because it doesn't know that it's working for a 386 or above.
Alternatively, it could replace the out-of-range short
<code><nobr>JNE</nobr></code> instruction with a very short
<code><nobr>JE</nobr></code> instruction that jumps over a
<code><nobr>JMP NEAR</nobr></code>; this is a sensible solution for
processors below a 386, but hardly efficient on processors which have good
branch prediction <em>and</em> could have used
<code><nobr>JNE NEAR</nobr></code> instead. So, once again, it's up to the
user, not the assembler, to decide what instructions should be generated.
See <a href="nasmdoc2.html#section-2.1.22">section 2.1.22</a>.
<h4><a name="section-12.1.3">12.1.3 <code><nobr>ORG</nobr></code> Doesn't Work</a></h4>
<p>People writing boot sector programs in the <code><nobr>bin</nobr></code>
format often complain that <code><nobr>ORG</nobr></code> doesn't work the
way they'd like: in order to place the <code><nobr>0xAA55</nobr></code>
signature word at the end of a 512-byte boot sector, people who are used to
MASM tend to code
<p><pre>
        ORG 0 

        ; some boot sector code 

        ORG 510 
        DW 0xAA55
</pre>
<p>This is not the intended use of the <code><nobr>ORG</nobr></code>
directive in NASM, and will not work. The correct way to solve this problem
in NASM is to use the <code><nobr>TIMES</nobr></code> directive, like this:
<p><pre>
        ORG 0 

        ; some boot sector code 

        TIMES 510-($-$$) DB 0 
        DW 0xAA55
</pre>
<p>The <code><nobr>TIMES</nobr></code> directive will insert exactly enough
zero bytes into the output to move the assembly point up to 510. This
method also has the advantage that if you accidentally fill your boot
sector too full, NASM will catch the problem at assembly time and report
it, so you won't end up with a boot sector that you have to disassemble to
find out what's wrong with it.
<h4><a name="section-12.1.4">12.1.4 <code><nobr>TIMES</nobr></code> Doesn't Work</a></h4>
<p>The other common problem with the above code is people who write the
<code><nobr>TIMES</nobr></code> line as
<p><pre>
        TIMES 510-$ DB 0
</pre>
<p>by reasoning that <code><nobr>$</nobr></code> should be a pure number,
just like 510, so the difference between them is also a pure number and can
happily be fed to <code><nobr>TIMES</nobr></code>.
<p>NASM is a <em>modular</em> assembler: the various component parts are
designed to be easily separable for re-use, so they don't exchange
information unnecessarily. In consequence, the
<code><nobr>bin</nobr></code> output format, even though it has been told
by the <code><nobr>ORG</nobr></code> directive that the
<code><nobr>.text</nobr></code> section should start at 0, does not pass
that information back to the expression evaluator. So from the evaluator's
point of view, <code><nobr>$</nobr></code> isn't a pure number: it's an
offset from a section base. Therefore the difference between
<code><nobr>$</nobr></code> and 510 is also not a pure number, but involves
a section base. Values involving section bases cannot be passed as
arguments to <code><nobr>TIMES</nobr></code>.
<p>The solution, as in the previous section, is to code the
<code><nobr>TIMES</nobr></code> line in the form
<p><pre>
        TIMES 510-($-$$) DB 0
</pre>
<p>in which <code><nobr>$</nobr></code> and <code><nobr>$$</nobr></code>
are offsets from the same section base, and so their difference is a pure
number. This will solve the problem and generate sensible code.
<h3><a name="section-12.2">12.2 Bugs</a></h3>
<p>We have never yet released a version of NASM with any <em>known</em>
bugs. That doesn't usually stop there being plenty we didn't know about,
though. Any that you find should be reported firstly via the
<code><nobr>bugtracker</nobr></code> at
<a href="https://sourceforge.net/projects/nasm/"><code><nobr>https://sourceforge.net/projects/nasm/</nobr></code></a>
(click on "Bugs"), or if that fails then through one of the contacts in
<a href="nasmdoc1.html#section-1.2">section 1.2</a>.
<p>Please read <a href="nasmdoc2.html#section-2.2">section 2.2</a> first,
and don't report the bug if it's listed in there as a deliberate feature.
(If you think the feature is badly thought out, feel free to send us
reasons why you think it should be changed, but don't just send us mail
saying `This is a bug' if the documentation says we did it on purpose.)
Then read <a href="#section-12.1">section 12.1</a>, and don't bother
reporting the bug if it's listed there.
<p>If you do report a bug, <em>please</em> give us all of the following
information:
<ul>
<li>What operating system you're running NASM under. DOS, Linux, NetBSD,
Win16, Win32, VMS (I'd be impressed), whatever.
<li>If you're running NASM under DOS or Win32, tell us whether you've
compiled your own executable from the DOS source archive, or whether you
were using the standard distribution binaries out of the archive. If you
were using a locally built executable, try to reproduce the problem using
one of the standard binaries, as this will make it easier for us to
reproduce your problem prior to fixing it.
<li>Which version of NASM you're using, and exactly how you invoked it.
Give us the precise command line, and the contents of the
<code><nobr>NASMENV</nobr></code> environment variable if any.
<li>Which versions of any supplementary programs you're using, and how you
invoked them. If the problem only becomes visible at link time, tell us
what linker you're using, what version of it you've got, and the exact
linker command line. If the problem involves linking against object files
generated by a compiler, tell us what compiler, what version, and what
command line or options you used. (If you're compiling in an IDE, please
try to reproduce the problem with the command-line version of the
compiler.)
<li>If at all possible, send us a NASM source file which exhibits the
problem. If this causes copyright problems (e.g. you can only reproduce the
bug in restricted-distribution code) then bear in mind the following two
points: firstly, we guarantee that any source code sent to us for the
purposes of debugging NASM will be used <em>only</em> for the purposes of
debugging NASM, and that we will delete all our copies of it as soon as we
have found and fixed the bug or bugs in question; and secondly, we would
prefer <em>not</em> to be mailed large chunks of code anyway. The smaller
the file, the better. A three-line sample file that does nothing useful
<em>except</em> demonstrate the problem is much easier to work with than a
fully fledged ten-thousand-line program. (Of course, some errors
<em>do</em> only crop up in large files, so this may not be possible.)
<li>A description of what the problem actually <em>is</em>. `It doesn't
work' is <em>not</em> a helpful description! Please describe exactly what
is happening that shouldn't be, or what isn't happening that should.
Examples might be: `NASM generates an error message saying Line 3 for an
error that's actually on Line 5'; `NASM generates an error message that I
believe it shouldn't be generating at all'; `NASM fails to generate an
error message that I believe it <em>should</em> be generating'; `the object
file produced from this source code crashes my linker'; `the ninth byte of
the output file is 66 and I think it should be 77 instead'.
<li>If you believe the output file from NASM to be faulty, send it to us.
That allows us to determine whether our own copy of NASM generates the same
file, or whether the problem is related to portability issues between our
development platforms and yours. We can handle binary files mailed to us as
MIME attachments, uuencoded, and even BinHex. Alternatively, we may be able
to provide an FTP site you can upload the suspect files to; but mailing
them is easier for us.
<li>Any other information or data files that might be helpful. If, for
example, the problem involves NASM failing to generate an object file while
TASM can generate an equivalent file without trouble, then send us
<em>both</em> object files, so we can see what TASM is doing differently
from us.
</ul>
<p align=center><a href="nasmdoca.html">Next Chapter</a> |
<a href="nasmdo11.html">Previous Chapter</a> |
<a href="nasmdoc0.html">Contents</a> |
<a href="nasmdoci.html">Index</a>
</body></html>