NASM 0.91

1 files changed, 199 insertions, 0 deletions

diff --git a/ndisasm.doc b/ndisasm.doc
new file mode 100644
index 0000000..5b5374a
--- /dev/null
+++ b/ndisasm.doc
@@ -0,0 +1,199 @@
+		  The Netwide Disassembler, NDISASM
+		  =================================
+
+Introduction
+============
+
+The Netwide Disassembler is a small companion program to the Netwide
+Assembler, NASM. It seemed a shame to have an x86 assembler,
+complete with a full instruction table, and not make as much use of
+it as possible, so here's a disassembler which shares the
+instruction table (and some other bits of code) with NASM.
+
+The Netwide Disassembler does nothing except to produce
+disassemblies of _binary_ source files. NDISASM does not have any
+understanding of object file formats, like `objdump', and it will
+not understand DOS .EXE files like `debug' will. It just
+disassembles.
+
+Getting Started: Installation
+=============================
+
+See `nasm.doc' for installation instructions. NDISASM, like NASM,
+has a man page which you may want to put somewhere useful, if you
+are on a Unix system.
+
+Running NDISASM
+===============
+
+To disassemble a file, you will typically use a command of the form
+
+	ndisasm [-b16 | -b32] filename
+
+NDISASM can disassemble 16 bit code or 32 bit code equally easily,
+provided of course that you remember to specify which it is to work
+with. If no `-b' switch is present, NDISASM works in 16-bit mode by
+default. The `-u' switch (for USE32) also invokes 32-bit mode.
+
+Two more command line options are `-r' which reports the version
+number of NDISASM you are running, and `-h' which gives a short
+summary of command line options.
+
+COM Files: Specifying an Origin
+===============================
+
+To disassemble a DOS .COM file correctly, a disassembler must assume
+that the first instruction in the file is loaded at address 0x100,
+rather than at zero. NDISASM, which assumes by default that any file
+you give it is loaded at zero, will therefore need to be informed of
+this.
+
+The `-o' option allows you to declare a different origin for the
+file you are disassembling. Its argument may be expressed in any of
+the NASM numeric formats: decimal by default, if it begins with `$'
+or `0x' or ends in `H' it's hex, if it ends in `Q' it's octal, and
+if it ends in `B' it's binary.
+
+Hence, to disassemble a .COM file:
+
+	ndisasm -o100h filename.com
+
+will do the trick.
+
+Code Following Data: Synchronisation
+====================================
+
+Suppose you are disassembling a file which contains some data which
+isn't machine code, and _then_ contains some machine code. NDISASM
+will faithfully plough through the data section, producing machine
+instructions wherever it can (although most of them will look
+bizarre, and some may have unusual prefixes, e.g. `fs or
+ax,0x240a'), and generating `db' instructions every so often if it's
+totally stumped. Then it will reach the code section.
+
+Supposing NDISASM has just finished generating a strange machine
+instruction from part of the data section, and its file position is
+now one byte _before_ the beginning of the code section. It's
+entirely possible that another spurious instruction will get
+generated, starting with the final byte of the data section, and
+then the correct first instruction in the code section will not be
+seen because the starting point skipped over it. This isn't really
+ideal.
+
+To avoid this, you can specify a `synchronisation' point, or indeed
+as many synchronisation points as you like (although NDISASM can
+only handle 8192 sync points internally). The definition of a sync
+point is this: NDISASM guarantees to hit sync points exactly during
+disassembly. If it is thinking about generating an instruction which
+would cause it to jump over a sync point, it will discard that
+instruction and output a `db' instead. So it _will_ start
+disassembly exactly from the sync point, and so you _will_ see all
+the instructions in your code section.
+
+Sync points are specified using the `-s' option: they are measured
+in terms of the program origin, not the file position. So if you
+want to synchronise after 32 bytes of a .COM file, you would have to
+do
+
+	ndisasm -o100h -s120h file.com
+
+rather than
+
+	ndisasm -o100h -s20h file.com
+
+As stated above, you can specify multiple sync markers if you need
+to, just by repeating the `-s' option.
+
+Mixed Code and Data: Automatic (Intelligent) Synchronisation
+============================================================
+
+Suppose you are disassembling the boot sector of a DOS floppy (maybe
+it has a virus, and you need to understand the virus so that you
+know what kinds of damage it might have done you). Typically, this
+will contain a JMP instruction, then some data, then the rest of the
+code. So there is a very good chance of NDISASM being misaligned
+when the data ends and the code begins. Hence a sync point is
+needed.
+
+On the other hand, why should you have to specify the sync point
+manually? What you'd do in order to find where the sync point would
+be, surely, would be to read the JMP instruction, and then to use
+its target address as a sync point. So can NDISASM do that for you?
+
+The answer, of course, is yes: using either of the synonymous
+switches `-a' (for automatic sync) or `-i' (for intelligent sync)
+will enable auto-sync mode. Auto-sync mode automatically generates a
+sync point for any forward-referring PC-relative jump or call
+instruction that NDISASM encounters. (Since NDISASM is one-pass, if
+it encounters a PC-relative jump whose target has already been
+processed, there isn't much it can do about it...)
+
+Only PC-relative jumps are processed, since an absolute jump is
+either through a register (in which case NDISASM doesn't know what
+the register contains) or involves a segment address (in which case
+the target code isn't in the same segment that NDISASM is working
+in, and so the sync point can't be placed anywhere useful).
+
+For some kinds of file, this mechanism will automatically put sync
+points in all the right places, and save you from having to place
+any sync points manually. However, it should be stressed that
+auto-sync mode is _not_ guaranteed to catch all the sync points, and
+you may still have to place some manually.
+
+Auto-sync mode doesn't prevent you from declaring manual sync
+points: it just adds automatically generated ones to the ones you
+provide. It's perfectly feasible to specify `-i' _and_ some `-s'
+options.
+
+Another caveat with auto-sync mode is that if, by some unpleasant
+fluke, something in your data section should disassemble to a
+PC-relative call or jump instruction, NDISASM may obediently place a
+sync point in a totally random place, for example in the middle of
+one of the instructions in your code section. So you may end up with
+a wrong disassembly even if you use auto-sync. Again, there isn't
+much I can do about this. If you have problems, you'll have to use
+manual sync points, or use the `-k' option (documented below) to
+suppress disassembly of the data area.
+
+Other Options
+=============
+
+The `-e' option skips a header on the file, by ignoring the first N
+bytes. This means that the header is _not_ counted towards the
+disassembly offset: if you give `-e10 -o10', disassembly will start
+at byte 10 in the file, and this will be given offset 10, not 20.
+
+The `-k' option is provided with two comma-separated numeric
+arguments, the first of which is an assembly offset and the second
+is a number of bytes to skip. This _will_ count the skipped bytes
+towards the assembly offset: its use is to suppress disassembly of a
+data section which wouldn't contain anything you wanted to see
+anyway.
+
+Bugs and Improvements
+=====================
+
+There are no known bugs. However, any you find, with patches if
+possible, should be sent to <jules@dcs.warwick.ac.uk> or
+<anakin@pobox.com>, and we'll try to fix them. Feel free to send
+contributions and new features as well.
+
+Future plans include awareness of which processors certain
+instructions will run on, and marking of instructions that are too
+advanced for some processor (or are FPU instructions, or are
+undocumented opcodes, or are privileged protected-mode instructions,
+or whatever).
+
+That's All Folks!
+=================
+
+I hope NDISASM is of some use to somebody. Including me. :-)
+
+I don't recommend taking NDISASM apart to see how an efficient
+disassembler works, because as far as I know, it isn't an efficient
+one anyway. You have been warned.
+
+Please feel free to send comments, suggestions, or chat to
+<anakin@pobox.com>. As with NASM, no flames please.
+
+- Simon Tatham <anakin@pobox.com>, 21-Nov-96