| [9] | 1 | dis88
|
|---|
| 2 | Beta Release
|
|---|
| 3 | 87/09/01
|
|---|
| 4 | ---
|
|---|
| 5 | G. M. HARDING
|
|---|
| 6 | POB 4142
|
|---|
| 7 | Santa Clara CA 95054-0142
|
|---|
| 8 |
|
|---|
| 9 |
|
|---|
| 10 | "Dis88" is a symbolic disassembler for the Intel 8088 CPU,
|
|---|
| 11 | designed to run under the PC/IX operating system on an IBM XT
|
|---|
| 12 | or fully-compatible clone. Its output is in the format of, and
|
|---|
| 13 | is completely compatible with, the PC/IX assembler, "as". The
|
|---|
| 14 | program is copyrighted by its author, but may be copied and re-
|
|---|
| 15 | distributed freely provided that complete source code, with all
|
|---|
| 16 | copyright notices, accompanies any distribution. This provision
|
|---|
| 17 | also applies to any modifications you may make. You are urged
|
|---|
| 18 | to comment such changes, giving, as a miminum, your name and
|
|---|
| 19 | complete address.
|
|---|
| 20 |
|
|---|
| 21 | This release of the program is a beta release, which means
|
|---|
| 22 | that it has been extensively, but not exhaustively, tested.
|
|---|
| 23 | User comments, recommendations, and bug fixes are welcome. The
|
|---|
| 24 | principal features of the current release are:
|
|---|
| 25 |
|
|---|
| 26 | (a) The ability to disassemble any file in PC/IX object
|
|---|
| 27 | format, making full use of symbol and relocation information if
|
|---|
| 28 | it is present, regardless of whether the file is executable or
|
|---|
| 29 | linkable, and regardless of whether it has continuous or split
|
|---|
| 30 | I/D space;
|
|---|
| 31 |
|
|---|
| 32 | (b) Automatic generation of synthetic labels when no sym-
|
|---|
| 33 | bol table is available; and
|
|---|
| 34 |
|
|---|
| 35 | (c) Optional output of address and object-code informa-
|
|---|
| 36 | tion as assembler comment text.
|
|---|
| 37 |
|
|---|
| 38 | Limitations of the current release are:
|
|---|
| 39 |
|
|---|
| 40 | (a) Numeric co-processor (i.e., 8087) mnemonics are not
|
|---|
| 41 | supported. Instructions for the co-processor are disassembled
|
|---|
| 42 | as CPU escape sequences, or as interrupts, depending on how
|
|---|
| 43 | they were assembled in the first place. This limitation will be
|
|---|
| 44 | addressed in a future release.
|
|---|
| 45 |
|
|---|
| 46 | (b) Symbolic references within the object file's data
|
|---|
| 47 | segment are not supported. Thus, for example, if a data segment
|
|---|
| 48 | location is initialized to point to a text segment address, no
|
|---|
| 49 | reference to a text segment symbol will be detected. This limi-
|
|---|
| 50 | tation is likely to remain in future releases, because object
|
|---|
| 51 | code does not, in most cases, contain sufficient information to
|
|---|
| 52 | allow meaningful interpretation of pure data. (Note, however,
|
|---|
| 53 | that symbolic references to the data segment from within the
|
|---|
| 54 | text segment are always supported.)
|
|---|
| 55 |
|
|---|
| 56 | As a final caveat, be aware that the PC/IX assembler does
|
|---|
| 57 | not recognize the "esc" mnemonic, even though it refers to a
|
|---|
| 58 | completely valid CPU operation which is documented in all the
|
|---|
| 59 | Intel literature. Thus, the corresponding opcodes (0xd8 through
|
|---|
| 60 | 0xdf) are disassembled as .byte directives. For reference, how-
|
|---|
| 61 | ever, the syntactically-correct "esc" instruction is output as
|
|---|
| 62 | a comment.
|
|---|
| 63 |
|
|---|
| 64 | To build the disassembler program, transfer all the source
|
|---|
| 65 | files, together with the Makefile, to a suitable (preferably
|
|---|
| 66 | empty) PC/IX directory. Then, simply type "make".
|
|---|
| 67 |
|
|---|
| 68 | To use dis88, place it in a directory which appears in
|
|---|
| 69 | your $PATH list. It may then be invoked by name from whatever
|
|---|
| 70 | directory you happen to be in. As a minimum, the program must
|
|---|
| 71 | be invoked with one command-line argument: the name of the ob-
|
|---|
| 72 | ject file to be disassembled. (Dis88 will complain if the file
|
|---|
| 73 | specified is not an object file.) Optionally, you may specify
|
|---|
| 74 | an output file; stdout is the default. One command-line switch
|
|---|
| 75 | is available: "-o", which makes the program display addresses
|
|---|
| 76 | and object code along with its mnemonic disassembly.
|
|---|
| 77 |
|
|---|
| 78 | The "-o" option is useful primarily for verifying the cor-
|
|---|
| 79 | rectness of the program's output. In particular, it may be used
|
|---|
| 80 | to check the accuracy of local relative jump opcodes. These
|
|---|
| 81 | jumps often target local labels, which are lost at assembly
|
|---|
| 82 | time; thus, the disassembly may contain cryptic instructions
|
|---|
| 83 | like "jnz .+39". As a user convenience, all relative jump and
|
|---|
| 84 | call opcodes are output with a comment which identifies the
|
|---|
| 85 | physical target address.
|
|---|
| 86 |
|
|---|
| 87 | By convention, the release level of the program as a whole
|
|---|
| 88 | is the SID of the file disrel.c, and this SID string appears in
|
|---|
| 89 | each disassembly. Release 2.1 of the program is the first beta
|
|---|
| 90 | release to be distributed on Usenet.
|
|---|
| 91 |
|
|---|
| 92 |
|
|---|
| 93 | .TH dis88 1 LOCAL
|
|---|
| 94 | .SH "NAME"
|
|---|
| 95 | dis88 \- 8088 symbolic disassembler
|
|---|
| 96 | .SH "SYNOPSIS"
|
|---|
| 97 | \fBdis88\fP [ -o ] ifile [ ofile ]
|
|---|
| 98 | .SH "DESCRIPTION"
|
|---|
| 99 | Dis88 reads ifile, which must be in PC/IX a.out format.
|
|---|
| 100 | It interprets the binary opcodes and data locations, and
|
|---|
| 101 | writes corresponding assembler source code to stdout, or
|
|---|
| 102 | to ofile if specified. The program's output is in the
|
|---|
| 103 | format of, and fully compatible with, the PC/IX assembler,
|
|---|
| 104 | as(1). If a symbol table is present in ifile, labels and
|
|---|
| 105 | references will be symbolic in the output. If the input
|
|---|
| 106 | file lacks a symbol table, the fact will be noted, and the
|
|---|
| 107 | disassembly will proceed, with the disassembler generating
|
|---|
| 108 | synthetic labels as needed. If the input file has split
|
|---|
| 109 | I/D space, or if it is executable, the disassembler will
|
|---|
| 110 | make all necessary adjustments in address-reference calculations.
|
|---|
| 111 | .PP
|
|---|
| 112 | If the "-o" option appears, object code will be included
|
|---|
| 113 | in comments during disassembly of the text segment. This
|
|---|
| 114 | feature is used primarily for debugging the disassembler
|
|---|
| 115 | itself, but may provide information of passing interest
|
|---|
| 116 | to users.
|
|---|
| 117 | .PP
|
|---|
| 118 | The program always outputs the current machine address
|
|---|
| 119 | before disassembling an opcode. If a symbol table is
|
|---|
| 120 | present, this address is output as an assembler comment;
|
|---|
| 121 | otherwise, it is incorporated into the synthetic label
|
|---|
| 122 | which is generated internally. Since relative jumps,
|
|---|
| 123 | especially short ones, may target unlabelled locations,
|
|---|
| 124 | the program always outputs the physical target address
|
|---|
| 125 | as a comment, to assist the user in following the code.
|
|---|
| 126 | .PP
|
|---|
| 127 | The text segment of an object file is always padded to
|
|---|
| 128 | an even machine address. In addition, if the file has
|
|---|
| 129 | split I/D space, the text segment will be padded to a
|
|---|
| 130 | paragraph boundary (i.e., an address divisible by 16).
|
|---|
| 131 | As a result of this padding, the disassembler may produce
|
|---|
| 132 | a few spurious, but harmless, instructions at the
|
|---|
| 133 | end of the text segment.
|
|---|
| 134 | .PP
|
|---|
| 135 | Disassembly of the data segment is a difficult matter.
|
|---|
| 136 | The information to which initialized data refers cannot
|
|---|
| 137 | be inferred from context, except in the special case
|
|---|
| 138 | of an external data or address reference, which will be
|
|---|
| 139 | reflected in the relocation table. Internal data and
|
|---|
| 140 | address references will already be resolved in the object file,
|
|---|
| 141 | and cannot be recreated. Therefore, the data
|
|---|
| 142 | segment is disassembled as a byte stream, with long
|
|---|
| 143 | stretches of null data represented by an appropriate
|
|---|
| 144 | ".zerow" pseudo-op. This limitation notwithstanding,
|
|---|
| 145 | labels (as opposed to symbolic references) are always
|
|---|
| 146 | output at appropriate points within the data segment.
|
|---|
| 147 | .PP
|
|---|
| 148 | If disassembly of the data segment is difficult, disassembly of the
|
|---|
| 149 | bss segment is quite easy, because uninitialized data is all
|
|---|
| 150 | zero by definition. No data
|
|---|
| 151 | is output in the bss segment, but symbolic labels are
|
|---|
| 152 | output as appropriate.
|
|---|
| 153 | .PP
|
|---|
| 154 | For each opcode which takes an operand, a particular
|
|---|
| 155 | symbol type (text, data, or bss) is appropriate. This
|
|---|
| 156 | tidy correspondence is complicated somewhat, however,
|
|---|
| 157 | by the existence of assembler symbolic constants and
|
|---|
| 158 | segment override opcodes. Therefore, the disassembler's
|
|---|
| 159 | symbol lookup routine attempts to apply a certain amount
|
|---|
| 160 | of intelligence when it is asked to find a symbol. If
|
|---|
| 161 | it cannot match on a symbol of the preferred type, it
|
|---|
| 162 | may return a symbol of some other type, depending on
|
|---|
| 163 | preassigned (and somewhat arbitrary) rankings within
|
|---|
| 164 | each type. Finally, if all else fails, it returns a
|
|---|
| 165 | string containing the address sought as a hex constant;
|
|---|
| 166 | this behavior allows calling routines to use the output
|
|---|
| 167 | of the lookup function regardless of the success of its
|
|---|
| 168 | search.
|
|---|
| 169 | .PP
|
|---|
| 170 | It is worth noting, at this point, that the symbol lookup
|
|---|
| 171 | routine operates linearly, and has not been optimized in
|
|---|
| 172 | any way. Execution time is thus likely to increase
|
|---|
| 173 | geometrically with input file size. The disassembler is
|
|---|
| 174 | internally limited to 1500 symbol table entries and 1500
|
|---|
| 175 | relocation table entries; while these limits are generous
|
|---|
| 176 | (/unix, itself, has fewer than 800 symbols), they are not
|
|---|
| 177 | guaranteed to be adequate in all cases. If the symbol
|
|---|
| 178 | table or the relocation table overflows, the disassembly
|
|---|
| 179 | aborts.
|
|---|
| 180 | .PP
|
|---|
| 181 | Finally, users should be aware of a bug in the assembler,
|
|---|
| 182 | which causes it not to parse the "esc" mnemonic, even
|
|---|
| 183 | though "esc" is a completely legitimate opcode which is
|
|---|
| 184 | documented in all the Intel literature. To accommodate
|
|---|
| 185 | this deficiency, the disassembler translates opcodes of
|
|---|
| 186 | the "esc" family to .byte directives, but notes the
|
|---|
| 187 | correct mnemonic in a comment for reference.
|
|---|
| 188 | .PP
|
|---|
| 189 | In all cases, it should be possible to submit the output
|
|---|
| 190 | of the disassembler program to the assembler, and assemble
|
|---|
| 191 | it without error. In most cases, the resulting object
|
|---|
| 192 | code will be identical to the original; in any event, it
|
|---|
| 193 | will be functionally equivalent.
|
|---|
| 194 | .SH "SEE ALSO"
|
|---|
| 195 | adb(1), as(1), cc(1), ld(1).
|
|---|
| 196 | .br
|
|---|
| 197 | "Assembler Reference Manual" in the PC/IX Programmer's
|
|---|
| 198 | Guide.
|
|---|
| 199 | .SH "DIAGNOSTICS"
|
|---|
| 200 | "can't access input file" if the input file cannot be
|
|---|
| 201 | found, opened, or read.
|
|---|
| 202 | .sp
|
|---|
| 203 | "can't open output file" if the output file cannot be
|
|---|
| 204 | created.
|
|---|
| 205 | .sp
|
|---|
| 206 | "warning: host/cpu clash" if the program is run on a
|
|---|
| 207 | machine with a different CPU.
|
|---|
| 208 | .sp
|
|---|
| 209 | "input file not in object format" if the magic number
|
|---|
| 210 | does not correspond to that of a PC/IX object file.
|
|---|
| 211 | .sp
|
|---|
| 212 | "not an 8086/8088 object file" if the CPU ID of the
|
|---|
| 213 | file header is incorrect.
|
|---|
| 214 | .sp
|
|---|
| 215 | "reloc table overflow" if there are more than 1500
|
|---|
| 216 | entries in the relocation table.
|
|---|
| 217 | .sp
|
|---|
| 218 | "symbol table overflow" if there are more than 1500
|
|---|
| 219 | entries in the symbol table.
|
|---|
| 220 | .sp
|
|---|
| 221 | "lseek error" if the input file is corrupted (should
|
|---|
| 222 | never happen).
|
|---|
| 223 | .sp
|
|---|
| 224 | "warning: no symbols" if the symbol table is missing.
|
|---|
| 225 | .sp
|
|---|
| 226 | "can't reopen input file" if the input file is removed
|
|---|
| 227 | or altered during program execution (should never happen).
|
|---|
| 228 | .SH "BUGS"
|
|---|
| 229 | Numeric co-processor (i.e., 8087) mnemonics are not currently supported.
|
|---|
| 230 | Instructions for the co-processor are
|
|---|
| 231 | disassembled as CPU escape sequences, or as interrupts,
|
|---|
| 232 | depending on how they were assembled in the first place.
|
|---|
| 233 | .sp
|
|---|
| 234 | Despite the program's best efforts, a symbol retrieved
|
|---|
| 235 | from the symbol table may sometimes be different from
|
|---|
| 236 | the symbol used in the original assembly.
|
|---|
| 237 | .sp
|
|---|
| 238 | The disassembler's internal tables are of fixed size,
|
|---|
| 239 | and the program aborts if they overflow.
|
|---|
