THIS DOCUMENTATION CONSISTS OF TWO PARTS. PART ONE IS A HISTORY OF RESOURCE DISASSEMBLER. PART TWO IS THE RESOURCE DISASSEMBLER DOCUMENTATION. RESOURCE DISASSEMBLER HISTORY: ------------------------------ The following text explains Bug Fixes and Changes in ReSource software since the printed manual. This includes all software later than ReSource V3.05. Section numbers refer to the printed manual, and are further identified by the following labels: [correction] - This is a correction to earlier documentation. [improvement] - This is an enhancement to an existing function. [bug fix] - This is a correction to a function that worked improperly. [new feature] - This is a feature that has not been previously mentioned. Where there are new functions, they have generally been added at the numerical end of the appropriate section. Changes for ReSource V4.00 (March 1990) ======================================= Synopsis: Generally, V4.00 is faster, and has more features that make it far easier to create a .asm file that will reassemble and run correctly the first time. The new "PROJECT/Disassemble" function can completely automate much of the disassembly process for many files. User-defined symbols enable you to create fully-symbolic disassemblies of files with unsupported or non-standard structures. The "next error line" function can intelligently seek out parts of a file that have not been fully and/or correctly disassembled. Version 4 is more intelligent at guessing data types. No longer will CODE, WORD or LONGWORD data types be selected at an odd address. But at even addresses, WORD and LONGWORD data types are used in preference to BYTE, unless the data is specifically addressed as a byte. Several functions have been changed. This may adversely affect macros, etc. It is *strongly* suggested that if you are upgrading from an earlier version that you take a few minutes to search for "V4." and find out if any changes affect your environment. General Info: [bug fix - V3.20] If the workbench screen is using interlace, ReSources' screen will now also use interlace. Previously, ReSource tried to open a screen of the same size as the Workbench screen, but didn't pick up the fact that interlace was on. Thanks to Brian Jackson and Darren M. Greenwald for reporting this bug. [improvement - V3.20] Scrolling is much smoother, because it now uses the blitter. Previous versions of ReSource did *not* use the blitter. [improvement - V4.00] Scrolling now uses blitter more efficiently (direct hardware access), making scrolling faster and smoother. [new feature - V3.20] Using "?" as the first parameter on the command line will now display the parameter syntax requirements, then exit immediately. [new feature - V3.20] ReSource will now accept "-I" or "-i" as the first parameter on the command line. This will force ReSource to use an interlaced screen. [bug fix - V3.20] On extreme rare occasions, when creating labels or symbols, ReSource would corrupt memory, the obvious symptoms being that most labels and symbols would display random characters. The bug would only appear if a "Save .RS" was performed immediately prior to more memory being allocated for the string buffer. Fixed. [bug fix - V3.20] If a label longer than 19 bytes was displayed as a "hidden" label, a system crash was likely. Fixed. [new feature - V3.20] ReSource macro files may now be disassembled, examined, edited, reassembled, and reused. "ShowMacros" is a support utility on the ReSource distribution disk. It is used to disassemble a ReSource macro file, into an assembly language source code file, suitable for reassembly. The output is compatible with the "CAPE" assembler, and the output file will be able to be used by ReSource as a macro file immediately. In order to use another assembler, remove the first line (the "bnryonly" directive). After assembly, you must strip the loader information from the file. To do this, simply load the file into ReSource as a load file, and then immediately save as a binary image file. Guidelines for editing the macro file source can be found in a separate file. 1.6 About the Mouse: [new feature - V3.20] When the left mouse button is held down, as well as the ctl key, symbols, end-of-line comments and full-line comments are now temporarily disabled, as well as optimization. This allows you to quickly see the value of any symbols present in code. [new feature - V3.20] While using the mouse to scroll, if the left Amiga key is held down, labels are created using forward references. Now, if the left mouse button is pressed while the pointer is within 3 pixels of the right screen border, ReSource will assume that you are holding the left-Amiga key down, until you let the left mouse button go. This makes it easy to create labels single- handed. You don't have to keep the pointer on the right while scrolling, only its position when you actually press the LMB is important. If you press the left-Amiga key while in one-button-parse, and then release it, ReSource will again test for the mouse position. [improvement - V3.20] When scrolling, the display used to "jump" when the top line on the display had any full-line comments, hidden labels, or a trailing blank line. This has been eliminated. [new feature - V3.20] If ReSource's window is selected (activated) when the intuition pointer is on the far left of the screen, a screen update will now *not* be performed. This may be necessary after saving to a ".asm" file, when the source profile information is to be saved to a file. 2.1.2 PROJECT/Open load file: [new feature - V3.20] It is now possible to abort from an "Open load file" operation. [bug fix - V3.20] When a file with overlays is loaded, only the root node is loaded. When this happens, the user is now notified of this, and must select "okay" on the requester before ReSource will continue. [new feature - V3.20] The "LABELS/Create multiple/Reloc32" function is called automatically after every "Open load file", unless there was no reloc32 table in the file, and providing that this is not overridden by the new "OPTIONS2/Auto labels/OFF" option. It may be stopped by pressing rAmiga-A, anyway. 2.1.11 PROJECT/Disassemble: [new feature - V4.00] This is a new function that does most of the work in converting "START+" references to label references. It can also recognize many types of "jump tables", especially those in programs created using one of the popular "C" compilers. It can be used on most executables, but before using, you (the user) should determine if a base register is being used to reference data and/or code. If so, use one of the "SPECIAL FUNCTIONS/Convert xx(A4) EA's/" functions to do the conversions, then go ahead and select the "PROJECT/ Disassemble" function. The following guide is applicable to most executables that require disassembling: 1. Check for base register addressing. Select the appropriate EA conversion function from the SPECIAL FUNCTIONS menu. 2. Select the "PROJECT/Disassemble" function. 3. Move the cursor to the start of the file, and select the "CURSOR/ Relative/Next uncertain D/T" function. This function asks ReSource to show you places in the file where it needs some help in determining what type of data (code/ASCII/bytes/words/longwords) is there. At each location, change the data type if required, and then *without scrolling*, select the "CURSOR/Relative/Next uncertain D/T" function again. This tells ReSource that it can now be certain that the data type there is correct. Keep doing this until you hit the end of the file. 4. Select the "PROJECT/Disassemble" function again. If you changed anything in step 2 to code, this will convert more labels. Repeat steps 3 and 4 until you no longer find any uncertain data types in step 3. 5. Move the cursor to the start of the file, and use the "CURSOR/Relative/ Next error line" function. ReSource will move the cursor to places in the file that require attention. These may be unresolved "START+" references, odd address errors, bad references, unreferenced code/data, library calls that haven't yet had a symbol created for them, or instructions that are either illegal, or extremely unlikely to be used. 6. The file is probably ready for reassembly, however you may first want to carefully examine the code, and create meaningful labels and symbols. Even though the "PROJECT/Disassemble" function may have been used before, perhaps several times for any particular file, after changing any other data type to "code", it may be useful to use it again. For example, there may be a large portion of code with only one entry point, which up until now has been shown as ASCII. After changing to code, the "PROJECT/Disassemble" function should be able to resolve ALL the "START"+" references for the entire subroutine, and all the subroutines that it calls, and so on. 2.1.8 PROJECT/Save .RS: [improvement - V3.20] ReSource now remembers the presence of any "AFLINE" macros, after saving/ reloading a ".RS" file. 2.1.10 PROJECT/Quit: [improvement - V3.20] When quitting, if any new macros have been defined, without being saved to a macro file, this fact will now be mentioned in the quit requester. 2.2.1.12 DISPLAY/Hiliting/Uninitialized data: [new feature - V3.20] When selected, any uninitialized data areas will be hilited. 2.2.1.13 DISPLAY/Hiliting/Optimize override: [new feature - V3.20] When selected, any code that has the optimize overrride attribute bit set will be hilited. 2.2.1.14 DISPLAY/Hiliting/DCB override: [new feature - V3.20] This function will hilite any areas that have been selected by "DISPLAY 2/DCB override/Set". 2.2.1.15 DISPLAY/Hiliting/Optimizations: [new feature - V3.20] When selected, any code that ReSource has optimized in any way will be hilited. 2.2.1.16 DISPLAY/Hiliting/Symbols: [new feature - V3.20] When selected, all symbols will be hilited. A symbol in ReSource is defined as a character string you assign to a number. This string will be displayed in place of the number, and will be hilited by this function. 2.2.2 DISPLAY/Set data type/: [correction - V3.20] Attempts to set the data type to ASCII or CODE in a BSS or uninitialized data area will now instead set the data type to BYTES. Regardless of the setting of the attributes bits, data in a BSS hunk or in an uninitialized data area will *always* show as "ds.b", "ds.w" or "ds.l". [bug fix - V3.20] Previously, where code, words or longwords started very close to the end of a section (this includes the end of the file), sometimes it would extend right across the section start, preventing the section statement from being displayed. Where this occurs, the data type at the first byte is now changed to bytes, and disassembly is restarted from the same address. This continues until the section statement is no longer hidden. [improvement - V3.20] If a line is displayed such that a reloc32 longword will overlap to the next line, the data type at the start of that line is changed to bytes/words, effectively preventing the overlap. [new feature - V3.20] If data type "word", "longword" or "code" is selected at an odd address, a DisplayBeep() is now generated. [improvement - V3.20] If a label is defined for an uninitialized data or BSS area, and the data type for the previous word was set to longword, ReSource will override the previous data type in order to avoid hiding the label. This will also be true for other combinations of data type sizes, such as when the previous byte had its data type set to words. This means that you should no longer see any hidden labels in a BSS or uninitialized data area. [bug fix - V3.20] The double-quote character ($22) was not being recognized as a valid ASCII character. These will now be displayed in ASCII strings, just like any other valid ASCII characters. [improvement - V4.00] Indexes on "$24(A0)" and "$24(A0,D0.W)" type effective addresses will no longer show as binary or ASCII. The problem before was that sometimes when there were 2 numbers on a line, an index and an immediate value, where one wanted the immediate value shown as ASCII or binary, the index would also show as ASCII or binary. Selecting decimal will still show both as decimal. 2.2.5 DISPLAY/Blank lines/: [new feature - V3.20] Selecting "DISPLAY/Blank lines/Entry points" function will create a blank line where data ends, and code starts. 2.2.7.2 DISPLAY/Titlebar info/Attributes: [correction - V3.20] When a user-defined label is created, the "internally produced" bit in the attributes table is now cleared. When the user defines or redefines the data type, the "Uncertain data type" attribute bit is now cleared. This bit is now also cleared when a label is removed. 2.2.9 DISPLAY/Block-fill: [improvement - V3.20] The "DISPLAY/Block fill" function had several problems: 1. Changing the data type for a byte or area with an area that had been block-filled, was extremely difficult, as it had to be done for each and every byte. 2. After a block fill, ASCII was not displayed correctly. 3. Scrolling backwards through an area that had been block-filled would give an inconsistent display. 4. The wait pointer should have been displayed, especially for large fills. These limitations have been removed. 2.2.9.1 DISPLAY/Block-fill/Set start: 2.2.9.2 DISPLAY/Block-fill/Set end: 2.2.9.3 DISPLAY/Block-fill/Fill: [correction - V3.20] To use the "Block fill" function, the start and end addresses must now be specified by selecting "DISPLAY/Block fill/Set start" and "DISPLAY/Block fill/Set end" at the appropriate locations in the file. The block-fill start and end addresses will default to the actual start and end of the file. Selecting "DISPLAY/Block-fill/Fill will copy the data type attributes of the first byte, from the start location up to, but not including, the end location. 2.2.10 DISPLAY/Fill-in data types: [improvement - V3.20] The second pass of "Fill-in data types" determines the line lengths. Much of this is now done on-the-fly, during normal disassembly. This is mostly noticeable when strings are displayed. [improvement - V3.20] When a line is disassembled, if a reloc32 starts the line, it will now *always* show as a longword. Previously, it sometimes showed as code, until the first "Fill-in data types" was done. [improvement - V3.20] The "DISPLAY/Fill-in data types" and "DISPLAY/Fill-in D/T Fwd" functions used to perform many functions, one of which was to try to guess data type changes where it seemed appropriate. Because other functions have been greatly improved, this became less necessary, and even sometimes annoying when it made the wrong choice. The Fill-in data type functions have been greatly simplified, and will no longer make any data type changes themselves. As a result of this, they take around half as much time as they used to. It is still a good idea to use "DISPLAY/Fill-in data types" before saving to either a ".asm" or ".RS" file, however these are the only occasions when it should be required. 2.16 DISPLAY 2/DCB override/: [new feature - V3.20] "DISPLAY 2" is a new menu. These functions set or clear an attribute bit for the current line determining whether the DCB directive will be used on this line if there is suitable data. This bit works in conjunction with the global DCB option (see "OPTIONS 1/DCB statements") to comprise an exclusive- OR function: If global DCB's are ON, this bit will turn them off locally. Conversely, if global DCB's are set to OFF, this bit will enable them locally. 2.3.3 SYMBOLS 1/User-defined symbols: [new feature - V4.00] Once your symbol base files have been loaded, select from the "SYMBOLS 1/ User-defined symbols" menu, to create a symbol using that particular base. For more details, see the file, "UserSymbols.doc". 2.3.4 SYMBOLS 1/Load user symbols: [new feature - V4.00] This function will load a previously defined symbol base into ReSource. When the requester pops up, type in the pathname of your symbol base. To unload a symbol base, select "SYMBOLS 1/Load user symbols/", and then select CANCEL on the requestor. 2.3.5 SYMBOLS 1/Arp/: [new feature - V4.00] There is a new symbol base, "FileRequest". 2.4 SYMBOLS 2/: [new feature - V3.20] There is a new symbol base, "String control". This is meant to be used for ASCII control characters, such as DEL ($7F), BS (8), etc. [bug fix - V3.20] Several values in the "CIA Resource" symbol base were incorrect. Fixed. [bug fix - V3.20] A number of "SYMBOL" functions were giving bad symbols when the value for which a symbol was required, was greater than $FFFFFF. Fixed. [new feature - V4.00] There are two new symbol bases, "RexxArg" and "RexxMsg". 2.17 OPTIMIZATION/: [new feature - V3.20] This is a new menu. ReSource can now be used to optimize 68000 code. With this release, long branches may be changed to short branches, when the branch is within range. This is true even for forward branches, and includes conditional and unconditional branches, as well as branch-to- subroutine instructions. It is expected that other forms of optimizing will be supported later. 2.17.1 OPTIMIZATION/Local override/: [new feature - V3.20] This function may be used to override all optimizing at specific places within a file. For example, if a branch was short, it will remain short; if a branch was not short, it will be specifically set to long. This attribute bit will disable all types of optimizing at all places within a file where this bit is set. There are new hiliting functions to support the optimization functions (see "DISPLAY/Hilite/Optimize override" and "DISPLAY/ Hilite/Optimizations"). 2.17.2 OPTIMIZATION/Branches/: [new feature - V3.20] This function enables/disables the optimization of branches on a global scale. Optimization is temporarily disabled while holding down the ctl key, as well as the left mouse button. 2.5.3.22 CURSOR/Relative/Next hilite: [new feature - V3.20] Move cursor forward to the next line which has any form of hiliting. By changing the type of hiliting, in the DISPLAY/Hiliting" menu, you can tailor the search for various attribute types to your own needs. 2.5.3.22 CURSOR/Relative/Next error line: [new feature - V4.00] This is a new function that advances the cursor to the next line that produces any of the following: 1. "START+" reference. 2. Odd address error: DC.W, DC.L, or code at an odd address. 3. Invalid code: Includes unknown mnemonics, and data which immediately follows code, where the last instruction was *not* one of the following: ILLEGAL, RTS, TRAP, STOP, RTE, TRAPV, RTR, JMP, BRA, BRA.S, or AFLINE. 4. Bad reference: Includes where code references code as data, or data as code. This is very sensitive to code/data which has not been disassembled properly. 5. JSR to a negative offset from A6, where the offset has no symbol. This is most cases will be a library call. It is assumed that most people will want to create an "_LVO" type symbol for these. 6. Any line with NO label, immediately after a code line using one of the following opcodes: ILLEGAL, RTS, TRAP, STOP, RTE, TRAPV, RTR, JMP, BRA, BRA.S, or AFLINE. Generally, this will find code and data for which the references have not been properly disassembled yet. Sometimes, code and data is referenced from an address which is calculated, rather than hard-coded into the program. In this case, it may be okay even without a label. It may also be that there are complete subroutines or blocks of ASCII etc., that are not used. This may occur when the programmer removes a function, but does not remove everything that the function was referencing. 7. Illegal opcodes, and extremely unusual opcodes. "Unusual" opcodes include the "TAS" instruction, branches with an odd offset, ADDQ and SUBQ with an address register as the destination, and an odd number for the source, using the "EXG" for exchanging a register with itself, using "LINK" or "UNLK" with the stack pointer, etc. The purpose of the "CURSOR/Relative/Next error line" function is to find areas that MAY not be disassembled properly. There will be cases where the code/data has been disassembled correctly, but will still get picked up. Note that when a "Calculate .asm size" or "Save .asm" is performed, lines that are picked up by the above function are pushed onto the cursor location stack also. 2.5.4.3 CURSOR/Absolute/Forward reference: [improvement - V3.20] The "CURSOR/Absolute/Forward reference" and "CURSOR/Absolute/Second forward reference" functions previously allowed you to reference a label only. It is now possible to forward-reference from symbols which themselves reference labels, i.e.: ADD.W D0,D0 MOVE.W JumpBase(PC,D0.W),D0 JMP JumpBase(PC,D0.W) JumpBase DC.W FirstOffset-JumpBase DC.W SecondOffset-JumpBase DC.W ThirdOffset-JumpBase DC.W FourthOffset-JumpBase FirstOffset ... Any of the symbols on the "DC.W" lines, are each defined as the distance between two labels. Each of the symbols on these lines is evaluated by subtracting the offset of "JumpBase" from "FirstOffset", or "SecondOffset", etc. 2.5.4.8 CURSOR/Absolute/Specify label: 2.5.4.9 CURSOR/Absolute/Specify symbol: [bug fix - V3.20] When using these functions, if the required label/symbol was at the start of the file, the function would fail. Fixed. 2.5.4.11 CURSOR/Absolute/Swap W/Previous: [new feature - V4.00] This swaps the current cursor location with the one at the top of the cursor location stack. 2.6.1.2 LABELS/Create single/Full-line comment: [new feature - V3.20] Tab characters and line feeds in full-line comments are now supported and will be displayed as they should, on-screen, in a screen printout, and in any saved source code. 2.6.1.3 LABELS/Create single/Label: [new feature - V3.20] When supplying a string (to a string requester) that will become a label, symbol, or comment, you may now use indirection to include in that string, some other already-defined label, symbol, or comment. Indirection means a string is not used literally. Rather, it somewhat resembles a macro in that it "points" to other information, and is "expanded" when later encountered. Indirection must start with an "escape" character (just hit the "escape" key), and must be followed by a decimal digit between zero and three, inclusive. This is how you specify which type of string that you require: 0 = Label 1 = Symbol 2 = Full-line comment (the first one attached to a line only) 3 = End-of-line comment This should be immediately followed by a hex, decimal, or binary number, specifying the offset in the current file to which the required string is attached. Another escape character is required immediately following the number, as a delimiter. You are then free to either supply more literal text, or you may use indirection several times within a single string. Consider the following program fragment: lbW000140 DC.W 6 DC.W 8 DC.W 12 lbC000146 RTS lbC000148 MOVEQ #0,D0 RTS lbC00014C MOVEQ #1,D0 RTS The word values at label "lbW000140" correspond to the distance between "lbC000146" and "lbW000140" on the first line (6), the distance between "lbC000148" and "lbW000140" on the second line (8), and the distance between "lbC00014C" and "lbW000140" on the third line (12). This is what is commonly referred to as a "jump table". In order to make the program assemble properly, the values 6, 8, and 12 should be changed to symbols specifying their true meaning, rather than just the value that they were when the program was last assembled/compiled: lbW000140 DC.W lbC000146-lbW000140 DC.W lbC000148-lbW000140 DC.W lbC00014C-lbW000140 lbC000146 RTS lbC000148 MOVEQ #0,D0 RTS lbC00014C MOVEQ #1,D0 RTS The above example addresses the immediate problem of representing the offsets symbolically. However, if you later change the label "lbC000146" to "NullSub", for instance, the symbol "lbC000146-lbW000140" will cause an assembly error. Now, by using dynamic indirection, whenever the symbol at label "lbW000140" is displayed, ReSource will use whatever label is defined at that moment. (Because the escape character is not normally displayable, the following example will use a carat ("^") to represent the escape character.) For example, for the line: lbW000140 DC.W lbC000146-lbW000140 instead of creating the symbol "lbC000146-lbW000140", you would instead specify "^0$146^-^0$140^" when asked by the "LABELS/Create single/Symbol" function. Dynamic indirection is now also used internally in ReSource. For example, the "SPECIAL FUNCTIONS/Convert specific EA's/" functions now use dynamic indirection when creating symbols. Functions that access labels, symbols, and comments will normally support dynamic indirection in strings, unless the option "OPTIONS 1/Symbols/" is set to "OFF". In this case, the literal string will be used. Dynamic indirection is relatively safe to use with symbols. It is possible to use with labels and comments, however some problems may arise if care is not taken. Duplicate labels may easily be created if dynamic indirection is used in the specification for a label. It should be quite safe in any comments, however. Symbols containing dynamic indirection will not be stored in the EQUate or XREF tables. It is expected that most strings using indirection will be symbols, that refer to labels, and therefore will not require to be EQUated or XREF'd. 2.6.1.4 LABELS/Create single/Label - fwd ref: [improvement - V3.20] When creating labels from forward references, if ReSource detects that a reference to an odd address is coming from code, a DisplayBeep() will be generated, and also a macro fail will result. If using "LABELS/Create multiple/All", the scan will stop. 2.6.1.5 LABELS/Create single/Symbol: [new function - V3.20] If the user creates a symbol which is currently also defined as a label, a DisplayBeep() will be generated. [improvement - V4.00] It is now possible to create a symbol for "(A0)" type effective address. In this case, there is an assumed zero index. Please note well that "(A0)" and "0(A0)" are two different forms of addressing, respectively "Address Register Indirect" and "Address Register Indirect with Displacement". It may be that assigning meaningful symbols, such as "bm_BytesPerRow" will render your code more readable; it will also make it longer. 2.6.5.1 LABELS/Create multiple/Reloc32: [bug fix - V3.20] This function now checks the validity of reloc32 pointers before attempting label creation. 2.6.5.2 LABELS/Create multiple/All: [improvement - V3.20] This function now uses a different algorithm to detect when it should stop creating labels. The chance of it mistaking ASCII for code is now much decreased. [improvement - V3.20] When creating "shop" ASCII labels, if no valid text can be found to use in the label name, instead of creating a label starting with "lbA", ReSource now creates the label "ascii.MSG", or "ascii.MSG0", or "ascii.MSG1", etc. [new feature - V3.20] References to the START+$FFFFFFFC and START+$FFFFFFF8 are now shown as "ProgStart-4" and "ProgStart-8" respectively. If the label "ProgStart" is not defined anywhere, it will be displayed as a label attached to the first byte of the current file. You can still have some other label attached to the start of the file. 2.7 LOCAL MACROS/: 2.8 GLOBAL MACROS/: [bug fix - V3.20] Holding down the left mouse button during macro execution no longer temporarily sets the execution speed to "Slow". This was previously causing some minor multitasking difficulties. [new feature - V3.20] Whenever functions within a macro are being executed, a very small group of pixels within the title bar are constantly changed. This is the only visible feedback that you will see while executing a macro when the execution speed is set to "Very fast". This is also done during searches, etc. [improvement - V3.20] During the creation of a macro, the responses within requesters are now "STORE" and "USE" instead of "OKAY" and "CANCEL" as a better indication of how ReSource responds to text input during a macro creation. [improvement - V3.20] While a macro is executing, if the "CANCEL" gadget is selected for a requester, the macro will now abort immediately. [bug fix - V3.20] It was sometimes difficult to abort from an executing macro, especially if the macro execution speed was set to "wait on mouse". Fixed. [improvement - V3.20] While macro execution speed is set to "Wait on mouse", and ReSource is waiting for the mouse click, if macro execution speed is changed, macro will continue immediately without having to click once more. [bug fix - V3.20] During the creation of a macro, if an attempt to create some other macro was initiated, the resulting macro often caused a system crash. Now, if an attempt is made to create a macro while already creating a macro, it will be ignored. [correction - V3.20] The function "LOCAL MACROS/Save local macros" has always saved all macros, and not just the local ones. It has been renamed "LOCAL MACROS/Save all macros". 2.9.2 STRINGS/Put label: [correction - V3.20] The location of this function has been changed, see "STRINGS/Put/Label". 2.9.3 STRINGS/Put attributes: [correction - V3.20] The location of this function has been changed, see "STRINGS/Put/Attributes". 2.9.2.1 STRINGS/Put/Label: [correction - V3.20] This function is now a sub-item on the "Put" menu-item. There is no functional change. 2.9.2.2 STRINGS/Put/Attributes: [correction - V3.20] This function is now a sub-item on the "Put" menu-item. There is no functional change. 2.9.2.3 STRINGS/Put/Base register: [new feature - V3.20] The support for base register-relative addressing has been extended to allow an address register other than A4 to be used. This can be done by using either "STRINGS/Put/Base register", or "SPECIAL FUNCTIONS/Specify base register". To use this function, you must first place a number between 0 and 7 inclusive, into the accumulator. The current base register in use will be visible in the "SPECIAL FUNCTIONS/Convert xx(A4) EA's" function; you may see "xx(A6)" instead, for example. For use in macros that must be able to calculate and enter the base register number, this function must be used rather than "SPECIAL FUNCTIONS/Specify base". 2.9.7.6 STRINGS/Maths functions/Divide: [improvement - V3.20] This function now handles full 32-bit divides. 2.9.7.7 STRINGS/Maths functions/Negate: [correction - V3.20] The number within the accumulator is negated, using the currently set operand size. If the result is zero, a macro 'fail' will result. 2.9.7.8 STRINGS/Maths functions/Logical NOT: [correction - V3.20] The number within the accumulator is NOT'd in bitwise fashion, using the currently set operand size. If the result is zero, a macro 'fail' will result. 2.9.7.9 STRINGS/Maths functions/Logical AND: [correction - V3.20] You will be asked to supply a number, which will be bitwise AND'd with the contents of the accumulator, and the result is stored back into the accumulator. If the result is zero, a macro 'fail' will result. 2.9.7.10 STRINGS/Maths functions/Logical OR: [correction - V3.20] You will be asked to supply a number, which will be bitwise OR'd with the contents of the accumulator, and the result is stored back into the accumulator. If the result is zero, a macro 'fail' will result. [bug fix - V3.20] When the result of a "STRINGS/Maths functions/Logical OR" was zero, a macro fail should have resulted, but didn't. Fixed. 2.9.7.11 STRINGS/Maths functions/Exclusive OR: [correction - V3.20] You will be asked to supply a number, which will be bitwise exclusive-OR'd with the contents of the accumulator, and the result is stored back into the accumulator. If the result is zero, a macro 'fail' will result. 2.9.7.11 STRINGS/Maths functions/ROR: [new feature - V3.20] The contents of the accumulator will be bitwise rotated once right, and the result is stored back into the accumulator. The accumulator size is used to determine whether 8, 16, or all 32 bits will be rotated. If the accumulator does not contain a valid numeric value, a macro 'fail' will result. [new feature - V4.00] This function now ask how many times to rotate. Macros created with earlier versions that use this function must be re-created with ReSource V4. 2.9.7.11 STRINGS/Maths functions/ROL: [new feature - V3.20] The contents of the accumulator will be bitwise rotated once left, and the result is stored back into the accumulator. The accumulator size is used to determine whether 8, 16, or all 32 bits will be rotated. If the accumulator does not contain a valid numeric value, a macro 'fail' will result. [new feature - V4.00] This function now ask how many times to rotate. Macros created with earlier versions that use this function must be re-created with ReSource V4. 2.9.7.12 STRINGS/Maths functions/Clear: [new feature - V4.00] This function places "0" into the accumulator. 2.9.7.13 STRINGS/Maths functions/LSR: 2.9.7.14 STRINGS/Maths functions/LSL: 2.9.7.15 STRINGS/Maths functions/ASR: 2.9.7.16 STRINGS/Maths functions/ASL: [new feature - V4.00] These new functions ask for a shift count, and using the currently set accumulator size (byte/word/longword), do the shift, and place the result back into the accumulator, using the currently set accumulator numeric base (decimal/hex/binary). If the result is zero, a macro fail will result. 2.9.8 STRINGS/Define string/: [correction - V3.20] These functions allow to you define the contents of either the accumulator, or one of the string buffers A-M. Whenever you are asked for a string using the simple string requester (NOT the large file requester), you can either type in a string literal, or input an escape character (just press the escape key), followed by either another escape character, or one of the letters A-M inclusive. If the second character is the escape character, the string being requested will be copied from the accumulator instead. If the second character that you typed (after the escape character) is one of the letters A-M, then the string being requested will instead be copied from the appropriate buffer A-M. This applies even when you are defining the contents of one of the string buffers. This method of using indirection should be particularly handy in sophisticated macros. The maximum string length in any buffer (including the accumulator) is 240 characters. 2.9.11 STRINGS/Output buffer/: [bug fix - V3.20] The functions "STRINGS/Output buffer/Append accumulator" had problems when more than 4K of information was put into it. Fixed. 2.10.1 SPECIAL FUNCTIONS/Repeat last command: [correction - V4.00] The repeat function has been changed slightly. Previously, all functions except cursor movements would be repeated by this function. Now, the last menu selection is repeated, regardless of whether it is a cursor movement function or not. The idea here is that it is cumbersome to repeatedly make menu selections and somewhat pointless to use a [repeat] key to repeat some other key. Now you may select a function from the menus, and press any number of keys to do other things; when the [repeat] key is pressed, it will repeat the same menu function last selected. 2.10.3 SPECIAL FUNCTIONS/Zap: [improvement - V3.20] When supplying a parameter for the "SPECIAL FUNCTIONS/Zap" function, if the string you supply starts with "l.", "w." or "b.", the number following will be treated as a longword, word, or byte, respectively. In this case, the accumulator operand size does not matter. The case of the letter "l", "w", or "b" may be upper or lower. 2.10.7 SPECIAL FUNCTIONS/Convert xx(A4) EA's/: [improvement - V3.20] The "SPECIAL FUNCTIONS/Convert xx(A4) EA's/This operand" previously would only work for lines following the pattern "LEA START+$xxxxxx,A4". Now, lines such as "MOVE.L #START+$xxxxxx,A6" will also work. [improvement - V3.20] When using "xx(A4)" type Effective Address conversions, the label "DT" has always been assumed to be defined. Now, if it is not defined by the user, ReSource will define it for you. It will be attached to the last DATA hunk in the file, or if no DATA hunks exists, the last BSS hunk, or failing that, the last CODE hunk. [correction - V3.20] This function previously toggled base register conversion. This has been replaced by the function "SPECIAL FUNCTIONS/Convert xx(A4) EA's/Disable". 2.10.7.8 SPECIAL FUNCTIONS/Convert xx(A4) EA's/Disable: [improvement - V3.20] This function allows one to turn off base register conversions. 2.10.12 SPECIAL FUNCTIONS/Specify Base Register/: [new function - V3.20] This function permits you to select the register to be used for base register conversions. See also "STRINGS/Put/Base register". 2.11.2.3 SAVE/Partial save/Reset start: 2.11.2.4 SAVE/Partial save/Reset end: [new function - V3.20] The start and end for partial saves now default to the start and end of the current file. Selecting these will reselect the default values. 2.11.3 SAVE/Save binary image/: 2.11.4 SAVE/Save .asm/: 2.11.6 SAVE/Save to memory/: 2.11.7 SAVE/Save tracks/: 2.11.10 SAVE/Save Screen: [new feature - V3.20] It is now possible to append to files when saving, rather than simply replacing them. To do this, the filename that you supply must start with "*>". For example, if you wish to append information to the file "ram:MySavedFile", when asked for a filename, you would type "*>ram:MySavedFile". This is valid for *any* file save, including screen saves, binary image saves, etc. 2.11.3 SAVE/Save binary image/: [bug fix - V3.20] This function would sometimes save less than what it should have. This would happen if there were at least 4 null bytes at the end of the current file. Fixed. 2.11.4 SAVE/Save .asm: [improvement - V3.20] It is now possible to abort from a "Save .asm", by using the normal abort key sequence (rAmiga-A). The file will still be created, but no further text will be saved to it. [improvement - V3.20] When using "SAVE/Save .asm/Partial" or "SAVE/Calc .asm size/Partial", no EQUate or Xref table will be created. [improvement - V3.20] "EQU" and "XREF" are now shown in the same case as you have set for code. [improvement - V3.20] "SAVE/Calc .asm size/" no longer sets name of file to "NIL:". [new feature - V3.20] During the functions "SAVE/Calculate .asm size/" and "SAVE/Save .asm/", for any lines which create code or data which will not assemble correctly (odd address, "START+" references, invalid code "????"), an address will be pushed onto the cursor stack, pointing to the start of each of these lines. Thus, after using one of these functions, use "CURSOR/Absolute/Previous location" to go directly to each erroneous line. This is an excellent way to quickly ensure that the source code you create will assemble properly. [new feature - V4.00] There is a new item on verbose save screen - "Bad references". There are two types of "bad references". The first type is where code is referenced using a data movement opcode, such as "MOVE" or "BSET". The second type is where data is referenced using a code reference, such as BRA, JSR, etc. Any lines that fall into this category are placed on the cursor location stack, the same way that "START+" references, invalid code, and odd address errors are handled now. The "invalid code" item on the verbose save screen now also picks up where data immediately follows code, *and* the last code instruction was none of the following: ILLEGAL, RTS, TRAP, STOP, RTE, TRAPV, RTR, JMP, BRA, BRA.S, or AFLINE. Also see "CURSOR/Relative/Next error line" for more information. [new feature - V3.20] You may have noticed a funny looking squiggle ";_[]" near the start of the source output, this is a hook for a profiler to be released in the near future. 2.11.10 SAVE/Save screen: [new function - V3.20] This function will prompt you for the name of a file. If the file can be opened, it will save the currently displayed text to that file. Use this to send a screen dump to the printer, or any other file. Note that this can be used at the completion of a "save .asm", to get a printout of the source code profile. Almost any function will cause a display refresh, so this must be the first function used. If you have to re-activate ReSource's window for any reason, in order to avoid refreshing the display (and erasing this information in doing so), place the mouse pointer at the extreme left edge of the screen, then press the LMB. 2.13.1 OPTIONS 2/ASCII longs: [improvement - V3.20] The "OPTIONS 2/ASCII longs/" options have been removed from the menus. Because any number can now be shown as ASCII individually (if within the valid ASCII range) these functions became obsolete. If you press a key which is bound to these functions, it will give the same result as if the key was not bound to anything. 2.13.6 OPTIONS 2/Assembler/CaPatch: [new function - V3.20] Source code produced for this assembler uses the "DX" directive, to support uninitialized data areas. This is the extra space at the end of data or code hunks, that appears to be BSS, but is actually attached to the data or code hunk. Other assemblers would use the "DS" directive instead, which makes the resulting program much larger than the original. This was not previously available to assembly language programmers. [new function - V3.20] When the selected assembler type is "Cape" or "CaPatch", the directives "bnryonly", "exeobj" and "objfile" are used where appropriate. 2.13.7 OPTIONS 2/Auto labels/: [new feature - V3.20] This function determines whether the "LABELS/Create multiple/Reloc32" function is called automatically after every "Open load file". 2.13.8 OPTIONS 2/Verbose saves/: [new feature - V3.20] The "SAVE/Save .asm" functions now give you a profile of the source code as it is saved. This may be disabled by selecting the new "OPTIONS2/Verbose saves/OFF" function. Each entry in the displayed table is counted as that condition occurs during the save, and the totals are displayed continuously. Please see "SAVE/Calculate .asm size/" and "SAVE/Save .asm/", for more information on this function. It is now possible to get a printout of this and any other screen in ReSource, using the new "SAVE/Save screen" function (see below). Speed penalty for enabling this function is approx. 20%. 2.13.9 OPTIONS 2/Multiple constants/: [new feature - V3.20] For byte, word, and longword lines, this option allows you to have many data constants displayed on each line, rather than just one. ReSource will limit the number of constants to your display width. 2.14.1 KEY BINDINGS/Rebind key: [improvement - V4.00] Now, when you select either a menu function or press a key, ALL functions in the menus, and ALL keys bound to those functions, will be displayed. Most functions will only have one menu function, however there are a few that are repeated in the menus (especially library symbol bases). Previously, you could not rebind the "PROJECT/Abort" function to any key. Now, if an attempt is made to bind a key to the Abort function, it effectively clears the binding for that key. ***************************************************************************** In an effort to minimize piracy, each copy of ReSource sold is individually assembled and linked, making it easy to tell who the original purchaser was, should it be pirated. Should you find any commercial copies of ReSource "floating around", send a copy to the author. Glen McDiarmid 28 Marginson Street, Ipswich, QLD. Australia 5405 (07) 812-2963 If you are the first to send in that particular copy of ReSource, you will recieve a complementary copy of my next software release. In any case, I will send back to you, the latest version of ReSource. This offer applies only to original purchasers of ReSource. - The Author ***************************************************************************** Documentation for ReSource (C) 1988 Glen McDiarmid TO GET STARTED QUICKLY: **************************************************************** Don't forget to put arp.library in your LIBS: directory! **************************************************************** Run ReSource from a CLI, and when you are presented with a file requester, select an executable file to disassemble (anything within your "C" directory will do nicely). Alternatively, you may disassemble Kickstart by supplying a filename of "*". Once loaded, you may scroll forwards/backwards through the file with the down/up arrow keys. Using the shift key with the up/down arrow keys will move you faster through the file. You may also use mouse-scrolling, by holding the left mouse button down, then SLOWLY moving the mouse forwards or backwards, depending on which way you want to move through the file. While moving forwards with the mouse, holding the left Amiga key down will start the label creation process, in a controlled manner. When labels are created, ReSource decides which type of data is being labelled, and it is generally correct in its judgement. Once you have made some labels, select the 'Fill-in data types' menu item, under the "DISPLAY" menu. Once you have created labels from all areas of code, select 'Fill-in data types' again, and you may then scroll through the file, checking for yourself that all is in order (there will occasionally be cases where ReSource made an incorrect judgement, and code made be shown as ASCII, or vice- versa). Use one of the "Set data types" sub-menu selections, to set the correct data type. Remember to use the "Fill-in data types" command again, so that code and data are shown correctly. If you are working on a large file, you may wish to save your work, so that you can continue it at a later time. To do this, select "save all" under the "PROJECT" menu. When you use the "save all" option, you are creating a "ReSource file", as it is only useable by ReSource. By default, the filename will end in ".RS". You may change this if you like. **************************************************************** ABOUT RESOURCE: ReSource is an interactive disassembler. To give you an idea of which files can and cannot be disassembled, the following is a list of files from a Workbench 1.2 disk, that ReSource can disassemble: C directory: all L directory: all LIBS directory: all DEMOS directory: Boxes, Dots, Spots SYSTEM directory: CLI, DiskCopy, Format, GraphicDump, IconEd, Say, SetMap. DEVS directory: all keymaps, all printer drivers, everything ending in ".device". FONTS directory: everything within sub-directories (topaz/11,emerald/17, etc.) UTILITIES directory: Calculator, Notepad ROOT directory: Preferences, Clock I personally wanted a good disassembler to fix bugs in many of the public domain programs that I use. I was also interested in getting to know how C programs worked, at the assembly language level. ReSource is the result of 3 and a half months full-time effort; during this time I have been using each version extensively. I am very impatient when it comes to waiting for programs to complete operations, this has resulted in a disassembler that is extremely fast, at the cost of memory usage. Even though ReSource was written purely in assembly language, it uses lots of memory, especially when disassembling large programs. Generally, if you have 1.5 Megs of memory, you will be able to disassemble most programs. To disassemble Kickstart, you will require at least 2 Megs if you have a hard drive, or 3.5 Megs if you do not have a hard drive. As a further condition, there must be at least 1.1 Megs of contiguous memory, for the attributes table. **************************************************************** GENERAL USAGE: **************************************************************** Don't forget to put arp.library in your LIBS: directory! **************************************************************** Disassembling a program consists of examining a load file (sometimes called "executable" or "object" files), and from the information contained therein, create a text file (assembler source code) which, when assembled, can be used identically to the original load file. It takes many, often hundreds, of hours of painstaking work to become proficient at disassembling even a small program manually. Even experts can spend many hours disassembling very small programs, while large Amiga programs may take weeks. From now on, this will not be the case with Amiga programs. Large programs (100K or larger) can be disassembled in an evening, while small programs (such as CD, PROMPT, AVAIL, ECHO, FILENOTE, etc., take around 3-5 seconds to produce re- assemblable source code. As an example, let's disassemble LoadWB, which you'll find in the C directory of just about any booting disk, including a standard Workbench disk (make sure that it comes from a V1.2 Workbench, not 1.1 or 1.3! At the CLI prompt, type: RUN RS C:LOADWB You don't really have to use the "run" command, but I find it convenient, so maybe you will too. When ReSource starts running, it will load the file "loadwb" from the C directory, and disassemble the first page for you. We can now start the label- creation process. This involves getting ReSource to examine lines of code, and on each line, if there is any reference to another part of the program, ReSource will decide which type of data is being referenced. For example, the first line of code in our program is: MOVE.L SP,START+$01E0 Okay, go to the menus, under "LABELS" menu, you'll find "Create single". A sub-menu box will pop out, and from this, select "Address symbol dest". Now, the first line of code in our program should be: MOVE.L SP,lbL0001E0 Now, scroll forward through the program (using shift-down arrow), until you find a line starting with "lbL0001E0": lbL0001E0 dc.l 0 The label "lbL0001E0" is something that ReSource has just now created. In this case, ReSource decided that the data being referenced was a Longword, hence the "L" in "lbL0001E0". If it was code that was being referenced, the label would have been "lbC0001E0" instead. There are five type of data recognized by ReSource: ASCII - CODE - BYTES - WORDS - LONGWORDS The processes involved in deciding which type of data is being referenced is quite complex, and such things as the surrounding code/data, the relative position of reloc32 areas, hunk types, relative position from the start of a hunk, the actual information being referenced, whether the data is word/longword aligned, the actual instruction from which the reference was derived, the proximity of other labels, and what data types they refer to, all take part in the decision-making process. If the first line of code in out program had been: MOVE.W SP,START+$01E0 , then the label created would have been "lbW0001E0" instead, and the data type at this label would have been set to words. If you like, you can manually set the data type of any byte in the program, by selecting a sub-menu item from the "Set data type" menu item, under "DISPLAY" in the menus. This will not create a label, but it will re-define the current byte within the file (on the top line of the display) as being ASCII, CODE, or whichever data type you selected. Generally, this is not required, except sometimes in large programs, but after letting ReSource do its thing first. If you like doing things with the mouse, you can even set the data type this way. Once you have mastered mouse scrolling, try holding down the left-shift key while still holding down the left mouse button. This will display everything as if it were set to the data type BYTES. Holding down the left alt key will display everything as if it were set to ASCII. Similarly, the left shift and left alt keys held down together to show everything in WORDs; hold down the ctl key and everything will be displayed as CODE. Hold down all three, and everything will be shown as LONGWORDS. If you decide make this data type permanent, press the menu button, and the current position within the program will be set to the data type currently being displayed. By holding down the right alt key, you can remove labels while scrolling. Now scroll back to the start of the program (select "Start of file" submenuitem, under the "Absolute" menuitem under the "CURSOR" menu). Alternatively, just use the up arrow key, to scroll back slowly. Look in the screen title bar to find out how far you are from the start of the file. This offset is being shown in hexdecimal. Now, use the down arrow key to scroll forward to the second line of code in our program: MOVE.L D0,START+$01E8 Again, select the "Address symbol dest" submenuitem, to create the label "lbL0001E8". Do this to as many lines of code as you like, so that you become familiar with the label creating process. What you have just done can be done far quicker, by using the "Create multiple" label functions. Firstly, select the "Open" menuitem, under "PROJECT" in the menus. Again, we will use "LoadWB" from within your C directory. Once it is loaded, look in the menu under "LABELS", go to the menuitem "Create multiple", and select "All" from the sub-menuitem box. Around three quarters of a second later, you should be at position "0001C8" relative from the start of the file. The top line of the display should read: lbL0001C8 dc.l 0 If this is correct, you should now find some more code to make labels from. To do this, you could use the down arrow key to scroll forward, the shift-arrow key to page forward, or let ReSource do the searching for you, by selecting "Next unparsed code" from the "CURSOR" menu. If there is no more code that has not been parsed, you will be returned to the start of the file. However in this case, there is more code to parse, so go to it! When eventually "Next unparsed code" returns you to the start of the file, slowly scroll through the file, and examine as you go. You should find some ASCII, but it isn't being shown like it really should. This is the time to select "Fill-in data types" from the "DISPLAY" menu. Okay, now the program is completely disassembled right? Well, nearly. If you followed the above instructions to the letter, there will be once more section of code that labels have NOT been created from. This will be at offset "000584". This is because this area of the program was only recognized as code, after it had been skipped over. In fact, the only reference to this part of the program is made at offset "0005E6", and the code is: JSR lbC000584 Again, create multiple labels within this area, and search for the next unparsed code. If you select "Next unparsed code" while at the start of the file, and ReSource cannot find any, then again select "Fill-in data types", and this should complete the disassembly of LoadWB. Actually, at this point, I generally will change some of the labels, so that they are meaningful. For instance, the first line of code places the contents of the SP register at "lbL0001E0", right? Scroll forward to the line starting with this label, and select "Address symbol" submenuitem, from the "Create single" menuitem, under "LABELS" menu. You will be requested to input a new label name. I would call this label "SaveSP"; you call it anything you like. Now, scroll backwards to the offset "0000D2": MOVE.L SaveSP,SP We didn't change this line, so what is going on? You have just witnessed one of the major benefits of an interactive disassembler; any label changes you make are reflected throughout the entire program, instantly. Anywhere else in the program that you can place a meaningful label, will help greatly in recognizing how a program executes, without actually executing it. Also, if you wish to make changes to the source, meaningful labels help greatly. While still within ReSource, you may add comments, both full-line, and end-of-line, to aid in the understanding of the program. **************************************************************** EXPLANATION OF FUNCTIONS: The following section gives details of the uses of each function, as they are shown in the menus. Not all functions are enabled in all versions, this is especially so in V0.x (demo version). PROJECT/Abort: Use this to abort out of most functions. PROJECT/Open: Requests you to select a file to open. Use this function to load executable files, as well as ReSource files. PROJECT/Restore: Same as PROJECT/Open, but assumes that you wish to open the same file as you last opened. PROJECT/Save .RS: Saves the file that you are currently working on, in a form useable only by ReSource. Also saves the current location with the file. To continue work on the file later, use the PROJECT/Open function. PROJECT/About: Gives you some specific details about the version of ReSource that you are currently using. PROJECT/Quit: Asks you for confirmation, then quits without saving. OUTPUT/Save .asm: Saves current file in assembler source code format. OUTPUT/O/P directory: Requests you to supply the name of a directory that .asm files will be sent to (you can still change this when you supply the name of the output file, it just makes it easier if you are disassembling many files). OUTPUT/Tabs: Use to select between real tabs (ASCII value 9) and spaces being used in the output source code. DISPLAY/Hiliting: Selective use of inverse video can be useful to give extra information about parts of a file. For instance, you may want to get a quick idea of which parts of a file came from a BSS hunk, rather than CODE or DATA hunks. To do this, select DISPLAY/Hiliting/BSS hunks. DISPLAY/Hiliting/Reloc32: I find it particularly useful to hilite the Reloc32 areas, especially when determining data types (reloc32 is documented in the Amiga technical reference manual. It ultimately means that a number of longwords in the file point to somewhere in memory, relative to the start of one of the hunks of the file. This almost always end up being somewhere within the file. This information helps ReSource greatly when defining data types). DISPLAY/Hiliting/Chip load hunks: Certain hunks of a load file may only be loaded into chip memory. Usually, graphics, especially sprites, will be included in one of these special hunks, and this information is sometimes useful, especially when you intend to re-assemble the file. "Chip load hunks" will hilite these hunks for you, also fast load hunks may be hilited. DISPLAY/Hiliting/Symbol scan: For all lines that you have created labels from, these lines will be hilited. DISPLAY/Hiliting/Data type uncertain: For most labels that ReSource creates automatically, it is certain of the data type that it assigns. Sometimes though, it cannot be 100% sure, and this function will hilite all lines that fall into this category. DISPLAY/Hiliting/Data type known: Similar to above function, only the lines where the ReSource was certain of the data type, will be hilited. DISPLAY/Hiliting/Internally produced refs: All lines which have a label that was created by ReSource, will be hilited. DISPLAY/Set data type: When you are certain of which type of data that you are looking at, select from one of the submenu items: Code - Ascii - Bytes - Words - Longwords DISPLAY/Set numeric base: By default, all numbers are shown in hexdecimal (base 16). You can change this to ASCII, DECIMAL or BINARY on any line by selecting from the appropriate sub-menu item. To change back to HEXDECIMAL, simply select the same function again. It is possible to change the default to decimal for numbers less than 16, or less than 10, using the decimal conversion function (see below). DISPLAY/Decimal conversion: By default, all numbers are show in hexdecimal. You can have numbers less than 16, or numbers less than 10, shown in decimal throughout the file, by selecting one of the appropriate sub-menu items. DISPLAY/Block-fill: This function will probably not get much use. It can be used to set the data type of blocks of data. For example, in a particular file, there may a large section of code, maybe 100K or so, and rather than rely on ReSource to make the correct judgement of data type every time, you can set the data type of every byte in the file to code, by doing the following: Scroll to the start of the block. Set the data type here to CODE. Select the "CURSOR/Remember" function. Now, scroll to the end of the block (don't use any function that stacks the cursor position, such as "CURSOR/Absolute/End of file", as this will change the remembered offset. When you get to the end of the block, select the "DISPLAY/Block-fill" function. The type of data at the start of the block will be echoed throughout the entire block. DISPLAY/Fill-in data types: This function has several uses, and will be one of the most-used functions. To understand what this function does, you will need to know how ReSource keeps track of data types (see section "Inside ReSource"). Suffice it to say, when you set the data type anywhere within a file, that data type is immediately echoed forward, to a maximum of several hundred bytes, but will not change any other places where the data type has already been set, or where there is an address symbol (label) on a line. Where there is large areas of a file where the data type has not been set, this function attempts to set the data type where appropriate. All of the above is done in the first pass. On the second pass, the length of each line is set, this is particularly useful where there is large areas of ASCII. This function should always be used just before saving a file as source code (OUTPUT/ Save .asm). DISPLAY/Set counter: The current offset in a file is always shown in the title bar, in hexdecimal. This is normal zero at the start of the file. You can change this, so that it is zero at somewhere other than the start of the file, by using this function. You may use this function to measure the size of a hunk, for example. To "reset" the counter, use the function "DISPLAY/Reset counter". DISPLAY/Reset counter: Resets the offset counter, in the title bar, so that it is zero at the start of the file. See "DISPLAY/Set counter". SYMBOLS: When you create an assembly-language program, if you wish to allocate some memory, you will probably have somewhere in you file: JSR _LVOAllocMem(A6) If you were to disassemble this program, this line of code would be show as: JSR -$0228(A6) , which is not particularly meaningful. When disassembling a program, if you can figure out which library base the A6 register is pointing to (in this case, it would be the EXEC library), you can get ReSource to make the appropriate substitution. In this example, you would select "SYMBOLS/E-G/Exec library". Following is another example: MOVE.L #$00038007,D7 MOVE.L 4,A6 JSR -$006C(A6) The second line loads Execbase into the A6 register, so you should move the third line to the top of the display, and select "SYMBOLS/E-G/Exec library". Scroll back a couple of lines, and you would see: MOVE.L #$00038007,D7 MOVE.L 4,A6 JSR _LVOAlert(A6) If you looked at the documentation for the Exec "Alert" call, you would find that one of the input parameters is required to be in the D7 register. If you then looked in the include file "exec/ alerts.i", you would find that the number "$00038007" consists of three values, OR'd together: AT_Recovery - AG_OpenLib - AO_DOSLib There is no need to go to all this trouble, simple line up the first line with the top of the display, and select "SYMBOLS/A-B/ Alert codes", and ReSource will make the appropriate substituition for you: MOVE.L #AT_Recovery!AG_OpenLib!AO_DOSLib,D7 MOVE.L 4,A6 JSR _LVOAlert(A6) Now isn't that much better than the original? There are over 200 different classes of symbols that ReSource can substitute (only two are enabled in the demo version). Consider the following lines of code: MOVE.L 4,A4 MOVE.L #$100000,$003A(A4) Let's assume that you wish to substitute a symbol for the "$003A" in the second line of code. By default, ReSource will attempt to substitute a symbol for the first number that it finds in a line of code. To change this, select "SYMBOLS/Set source/dest/ Destination", and then the appropriate symbol base (Exec library, in this example). CURSOR/Remember: Where it is possible to lose your place within a file by using certain functions (such as "CURSOR/Absolute/Start of file"), ReSource will store the current cursor location, just prior to the function being executed. To return to the previous cursor location, select "CURSOR/Absolute/Previous location". When you plan to return to a specific place within the file, using this function will make it easier to do so. It simply stores the cursor location on a stack, for later access. CURSOR/Clear Loc stack: The cursor location stack can contain up to 256 locations. If more locations are "pushed" onto this stack, the location at the bottom (the oldest) are forgotten. This function will empty the cursor location stack. CURSOR/Relative/Next byte: The cursor position is incremented. CURSOR/Relative/Previous byte: The cursor position is decremented. CURSOR/Relative/Next line: Scroll forward by one line. CURSOR/Relative/Previous line: Scroll backwards by one line. The length of a line will depend on what the data type is. Until you first use "DISPLAY/ Fill-in data types", backwards scrolling may not be quite what you expect. CURSOR/Relative/Next page: Scroll forward by one page. This will be approximately 20 lines. CURSOR/Relative/Previous page: Scroll backwards by one page. This will be approximately 20 lines. CURSOR/Relative/Skip forward: Scroll forward by approx 4096 bytes ($1000). CURSOR/Relative/Skip Backward: Scroll backward by approx 4096 bytes ($1000). CURSOR/Relative/Next unparsed code: Scroll forward to the next line of code, that has been labelled, and that has not been parsed for labels yet. CURSOR/Relative/Next data type change: Scroll forward to the next byte whose data type is different to the data type of the current byte. CURSOR/Relative/Previous data type change: Scroll backward to the first byte found whose data type is different to the data type of the current byte. CURSOR/Relative/Next uncertain data type: Scroll forward to the next position within the file that ReSource has labelled, but at the time was not quite sure of which data type to set. CURSOR/Relative/Next backward reference: Using the "CURSOR/Absolute/Backward reference" function, it is possible to find the first reference to the current position within the file. Use this function to find further references to the same position. The search function could be used instead, but may also find references within comments, mnemonics, or even within other labels. CURSOR/Absolute/End of file: Move cursor to the last line of the file. CURSOR/Absolute/Start of file: Move cursor to the first line of the file. CURSOR/Absolute/Forward reference: I'll use an example to explain this one: JSR lbC0132DE If you wanted to "check out" the subroutine at label "lbC0132DE", but later return to the current cursor position, simply scroll until this line is on the top line of the display, and select "CURSOR/Absolute/Forward reference". The current cursor location is stored (on a stack), so that you can return to this cursor position, using the "CURSOR/Absolute/Previous location" function. CURSOR/Absolute/Forward reference: This is similar to the "CURSOR/Absolute/Forward reference" function, except that on a line such as: MOVE.L lbL00DEAF,lbL00BEEF the second label is used (lbL00BEEF), rather than the first (lbL00DEAF). CURSOR/Absolute/Backward reference: Use to find the first reference made to the current cursor position. See "CURSOR/Absolute/Next backward reference". CURSOR/Absolute/Previous location: With many functions that change the cursor location substantially, the current cursor position is stored on a stack. To "pop" the last saved location, use this function. CURSOR/Scrolling speed: You can select from five scrolling speeds. This relates to the speed/smoothness of scrolling when using the "CURSOR/ Relative/Next line" and "CURSOR/Relative/Previous line" functions. CURSOR/Search/Set search pattern: You will be requested to input a string. Unless you select "CANCEL", the string you input will be searched for immediately, starting at the current cursor position. Normal ARP wildcards are accepted: (a|b|c) Will match one of a, b or c. These can be patterns. ? Matches any single character # Pattern repeated 0 or more times, in particular, #? matches anything. [char] A set of characters, for example, [abc] or [a..c] specify the same set. [^char] Match everything but this set of characters. * 0 or more occurances of any character. CURSOR/Search/Find next occurence: Using the current search string, search forward from the current cursor position. See "CURSOR/Search/Set search pattern". LABELS/Create single/End-of-line comment: You will requested for a string, which will be shown at the end of the current line, starting with " ; ". LABELS/Create single/Full-line comment: You will requested for a string, which will be shown on a seperate line, previous to the current line, starting with "; ". Generally, this will be used to add a comment too long to put at the end of the current line. LABELS/Create single/Address symbol: You will be requested for a string, which will become the label for the current line. Any references to the current line will use the new label name, throughout the entire file, immediately. LABELS/Create single/Address symbol dest: The current line of code will be searched for references to positions within the current file. If any are found, ReSource will make a decision on which type of data is at the position referenced, it will then set the data type, and create a label at that offset. This new label will be immediately used for all references to that location, which of course includes the reference within the current line. If the current line is not being shown as code, or if there is no references, or there is a reference, but it is outside of the range of the current file, then this function will do nothing. Normally, this function will only be used within macros, as it is easier and quicker to hold down the left Amiga key, while holding down the left mouse button, possibly while scrolling also. LABELS/Create single/Value symbol: Following is several examples of address symbols (labels), and value symbols. lbC000124 MOVE.B bm_Depth(A0),D0 In the above line, "lbC000124" is an address symbol, and "bm_Depth" is a value symbol. MOVE.B bm_Depth(A0),DepthByte In this line, "DepthByte" is and a reference to an address symbol (label), NOT a value symbol. MOVE.L #MEMF_CLEAR,D1 In this line, "MEMF_CLEAR" is a value symbol. If a value symbol had not been created for this line, the line would be: MOVE.L #$10000,D1 Address symbols (labels) always equate to a position within the file, while value symbols may equate to any value at all. Unfortunately, there is several cases where a value symbol may equate to a position within the file: MOVEA.L #lbC000134,A0 JSR (A0) In this case, you may assign a value symbol, in which case the value symbol will be shown, not the label name of the position within the file that the instruction refers to. If however, you later remove the value symbol, the then label name of the line being referenced (at present, this is "lbC000134"), will be shown. When you create an address symbol or value symbol, the name is NOT checked for validity, it is up to you to decide whether or not the assembler that you will be using will accept the resulting code. For example: MOVE.L #FFFFFFFA,D0 may be changed to: MOVE.L #-6,D0 by creating a value symbol "-6". Virtually any value can be given a value symbol, including bit numbers: BTST #AFB_68020,$0124(A6) LABELS/Create single/Value symbol - dest: Similar to "LABELS/Create single/Value symbol" function, except that the second reference within the current line will used, rather than the first: BTST #4,SysFlags(A6) LABELS/Edit single: All of these functions are identical to their counterparts in "LABELS/Create single", except that if their is an existing label/symbol/comment, you will be requested to edit it, rather than create a new one. Given the editing capabilities of a string gadget, the create functions are a luxury really, although I find that when I change a label/symbol/comment, I generally make it nothing like the original, hence I nearly always use the create functions, to save me the trouble of pressing "rAmiga-X". LABELS/Remove single/Address symbol: Remove any address symbol (label) for the current line. LABELS/Remove single/Value symbol: Remove ALL value symbols in the current line. LABELS/Remove single/End-of-line comment: Remove any end-of-line comment for the current line. LABELS/Remove single/All: Remove all symbols and comments for the current line. LABELS/Create multiple/Reloc32 all: For each reloc32 pointer within the current file, determine the data type being referenced, set the data type, and create a label at that address. This function should be used with caution, as when it makes a decision on the data type, it does not have the same information available as when creating labels normally. This function should be most useful after creating labels from all code in a program, where there is one or more large tables of pointers. LABELS/Create multiple/All: Starting at the current address, the "LABELS/Create single/Address symbol dest" function is executed, and if ReSource thinks that there was valid code in the current line, the "CURSOR/Relative/Next line" function is executed, and the entire function loops, otherwise the "PROJECT/-=Abort=-" function is executed. This function can make the disassembly process very fast, the disadvantage being that there is a very slight chance that what ReSource thinks is valid code, is really ascii, and invalid labels will be created. SPECIAL FUNCTIONS/Repeat last command: Execute the last function that was executed. This does not include most cursor movements. By rebinding this function to an easily-accessed key, such as the space bar, (and saving the keytable) there should be much less need to rebind keys often. SPECIAL FUNCTIONS/Convert xx(A4) EA's These functions were specifically designed to be used when disassembling 'C' programs, in which the A4 register is used as a base register for accessing data, throughout all or most of the program. Let's use an example program here: SECTION test000000,CODE LEA START+$11E,A4 LEA 0(A4),A1 MOVE.L $000C(A4),D0 .... rest of code SECTION test00011E,DATA dc.b 'dos.library',0 dc.l $00010001 END In the above program, the A4 register will point to the start of the data segment. There are three ways to tell ReSource where the A4 register will point to; in the above example, the "This operand" function could be used with the cursor at start of file, or the "This address" function could be used with the cursor at offset $00011E, or the "Specify" function could be used, suppying a parameter of "11E". Basically, with this function, you are telling ReSource where, relative to the start of the program, the A4 register can be assumed to be pointing. After you do this, any effective address that involves a word offset to the A4 register, will be shown as an absolute address. Thus, the example program above will appear as: SECTION test000000,CODE LEA START+$011E,A4 LEA START+$011E,A1 MOVE.L START+$012A,D0 .... rest of code SECTION test00011E,DATA dc.b 'dos.library',0 dc.l $00010001 END The advantage here is that labels can automatically be created where they could not before. If this conversion process is not used, it is likely that the program will not successfully re- assemble, as different assemblers assemble the same source code into different opcodes. For example, the assembler that I normally use does virtually no optimizing, and so the resulting program is often larger than the original, even if I did not modify the source code. For example: MOVE.L 4,A6 If absolute long addressing is used, the instruction above will be 6 bytes long, whereas if absolute short addressing is used, it will be only 4 bytes long. Where you wish to do EA conversions in only a portion of a program, you can set the lower and upper limits. Changing to absolute EA's will increase the size of the resulting program, unless you convert back to relative addressing, within the source code. I believe that one of the features of BLINK (from the Software Distillery) can help to make this conversion. SPECIAL FUNCTIONS/Convert specific EA's: Please read and understand the "SPECIAL FUNCTIONS/Convert xx(A4) EA's" functions first! Where you want to do specific EA conversions, use "Set base #1" (or #2, or #3), when the cursor is the same as where the base register (whatever that is, it does not have to be A4 this time) can be assumed to point to. Assuming that you set base #1, and it is the A5 register that is being used as a base register, you will then use the "Convert W/ Base #1" function to convert lines like: MOVE.L $0032(A5),A6 .. into: MOVE.L lbL0014AC(A5),A6 Note here that there has not actually been an EA conversion, but a label has been created, the data type at label "lbL0014AC" has been determined and set, and a value symbol ("lbL0014AC") has been created for this line. It is up to you then to make the necessary changes to the resulting source code, if re-assembling is required. Whereas the "Convert xx(A4) EA's" function converts immediately and automatically, you must use the "Convert W/Base #1" function on each line that you want converted. If you wish to convert a destination address, first use the "SYMBOLS/Set source/dest/Destination" function first. MACROS: There are currently twelve user-definable macros available in ReSource. To start macro #1, select "MACROS/Start/ #1", select the functions to be included in the macro (you can use the menus, or press keys, it's all the same thing to the macro). When you are done, select "MACROS/Start/#1" again, to end the macro. To run the macro, select "MACROS/Execute/#1". The display is always refreshed during the defining of a macro, however it is not during the execution. At the end of a macro, the display is always refreshed. You may nest macros, but you should not use recursion. If ReSource finds that the nesting level has exceeded 40, the macro will be abandoned. Macro files can be saved and re-loaded. When ReSource first starts up, it looks for "S:RS.macros". If it finds it, it will load it, and execute macro #12 immediately (that is why macro #12 is hilited in the menus). This is used to configure ReSource. Just start macro #12, set what option you want, end macro #12, save the macro file as "S:RS.macros", and ReSource will be configured every time that you run it. KEY BINDINGS: Every function in ReSource can be found in the menus. You do not need to use any keys at all, but you probably will want to. You can bind any function to any key. All Amiga keys are supported, you may use shift, alt, ctl, lAmiga, rAmiga, shift-alt, shift-ctl, alt-ctl, or shift-alt-ctl in combination with any key, as a distinct key to bind a function to. Thus, you have complete control over which keys do what. After re-binding some keys, you will probably want to save the keytable. If you save the keytable as "S:RS.keytable", it will be loaded every time you run ReSource. You may want to create several keytables, suitable for doing differing program types (C, assembler, etc.). OPTIONS/Show offsets: If this option is set to ON, all lines will start with either a label, or the offset from the start of the file. OPTIONS/Display Beep: If this option is set to ON, the "BeepDisplay" function is used to give feedback to the user, that either a function has failed, or that a lengthy function has completed, and that the user should now wake up. OPTIONS/User Feedback: If this option is set to ON, messages will appear in the title bar, to let the user know what ReSource is doing, especially while doing functions that take a lot of time, extraordinary functions that only ReSource has direct control over (such as dynamically allocating more memory for strings, etc.), and also information about what hunks, etc., that it finds in a load file. OPTIONS/Feedback Delays: If this option is set to ON, whenever a feedback message is displayed, ReSource will wait for you to read the message, before continuing. You will probably not want to keep this on all the time, as it can slow down the disassembly process somewhat, but while you are learning to use ReSource, it will probably be very useful. OPTIONS/Labels: If this option is set to ON, labels will be displayed. This is the default. OPTIONS/Value symbols: If this option is set to ON, value symbols will be displayed. This is the default. OPTIONS/End-of-line comments: If this option is set to ON, end-of-line comments will be displayed. This is the default. OPTIONS/Full-line comments: If this option is set to ON, full-line comments will be displayed. This is the default. **************************************************************** Don't forget to put arp.library in your LIBS: directory! ****************************************************************