Really Useful CD 1

home *** CD-ROM | disk | FTP | other *** search

/ Really Useful CD 1 / ReallyUsefulCD1.iso / extras / progutils / _moddis / docs / changes23 < prev next >

Wrap

Text File | 1991-11-16 | 12.5 KB | 262 lines

This file describes the changes from version 2 to version 3 of ModDis. CONFIGURATION VARIABLES ======================= There are now six logical variables in PROCinit which the user can change to suit his own preferences. All are TRUE by default. They are: debug% If TRUE debugging information is displayed in cyan while the program is running. This is useful for keeping an eye on where the program has got to. flop% If TRUE floating point instructions are recognised and disassembled using the FNflop macro, otherwise floating point instructions are rejected as coprocessor instructions. verbose% If TRUE full output is enabled while Script files are being replayed. This displays the full prompts and responses.If you are re-creating a particularly large Source file from its Script you may like to set verbose% to FALSE to speed up the process. guessalign% If TRUE alignment-byte guessing is enabled guessbratab% If TRUE branch-table guessing is enabled guessldrstr% If TRUE load/store double guessing is enabled FLOATING POINT MNEMONICS ======================== The program will now disassemble floating-point instructions using a macro FNflop. This is accessed by a LIBRARY call which is built into every source file generated by ModDis. Also enabled are assembler directives FNequfs, FNequfd, FNequfe and FNequfp which store floating-point numbers to single, double, extended precision and packed decimal respectively. These directives are used by the program in response to LDF and STF instructions. EXTERNAL PROCEDURES =================== In version 2 of ModDis, the user was allowed to define to procedures (PROCexternal and PROCdisexternal) to allow the program to deal with unusual situations. These have now been moved outside the program and are stored in a file in the Externals directory, which is accessed via a LIBRARY statement in ModDis. The default file (Externals.Default) consists of two empty procedures, namely: DEFPROCdisexternal ENDPROC DEFPROCexternal ENDPROC PROCexternal is called once before the analysis of the module begins. PROCdisexternal is called during the final phase when the assembly listing is being spooled to file whenever a type 7 (external) is encountered. For example, if,say, a Sprite file of length &100 bytes is embedded in a module at offset &1234 then the user might create the following External file: DEFPROCdisexternal PRINT"]" PRINT"OSCLI""Load SpriteFile ""+STR$~(O%)" PRINT"O%+=&100" PRINT"P%+=&100" PRINT"[OPT pass%" offset%+=&100 ENDPROC DEFPROCexternal FORoffset%=&1234TO&1333 type%(offset%)=7 NEXT ENDPROC In PROCexternal all the bytes corresponding to the Sprite file are set to type 7 (external) at the start of the program. When the disassembly proper comes across the first type 7 byte it calls PROCdisexternal. This prints the appropriate messages to exit the assembler, load the Sprite file at the assembler pointer O%, increment both O% and P% and re-enter the assembler. Finally it increments the ModDis pointer offset%. SCRIPT FILE FORMAT ================== The Script file format has been extensively revised. The format is now a series of blocks like this: begin keyword ... ... ... end A line starting with the word "begin" marks the beginning of a block and a line consisting only of the word "end" marks the end. There can be any number of lines between the begin and end, although most blocks use only one. The order of the blocks is not important, except that the responses block must come last. The keywords currently recognised are as follows: KEYWORD MEANING version The version number of ModDis used to produce the script file. eg ModDis 3.04. This information is placed in the Script file by ModDis when it's created, and is used to make sure that the Script file is compatible with the version of the program in use. module The name and version number of the module eg SpriteUtils 1.04 (22 Jul 1988) This is placed in the Script file by ModDis when it's created and is used to make sure that the Script file refers to the same module. nonreturn The number of subroutines which modify their return address in some way, followed by the offsets of these subroutines. In most cases this will simply be a single zero. It is intended to cope with things like this: BL s1234 EQUS "Hello world" .... where the subroutine at offset 1234 does not return to execute the following instruction. To cope with this, the user would enter 1,1234 in the nonreturn block, meaning one subroutine at offset &1234. Note that ModDis does not automatically recognise these cases - it's up to you to spot them and modify the Script file manually to cope with them. external The name of the BASIC file in the Externals directory which contains the external procedures used for this module. The default is "Default", which uses a file with empty procedures. If you want to use the external facility you should write your own external routines, store them in a file in the Externals directory and edit this block to contain the name of your External file. responses The user responses, written as 3 numbers separated by commas. They consist of the offset in hex, the type of data at this offset and the number of items. For example, 1240,-1,1 would mean one zero-terminated string at offset &1240. At present the responses block must be the last one in the Script file, and is not terminated by an "end". This may change in the future . If you try to run this version with a Script file from version 2 it will display an error message and stop, but will write a file called "Header" into the current directory. You can simply paste this header into your old Script file to bring it up to version 3 standard. (Note: A few people have pre-release copies of version 3. If you are one of these, you should delete the first 2 lines of the Script file before adding the new header) TYPE GUESSING ============= Version 3 of ModDis includes "guessing" for the first time. If it encounters some bytes of unknown type and there is no entry in the Script file the program applies some simple rules to try to establish what their type is before asking the user for help. At the moment there are three types of guessing: Alignment bytes If the program is not on a word boundary, and all the bytes to the word boundary are zero then it guesses that these are alignment bytes. This action is controlled by the variable guessalign% - it takes place if the variable is TRUE Branch tables If the program is on a word boundary and both this instruction and the previous one are unconditional branches then it guesses that this is part if a branch table. This action is controlled by the variable guessbratab% - it takes place if the variable is TRUE. Load/store word If the program is at a load/store register instruction, then the location loaded from/stored to is guessed to be a double. This action is controlled by the variable guessldrstr% - it takes place if the variable is TRUE. These three types of guessing were chosen initially because they were easy to implement and because they give very good results in practice. In most cases the amount of user interaction (and hence the size of the Script file) is reduced by about 30% and in extreme cases by as much as 60%. In the case of some very short modules guessing allows disassembly to be completed with no user intervention at all. The branch table guessing is particularly welcome since the old recognition routines never worked particularly well, and it was very tedious to be forced to single-step through a long table when it was perfectly obvious what it was. There is, however, a penalty to be paid in that the guesses may sometimes not be what you would have chosen. For instance, it is common for certain strings (like TASK) to be stored as a double, but if it is accessed by an LDR then guessing will disassemble it as a double rather than a string. Also, guessing alignment bytes will only work if the original programmer has taken the trouble to initialise his workspace to zeros when the original module was assembled. If there are any garbage bytes showing through guessing will fail to recognise them alignment bytes. Note that the program always checks the Script file first before resorting to guessing, so if you find that it's guessing wrong in one particular case you can manually add this one case to the Script file and leave guessing enabled for the rest of the module. If you find the program is guessing consistently wrong you should disable guessing and carry on as normal. CONFLICTS ========= Previous version did not deal with conflicts very well. If the program identified a byte as one type and then found it was already marked as another it simply stopped the program with an error message like "Expecting type n at nnnn". This version has improved things slightly, and now offers the prompt "[A]dvance, [R]etreat, [S]top ?" when a conflict arises. Pressing "A" means go ahead and overwrite the old type with the new one. "R" means back off and leave things as they are while "S" means stop the program while you figure out what's happening. SYSTEM VARIABLES ================ ModDis now stores the current filename in a system variable called ModDis$File. When prompted for a filename you can just press Return and ModDis will look up the system variable and use it as a filename. This system variable is also used by the Checker program if you don't give it a filename. The idea is that if you need to exit ModDis to edit the Script file manually, you can restart easily. Obviously the system variable is created the first time ModDis is run and is lost if the computer is reset so you must supply a filename at least once at the start of the ModDis session. COMMENTS ======== Comments can now be placed in the Script file, but only in the responses block at the moment. Putting a ! as the first character on a line will cause that line to be ignored by the program. I only added this feature so that I could experiment with removing certain responses from the Script file to see if the guessing routines could cope without them, so it will probably be of limited use to the user. OTHER MINOR CHANGES =================== There have been many other minor changes to ModDis, mainly correcting various bugs. For instance, version 2.01 incorrectly treated a conditional OS_Exit as an end-of-code, while ADD PC and SUB PC instructions were not. These and various other changes mean that Script files which worked with version 2 may no longer contain enough information to disassemble a module, and you may find yourself answering one or two extra questions. Similarly, the new guessing routines may render information already in the Script file unnecessary, but this will not impair the program's operation. The program now checks the validity of your responses, so that it refuses type 3, 4 or 5 if it is not on a word boundary, and refuses type 2 if it is not on an even address. If your Script file contains invalid responses of this kind ModDis will get stuck in an infinite loop - the only solution is to edit the Script file to correct or remove the offending response. Version 2 allowed labels to run into the assembler listing if they were exactly 19 characters long, and the comment field sometimes contained characters which confused the BASIC assembler. Both these problems have now been fixed. A bug which occasionally caused ADR to appear with no operand was finally tracked down and cured. OS_GenerateError is now recognised as end-of-code. Handling of the SWI-table is improved. It can now cope with tables with more branches than names, branch tables split into two by other code, etc.