ndisasm.doc

   1                   The Netwide Disassembler, NDISASM
   2                   =================================
   3
   4 Introduction
   5 ============
   6
   7 The Netwide Disassembler is a small companion program to the Netwide
   8 Assembler, NASM. It seemed a shame to have an x86 assembler,
   9 complete with a full instruction table, and not make as much use of
  10 it as possible, so here's a disassembler which shares the
  11 instruction table (and some other bits of code) with NASM.
  12
  13 The Netwide Disassembler does nothing except to produce
  14 disassemblies of _binary_ source files. NDISASM does not have any
  15 understanding of object file formats, like `objdump', and it will
  16 not understand DOS .EXE files like `debug' will. It just
  17 disassembles.
  18
  19 Getting Started: Installation
  20 =============================
  21
  22 See `nasm.doc' for installation instructions. NDISASM, like NASM,
  23 has a man page which you may want to put somewhere useful, if you
  24 are on a Unix system.
  25
  26 Running NDISASM
  27 ===============
  28
  29 To disassemble a file, you will typically use a command of the form
  30
  31         ndisasm [-b16 | -b32] filename
  32
  33 NDISASM can disassemble 16 bit code or 32 bit code equally easily,
  34 provided of course that you remember to specify which it is to work
  35 with. If no `-b' switch is present, NDISASM works in 16-bit mode by
  36 default. The `-u' switch (for USE32) also invokes 32-bit mode.
  37
  38 Two more command line options are `-r' which reports the version
  39 number of NDISASM you are running, and `-h' which gives a short
  40 summary of command line options.
  41
  42 COM Files: Specifying an Origin
  43 ===============================
  44
  45 To disassemble a DOS .COM file correctly, a disassembler must assume
  46 that the first instruction in the file is loaded at address 0x100,
  47 rather than at zero. NDISASM, which assumes by default that any file
  48 you give it is loaded at zero, will therefore need to be informed of
  49 this.
  50
  51 The `-o' option allows you to declare a different origin for the
  52 file you are disassembling. Its argument may be expressed in any of
  53 the NASM numeric formats: decimal by default, if it begins with `$'
  54 or `0x' or ends in `H' it's hex, if it ends in `Q' it's octal, and
  55 if it ends in `B' it's binary.
  56
  57 Hence, to disassemble a .COM file:
  58
  59         ndisasm -o100h filename.com
  60
  61 will do the trick.
  62
  63 Code Following Data: Synchronisation
  64 ====================================
  65
  66 Suppose you are disassembling a file which contains some data which
  67 isn't machine code, and _then_ contains some machine code. NDISASM
  68 will faithfully plough through the data section, producing machine
  69 instructions wherever it can (although most of them will look
  70 bizarre, and some may have unusual prefixes, e.g. `fs or
  71 ax,0x240a'), and generating `db' instructions every so often if it's
  72 totally stumped. Then it will reach the code section.
  73
  74 Supposing NDISASM has just finished generating a strange machine
  75 instruction from part of the data section, and its file position is
  76 now one byte _before_ the beginning of the code section. It's
  77 entirely possible that another spurious instruction will get
  78 generated, starting with the final byte of the data section, and
  79 then the correct first instruction in the code section will not be
  80 seen because the starting point skipped over it. This isn't really
  81 ideal.
  82
  83 To avoid this, you can specify a `synchronisation' point, or indeed
  84 as many synchronisation points as you like (although NDISASM can
  85 only handle 8192 sync points internally). The definition of a sync
  86 point is this: NDISASM guarantees to hit sync points exactly during
  87 disassembly. If it is thinking about generating an instruction which
  88 would cause it to jump over a sync point, it will discard that
  89 instruction and output a `db' instead. So it _will_ start
  90 disassembly exactly from the sync point, and so you _will_ see all
  91 the instructions in your code section.
  92
  93 Sync points are specified using the `-s' option: they are measured
  94 in terms of the program origin, not the file position. So if you
  95 want to synchronise after 32 bytes of a .COM file, you would have to
  96 do
  97
  98         ndisasm -o100h -s120h file.com
  99
 100 rather than
 101
 102         ndisasm -o100h -s20h file.com
 103
 104 As stated above, you can specify multiple sync markers if you need
 105 to, just by repeating the `-s' option.
 106
 107 Mixed Code and Data: Automatic (Intelligent) Synchronisation
 108 ============================================================
 109
 110 Suppose you are disassembling the boot sector of a DOS floppy (maybe
 111 it has a virus, and you need to understand the virus so that you
 112 know what kinds of damage it might have done you). Typically, this
 113 will contain a JMP instruction, then some data, then the rest of the
 114 code. So there is a very good chance of NDISASM being misaligned
 115 when the data ends and the code begins. Hence a sync point is
 116 needed.
 117
 118 On the other hand, why should you have to specify the sync point
 119 manually? What you'd do in order to find where the sync point would
 120 be, surely, would be to read the JMP instruction, and then to use
 121 its target address as a sync point. So can NDISASM do that for you?
 122
 123 The answer, of course, is yes: using either of the synonymous
 124 switches `-a' (for automatic sync) or `-i' (for intelligent sync)
 125 will enable auto-sync mode. Auto-sync mode automatically generates a
 126 sync point for any forward-referring PC-relative jump or call
 127 instruction that NDISASM encounters. (Since NDISASM is one-pass, if
 128 it encounters a PC-relative jump whose target has already been
 129 processed, there isn't much it can do about it...)
 130
 131 Only PC-relative jumps are processed, since an absolute jump is
 132 either through a register (in which case NDISASM doesn't know what
 133 the register contains) or involves a segment address (in which case
 134 the target code isn't in the same segment that NDISASM is working
 135 in, and so the sync point can't be placed anywhere useful).
 136
 137 For some kinds of file, this mechanism will automatically put sync
 138 points in all the right places, and save you from having to place
 139 any sync points manually. However, it should be stressed that
 140 auto-sync mode is _not_ guaranteed to catch all the sync points, and
 141 you may still have to place some manually.
 142
 143 Auto-sync mode doesn't prevent you from declaring manual sync
 144 points: it just adds automatically generated ones to the ones you
 145 provide. It's perfectly feasible to specify `-i' _and_ some `-s'
 146 options.
 147
 148 Another caveat with auto-sync mode is that if, by some unpleasant
 149 fluke, something in your data section should disassemble to a
 150 PC-relative call or jump instruction, NDISASM may obediently place a
 151 sync point in a totally random place, for example in the middle of
 152 one of the instructions in your code section. So you may end up with
 153 a wrong disassembly even if you use auto-sync. Again, there isn't
 154 much I can do about this. If you have problems, you'll have to use
 155 manual sync points, or use the `-k' option (documented below) to
 156 suppress disassembly of the data area.
 157
 158 Other Options
 159 =============
 160
 161 The `-e' option skips a header on the file, by ignoring the first N
 162 bytes. This means that the header is _not_ counted towards the
 163 disassembly offset: if you give `-e10 -o10', disassembly will start
 164 at byte 10 in the file, and this will be given offset 10, not 20.
 165
 166 The `-k' option is provided with two comma-separated numeric
 167 arguments, the first of which is an assembly offset and the second
 168 is a number of bytes to skip. This _will_ count the skipped bytes
 169 towards the assembly offset: its use is to suppress disassembly of a
 170 data section which wouldn't contain anything you wanted to see
 171 anyway.
 172
 173 Bugs and Improvements
 174 =====================
 175
 176 There are no known bugs. However, any you find, with patches if
 177 possible, should be sent to <jules@earthcorp.com> or
 178 <anakin@pobox.com>, and we'll try to fix them. Feel free to send
 179 contributions and new features as well.
 180
 181 Future plans include awareness of which processors certain
 182 instructions will run on, and marking of instructions that are too
 183 advanced for some processor (or are FPU instructions, or are
 184 undocumented opcodes, or are privileged protected-mode instructions,
 185 or whatever).
 186
 187 That's All Folks!
 188 =================
 189
 190 I hope NDISASM is of some use to somebody. Including me. :-)
 191
 192 I don't recommend taking NDISASM apart to see how an efficient
 193 disassembler works, because as far as I know, it isn't an efficient
 194 one anyway. You have been warned.
 195
 196 Please feel free to send comments, suggestions, or chat to
 197 <anakin@pobox.com>. As with NASM, no flames please.
 198
 199 - Simon Tatham <anakin@pobox.com>, 21-Nov-96