DISASM.TXT					John Wilson  10-Oct-1997

*** NOTE:  DISASM.SAV is obsolete, it has been superseded by DISSAV.SAV ***
*** John Wilson 21-May-1999 ***

DISASM.SAV is a two-pass PDP-11 disassembler by John Wilson (this one is
anyway, it's an obvious filename so there are probably other DISASMs by other
authors).  I wrote it ages ago when I was even more clueless than now so I'm
too embarrassed to even look at the source, I'm sure it's a mess.  Anyway it
goes like this:

.RUN DISASM
DISASM	V1.0	<system ID string if RSTS>
*out[.MAC]=in[.SAV]/switches

Possible switches:
/S:oooooo	starting octal addr (in .SAV file) to disassemble
/E:oooooo	ending octal addr (in .SAV file) to disassemble
/T:oooooo	transfer address to begin execution trace
		(default is .SAV transfer address from loc 000040)

The disassembler makes two passes.  The first pass detects (or tries to detect)
the difference between code and data, and figures out what addresses are branch
targets (and thus require labels).  It does this by building a bitmap of all
words of the file and doing a "dry" disassembly (i.e. no source output) of each
word of the file.  As an instruction is traced it is entered into the bitmap as
code (rather than data).  If the instruction ends a thread (RTS, HALT etc., or
a computed JMP) then tracing stops.  If it's an unconditional branch (BR or
JMP) then tracing continues at the target address.  If it's a JSR or
conditional branch, then each path is searched recursively.

On the second pass the .SAV file is disassembled linearly, with labels
generated as appropriate and code/data generated according to the bitmap.  All
non-trivial programs will contain some type of jump or dispatch tables and/or
some other kind of computed JMP, which the disassembler will not be able to
find (and could not even guess at without some very sophisticated heuristics to
figure out the bounds on the possible values in each register during a real
run).  So there will be dead code shown as data that actually should have been
disassembled as instructions.  In this case you can make successive runs of the
disassembler, telling it what code to disassemble using the /S, /E, and /T
switches, and then edit the resulting file in with the main disassembled file
by hand.  Yes I know it's cumbersome.  Ideally this could be done using a file
to hold a long list of transfer and data addresses (my DASM.COM 8080/Z80/8086
disassembler for DOS does this, it's also available from FTP.DBIT.COM), so that
you could produce a fresh source file each time you find a new transfer address
to add, w/o having to do any hand editing.  Actually my plan for DISASM.SAV was
to do this using simple directives that could be embedded in a .MAC file
produced in a previous disassembly, that way you wouldn't destroy any previous
work in commenting the disassembled code, the disassembler would just insert
the new source code into your edited source file.  But I never got around to
it.  Some day...

I had planned to write a version of this that used the extra information
available in a .OBJ file, but it would be pretty hard work to combine that with
the execution trace.  I got as far as writing a program that understands the
record format in a .OBJ file and dumps out all the records in text form, but
that's not much help.  Anyway I gather this is familiar territory to the other
PDP-11 disassemblers out there, I wish I'd heard of them when I wrote my stuff.

DISASM.MAC contains a conditional assembly flag named "RSTS" which decides
whether DISASM.SAV will display a RSTS version banner on startup (since I wrote
the program on a RSTS V7.0-07 system), in practice it seems that this can be
left on in real RT-11 (I haven't looked up what EMT 364 in does in real RT-11
but the program doesn't bomb for what that's worth).

Happy hacking,

John Wilson
D Bit