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 [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 Redirect the output of DSM from its default file to the user specified file, 'outputfile.' -s [] 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 specified at the same time if desired. 3.3.2.2 Offset Files In order to use the '-f' option you must first create an offset file. This file must be in the same directory as the program you wish to disassemble, and must have the same name as this program followed by the suffix '.off.' For example, if you wanted to use the '-f' option on the program 'makedir,' which is located in the Workbench 'c' directory, you would first have to create the offset file, 'c/makedir.off.' 3.3.2.3 Offset File Format An offset file can be created using the AmigaDOS editor, ed, or any other editor or wordprocessor which you are accustomed to using. An offset file consists of a number of offset data blocks and is terminated by the number -1. Each offset data block has the following format: segment number number of offsets for this segment, n offset 1 offset 2 . . . offset n -1 Note that each of the parameters in an offset file must start on the initial space of a line, and that each parameter must appear on a separate line. Comments may appear in an offset file. To place comments in the file, begin a line with the asterisk character, '*.' Characters following the asterisk are ignored by DSM. Parameters in the offset file may be specified in decimal or hexadecimal notation, whichever is preferable. To indicate to DSM that a parameter is a hexadecimal number, the number must be preceded with the character '$,' or, as is the practice in the C programming language, by the characters '0x.' To illustrate the use of offset files, let's disassemble the 'makedir' program using the '-f' option. To do this, you must first create an offset file in the Workbench 'c' directory, since this is the directory in which the 'makedir' is found. Using a text editor or wordprocessor, create the file shown on the next page and name it 'c/makedir.off' (note that this offset file can be found in the 'examples' directory on the DSM diskette). Type each line of the file as listed to create the offset file. After creating the file make sure that it is in the Workbench 'c' directory, and that it has the name 'makedir.off.' You are then ready to initiate disassembly. Enter the command DSM c/makedir -f from the CLI. If any fatal errors occur, refer to Appendix 1, and make sure that you have correctly created the offset file. * c/makedir.off * * first offset data block * * segment number 0 0 * 1 offset for this segment 1 * offset is 0 from the start of segment 0 $0 * -1 to indicate end of first offset block -1 * segment number 1 1 * 1 offset for this segment 1 * offset is hexadecimal 24 (note the 0x format for hex numbers) 0x24 * -1 to indicate end of second offset data block -1 * * now terminate the offset file with -1 -1 3.3.3 The -h Option The '-h' option is used to insert a hex-dump of the disassembled program into the output of DSM. This option is useful for determining code fragment offsets for use in creating offset files. Hex-dump information is included in the output of DSM as assembly language comments, and thus will not interfere with subsequent reassembly. The hex-dump information for a statement follows immediately after the statement's assembly language representation, and takes the form * offset from beginning of segment' hexadecimal data For example, if the instruction 'rts' appeared 10 bytes after the beginning of a segment, use of the '-h' option would cause DSm's output to include the following lines: rts * 0000000a' 4e75 3.3.4 The -o Option The '-o' option permits the user to redirect the output of DSM from the default file to a user specified file. For example, suppose you wanted to direct the disassembly of the 'makedir' program to the file 'disassembly_of_makedir,' which is to be located in drive df1. Furthermore, suppose you also wanted to use the '-f' option having previously created the file 'makedir.off' in the Workbench 'c' directory. To do this, you would issue the command: DSM c/makedir -o df1:disassembly_of_makedir -f Alternately, you could have entered DSM c/makedir -f -o df1:disassembly_of_makedir since options may be specified in any order. However, the command DSM c/makedir -o -f df1:disassembly_of_makedir would produce an error since the output file name must immediately follow the '-o' option. 3.3.5 The -s Option The '-s' option is used to split the output of DSM into more than one file. This option may facilitate source code modification by permitting you to split the disassembly of a large program into a number of smaller files. When the '-s' option is used, a new output file will be created each time DSM detects the start of a segment. The output files are named by appending the base output file name with '.segment number.file number for this segment.' For example, if you entered the command DSM c/makedir -s DSM would create the files 'c/makedir.dsm.0.1' and c/makedir.dsm.1.1,' since the base output file is 'c/makedir.dsm' and two segments (segment number 0 and segment number 1) exist in the 'makedir' program. Similarly, if you entered the command DSM c/makedir -s -o df1:disassembly_of_makedir DSM would create the files 'df1:disassembly_of_makedir.0.1,' and 'df1:disassembly_of_makedir.1.1.' An optional size parameter may be specified along with the '-s' option. This parameter determines the maximum number of blocks (note: a block is 256 bytes) in an output file. For example, if you wanted to disassemble the AmigaDOS program 'execute,' and did not want output files to exceed 25 blocks in length, you would enter the command DSM c/execute -s 25 which would cause DSM to create the files 'c/execute.dsm.0.1,' 'c/execute.dsm.1.1,' 'c/execute.dsm.1.2,' 'c/execute.dsm.1.3,' and 'c/execute.dsm.1.4.' Note that if a segment is split into more than one file, DSM imbeds include statements into its output which link all files for a given segment to the first file created for that segment. Thus, if you wished to reassemble segment 1 of the execute program in the above example, you would invoke an assembler specifying only the file 'c/execute.dsm.1.1,' since include statements within the output files would cause 'c/execute.dsm.1.2,' 'c/execute.dsm.1.3,' and 'c/execute.dsm.1.4' to be automatically assembled along with 'c/execute.dsm.1.1.' 3.3.6 The -v Option The '-v' option is used to cause error messages to be logged to a verification file instead of to the screen. The name of the verification file will be formed by appending the executable file name with the extension '.ver.' For example, the command DSM DSM:examples/speaktime -v will cause DSM to create a verification file called 'DSM:examples/speaktime.ver.' EXAMPLES 4.1 Purpose of the Examples Chapter The purpose of this chapter is to provide an example of how one might go about using the '-f' option to improve the disassembly of a typical program. For our purposes, we have chosen to base this example on the disassembly of the speaktime program. 4.2 The Speaktime Program Located in the examples directory of the DSM diskette, you will find the 'speaktime' program. When activated, 'speaktime' uses the Amiga audio device to announce the current time. This chapter further illustrates the use of DSM by going through the steps involved in producing an accurate disassembly of the 'speaktime' program. 4.3 Initial Disassembly of the Speaktime Program Enter the CLI and type the command: DSM DSM:examples/speaktime After disassembly, examine the resultant file, 'DSM:examples/speaktime.dsm,' using a text editor or wordprocessor. If you want to use the AmigaDOS editor, ed, you can accomplish this by entering the command: ed DSM:examples/speaktime.dsm Scroll up and down the output file. Note that disassembly is probably incomplete at this time, in that several code fragments appear to have been disassembled as data fragments. For example, in segment 0, beginning in line 146, you should see statements: beq.s L12 rts L15 dc.b $4e,$56,$ff,$fc,$2f,$2e dc.b $00,$08,$4e,$b9 It is entirely possible that the dc.b statements which follow the 'rts' should actually have been disassembled as code statements. 4.4 Determining Offsets Using the -h Option In order to improve the disassembly of the 'speaktime' program, you will need to construct an offset file. At this point you need to determine what the offsets to data statements which you think might be code are. Offsets can most easily be determined using the '-h' option. To disassemble 'speaktime' using the '-h' option, enter the command: DSM DSM:examples/speaktime -h After entering the command, DSM should query you as follows: Warning 8. Existing output file(s) will be lost if DSM continues. Do you wish to continue (y/n)? Type 'y' and then hit the return key since you no longer need the existing disassembly of 'speaktime.' 4.5 Improving the Disassembly with the -f Option The disassembly of 'speaktime' produced in the previous section will allow you to determine what offsets should be specified in your offset file. Using an editor or wordprocessor examine the newly created file, 'examples/speaktime.dsm.' Beginning at line 390, you should see the following statements: beq.s L12 * 000001d8' 67c0 rts * 000001da' 4e75 L15 dc.b $4e,$56,$ff,$fc,$2f,$2e * 000001dc' 4e56 fffc 2f2e dc.b $00,$08,$4e,$b9 * 000001e2' 0008 4eb9 Directly under the label 15 identifier, L15,lies an offset to a probable code fragment: $000001dc with respect to segment 0. This segment should be included in your offset file. Note that it will not be necessary to specify the offset $000001e2 for segment 0 in your offset file, since code at this location will probably be disassembled as part of the code fragment located at L15. A close examination of the 'speaktime' disassembly should enable you to chose other offsets for inclusion into the offset file. When you finish choosing offsets, you are ready to create the offset file. Follow the format outlined in Section 3.3.2.3 and be sure to name the offset file 'DSM:examples/speaktime.off.' Also, remember to specify an offset of 0 with respect to segment 0, in accordance with Section 3.3.2.1. The offset file you create should look something like this: * DSM:examples/speaktime.off * * segment number 0 0 * 6 offsets for this segment 6 * Note that an offset of 0 has been specified for segment 0 $0 $1dc $2e6 $46e $4e6 $620 * -1 to terminate first offset data block -1 * segment number 5 5 * 1 offset for segment 5 1 * $fa is the offset $fa * -1 to terminate the second offset data block -1 * -1 to terminate file -1 Note that the offset file list above is included in the 'examples' directory of the DSM diskette. When you are satisfied with your offset file, issue the command: DSM DSM:examples/speaktime -f -h If everything goes well, you should end up with a much more complete disassembly of the 'speaktime' program. The '-h' option was included in the invocation command since additional offsets may be needed to achieve complete disassembly of all code fragments in the 'speaktime' program. 4.6 Disassembly is an Iterative Process Disassembly is an iterative process; each successive disassembly should lead to a more complete listing of a program's code, and suggest additional offsets to be used in the next pass at disassembly. Through this process, DSM should enable you to arrive at that which is impossible to achieve using any other disassembler currently available for the Amiga: a completely accurate translation of the target program into MC68000 code and data statements. THE ATEM UTILITY 5.1 ATOM vs. ATEM The "AmigaDOS Technical Reference Manual," in the Additional Information section describes the ATOM utility. ATOM was designed to allow programmers to modify object code files to control the type of memory (CHIP, FAST, or PUBLIC) that program segments will be loaded into. ATEM performs this same function except that ATEM operates on executable files (i.e. programs) instead of object files. 5.2 When to Use ATEM You should use ATEM only when you need to force a program segment to load into a particular type of memory. If, while disassembling a program with DSM, you encounter Warning 3 or Warning 4, ATEM must be used on the recompiled program built from DSM's source code output files. ATEM may also be useful in fixing older Amiga programs which do not run correctly when memory expansion devices are attached. To perform such a fix, run ATEM on the problem program, and force all DATA segments to load into CHIP memory. By doing this, you will ensure that Amiga's graphic chips will be able to access the DATA segments. 5.3 ATEM Invocation Syntax ATEM is invoked through the CLI by issuing a command of the form: ATEM where the 'filename' parameter is the name of the program you want ATEM to work on. For example, to invoke ATEM on a program called 'foo,' you would enter the command ATEM foo 5.4 How to Use ATEM When ATEM is invoked, it makes a backup copy of the target program. The name of the backup copy is formed by appending '.bak' to the target program's name. ATEM then operates directly on the original copy of the target program. If you make a mistake with ATEM, you can recover by discarding the modified program and starting over again with the backup. ATEM is completely interactive. It will query you about the segment number you want to affect, and then it will ask you what type of memory the segment should load into. By responding to ATEM'S prompts, you should have no trouble whatsoever in modifying executable programs. APPENDIX 1: ERROR CODES AND MESSAGES A1.1 Error Codes and Messages This appendix describes DSM's error codes and messages. A1.1.1 Warnings Warnings are non-fatal in nature, i.e., they do not result in the termination of disassembly. Warnings are issued when code statements of a questionable nature are detected, or to alert the user to some condition which is out of the ordinary. Warning 1. Executable may exceed segment bounds. The last instruction in a segment should be bra, jmp, rte, rtr, or rts, otherwise, program execution will continue past the bounds of the current segment with unpredictable results. If the last instruction in a segment is not one of these, Warning 1 will be issued. Warning 2. Reference out of segment bounds. If DSM determines that an instruction would cause the Amiga to execute code which is not within the bounds of the source program's segments, marning 2 will be issued. Warning 3. Segment must be loaded into CHIP memory. Use ATEM utility to modify executable file. If DSM detects that a segment must be loaded into CHIP memory, Warning 3 will be issued. If you decide to reassemble and link the disassembler's output, you must use the ATEM utility to modify the resultant executable file. ATEM allows users to modify executable files so that segments will load into either CHIP, FAST, or PUBLIC memory. Warning 4. Segment must be loaded into FAST memory. Use the ATEM utility to modify executable file. If DSM detects that a segment must be loaded into FAST memory, Warning 4 will be issued. If you decide to reassemble and link the disassembler's output, you must use the ATEM utility to modify the resultant executable file. ATEM allows users to modify executable files so that segments will load into either CHIP, FAST, or PUBLIC memory. Warning 5. Estimated memory required to disassemble program (required kilobytes) exceeds available free memory (free memory kilobytes). If the estimated amount of memory required to disassemble a program (required kilobytes) exceeds the available free memory (free memory kilobytes) DSM will issue this warning. Later DSM will ask you if you wish to continue disassembly. If the required kilobytes is more than 20% larger than the free memory kilobytes you should probably answer no at the prompt, since it is unlikely that DSM will be able to fully disassemble the program due to memory constraints. If required kilobytes is within 20% of free memory kilobytes, you may wish to answer yes at the prompt. The estimated required kilobytes is a conservative prediction of the amount of memory required. If you encounter this warning while directing DSM's output to the ram disk, try redirecting the output file to df0 or df1. If you are running other applications simultaneously with DSM, you may be able to avoid this warning by clearing all other programs from memory and running DSM by itself. Warning 6. Estimated disassembler output size (output kilobytes) exceeds available free space (free kilobytes) in volume (volume name). Warning 6 will be issued whenever the estimated output file size (output kilobytes) exceeds the available free space on the disk which will receive DSM's output (free kilobytes). As with Warning 5, DSM will later ask you if you wish to continue disassembly. If output kilobytes is more than 20% larger than free kilobytes you should probably answer no at the prompt. If however, output kilobytes is within 20% of free kilobytes, you may wish to answer yes at the prompt. Since output kilobytes is a conservative estimate of how large the output file size will be, it is possible that enough free disk space exists despite this warning. If you encounter this error while using the '-h' option, try disassembling the program without the '-h' option. If the disk which you want to place DSM's output into is not 100% blank, you may be able to get around this warning by directing DSM's output onto a blank diskette. Also, if you own a hard disk drive, you can probably avoid this problem by directing DSM's output to dh0 instead of df0, df1, or ram. Warning 7. Existing verification file will be lost if DSM continues. If you are using the '-v' option, and DSM detects that an existing verification will be overwritten if disassembly continues, DSM will issue Warning 7. If you don't want to lose the old verification file, be sure to answer no when DSM asks you whether or not you wish to continue. Warning 8. Existing output file(s) will be lost if DSM continues. If DSM detects that existing output files will be overwritten if disassembly continues, DSM will issue Warning 8. If you don't want to lose these file(s), be sure to answer no when DSM asks you whether or not you wish to continue disassembly. Warning 9 and 10. Reserved for future releases. These warning are not applicable to the current version of DSM, but may be used in future releases. A1.1.2 Non-fatal Errors Non-fatal errors are just that - non-fatal - and hence, do not cause disassembly to terminate. Non-fatal errors are associated with the disassembly of code fragments; non-fatal errors are not issued during data fragment disassembly. If, during the disassembly of a code statement, a byte sequence which does not represent a valid MC68000 instruction is detected, or if a determination is made that the execution of the byte sequence will invariably lead to a microprocessor error exception, DSM will issue a non-fatal error. Then, DSM will return to the start of the current fragment, and repeat disassembly, only this time, instead of disassembling the fragment as code, it will be disassembled as data. Error 11. Illegal address specified. Microprocessor instructions must be word aligned on the MC68000. If DSM detects a reference to a code statement which is not word aligned, Error 11 will result. Error 12. Bad extension word. Certain MC68000 instructions consist of more than one information word. Words following the initial two bytes of an instruction are known as extension words. If DSM detects an extension word which is illegal in the context of the current instruction, Error 12 will be issued. Error 13. Invalid instruction op-code. Bits 12 through 15 of an instruction form the instruction's op-code. No valid MC68000 instructions utilize op-codes 10, or 15. If op-codes 10 or 15 are detected during the disassembly of what is supposed to be an instruction word, DSM will issue Error 13. Error 14. Invalid instruction code. This error indicates that the current machine word does not represent a valid MC68000 instruction. Error 15. Illegal effective address mode. Error 15 results when an effective address mode which is not allowed for the current instruction is detected. Error 16. Invalid index extension word. Address register indirect addressing with index, and program counter with index addressing require an index which is divisible by two, since MC68000 instructions must be word aligned. If DSM detects an index extension word which is not divisible by two, Error 16 will be issued. Error 17. Illegal size specified. Certain MC68000 instructions use bits 6 and 7 of the instruction word to indicate the number of bytes which will be affected. These two bits are collectively known as the size field. Error 17 results when DSM finds a size field which is not allowed for the current instruction. Error 18. Invalid exchange mode specified. Bits 3 through 7 of an 'exg' instruction specify the exchange mode. Error 18 results if the combination of bits 3 through 7 in an 'exg' instruction do not specify a valid exchange mode. Error 19. Exceeded initialized segment bounds. If, during disassembly of an instruction, DSM exceeds the bounds of the current segment, Error 19 will be issued. Error 20. Reserved for future releases. This error is not applicable to the current version of DSM, but may be used in future releases. A1.1.3 Fatal Errors Fatal errors are associated with conditions which make it impossible for DSM to proceed with normal program disassembly. Upon issuance of a fatal error, program disassembly will be terminated. Error 21. Hunk number out of range in relocation block. This error indicates that the program under disassembly was not compiled correctly. Error 21 is issued when reference to a non-existent segment is made within a program's relocation block. Refer to the 'AmigaDOS Technical Reference Manual' for further details. Error 22. Illegal length format in symbol hunk. The high byte of a symbol hunk-length longword must be set to zero. This error will occur if the program you are disassembling was not compiled correctly. For further information about symbol hunks, refer to the 'AmigaDOS Technical Reference Manual.' Error 23. Unable to close file. If DSM is unable to close a previously opened file, Error 23 will result. Error 24. Unable to open file. DSM issues Error 24 when it is unable to open a file. This error is most often associated with incorrect utilization of the '-o' option. For example, the command DSM c/makedir -o df1: will result in the issuance of Error 24 since df1 is a disk drive specifier, and, in and of itself, is not a valid name. Error 25. Overlay files not currently supported. DSM is not currently compatible with programs which make use of overlays. Error 26. Illegal offset in offset file. Offsets specified in an offset file must be divisible by two. Additionally, an offset for a particular segment may not be repeated in an offset file. Error 27. Inappropriate hunk type used in load file. If DSM detects a hunk type longword which is not appropriate for a binary load file, Error 27 will result. This error indicates that the program you are disassembling was not compiled correctly. Refer to the 'AmigaDOS Technical Reference Manual' for details concerning hunk types. Error 28. (This error message has been deleted). Error 29. (This error message has been deleted). Error 30. Invalid syntax. This error is issued whenever you invoke DSM utilizing invalid syntax. Review Chapter 3 if you consistently encounter this error. Error 31. Error in memory allocation. Error 31 results when DSM is unable to allocate enough memory to commence disassembly. If you encounter this error while directing the output of DSM to the ram disk, try redirecting the output to df0 or df1. If you are running other applications simultaneously with DSM, you may be able to avoid Error 31 by clearing all other programs from memory and running DSM itself. Error 32. Error in memory reallocation. DSM dynamically allocates memory during program disassembly. If DSM is unable to allocate memory as needed after the commencement of disassembly, Error 32 will be issued. Refer to Error 31 for guidance on how to potentially eliminate this error. Error 33. Not a load file. The current version of DSM is not capable of disassembling Amiga object files. Files specified for disassembly must be load files, i.e. executable programs. Error 34. Offset exceeds segment bounds. Offsets specified in an offset file must not refer to code lying outside the bounds of a program's segments. Error 35. Error in offset file format. If DSM detects an error in the format of an offset file, Error 35 will result. Refer to Section 3.3.2.3 for proper offset file format. Error 36. Output size specified must be at least 25 blocks. The smallest file size that you may specify using the '-s' option is 25 blocks. If you encounter this error, re-enter the command you used to invoke DSM, only this time specify 25 for the output file size. Error 37. Unexpected end in binary file. This error indicates that the program you are attempting to disassemble was not compiled correctly. If you have the original program object files, recompile the program using alink. Error 38. Unrecognized hunk type in load file. If DSM does not recognize a hunk type longword, Error 38 will result. refer to the 'AmigaDOS Technical Reference Manual' for details concerning hunk types. Note that this error will only occur if the program you are disassembling was not correctly compiled. Error 39. Unrecognized option. The options which DSM currently recognizes are as follows: -e, -f, -h, -o, -s, and -v. Error 39 will occur if you specify any option other than those listed above. Error 40. I/O error while writing to file. If an I/O error occurs while writing to a file, DSM will issue Error 40. A1.1.4 Other Errors Error numbers greater than 100 indicate that something is probably wrong with the DSM program itself. If DSM crashes inexplicably, this too could mean that a bug exists is DSM. OTG Software will attempt to assist you in resolving any problems you may encounter as the result of an error inherent to the DSM program. APPENDIX 2: SOURCE CODE MODIFICATION A2.1 Potential Source Code Modification Problems If you plane to modify DSM's output, you may encounter problems in the subsequent reassembly and recompilation of the modified code. This Appendix discusses some of these problems, and the means for potentially overcoming them. A2.2 Assembler Limitations Our experience with assemblers currently available for the Amiga has been somewhat short of satisfactory. Some of the limitations we have encountered are presented below. A2.2.1 Absolute Short Versus Absolute Long Addressing Some assemblers do not provide the means whereby absolute short addressing can be distinguished from absolute long addressing. For example, an assembler might assemble jmp $ffff8000 as $4ef9 $ffff $8000, thus interpreting the address $ffff8000 as an absolute long address. If the instruction were assembled utilizing the absolute short addressing mode, $4ef8 $8000 would result. According to the Motorola MC68000 assembly language document M68KMASM/D10, one should be able to force absolute short addressing by rewriting the jmp instruction as follows: jmp ($ffff8000).w Unfortunately, some assemblers do not recognize this syntax and will respond to the rewritten instruction with an error message. If the program you are disassembling makes use of jump tables, this could lead to serious problems; offsets in a jump table could become misaligned when absolute short addressing is required, but is instead assembled using absolute long addressing. Since an instruction which uses absolute long addressing requires two more bytes of memory than one which uses absolute short addressing, jump table offsets could become misaligned by two bytes for each occurrence of the incorrect assembly. The only way to force absolute short addressing in these situations is to substitute the problem instruction with its hexadecimal equivalent in a dc.b statement. DSM Version 1.0d now automatically makes this substitution for you. The assembly language mnemonic of the substituted instruction is shown immediately below the dc.b statement to indicate that the dc.b statement is, in fact, code. Thus, to force absolute short addressing in the above example, DSM would replace the 'jmp' instruction with the following data statement: dc.b $4e,$f8,$80,$00 ; jmp ($ffff8000).w Note that DSM performs a similar data statement substitution if it needs to force long addressing, as might occur with the instruction: jmp $00000000 A2.2.2 Immediate Addressing and Instruction Substitution Some assemblers refuse to recognize the immediate addressing mode for certain instructions; instead, an equivalent, but different, instruction is substituted. For example, some assemblers will not correctly assemble the instruction: add.b #$01,d1 Instead, the instruction addi.b #$01,d1 is substituted. We have found that substitution of 'andi' for 'and,' 'cmpi' for 'cmp,' 'ori' for 'or,' and 'subi' for 'sub' may also occur. These substitutions probably will not cause problems in a program since the substituted instruction requires the same number of bytes and affects the status register in the same way, as the original instruction. If, however, a program checks to see if it has been modified, instruction substitution could lead to problems. In this case, replace problem instructions with their hexadecimal equivalent in dc.b statements. A2.2.3 BSS Segments Some assemblers do not recognize BSS segments. For example the statement SECTION BSS,segment1 will produce an error message in some assemblers. This is usually not a problem so long as the assembler is able to accept DATA segment statements. In the above example, the assembly error could be eliminated by replacing the BSS segment with the following: SECTION DATA,segment1 A2.3 Compiler Limitations To date, we have experienced no problems with the Amiga compiler, alink. However, some assembly packages supply their own compilers. The following section notes a problem which we have encountered using an alink incompatible compiler. A2.3.1 Spurious BSS Segments Some compilers append an extra BSS segment to the end of a program. In and of itself, this should not lead to any problems, unless the program checks to see how many segments it is composed of. If the extra BSS segment causes a program to crash, you should probably recompile the program using alink. Alternately, using the 'AmigaDOS Technical Reference Manual' as a guide, you could use a line editor to remove the ending BSS segment. A2.4 Jump Tables Some programs utilize jump tables which consist of a series of offsets to various code fragments. If you plan to modify such a program, you may have to adjust these offsets to ensure that they will reference the appropriate code fragments upon recompilation. For example, if an offset referred to code which began 10 bytes after the start of a segment, and you proceeded to add 20 bytes to the beginning of this segment, you would have to adjust the offset by increasing it by 20. Doing so will ensure that, after recompilation, the adjusted offset will reference the correct code. End of file Docs provided by TNG and The Corsair