"Fossies" - the Fresh Open Source Software Archive

Member "nasm-2.15.05/doc/html/nasmdoca.html" (28 Aug 2020, 8775 Bytes) of package /linux/misc/nasm-2.15.05-xdoc.tar.xz:

As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) HTML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 <?xml version="1.0" encoding="UTF-8" standalone="no" ?>
    2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
    3 <html xmlns="http://www.w3.org/1999/xhtml">
    4 <head>
    5 <title>NASM - The Netwide Assembler</title>
    6 <link href="nasmdoc.css" rel="stylesheet" type="text/css" />
    7 <link href="local.css" rel="stylesheet" type="text/css" />
    8 </head>
    9 <body>
   10 <ul class="navbar">
   11 <li class="first"><a class="prev" href="nasmdo13.html">Chapter 13</a></li>
   12 <li><a class="next" href="nasmdocb.html">Appendix B</a></li>
   13 <li><a class="toc" href="nasmdoc0.html">Contents</a></li>
   14 <li class="last"><a class="index" href="nasmdoci.html">Index</a></li>
   15 </ul>
   16 <div class="title">
   17 <h1>NASM - The Netwide Assembler</h1>
   18 <span class="subtitle">version 2.15.05</span>
   19 </div>
   20 <div class="contents"
   21 >
   22 <h2 id="appendix-A">Appendix A: Ndisasm</h2>
   23 <p>The Netwide Disassembler, NDISASM</p>
   24 <h3 id="section-A.1">A.1 Introduction</h3>
   25 <p>The Netwide Disassembler is a small companion program to the Netwide
   26 Assembler, NASM. It seemed a shame to have an x86 assembler, complete with
   27 a full instruction table, and not make as much use of it as possible, so
   28 here's a disassembler which shares the instruction table (and some other
   29 bits of code) with NASM.</p>
   30 <p>The Netwide Disassembler does nothing except to produce disassemblies of
   31 <em>binary</em> source files. NDISASM does not have any understanding of
   32 object file formats, like <code>objdump</code>, and it will not understand
   33 <code>DOS .EXE</code> files like <code>debug</code> will. It just
   34 disassembles.</p>
   35 <h3 id="section-A.2">A.2 Running NDISASM</h3>
   36 <p>To disassemble a file, you will typically use a command of the form</p>
   37 <pre>
   38        ndisasm -b {16|32|64} filename
   39 </pre>
   40 <p>NDISASM can disassemble 16-, 32- or 64-bit code equally easily, provided
   41 of course that you remember to specify which it is to work with. If no
   42 <code>-b</code> switch is present, NDISASM works in 16-bit mode by default.
   43 The <code>-u</code> switch (for USE32) also invokes 32-bit mode.</p>
   44 <p>Two more command line options are <code>-r</code> which reports the
   45 version number of NDISASM you are running, and <code>-h</code> which gives
   46 a short summary of command line options.</p>
   47 <h4 id="section-A.2.1">A.2.1 COM Files: Specifying an Origin</h4>
   48 <p>To disassemble a <code>DOS .COM</code> file correctly, a disassembler
   49 must assume that the first instruction in the file is loaded at address
   50 <code>0x100</code>, rather than at zero. NDISASM, which assumes by default
   51 that any file you give it is loaded at zero, will therefore need to be
   52 informed of this.</p>
   53 <p>The <code>-o</code> option allows you to declare a different origin for
   54 the file you are disassembling. Its argument may be expressed in any of the
   55 NASM numeric formats: decimal by default, if it begins with
   56 `<code>$</code>' or `<code>0x</code>' or ends in `<code>H</code>' it's
   57 <code>hex</code>, if it ends in `<code>Q</code>' it's <code>octal</code>,
   58 and if it ends in `<code>B</code>' it's <code>binary</code>.</p>
   59 <p>Hence, to disassemble a <code>.COM</code> file:</p>
   60 <pre>
   61        ndisasm -o100h filename.com
   62 </pre>
   63 <p>will do the trick.</p>
   64 <h4 id="section-A.2.2">A.2.2 Code Following Data: Synchronization</h4>
   65 <p>Suppose you are disassembling a file which contains some data which
   66 isn't machine code, and <em>then</em> contains some machine code. NDISASM
   67 will faithfully plough through the data section, producing machine
   68 instructions wherever it can (although most of them will look bizarre, and
   69 some may have unusual prefixes, e.g. `<code>FS OR AX,0x240A</code>'), and
   70 generating `DB' instructions ever so often if it's totally stumped. Then it
   71 will reach the code section.</p>
   72 <p>Supposing NDISASM has just finished generating a strange machine
   73 instruction from part of the data section, and its file position is now one
   74 byte <em>before</em> the beginning of the code section. It's entirely
   75 possible that another spurious instruction will get generated, starting
   76 with the final byte of the data section, and then the correct first
   77 instruction in the code section will not be seen because the starting point
   78 skipped over it. This isn't really ideal.</p>
   79 <p>To avoid this, you can specify a `synchronization' point, or indeed as
   80 many synchronization points as you like (although NDISASM can only handle
   81 2147483647 sync points internally). The definition of a sync point is this:
   82 NDISASM guarantees to hit sync points exactly during disassembly. If it is
   83 thinking about generating an instruction which would cause it to jump over
   84 a sync point, it will discard that instruction and output a
   85 `<code>db</code>' instead. So it <em>will</em> start disassembly exactly
   86 from the sync point, and so you <em>will</em> see all the instructions in
   87 your code section.</p>
   88 <p>Sync points are specified using the <code>-s</code> option: they are
   89 measured in terms of the program origin, not the file position. So if you
   90 want to synchronize after 32 bytes of a <code>.COM</code> file, you would
   91 have to do</p>
   92 <pre>
   93        ndisasm -o100h -s120h file.com
   94 </pre>
   95 <p>rather than</p>
   96 <pre>
   97        ndisasm -o100h -s20h file.com
   98 </pre>
   99 <p>As stated above, you can specify multiple sync markers if you need to,
  100 just by repeating the <code>-s</code> option.</p>
  101 <h4 id="section-A.2.3">A.2.3 Mixed Code and Data: Automatic (Intelligent) Synchronization </h4>
  102 <p>Suppose you are disassembling the boot sector of a <code>DOS</code>
  103 floppy (maybe it has a virus, and you need to understand the virus so that
  104 you know what kinds of damage it might have done you). Typically, this will
  105 contain a <code>JMP</code> instruction, then some data, then the rest of
  106 the code. So there is a very good chance of NDISASM being
  107 <em>misaligned</em> when the data ends and the code begins. Hence a sync
  108 point is needed.</p>
  109 <p>On the other hand, why should you have to specify the sync point
  110 manually? What you'd do in order to find where the sync point would be,
  111 surely, would be to read the <code>JMP</code> instruction, and then to use
  112 its target address as a sync point. So can NDISASM do that for you?</p>
  113 <p>The answer, of course, is yes: using either of the synonymous switches
  114 <code>-a</code> (for automatic sync) or <code>-i</code> (for intelligent
  115 sync) will enable <code>auto-sync</code> mode. Auto-sync mode automatically
  116 generates a sync point for any forward-referring PC-relative jump or call
  117 instruction that NDISASM encounters. (Since NDISASM is one-pass, if it
  118 encounters a PC-relative jump whose target has already been processed,
  119 there isn't much it can do about it...)</p>
  120 <p>Only PC-relative jumps are processed, since an absolute jump is either
  121 through a register (in which case NDISASM doesn't know what the register
  122 contains) or involves a segment address (in which case the target code
  123 isn't in the same segment that NDISASM is working in, and so the sync point
  124 can't be placed anywhere useful).</p>
  125 <p>For some kinds of file, this mechanism will automatically put sync
  126 points in all the right places, and save you from having to place any sync
  127 points manually. However, it should be stressed that auto-sync mode is
  128 <em>not</em> guaranteed to catch all the sync points, and you may still
  129 have to place some manually.</p>
  130 <p>Auto-sync mode doesn't prevent you from declaring manual sync points: it
  131 just adds automatically generated ones to the ones you provide. It's
  132 perfectly feasible to specify <code>-i</code> <em>and</em> some
  133 <code>-s</code> options.</p>
  134 <p>Another caveat with auto-sync mode is that if, by some unpleasant fluke,
  135 something in your data section should disassemble to a PC-relative call or
  136 jump instruction, NDISASM may obediently place a sync point in a totally
  137 random place, for example in the middle of one of the instructions in your
  138 code section. So you may end up with a wrong disassembly even if you use
  139 auto-sync. Again, there isn't much I can do about this. If you have
  140 problems, you'll have to use manual sync points, or use the <code>-k</code>
  141 option (documented below) to suppress disassembly of the data area.</p>
  142 <h4 id="section-A.2.4">A.2.4 Other Options</h4>
  143 <p>The <code>-e</code> option skips a header on the file, by ignoring the
  144 first N bytes. This means that the header is <em>not</em> counted towards
  145 the disassembly offset: if you give <code>-e10 -o10</code>, disassembly
  146 will start at byte 10 in the file, and this will be given offset 10, not
  147 20.</p>
  148 <p>The <code>-k</code> option is provided with two comma-separated numeric
  149 arguments, the first of which is an assembly offset and the second is a
  150 number of bytes to skip. This <em>will</em> count the skipped bytes towards
  151 the assembly offset: its use is to suppress disassembly of a data section
  152 which wouldn't contain anything you wanted to see anyway.</p>
  153 </div>
  154 </body>
  155 </html>