DSM User's Manual GETTING STARTED (If you need this section; you don't need this program!) HOW TO USE DSM 2.1 How to Use DSM This chapter describes how to use DSM. It is designed to get you disassembling programs as quickly as possible, without getting caught up in the technical aspects of DSM. 2.2 Setting-up DSM To use DSM, it should first be copied to the Workbench 'c' directory. By copying DSM to the 'c' directory you will be able to invoke the disassembler as if it were an Amiga DOS command. 2.3 Using DSM Using DSM is easy. It doesn't require that you have a deep understanding of the MC68000 processor set, or that you be familiar with the Amiga load file structure. To the contrary! DSM was designed to be very user friendly. Just enter a simple command, and DSM automatically disassembles the program of your choice. Thus, to disassemble a program called 'programname' you would enter the command DSM programname -e where the '-e' following 'programname,' tells DSM to invoke its expert system option (which often leads to a better disassembly of program code). Entering this command causes DSM to create the file 'programname.dsm,' which will contain the assembly language source code listing for 'programname.' Thus, if you wanted to disassemble the 'makedir' program on the 'c' directory of the Workbench diskette, you would enter the command DSM c/makedir -e This would cause DSM to create the file 'c/makedir.dsm' which would contain the source code listing for the 'makedir' program. And, if you didn't want the source code listing to end up in the same directory as the target program, you would use the '-o' option. Thus, to force DSM to redirect its output to the ram disk, you would enter the command DSM c/makedir -e -o ram:makedir.dsm That's all there is to it. By using the '-e' and '-o' options, you can quickly and easily disassemble most any Amiga program you desire. 2.4 How to Tell that DSM is Done In phase 2 of the disassembly process, DSM prints out the label of the instruction/data statement currently under disassembly. Do not be alarmed if DSM does not end the disassembly process after it reaches the last label. This simply means that DSM is disassembly unlabeled statements which exist after the last labeled statement. You will be able to tell that DSM is done when the CLI prompt '1>' is printed to the screen. 2.5 Other Options After you've gotten comfortable with using the '-e' and '-o' options, you may wish to try using some of DSM'S other options, such as '-h,' for producing hex dumps in the disassembly, or '-s,' for splitting the output of DSM into more than one file. The following chapter fully discusses all of DSM's options, and explains how DSM works. The material, therein, although not required for casual use of DSM, may be of interest to the advanced user, especially if he or she is seeking to improve DSM's output by taking advantage of DSM's powerful '-f' option. TECHNICAL INFORMATION 3.1 Invocation Syntax This section explains how to invoke the DSM disassembler. It assumes that you have copied the DSM program to the Workbench 'c' directory as explained in Section 2.2 The disassembler may only be invoked from the CLI. Invocation of the disassembler is initiated by entering a command of the form: DSM <filename> [options] where parameters enclosed between < > are supplied by the user, and where parameters enclosed between [ ] are optional, and thus need not necessarily be supplied. Note that the filename parameter must appear prior to the options for the disassembler to function properly. For example, if you wanted to disassemble the AmigaDOS program 'makedir' you would enter the command: DSM c/makedir The disassembler's default output file is created by appending '.dsm' to the user supplied filename. In the above example, the default output file would have been 'c/makedir.dsm.' 3.2 Aborting Program Disassembly At any time during the disassembly process, DSM may be aborted by simultaneously depressing the control key and the 'C' key on the Amiga keyboard. 3.3 Options DSM supports the following options: -e Invoke DSM's expert system to assist in detecting statements. -f Disassemble the program using offsets specified in an offset file. -h Include a hex-dump of the program in the disassembler's output file. -o <outputfile> Redirect the output of DSM from its default file to the user specified file, 'outputfile.' -s [<size>] Split the output of the disassembler into separate files. If the optional size parameter is provided, the maximum size will be 'size' blocks. Regardless of whether or not the size parameter is entered, DSM will create a new output file whenever it detects the beginning of a program segment. -v Log error messages to a verification file instead of to the screen. The name of the verification file is created by appending '.ver' to the name of the program under disassembly. Options are supplied after the file name, and may be given in either upper or lower case letters. For example, if you wanted to redirect the disassembly of the 'makedir' program to the file 'my_output_file' you would enter the command: DSM c/makedir -O my_output_file Note that the command DSM c/makedir -o my_output_file would accomplish the same thing, since options may be specified in either upper or lower case. 3.3.1 The -e Option The '-e' option invokes DSM's expert system to aid in disassembly. Using this option will cause DSm to use its expert system to determine whether or not statements in a CODE segment should be treated as data, or code. Any references to statements which DSM detects while in expert system mode will be identified in the source code output file by labels which begin with the letter 'E.' These labels designate unconfirmed references which DSM was able to infer using various expert system techniques. This is in contrast with labels which begin with the letter 'L' in the source code output file. Labels beginning with the letter 'L' designate confirmed references which DSM was able to verify by tracing the flow of the program under disassembly. Disassembly can usually be much improved by using the '-e' option; however, since DSM is making inferences while in this mode, some data statements may be mistakenly disassembled as code if this option is used. 3.3.2 The -f Option The '-f' option is used to specify the location of code statements to the disassembler. To use the '-f' option you must first create an offset file. 3.3.2.1 How DSM Works In order to take full advantage of the '-f' option, you should first understand how DSM works. DSM disassembles a program by converting all known code statements info their corresponding MC68000 instruction mnemonics. Any statements remaining at the conclusion of this process, are assumed to be data statements unless the '-e' option is specified. The AmigaDOS operating system guarantees that the first statement in a program must be a code statement. Therefore, DSM assumes that a series of contiguous code statements, i.e., a code fragment, begins at this point. DSM disassembles this fragment and keeps track of references to other code fragments. The location of the code fragments are detected during disassembly. For example, if DSM encounters the statement jmp $27771070 it knows that at address $27771070 another code fragment may be found. Disassembly of a code fragment is terminated whenever the instructions bra, jmp, rte, rtr, or rts are detected, since statements following these instructions are not necessarily code statements. When disassembly of the current code fragment terminates, DSM checks to see if it knows the location of any other code fragments. If it does, these code fragments are in turn disassembled, and just as before, references to additional code fragments are noted. The disassembly process ends when all known code fragments have been disassembled. This disassembly method guarantees that all statements disassembled as code are, in fact, code statements. Unfortunately, some of the remaining statements (these statements are assumed to be data statements) may actually be code statements. Disassembly of code statements as data statements will occur if DSM can not detect a reference to the code statements. This happens when code statement references are made exclusively with the following addressing modes: address register indirect, address register indirect with displacement, address register indirect with index, or program counter with index. In order to overcome this difficulty, you may either invoke DSM's expert system by using the '-e' option as explained in Section 3.3.1, or you can specify the location of additional code fragments to DSM by using the '-f' option. In the latter case, DSM will not infer the location of code fragments; thus, provided that the locations of code fragments you specify in the offset file are correct, no data statements will be mistakenly disassembled as code when the '-f' option is used instead of the '-e' option. Note that use of the '-f' option over-rides the assumption that the first statement in the initial segment of a program, is a code statement; if you wish to continue disassembling under this assumption, you must specify an offset of 0 with respect to the 0th program segment. Finally, note that the '-e' and '-f' options are not mutually exclusive; both options may be spec...
Amiga7878