1 files changed, 178 insertions, 0 deletions
diff --git a/doc/html/nasmdo12.html b/doc/html/nasmdo12.html
new file mode 100644
index 0000000..9c937f8
--- /dev/null
+++ b/doc/html/nasmdo12.html
@@ -0,0 +1,178 @@
+<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>