ReSource Reference Manual V1.0 For ReSource V3.05 and later Intelligent Interactive Disassembler for Amiga® Programmers Copyright © 1988, 1989 by Glen McDiarmid All Rights Reserved. Copyright Notice ReSource software and documentation are copyright by Glen McDiarmid. No part of the software or documentation may be reproduced, transmitted, translated into other languages, posted to a network, or distributed by electronic or other means without the express permission of the author, or his agents. In an effort to minimize piracy, each copy of ReSource sold is individually assembled and linked. Complex macros used during assembly are capable of creating literally millions of unique code combinations, making it easy to trace any illegal copies back to the original purchaser. Software thieves will be prosecuted to the full extent of the law. Disclaimer No responsibility will be accepted for damage that may appear to have resulted from the use of this product. The user assumes all responsibility in using this product. The material contained in this documentation is believed to be accurate, but the author reserves the right to update the software and/or documentation without notice. Distribution ReSource software and documentation are available from: Glen McDiarmid The Puzzle Factory 28 Marginson Street P.O. Box 986 Ipswich, Queensland Veneta, OR 97487 AUSTRALIA 4305 U.S.A. (07) 812-2963 (503) 935-3709 Update Policy Our update policy is very simple: For updates within a version (revision changes only), we simply ask that you return your original ReSource disk. If you provide postage and a return mailer, we will return it free of charge with the latest revision of the software. Otherwise, there will be a charge for media and shipping. For major updates, we will charge a nominal fee. Please send in your original ReSource disk and we will ship you the latest version. Trademarks Amiga, AmigaDOS, Kickstart, Intuition, and Workbench are trademarks of Commodore-Amiga, Inc. C.A.P.E. 68K, and C.A.P.E. are trademarks of Inovatronics, Inc. FastFonts © by MicroSmiths, Blitzfonts © by Hayes Haugen. [NOTE: Page numbers are only shown in the printed manual. Also, this document is an early version, and there have been some additions and corrections to the final, printed version. Sorry! JL] Table Of Contents Introduction . . . . . . . . . . . . . . . . . . . . . . . xx Getting Started . . . . . . . . . . . . . . . . . . . . . xx System Requirements . . . . . . . . . . . . . . . . . . xx The Command Line . . . . . . . . . . . . . . . . . . . xx Part 1. Tutorial . . . . . . . . . . . . . . . . . . . . xx 1. About the User Interface . . . . . . . . . . . . . xx 2. Definition of the Current Line . . . . . . . . . . xx 3. Disassembling a Program . . . . . . . . . . . . . . xx 4. About Menus . . . . . . . . . . . . . . . . . . . . xx 5. About Keys . . . . . . . . . . . . . . . . . . . . xx 6. About Load Files . . . . . . . . . . . . . . . . . xx 7. About Data Files . . . . . . . . . . . . . . . . . xx 8. About Output . . . . . . . . . . . . . . . . . . . xx 9. About Symbols . . . . . . . . . . . . . . . . . . . xx 10. Display Preferences . . . . . . . . . . . . . . . . xx 11. About Searches . . . . . . . . . . . . . . . . . . xx 12. ARP and Wildcards . . . . . . . . . . . . . . . . . xx Part 2. Reference . . . . . . . . . . . . . . . . . . . . xx 1. PROJECT MENU . . . . . . . . . . . . . . . . . . . xx 1. Abort . . . . . . . . . . . . . . . . . . . . . xx 2. Open load file . . . . . . . . . . . . . . . . xx 3. Open binary file. . . . . . . . . . . . . . . . xx 4. Restore file . . . . . . . . . . . . . . . . . xx 5. Dismble memory . . . . . . . . . . . . . . . . xx 6. Read tracks . . . . . . . . . . . . . . . . . . xx 7. O'lay binary image . . . . . . . . . . . . . . xx 8. Save .RS . . . . . . . . . . . . . . . . . . . xx 9. About . . . . . . . . . . . . . . . . . . . . . xx 10. Quit . . . . . . . . . . . . . . . . . . . . . xx 2. DISPLAY MENU . . . . . . . . . . . . . . . . . . . xx 1. Hiliting (menu) . . . . . . . . . . . . . . . . xx 1. None . . . . . . . . . . . . . . . . . . . xx 2. BSS hunks . . . . . . . . . . . . . . . . . xx 3. DATA hunks . . . . . . . . . . . . . . . . xx 4. CODE hunks . . . . . . . . . . . . . . . . xx 5. Chip load hunks . . . . . . . . . . . . . . xx 6. Fast load hunks . . . . . . . . . . . . . . xx 7. Reloc32 . . . . . . . . . . . . . . . . . . xx 8. Symbol scan . . . . . . . . . . . . . . . . xx 9. Data type uncertain . . . . . . . . . . . . xx 10. Data type known . . . . . . . . . . . . . . xx 11. Internally produced refs . . . . . . . . . xx 2. Set data type (menu) . . . . . . . . . . . . . xx 3. Set numeric base (menu) . . . . . . . . . . . . xx 4. Decimal conversion (menu) . . . . . . . . . . . xx 5. Blank lines (menu) . . . . . . . . . . . . . . xx 6. Cursor address (menu) . . . . . . . . . . . . . xx 1. Relative . . . . . . . . . . . . . . . . . xx 2. Absolute . . . . . . . . . . . . . . . . . xx 7. Titlebar info (menu) . . . . . . . . . . . . . xx 1. Filename . . . . . . . . . . . . . . . . . xx 2. Attributes . . . . . . . . . . . . . . . . xx 3. Accumulator . . . . . . . . . . . . . . . . xx 8. Wrap . . . . . . . . . . . . . . . . . . . . . xx 9. Block-fill . . . . . . . . . . . . . . . . . . xx 10. Fill-in data types . . . . . . . . . . . . . . xx 11. Fill-in D/T Fwd . . . . . . . . . . . . . . . . xx 12. Set counter . . . . . . . . . . . . . . . . . . xx 13. Reset counter . . . . . . . . . . . . . . . . . xx 14. Flip case - code . . . . . . . . . . . . . . . xx 15. Flip case - data . . . . . . . . . . . . . . . xx 3. SYMBOLS1 MENU . . . . . . . . . . . . . . . . . . . xx 1. Set Source/dest (Menu) . . . . . . . . . . . . xx 2. Object (Menu) . . . . . . . . . . . . . . . . . xx 4. SYMBOLS2 MENU . . . . . . . . . . . . . . . . . . . xx 5. CURSOR MENU . . . . . . . . . . . . . . . . . . . . xx 1. Remember . . . . . . . . . . . . . . . . . . . xx 2. Clear loc stack . . . . . . . . . . . . . . . . xx 3. Relative (Menu) . . . . . . . . . . . . . . . . xx 1. Next byte . . . . . . . . . . . . . . . . . xx 2. Previous byte . . . . . . . . . . . . . . . xx 3. Next line . . . . . . . . . . . . . . . . . xx 4. Previous line . . . . . . . . . . . . . . . xx 5. Next label . . . . . . . . . . . . . . . . xx 6. Previous label . . . . . . . . . . . . . . xx 7. Next symbol . . . . . . . . . . . . . . . . xx 8. Previous symbol . . . . . . . . . . . . . . xx 9. Next section . . . . . . . . . . . . . . . xx 10. Previous section . . . . . . . . . . . . . xx 11. Next reloc32 . . . . . . . . . . . . . . . xx 12. Previous reloc32 . . . . . . . . . . . . . xx 13. Next page . . . . . . . . . . . . . . . . . xx 14. Previous page . . . . . . . . . . . . . . . xx 15. Skip forward . . . . . . . . . . . . . . . xx 16. Skip backward . . . . . . . . . . . . . . . xx 17. Next unparsed code . . . . . . . . . . . . xx 18. Next D/T change . . . . . . . . . . . . . . xx 19. Previous D/T change . . . . . . . . . . . . xx 20. Next uncertain D/T . . . . . . . . . . . . xx 21. Next backward reference . . . . . . . . . . xx 4. Absolute (Menu) . . . . . . . . . . . . . . . . xx 1. End of file . . . . . . . . . . . . . . . . xx 2. Start of file . . . . . . . . . . . . . . . xx 3. Forward reference . . . . . . . . . . . . . xx 4. Second forward reference . . . . . . . . . xx 5. Backward reference . . . . . . . . . . . . xx 6. Previous location . . . . . . . . . . . . . xx 7. Specify offset . . . . . . . . . . . . . . xx 8. Specify label . . . . . . . . . . . . . . . xx 9. Specify symbol . . . . . . . . . . . . . . xx 10. Specify percentage . . . . . . . . . . . . xx 5. Copy (Menu) . . . . . . . . . . . . . . . . . . xx 6. Paste (Menu) . . . . . . . . . . . . . . . . . xx 7. Swap (Menu) . . . . . . . . . . . . . . . . . . xx 8. Scrolling speed (Menu) . . . . . . . . . . . . xx 9. Normal search (Menu) . . . . . . . . . . . . . xx 1. Set search string . . . . . . . . . . . . . xx 2. Find next occurrence . . . . . . . . . . . xx 3. Find previous occurrence . . . . . . . . . xx 4. Find nearest occurrence . . . . . . . . . . xx 5. Search this line . . . . . . . . . . . . . xx 6. Search accumulator . . . . . . . . . . . . xx 10. Pattern search (Menu) . . . . . . . . . . . . . xx 6. LABELS MENU . . . . . . . . . . . . . . . . . . . . xx 1. Create single (Menu) . . . . . . . . . . . . . xx 1. End-of-line comment . . . . . . . . . . . . xx 2. Full-line comment . . . . . . . . . . . . . xx 3. Label . . . . . . . . . . . . . . . . . . . xx 4. Label - fwd ref . . . . . . . . . . . . . . xx 5. Symbol . . . . . . . . . . . . . . . . . . xx 6. Symbol - dest . . . . . . . . . . . . . . . xx 2. Edit single (Menu) . . . . . . . . . . . . . . xx 3. Replace single (Menu) . . . . . . . . . . . . . xx 1. Label . . . . . . . . . . . . . . . . . . . xx 4. Remove single (Menu) . . . . . . . . . . . . . xx 1. Label . . . . . . . . . . . . . . . . . . . xx 2. Symbol . . . . . . . . . . . . . . . . . . xx 3. End-of-line comment . . . . . . . . . . . . xx 4. Full-line comment . . . . . . . . . . . . . xx 5. All . . . . . . . . . . . . . . . . . . . . xx 5. Create multiple (Menu) . . . . . . . . . . . . xx 1. Reloc32 . . . . . . . . . . . . . . . . . . xx 2. All . . . . . . . . . . . . . . . . . . . . xx 7. LOCAL MACROS MENU . . . . . . . . . . . . . . . . . xx 8. GLOBAL MACROS MENU . . . . . . . . . . . . . . . . xx 9. STRINGS MENU . . . . . . . . . . . . . . . . . . . xx 1. Get (Menu) . . . . . . . . . . . . . . . . . . xx 1. Label . . . . . . . . . . . . . . . . . . . xx 2. Symbol . . . . . . . . . . . . . . . . . . xx 3. Symbol - dest . . . . . . . . . . . . . . . xx 4. Symbol value . . . . . . . . . . . . . . . xx 5. Symbol value - dest . . . . . . . . . . . . xx 6. End-of-line comment . . . . . . . . . . . . xx 7. Full-line comment . . . . . . . . . . . . . xx 8. Search string . . . . . . . . . . . . . . . xx 9. Filename . . . . . . . . . . . . . . . . . xx 10. Save .asm name . . . . . . . . . . . . . . xx 11. Save .RS name . . . . . . . . . . . . . . . xx 12. Macros filename . . . . . . . . . . . . . . xx 13. Keytable filename . . . . . . . . . . . . . xx 14. Cursor longword . . . . . . . . . . . . . . xx 15. Cursor offset . . . . . . . . . . . . . . . xx 16. Accumulator length . . . . . . . . . . . . xx 17. Partial save size . . . . . . . . . . . . . xx 18. File . . . . . . . . . . . . . . . . . . . xx 19. Attribute bits . . . . . . . . . . . . . . xx 2. Put label . . . . . . . . . . . . . . . . . . . xx 3. Put attributes . . . . . . . . . . . . . . . . xx 4. Edit functions (Menu) . . . . . . . . . . . . . xx 1. Clip start . . . . . . . . . . . . . . . . xx 1. Clip end . . . . . . . . . . . . . . . . . xx 1. Prepend . . . . . . . . . . . . . . . . . . xx 1. Append . . . . . . . . . . . . . . . . . . xx 1. Reverse . . . . . . . . . . . . . . . . . . xx 1. Lower case . . . . . . . . . . . . . . . . xx 5. Operand size (Menu) . . . . . . . . . . . . . . xx 6. Accumulator (Menu) . . . . . . . . . . . . . . xx 7. Maths functions (Menu) . . . . . . . . . . . . xx 1. Increment . . . . . . . . . . . . . . . . . xx 2. Decrement . . . . . . . . . . . . . . . . . xx 3. Add . . . . . . . . . . . . . . . . . . . . xx 4. Subtract . . . . . . . . . . . . . . . . . xx 5. Multiply . . . . . . . . . . . . . . . . . xx 6. Divide . . . . . . . . . . . . . . . . . . xx 7. Negate . . . . . . . . . . . . . . . . . . xx 8. Logical NOT . . . . . . . . . . . . . . . . xx 9. Logical AND . . . . . . . . . . . . . . . . xx 10. Logical OR . . . . . . . . . . . . . . . . xx 11. Exclusive OR . . . . . . . . . . . . . . . xx 8. Define string (Menu) . . . . . . . . . . . . . xx 9. Swap with buffer (Menu) . . . . . . . . . . . . xx 10. Input buffer (Menu) . . . . . . . . . . . . . . xx 11. Output buffer (Menu) . . . . . . . . . . . . . xx 10. SPECIAL FUNCTIONS MENU . . . . . . . . . . . . . . xx 1. Repeat last command . . . . . . . . . . . . . . xx 2. Dos Command . . . . . . . . . . . . . . . . . . xx 3. Zap . . . . . . . . . . . . . . . . . . . . . . xx 4. Screen (Menu) . . . . . . . . . . . . . . . . . xx 5. Set task priority . . . . . . . . . . . . . . . xx 6. Origin (Menu) . . . . . . . . . . . . . . . . . xx 7. Convert xx(A4) EA's (Menu) . . . . . . . . . . xx 8. Convert specific EA's (Menu) . . . . . . . . . xx 9. Data type set (Menu) . . . . . . . . . . . . . xx 10. Convert to.. (Menu) . . . . . . . . . . . . . . xx 11. Reloc32 (Menu) . . . . . . . . . . . . . . . . xx 11. SAVE MENU . . . . . . . . . . . . . . . . . . . . . xx 1. O/P Directory . . . . . . . . . . . . . . . . . xx 2. Partial save (Menu) . . . . . . . . . . . . . . xx 1. Set start . . . . . . . . . . . . . . . . . xx 2. Set end . . . . . . . . . . . . . . . . . . xx 3. Save binary image (Menu) . . . . . . . . . . . xx 4. Save .asm (Menu) . . . . . . . . . . . . . . . xx 5. Calculate .asm size (Menu) . . . . . . . . . . xx 1. All . . . . . . . . . . . . . . . . . . . . xx 2. Partial . . . . . . . . . . . . . . . . . . xx 6. Save to memory (Menu) . . . . . . . . . . . . . xx 7. Save tracks (Menu) . . . . . . . . . . . . . . xx 8. Tabs (Menu) . . . . . . . . . . . . . . . . . . xx 9. Symbol table (Menu) . . . . . . . . . . . . . . xx 12. OPTIONS1 MENU . . . . . . . . . . . . . . . . . . . xx 1. Show offsets (Menu) . . . . . . . . . . . . . . xx 2. Display beep (Menu) . . . . . . . . . . . . . . xx 3. User feedback (Menu) . . . . . . . . . . . . . xx 4. Feedback Delays (Menu) . . . . . . . . . . . . xx 5. Labels (Menu) . . . . . . . . . . . . . . . . . xx 6. Hidden labels (Menu) . . . . . . . . . . . . . xx 7. Symbols (Menu) . . . . . . . . . . . . . . . . xx 8. End-of-line comments (Menu) . . . . . . . . . . xx 9. Full-line comments (Menu) . . . . . . . . . . . xx 10. Chip-load info (Menu) . . . . . . . . . . . . . xx 11. Section statements (Menu) . . . . . . . . . . . xx 12. End statement (Menu) . . . . . . . . . . . . . xx 13. DCB statements (Menu) . . . . . . . . . . . . . xx 14. Reference recognition (Menu) . . . . . . . . . xx 13. OPTIONS2 MENU . . . . . . . . . . . . . . . . . . . xx 1. ASCII longs (Menu) . . . . . . . . . . . . . . xx 2. Short branches (Menu) . . . . . . . . . . . . . xx 3. Leading zeroes (Menu) . . . . . . . . . . . . . xx 4. Assembler (Menu) . . . . . . . . . . . . . . . xx 14. KEY BINDINGS MENU . . . . . . . . . . . . . . . . . xx Introduction ReSource was originally just an interactive disassembler, but Version 3 is much more than this. Because ReSource can get its input from a file, track, or memory, and output all or part to any of these, it is more of a general purpose hacking tool. It can be used to browse through files, without ever bothering to save anything, just to find out what is inside. It also knows quite a bit about AmigaDOS(TM) and the Amiga® OS. This built-in intelligence will save you a great deal of time when disassembling files. ReSource is also blindingly fast. It is completely written in assembly language, and does all text rendering using its own special internal routines. When you run ReSource, you cannot do anything until you give it something to work on. You can supply the name of the file to load on the command line: 1> [run] ReSource c:popcli Alternatively, you can wait until ReSource starts running, and select a file using the ARP file requester. For full specifications on command line parameters, see below. Providing that there is enough memory available, you can load ANY file into ReSource. If ReSource recognizes it as a load file (one that can be run; an executable program), it will load the program, and perform any necessary relocation, etc., as if the program is going to be actually run. If the file that you request loaded is not a load file, it will be loaded "as-is". Load files may be also loaded "as-is", by using the "Load binary" function, in the "PROJECT" menu. This will give you access to the hunk, symbol, and relocation information, that otherwise gets stripped when the program is loaded into memory. Libraries, devices drivers, and fonts are also load files, which means that you can disassemble them, save the assembler source code, modify them, and re-assemble them. Getting Started If the version/revision of ReSource you have purchased is higher than the version indicated on the title page of this manual, please refer to "History.doc", an ASCII file on your ReSource disk containing incremental documentation. A "ReadMe" file may also be present containing information about your particular release of ReSource. System Requirements ReSource is designed to work on any properly configured Amiga® 500, 1000, 2000, or 2500. Kickstart V1.2 or higher is required. Because ReSource uses functions in the "ARP" library, you must have the file "arp.library" in your "LIBS:" directory when you run ReSource. This file is supplied with the commercial version of ReSource, and is available from most BBS's. The version of "arp.library" must be 34 or higher. While ReSource will run on a 512K Amiga®, you will be severely limited in the size of programs that you may disassemble. One megabyte of RAM should be considered the minimum necessary to disassemble all but the smaller programs, and you will need 1 1/2 to 2 megabytes of RAM if you want to work with programs larger than 30-40K. To make the best use of the menus, run FastFonts©, or Blitzfonts©. Otherwise, scanning through the menus will be very sluggish due to the large number of sub-items. The Command Line When you run ReSource from a CLI, you can supply a parameter, so that ReSource gets its input right away. The following parameters are accepted with the following meanings: 1> ReSource (The executable program will be loaded as a load file ONLY if it is a load file. Otherwise it will be loaded as a binary file) 1> ReSource *b (The file will be loaded as a binary image) 1> ReSource *m (Load memory, from location to location ) 1> ReSource *DFn: [#sec] [Offsec] (Load from drive DFn: starting at cylinder and continuing to . The default is to read complete track(s). This may be modified by the next two optional parameters: The fourth parameter specifies that ReSource should read [#sec] sectors, and the fifth parameter specifies that these sectors should start at [Offsec] sector.) 1> ReSource * (Kickstart(TM) as it appears in memory is loaded) Examine the following examples: 1> ReSource c:popcli (The program "popcli" will be loaded as a load file, from the C: device) 1> ReSource libs:arp.library (Load the file "arp.library", from the LIBS: device, as a load file) 1> ReSource *b c:popcli (The file "popcli" will be loaded as a binary image, from the C: device) 1> ReSource *m $FC0000 $FD0000 (The first 64K of Kickstart(TM) will be loaded) 1> ReSource *DF0: 0 0 1 (The boot sector from DF0: will be loaded, a total of 512 bytes. Use this to check for/disassemble viruses) 1> ReSource *DF1: 40 41 (The entire directory cylinder from DF1: will be loaded, 11K in all) 1> ReSource *m $400 $800 (For most Amigas®, this will load the Exec library) 1> ReSource *m 0 1 (Load one byte of memory, at location zero) ReSource may be "Run" without problem, and multitasks beautifully. It will even allow you to change the task priority from inside ReSource. Do not load ReSource from the Workbench(TM). Tutorial About the User Interface Because of the large number of functions in ReSource, it was decided to use one-and two-character menu names, so that more menus could be used. Looking from the left, the first menu is "P", which stands for "PROJECT". The real menu name is directly under the one-or two-character name, in capital letters, so should be fairly easy to find them. In all future reference to menus, the full menu name will be used. In the reference section, a heading ending with a ":" refers to the lowest hierarchical menu item for that function. In some cases, the heading will end with a "/:" to indicate that there are several sub-items with related functions being discussed under that heading, e.g.: DISPLAY/Block-fill: Refers to a single item. DISPLAY/Wrap/: Refers to a group of sub-items. When describing a function, rather than tell you what key to press to invoke that function, I'll describe where in the menus you will find it. For example, the "Quit" function would be described as "PROJECT/Quit". The function to restore the current file would be "PROJECT/Restore". You will find both of these under the "PROJECT" menu. Functions in sub-menu boxes will be described in a similar way, e.g., "SAVE/Tabs/Spaces". Because any key can have any function bound to it (except "PROJECT/Abort"), key usage will not be discussed, when referencing functions. However, to make it easier to get started, some key bindings will be present, even without loading a keytable. Note that loading a keytable may override these keybindings: up arrow..............................scroll up one line down arrow............................scroll down line line shift-up arrow........................page backward shift-down arrow......................page forward right arrow...........................forward reference left arrow............................previous location right-Amiga Q.........................quit right-Amiga O.........................open a file To rebind a key, select "KEY BINDINGS/Rebind key" from the menus, select a function from the menus to have bound, then press the key that you want it bound to. You can overwrite key bindings if you want. When done, you should save the keytable as "S:RS.keytable". This can be done by selecting "KEY BINDINGS/Save" from the menus. Even both of these functions can be bound to a key, in fact the only function that is not practical to rebind is "PROJECT/ Abort", which is always bound to right-Amiga A. A sample keytable is provided for your use. The key mapping used in the file is described in a file named "MyKeyBindings.doc". Alternately, you may use the supplied program "ShowKeys" to read your S:RS.keytable at any time. ShowKeys may be used without parameters or it will accept the pathname of a keytable as an optional parameter. You may want to redirect output to your printer for hardcopy. Definition of the Current Line Many functions in ReSource operate only on the current line. Because there is no real "cursor", it is necessary to define the "current line": >> The "current line" is the top line, as you see it on ReSource's screen. << If there is a section statement (e.g., SECTION BSS) to be displayed at the cursor address, this will be shown before any other text, and will force it to be shown on the next line down. If this is not the first section statement in the program, there will be an extra blank line, which will be shown before the section statement. After the section statement, and before the rest of the line, one or more "full-line comments" can be attached. Immediately after the cursor line, any "hidden labels" will be shown. A hidden label may also have a full-line comment attached, which will be shown immediately before it, but after the cursor line. Note that in this example: SECTION prog000000,CODE ;Section statement ;This is a full line comment! ;This is another full line comment! MOVE.L D1-D4/A2-A6,-(SP) ;Line of code all the above text is one line. Whenever you scroll up or down a line, all parts of the "current line" will scroll together, which may sometimes be visually jarring if there are many extra lines of text attached. To put it simply, the first "real" line of code or data in the window is the current line. Disassembling a Program To disassemble a program is to interpret what went into the program to make it work. It can be a very complex and trying task, but with practice one can become quite adept at it. There are many different and separate things to do when disassembling. One of the most important is to separate the code from the data. There is only one part of a load file that is guaranteed to be code, and that is at the very start. One very useful function of ReSource is its ability to scan lines of code, looking for references to other parts of the program being disassembled. When a reference is made, it creates a label at that address, which will be used in all future references to that part of the program. More importantly, ReSource can determine what type of data is being referenced, and be correct (almost) every time. If you intend to reassemble the source, you should still verify it before saving, as mistakes will occasionally occur. Before ReSource makes a decision about what type of data is being referenced, it examines many different pieces of information that are available, including the actual instruction that made the reference. There are a few ways of getting ReSource to scan lines of code. The simplest way is by using the "LABELS/Create single/Label - fwd ref". This scans only the current line, and does NOT advance the cursor. If a line of code makes a reference to somewhere within the program, that HASN'T got a label yet, it will be shown as some offset from the label "START", which is imagined to be (but is not actually, unless YOU have done it) attached to the first byte of the program. You could create a label called "START", at the first byte of the program. However, when you re- assemble, there is a chance that some different length instructions will be generated. This will make all references past the first different length instruction inaccurate. Another way to get ReSource to scan lines of code is with the "LABELS/Create multiple/ALL". This function scans the current line. If ReSource is reasonably sure that it is code, it will scan the line, and move on to the next line. This process will repeat until either the end of file, or until ReSource believes that the current line may not be code, even though it may currently be displayed as such. After executing this function, if the cursor isn't at the end of file, and there is more code that hasn't been "scanned" yet, you can scroll to the start of the next block of code, and execute this function again, repeating until all code in the program has been scanned. At this point, most references within the program will be to labels, and not use the "START+$xxxx" type of reference. To make sure of this, you can set up a search for "START+", and perhaps scan the lines individually. There is still another way to scan code, and it may be best when you are first starting to use ReSource and haven't yet learned when to scan the entire program, and when not to. First, make the top of the file the current line. Then, hold down the left-Amiga key, and while also holding down the left mouse button, scroll through the file until you come to the end. This sequence calls the function "LABELS/Create single/Label - fwd ref" repeatedly and generates labels for all forward references within the file. When all code in a program has been "scanned", the next function that you will generally want to use is "DISPLAY/Fill-in data types". This function does two passes over the entire program, and does NOT shift the cursor. The first pass looks at what data types have been set, and makes some assumptions about all places in the program where the data type has not been specifically set. When you "Set data type", you are telling ReSource "this is CODE", or "this is ASCII", or "these are to be displayed as bytes", etc. Generally, this data type will be assumed from this byte forward, until the next byte that has had the data type specifically set. Many conditions are tested when making decisions about what type of data is where. Providing that you have "scanned" all code in the program, after executing the "Fill-in data types" function the resulting source code will look like source code should look. The second pass in "Fill-in data types" is called "Calculating line lengths" in the title bar. This is used to let ReSource know how far back to go, when scrolling backwards. Also, string lengths are determined during this pass. When you first load in a file, all line lengths are set to two bytes. When scrolling forward, most things will be shown properly anyway, but if you scroll backwards before first doing a "Fill-in data types", a jarring display will result. At this point, if you output to a ".asm" file, it will probably be good enough to re-assemble. However, most people will want to examine the file, and make it more readable, especially if the program needs to be modified. An excellent place to start is by finding where any libraries are being opened, finding where the library base is being stored, and giving meaningful names to these data storage locations. Assume that the following code is a small part of a program: MOVE.L 4,A6 LEA START+$06B6(PC),A1 JSR -$0198(A6) MOVE.L D0,START+$0C36 BNE.S START+$06AE MOVE.L #$00038007,D7 JSR -$006C(A6) BRA.S START+$06B2 JSR START+$0142 ADDQ.W #8,SP RTS BCC START+$0727 ???? BGE START+$0725 BHI START+$0730 BSR START+$0732 ???? After scanning all code in this program, it would look like this: MOVE.L 4,A6 lbC000694 LEA doslibrary.MSG(PC),A1 JSR -$0198(A6) MOVE.L D0,START+$0C36 BNE.S lbC0006AE MOVE.L #$00038007,D7 JSR -$006C(A6) BRA.S lbC0006B2 lbC0006AE JSR lbC000142 lbC0006B2 ADDQ.W #8,SP RTS doslibrary.MSG dc.b 'do' dc.b 's.' dc.b 'li' dc.b 'br' dc.b 'ar' dc.b 'y',0 Next, "DISPLAY/Fill-in data types" will be used: MOVE.L 4,A6 lbC000694 LEA doslibrary.MSG(PC),A1 JSR -$0198(A6) MOVE.L D0,lbL000C36 BNE.S lbC0006AE MOVE.L #$00038007,D7 JSR -$006C(A6) BRA.S lbC0006B2 lbC0006AE JSR lbC000142 lbC0006B2 ADDQ.W #8,SP RTS doslibrary.MSG dc.b 'dos.library',0 The astute will have noticed that because the A6 register was loaded from location 4, it will point to the Exec library base. Therefore, the third line of this block of code is a call to somewhere in the Exec library. By scrolling so that this line becomes the top line on the screen, and selecting the "SYMBOLS/Libraries/Exec", our block of code will now look like this: MOVE.L 4,A6 lbC000694 LEA doslibrary.MSG(PC),A1 JSR _LVOOldOpenLibrary(A6) MOVE.L D0,lbL000C36 BNE.S lbC0006AE MOVE.L #$00038007,D7 JSR -$006C(A6) BRA.S lbC0006B2 lbC0006AE JSR lbC000142 lbC0006B2 ADDQ.W #8,SP RTS doslibrary.MSG dc.b 'dos.library',0 Checking the documentation for the "OldOpenLibrary" Exec call will tell us that on return, the D0 register will contain the library base for the library just opened, if successful. Because we know that it was the DOS library that was opened, the label "lbL000C36" referenced on the fourth line could now be called "Dos_Base", instead of "lbL000C36": MOVE.L 4,A6 lbC000694 LEA doslibrary.MSG(PC),A1 JSR _LVOOldOpenLibrary(A6) MOVE.L D0,Dos_Base BNE.S lbC0006AE MOVE.L #$00038007,D7 JSR -$006C(A6) BRA.S lbC0006B2 lbC0006AE JSR lbC000142 lbC0006B2 ADDQ.W #8,SP RTS doslibrary.MSG dc.b 'dos.library',0 If the D0 register DID contain a non-zero value, it means that "dos.library" did open successfully, and the following conditional branch WILL be taken. Where this branches to, is labeled "lbC0006AE". A better name for this might be "DosOpenedOkay". Scroll so that the line "lbC0006AE JSR lbC000142" is on the top line of the display, and select "LABELS/Create single/Label". When requested, type in "DosOpenedOkay": MOVE.L 4,A6 lbC000694 LEA doslibrary.MSG(PC),A1 JSR _LVOOldOpenLibrary(A6) MOVE.L D0,Dos_Base BNE.S DosOpenedOkay MOVE.L #$00038007,D7 JSR -$006C(A6) BRA.S lbC0006B2 DosOpenedOkay JSR lbC000142 lbC0006B2 ADDQ.W #8,SP RTS doslibrary.MSG dc.b 'dos.library',0 If the call to "OldOpenLibrary" was unsuccessful, the branch on the fifth line would NOT be taken. In this case, the D7 register is loaded with the value "$38007", and a call is made to the subroutine at offset -$6C from where the A6 register is currently pointing. We do know that the A6 register was pointing to the Exec library base before, and we also know that none of the code executed so far has destroyed the value in A6, so we can safely assume that A6 still points to Exec library base. Hence, by scrolling so that the seventh line of this block is on the top line of the display, and selecting "SYMBOLS/Libraries/Exec" again, our block will look like this: MOVE.L 4,A6 lbC000694 LEA doslibrary.MSG(PC),A1 JSR _LVOOldOpenLibrary(A6) MOVE.L D0,Dos_Base BNE.S DosOpenedOkay MOVE.L #$00038007,D7 JSR _LVOAlert(A6) BRA.S lbC0006B2 DosOpenedOkay JSR lbC000142 lbC0006B2 ADDQ.W #8,SP RTS doslibrary.MSG dc.b 'dos.library',0 After reading the documentation for the Exec call "Alert", we find out that on entry, the D7 register should contain a number representing an alert code. By scrolling so the the line "MOVE.L #$00038007,D7" is on the top line of the display, and selecting "SYMBOLS/A-B/Alert codes", our block will now look like this: MOVE.L 4,A6 lbC000694 LEA doslibrary.MSG(PC),A1 JSR _LVOOldOpenLibrary(A6) MOVE.L D0,Dos_Base BNE.S DosOpenedOkay MOVE.L #AT_Recovery!AG_OpenLib!AO_DOSLib,D7 JSR _LVOAlert(A6) BRA.S lbC0006B2 DosOpenedOkay JSR lbC000142 lbC0006B2 ADDQ.W #8,SP RTS doslibrary.MSG dc.b 'dos.library',0 Examining the include file "exec/alerts.i" will tell us that "AT_Recovery" is used for recoverable alerts, "AG_OpenLib" means that a library failed to open, and "AO_DOSLib" tells us which library is in question. Because this is a recoverable alert, the following line of code ("BRA.S lbC0006B2") WILL be executed, in which case we might change the label "lbC0006B2" to something like "DosDidntOpen", or "NoDosAvailable". This is important, since if any other code in this program makes a reference to one of the labels that we have changed, it too will use the new name. In this example, another part of the program that WAS: lbC0007DE MOVE.L 4(SP),D1 MOVE.L lbL000C36,A6 JMP -$0024(A6) lbC0007EA MOVE.L D4,-(SP) MOVEM.L 8(SP),D1-D4 MOVE.L lbL000C36,A6 JSR -$008A(A6) MOVE.L (SP)+,D4 RTS lbC0007FE MOVE.L 4(SP),D1 MOVE.L lbL000C36,A6 JMP -$007E(A6) now will be shown as: lbC0007DE MOVE.L 4(SP),D1 MOVE.L Dos_Base,A6 JMP -$0024(A6) lbC0007EA MOVE.L D4,-(SP) MOVEM.L 8(SP),D1-D4 MOVE.L Dos_Base,A6 JSR -$008A(A6) MOVE.L (SP)+,D4 RTS lbC0007FE MOVE.L 4(SP),D1 MOVE.L Dos_Base,A6 JMP -$007E(A6) After using the function "SYMBOLS/Libraries/Dos" a few times, it would become: lbC0007DE MOVE.L 4(SP),D1 MOVE.L Dos_Base,A6 JMP _LVOClose(A6) lbC0007EA MOVE.L D4,-(SP) MOVEM.L 8(SP),D1-D4 MOVE.L Dos_Base,A6 JSR _LVOCreateProc(A6) MOVE.L (SP)+,D4 RTS lbC0007FE MOVE.L 4(SP),D1 MOVE.L Dos_Base,A6 JMP _LVOCurrentDir(A6) To continue, we would replace a few labels: CloseSUB MOVE.L 4(SP),D1 MOVE.L Dos_Base,A6 JMP _LVOClose(A6) CreateProcSUB MOVE.L D4,-(SP) MOVEM.L 8(SP),D1-D4 MOVE.L Dos_Base,A6 JSR _LVOCreateProc(A6) MOVE.L (SP)+,D4 RTS CurrentDirSUB MOVE.L 4(SP),D1 MOVE.L Dos_Base,A6 JMP _LVOCurrentDir(A6) Okay, so far so good. Now, where the line: JSR lbC0007FE used to be, it would be replaced by: JSR CurrentDirSUB This happens automatically, whenever you replace any label. The process helps itself; starting is hardest, the rest come fairly easily. In general, where a label is used, if you have any idea of what is happening at all, you should replace it with a label that will remind you of what the code is doing. It doesn't matter what name you use (as long as it is a legal label for the assembler that you plan to use); if necessary you can replace it with something better later on. Anything nominally mnemonic will be superior to a "shop" label while you're trying to understand the code. One last point that needs to be covered briefly is the cursor location stack. When certain functions are called, or whenever YOU want to, the current cursor loacation may be pushed onto ReSource's location stack. This will allow you to easily move around in code. Returning to our example program, place the second line, at label lbC000694, on the cursor line, and then select "CURSOR/Absolute/Forward reference". The last line will move up to the cursor line. You can now use "LABELS/Create single/Label" to change the name "doslibrary.MSG" into something more meaningful, like "DosName". Now use "CURSOR/Absolute/Previous location", and you will find yourself back at the second line of the file, with a new name for the first operand. Normally you will just use right-Arrow, and left-Arrow for these two functions rather than using the menus. MOVE.L 4,A6 lbC000694 LEA doslibrary.MSG(PC),A1 JSR _LVOOldOpenLibrary(A6) MOVE.L D0,Dos_Base BNE.S DosOpenedOkay MOVE.L #AT_Recovery!AG_OpenLib!AO_DOSLib,D7 JSR _LVOAlert(A6) BRA.S lbC0006B2 DosOpenedOkay JSR lbC000142 lbC0006B2 ADDQ.W #8,SP RTS doslibrary.MSG dc.b 'dos.library',0 About Menus The menus in ReSource fully support drag-selecting, and multiple selection. Many options within ReSource have a "checked" menu, which in most cases is "hot". This means that even though ReSource may be busy doing something, if you make a selection in the menus that effects the current operation, it will take effect IMMEDIATELY. For example, while saving the source code to a ".asm" file, if you select "OPTIONS 1/Symbols/Off", from that point on, the output file will not show any symbols. Similarly, if you selected "OPTIONS/ DCB statements/On" during the save, DCB statements would be used in the output file from that point on. This feature is handy during the execution of macros, as you will see in the section on macros. About Keys As mentioned previously, any function except the "PROJECT/Abort" function can be bound to any key. All non-qualifier keys can be used, with or without any of the following combinations of qualifier keys: shift - left or right, or caps lock, all treated as one alt - left or right, both treated as one ctrl shift-ctrl alt-ctrl shift-alt shift-alt-ctrl left-Amiga right-Amiga For example, to rebind the "Open load file" function to right-Amiga O, select "KEY REBINDINGS/Rebind key", then select "PROJECT/Open load file", then press and hold down the right-Amiga key, press and release the "O" key, and finally release the right Amiga key. From then on, instead of using the menus for opening a file, you could just press right-Amiga O. To make this binding permanent, you would save the current bindings, to a ReSource KEYTABLE. Select "KEY BINDINGS/Save", and type in the name of a file to save the key bindings to. If you want these bindings used every time you start ReSource, you need to save the key bindings as "S:RS.keytable". With many programs, when you press and hold down the down arrow key, to scroll down, a backlog of key repeats will form, making it difficult to stop the scrolling, even after releasing the offending key. Where this would be a problem, the repeats are flushed, making key control better. About Load Files There are five functions that deal with loading. These are: "PROJECT/Open load file" "PROJECT/Open binary file" "PROJECT/Restore" "PROJECT/Dismble memory" "PROJECT/Read tracks" The first of these will examine the start of the file, to check if it is an Amiga® load file. Amiga® load files include all executable programs (excepting those using overlays), libraries, device drivers, and fonts. With this type of load, ReSource examines, then strips out, all hunk, relocation, and debug symbol information. This information is not lost, it is used internally to ReSource, to make better decisions about data type setting, etc. ReSource was designed with speed as the PRIMARY objective. It is does not use memory sparingly. To load a file, ReSource sometimes requires a great deal of memory, especially when disassembling large files. For any file, the approximate memory requirement will be 6 to 10 times the file size. As a further requirement, much of this is required to be contiguous. ReSource is NOT practical on a 512K machine. If you have 2 Megs of fast memory, you will be able to disassemble most programs. Users with 1 Meg machines will feel constrained when attempting to disassemble 30-40K executables, but should have little difficulty with programs smaller than this and most C: programs. Any debug symbols will be shown as labels in their proper places within the program, and even the relocation information is available. For example, if you select "DISPLAY/Hiliting/Reloc32", any relocated pointers are hilited. When disassembling, this information is quite valuable, as it helps you to tell where code is, where tables of pointers are, etc. ReSource also makes heavy use of this information in many functions, and this is one of the main reasons that it is so accurate in determining data types, especially when telling code from ASCII. The hunk information also tells you whether something was meant to load into chip memory, which immediately lets you know that it is probably graphics or sound data. If a program has the debug symbols left in it, it makes the disassembling process much easier. When the file is loaded, for each debug symbol found, if it is nine characters long, starts with "lb", and is followed by an upper case "A", "B", "C", "L", or "W", at the point that the label is attached, the data type will immediately be set to ASCII, bytes, code, longwords, or words, respectively. Additionally, local labels, of the "1$" variety, and labels ending in "SUB" are recognized as code, and labels ending in ".MSG" are recognized as ASCII. Thus, if you have to disassemble a program that you previously disassembled, then reassembled, most of the data types will be set for you, as the file is loaded. There is one other type of file that can be loaded in using "PROJECT/Open load file", the ReSource data file, or ".RS" file. It is discussed in detail in another section. If ReSource cannot load the file as an Amiga® load file, it will automatically attempt to load it as a binary file, without looking for hunk, relocation, and debug symbol information. If it is an Amiga® load file, but has been corrupted, ReSource will refuse to load it. You can still load it, however, using the "PROJECT/Load binary file" function. With this function, you can load any file that will fit into available memory. This is handy for disassembling operating systems, or text files. In the case of normal Amiga® load files, you may wish to examine the hunk information in them. The "PROJECT/Restore" function will attempt to load the same file that you loaded last, this is useful when you make a mess of things, and just want to start again. The restore function is only usable when you loaded a file, NOT when you disassemble memory directly, or read tracks from a floppy disk. This will be fixed in a future version. When you are asked to select a file using the file requester, you may cancel the load immediately, and retain the current file. If you hit the "okay" gadget, and the file is not successfully loaded, (perhaps because it is too large for available memory), you have lost your current file. If, at this time, you select "cancel", ReSource will give you the chance to quit, in case you cannot or are unwilling to load any file. If you don't quit, ReSource will again offer the file requester, where you may select a file to disassemble. About Data Files The ReSource data file, or ".RS" file, is a file containing most of the data areas internal to ReSource, while any particular file is loaded. This is used to save your work, and later load it back into ReSource, so you can continue disassembling a program some other time, without losing any of what you have already done. You could even send this file to a friend, assuming that he/she has purchased ReSource. This should be particularly useful in disassembling the Amiga® operating system, (Kickstart(TM)), as the Kickstart(TM) ".RS" file does not contain any copyrighted material, and so can be legally distributed. This is only true for Kickstart(TM) ".RS" files. The executable must be cleared before you distribute ".RS" files of any program that is not in the Public Domain. See "PROJECT/O'lay binary image" in the reference section. Be aware that you will require at least two megs of fast memory to load a Kickstart(TM) ".RS" file. Even the cursor position is saved in a .RS file, making it easy for you to remember what you were doing last when you saved the ".RS" file. The ".RS" file is only recognized with "PROJECT/Open load file", not the "PROJECT/Open binary file", although you may load it as a binary image if you want. It is the content of the file that allows ReSource to recognize a ".RS" file, not the name of the file. However, the file should have an extension of ".RS", so it is immediately recognizable by humans as a ReSource data file. To save your work (it doesn't matter how you loaded it), select "PROJECT/Save .RS", and select a filename to save to. About Output Eventually, after disassembling a program, you will probably want to save it as a text file, that you will later assemble, perhaps after doing some modifications. By using the "SAVE/Save .asm" function, the entire file can be saved as a text file, exactly as you see it on the screen. If you only wish to save part of the file, use "SAVE/Save .asm/Partial". Another output function is "SAVE/Save binary image". One use for this is to perform modifications to a file, by overwriting the current information. For example, if you have a program that has some annoying feature, you could quickly find the offending code with ReSource, then simply overwrite it with "NOP" instructions. You may use "SPECIAL FUNCTIONS/Zap" to enter "NOP" opcodes as "'Nq" or "$4E71". Look up the hex values of any other opcodes that you may need. Once this has been done, select "SAVE/Save binary image", and you can use the file immediately, without going through the complete disassemble/re-assemble/link process. To find out how large the output .asm file will be, you can select "SAVE/ Calculate .asm size/ALL". This will tell you the output size, in bytes, K's, and as a percentage of a floppy disk (which may be larger than 100%). If you change any of the options, it will most probably have some effect on the size of the output file. To make the output .asm file smaller, most things in the "OPTIONS" menu should be switched OFF, except for "DCB instructions", which if used, can shrink the size of a .asm file considerably, especially if there are large data areas. Either real tabs (ASCII value 9) or spaces may be used in the output file. Selecting "SAVE/Tabs/Real tabs" will also make the output file size smaller, as will "DISPLAY/Blank lines/None". If the size of the output file is not a problem, then set these options to suit your tastes. Another way to deal with limited space for .asm files, is to save them as two or more partial files using "SAVE/Save .asm/Partial" repeatedly. Before leaving this section, a brief look at how ReSource achieves its fast screen output is in order. All text that is displayed on the ReSource screen, except that which is done for the menus by Intuition, uses text rendering routines internal to ReSource. This makes text rendering extremely fast, but also means that the font can't be easily changed. The text rendering routines were originally inspired by Warptext II. The major difference here is that four characters instead of one are rendered in the main loop. This has the obvious benefit of increasing speed of rendering, but is also the reason why the start and end of hilited areas are sometimes displaced by up to 3 characters. For efficiency, large cleared areas (such as the first tab in a line) are handled by separately. The blitter is currently not explicitly used in ReSource at all. About Symbols When you create a symbol, unless you have set "SAVE/Symbol table" to "None", the symbol and its value will be stored, so that a symbol table can be created at the beginning of the output source code file. This symbol table can take the form of an equate table, e.g.: AG_OpenLib EQU $00030000 AO_DOSLib EQU $00008007 AT_Recovery EQU $00000000 _LVOAlert EQU $FFFFFF94 _LVOClose EQU $FFFFFFDC _LVOCreateProc EQU $FFFFFF76 _LVOCurrentDir EQU $FFFFFF82 Alternatively, it can take the form of an "XREF" table, e.g.: XREF AG_OpenLib XREF AO_DOSLib XREF AT_Recovery XREF _LVOAlert XREF _LVOClose XREF _LVOCreateProc XREF _LVOCurrentDir The symbol table is also stored in a ".RS" file. When it is time to create the .asm file, you can select either "EQU" or "XREF" as the type of symbol table to create. Even though you may create many symbols with the same name, the symbol table will contain only one entry for each symbol. Thus, it will correctly assemble with most assemblers. If you select the "None" option, no symbol table will be generated. Display Preferences To cater to different tastes, the manner in which ReSource displays information may be varied dramatically. Overlong lines may or may not wrap around, code may be shown in upper case, or lower case. Data declarations may be shown in upper case or lower case. You may have blank lines appear after conditional branches, after all branches, after system calls, or none at all. Any number may be shown in hexadecimal, decimal, binary, or ASCII if within the required range. Leading zeroes may be suppressed, or shown. Numbers below 10 in value, or below 16 in value may be globally converted to decimal, or there may be no conversion. Each line that doesn't start with a label may instead show the current offset. Section statements, the END statement, labels, hidden labels, symbols, and two types of comments may individually be set ON or OFF at any time. The settings of these options can be made permanent by selecting the required functions in Macro #19 (the last local macro), and saving the macro table as "S:RS.macros". See the section on macros for more information. Selecting "OPTIONS 1/Labels/Off" does NOT remove any labels, it simply stops them from being shown, until you select "OPTIONS 1/Labels/On". For example, you might wish to search for "lbC" as a string inside a comment, and unless you turn labels off, you will have to spend a long time searching for the real target, as many labels will start with "lbC". About Searches ReSource has some very powerful search functions. You may select from a normal search, or a pattern search. You may search forward, backward, or a special combined search, that searches in both directions at the same time, which will find the "nearest" occurrence of the search string. For use in macros, you can also search just the current line, or the accumulator. The text that you see on the display will be the text that is searched. For the purpose of searches, tabs are set to real tabs, not spaces. Thus, if you wish to search for: MOVE.L #100,D0 you would press "tab" where you see spaces in the above line. When using the pattern search, the wildcards are those used in all ARP programs. For completeness, they are repeated here. ARP and Wildcards ARP has an extensive set of wildcards, and most ARP programs allow them to be used. ARP supports ALL of the AmigaDOS(TM) set of wildcards, as well as the more standard Unix style of wildcards. ARP supports the following wildcard characters. Note that these are valid inside or out of quotes: (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 occurrences of any character. These can be used in combination, of course, so that *.(c|h) or *.[ch] will match any filenames ending in either .c or .h proceeded by any number of characters, including no characters. For example, if you want to search for "JSR" or "BSR", you could specify "?SR" as the search pattern, and you would use the pattern search, not the normal search. Here are some more examples: lb[ABCWL] would find any occurrence of "lbA", "lbB", "lbC", "lbW", or "lbL" "lbM" would NOT constitute a valid match. J(MP|SR) -$????*(A6*) would get a match on the following lines: JMP -$00C6(A6) JSR -$00C6(A6) JSR -$01FE(A6) JMP -$FFFF(A6) but not on the following lines: JMP $00C6(A6) JSR -$00C6(A5) JSR $1FE(A6) JMP (A6) Note that a real tab character was used above, between "J(MP|SR)" and "-$????*(A6*)". During a search, it is unimportant whether tabs are set to real tabs or spaces. Reference Section 2.1.1 PROJECT/Abort: Use this to abort searches and macros. This is the only function in ReSource which should NOT be bound to a different key. It is permanently bound to right-Amiga A, for "Abort". 2.1.2 PROJECT/Open load file: ReSource will present the ARP file requester. When you either double-click on a file name, select a file and press "return", or click on the "okay" gadget, ReSource will attempt to load the file as an executable, or "load" file. If there are any debug symbols in the executable, these will be stored, and will become labels at the appropriate places in the file. Relocation is performed where required. If the file has overlays, ReSource will attempt to load the root hunk. Each debug symbol encountered is attached to the appropriate byte in the file, and for those debug symbols (labels) that are nine characters long, and start with "lb", immediately followed by 'A', 'B', 'C', 'L', or 'W', the data type at the appropriate byte will be set to ASCII, Bytes, Code, Longwords, or Words, respectively. Additionally, local labels, of the "1$" variety, and labels ending in "SUB" are recognized as code, and labels ending in ".MSG" are recognized as ASCII. Any BSS hunks or uninitialized data areas found are expanded fully. You may hilite areas where relocation has been performed by selecting "DISPLAY/ Hiliting/Reloc32". You are limited to files smaller than 16 Megabytes, and further limited by how much memory you have. To disassemble a 100K file, you will require approximately 850K of memory, of which at least 400K must be contiguous. If the file has large BSS hunks, this will greatly increase the memory requirements. If you intend to load a file, do some zaps, then save it and later run it, use "PROJECT/Open binary file" instead, otherwise the file will get saved with the loader information stripped out of it. 2.1.3 PROJECT/Open binary file: Similar to "PROJECT/Open load file", except that no translation of the file is performed; the file is read in "as-is". This allows you to see the loader information in executables, object files, etc. You can also load in text files, data base files, in fact any file whatsoever, memory permitting. If you select "PROJECT/Open load file" for a non-executable file, the file will be loaded as a binary image instead, therefore "PROJECT/Open binary file" is not really required except when you wish to force an "as-is" load for an executable file. If you wish to do some zaps (small modifications) to an executable file, (or an ".RS" file, for that matter) without going through the disassemble/edit/reassemble/link cycle, you could load the file with this function, do the zaps (see "SPECIAL FUNCTIONS/Zap"), then use "SAVE/Save binary image/All" to save the modified program. 2.1.4 PROJECT/Restore file: Useful only when the current buffer was loaded using "PROJECT/Open binary file" or "PROJECT/Open load file". This function will attempt to load a file, with the same name as the current file, using the same function that loaded the current file originally. Do not use this function if the current buffer was loaded from tracks, or directly from memory. 2.1.5 PROJECT/Dismble memory: Disassembles a block of memory directly. You will be asked to supply a start and end address for the memory region to be disassembled. The memory is NOT copied to a separate buffer, it is disassembled "as-is", which means that if you hold down the left mouse button, in some areas you can see the memory being dynamically updated. It also means that you can modify memory directly. Anywhere. For each address that you supply, if the number starts with a "$", the number is assumed to be hexadecimal. If it starts with "%", it is assumed to be a binary number. If neither, decimal is assumed. If you wish to work on a COPY of a block of memory, to avoid modifying the original, or perhaps because the original will not be around for long, disassemble the memory directly, and save the data with the "PROJECT/Save .RS" function. Then use "PROJECT/Open load file" to load the ".RS" file normally. 2.1.6 PROJECT/Read tracks: You will be asked to supply the parameters for the track to read. The first parameter must be either "DF0:", "DF1:", "DF2:", or "DF3:" (lower case is okay). This represents the drive that holds the disk to be read from. The second parameter is the number of the cylinder to start reading from. The third parameter is the number of the last cylinder to be read, plus one. For example, if you wanted to read the first cylinder from the disk in DF0:, the parameters would be "DF0: 0 1". The fourth parameter is optional, and represents the number of extra sectors to read. For example, if you wished to read only the very first sector from DF1:, the parameters would be "DF1: 0 0 1". If you wished to read the first sector from the directory track of DF2:, the parameters would be "DF2: 40 40 1". The fifth parameter is also optional, and it represents the sector offset, to start the read. For example, if you wished to read sectors nine and ten on cylinder 79 of the disk in DF3:, the parameters would be "DF3: 79 79 2 9". 2.1.7 PROJECT/O'lay binary image: This function prompts you for a filename. ReSource will attempt to open the file, and read the contents, overlaying the current file. This is NOT the same as opening a file normally, as all labels, symbols, comments, data types, etc., stay as they are. Only the actual contents of the executable itself are overwritten. For example, you may wish to pass on a ".RS" file to someone, but because the program you have disassembled is copyrighted, you cannot legally distribute the normal ".RS" file, as it contains the executable. By using this function, and inputting a filename of "*" (asterisk), ReSource will completely clear the executable within the current file. You may then save to a ".RS" file, which may then be distributed, devoid of the executable. If another person has previously purchased the program that you have disassembled, they may load it into ReSource, and use "SAVE/Save binary image/All", to save the executable to a file. They then load the special ".RS" file which you created. Next, they then use "PROJECT/ O'lay binary image", supplying as a filename, the name of the file previously saved with the "SAVE/Save binary image/All" function. This effectively puts the executable back into the ".RS" file. The other save functions may then be used, to save to a .asm file, for example. Please make sure the executable section IS cleared before you share ".RS" files that are disassemblies of copyrighted material. Failure to do this may result in your meeting many new people - mostly lawyers. 2.1.8 PROJECT/Save .RS: Use this function to save what you are currently working on, regardless of how far you have gotten in disassembling it. EVERYTHING is saved, even your current position within the file. Actually, if you disassemble the Amiga® operating system directly, the ".RS" file that you create will NOT contain the executable, therefore the ".RS" files can be legally distributed, as they contain no copyrighted material. This is not the case for other ".RS" files, as the executable will be saved along with other information. Please see "PROJECT/O'lay binary image", above. 2.1.9 PROJECT/About: Get information about the version number, author, agents, and people that helped in the development of ReSource. 2.1.10 PROJECT/Quit: Asks you for confirmation, then quits without saving. If this function is used within an executing macro, it will NOT ask the operator for confirmation. 2.2.1.1 DISPLAY/Hiliting/None: Use the hiliting functions to select attributes for which the data with those attributes will be shown with the foreground/background colors inverted. Selecting this function will disable all types of hiliting. 2.2.1.2 DISPLAY/Hiliting/BSS hunks: Data within BSS hunks and uninitialized data areas will be hilited. 2.2.1.3 DISPLAY/Hiliting/Data hunks: Data within data hunks will be hilited. Data hunks often will contain only data constants, but may also contain code. 2.2.1.4 DISPLAY/Hiliting/Code hunks: Data within code hunks will be hilited. Code hunks often will contain only code, but may also contain data constants. 2.2.1.5 DISPLAY/Hiliting/Chip load hunks: Data within code or data hunks that MUST be loaded into chip memory (only) will be hilited. Data falling into this category will usually be graphics or sound data, to be accessed directly by the blitter, copper or DMA. 2.2.1.6 DISPLAY/Hiliting/Fast load hunks: Similar to the above function, except that the data is forced to load into FAST memory only. 2.2.1.7 DISPLAY/Hiliting/Reloc32: Being able to see where relocation has been performed is extremely useful when disassembling a program. If it were not for the relocation information, disassembling programs would be many times harder. ReSource makes use of this information internally, especially when filling in data types. 2.2.1.8 DISPLAY/Hiliting/Symbol scan: When you use the "LABELS/Create single/Label - fwd ref" or "LABELS/Create multiple/All", all data scanned for references are marked as being scanned. Use this function to hilite data falling into this category. 2.2.1.9 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. 2.2.1.10 DISPLAY/Hiliting/Data type known: Similar to above function, only the lines where the ReSource WAS certain of the data type, will be hilited. This will also include lines that YOU have set using "DISPLAY/Set data type/" (see below). 2.2.1.11 DISPLAY/Hiliting/Internally produced refs: All lines which have a label that was created by ReSource, rather than directly by the user, will be hilited. 2.2.2 DISPLAY/Set data type/: When you are certain of which type of data that you are looking at, select from one of the sub-menu items: Code, ASCII, Bytes, Words, Longwords. 2.2.3 DISPLAY/Set numeric base/: By default, all numbers are shown in hexadecimal (base 16). You can change this to ASCII, DECIMAL, BINARY, or back to HEXADECIMAL on any line by selecting from the appropriate sub-item. 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). The function "DISPLAY/Set numeric base/ASCII" will enable virtually any number at all to be shown as ASCII, providing that no non-valid ascii characters are present. Be aware that the following lines: dc.l $4E dc.l $4E00 dc.l $4E004E00 dc.l $4E4E00 dc.l $4E000000 dc.l $444F53 dc.l $444F5300 dc.l $4B49434B will, by using the ASCII numeric base, be shown as: dc.l 'N' dc.l 'N'<<8 dc.l $4E004E00 dc.l 'NN'<<8 dc.l 'N'<<24 dc.l 'DOS' dc.l 'DOS'<<8 dc.l 'KICK' Note that the third line contained a non-valid ASCII character. Although some others contained zeroes in the lower byte(s), they can be safely shown as being an ASCII value shifted 8/16/24 to the left. 2.2.4 DISPLAY/Decimal conversion/: By default, all numbers are shown in hexadecimal. 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-items. 2.2.5 DISPLAY/Blank lines/: To better define subroutines, and logical blocks of code, ReSource can insert blank lines in the source code. You may select whether a blank line is inserted after each conditional branch, unconditional branch, return, or system call. You may select more than one, in which case a blank line will appear after any line which falls into any of the selected categories. A line will never be followed by more than one blank line, regardless of how many selected categories it falls into. 2.2.6.1 DISPLAY/Cursor address/Relative: The cursor address will be shown in the title bar, as a hexadecimal offset from the start of the file. 2.2.6.2 DISPLAY/Cursor address/Absolute: The cursor address will be shown in the title bar, as a hexadecimal absolute machine address. This allows you to quickly find the cursor position in memory with other utilities, such as MetaScope, perhaps to carry out large scale modifications. 2.2.7.1 DISPLAY/Titlebar info/Filename: Information is displayed in the title bar in several fields. From the left, the first is the program name. The second is a decimal number, representing the cursor position relative to the file size, and is a percentage. The next field is a hexadecimal number, representing the cursor position, and can be shown either as an offset from the start of the file, or as an absolute memory location. The next field is the one that this function relates to. By selecting this function, the current file name will be shown. If user feedback is ON, informative messages will sometimes be shown in this field also. 2.2.7.2 DISPLAY/Titlebar info/Attributes: The second field of the title bar will display information representing the current attributes of the cursor byte. This information is NOT required for general program usage, and was originally included for debugging purposes only, and left in to satisfy those that want to know how the attributes table in ReSource works. The attributes table is four times the size of the current file, plus 16 bytes. It is used internally as a large bitmap, to store information about each and every byte in the current file. Because it is four times the file size, 32 bits are available for each byte in the current file. For each character in the string displayed, if lower case, the bit that that character represents is clear, if upper case, the bit is set. Going from the left, the bit definitions are: S: Start of a line of code/data B: Bss hunk D: Data hunk C: Code hunk R: Reloc32 area F: First byte of reloc32 area L: Label attached to this byte S: Symbol attached to this byte F: Full-line comment attached to this byte E: End-of-line comment attached to this byte P: Parsed previously (symbol scan) I: Internally referenced L: Low priority. The data type has been set, but can be overridden by internal routines. The data type can always be overridden by the user. This bit was generally set when ReSource had to decide on a data type to set for a byte, but when it did so, it wasn't really sure that it was correct. A: Show numeric operands as ASCII if possible. Decimal conversion is on a higher priority than this bit. B: Show numeric operands as Binary. Decimal conversion is on a higher priority than this bit. D: Show numeric operands as Decimal if possible. F: Data in this hunk is to be loaded into FAST memory only. C: Data in this hunk is to be loaded into CHIP memory only. : [Next 4 bits are reserved for future use] U: User should check the data type that has been set, as ReSource wasn't really sure that it chose the correct one. Use "CURSOR/Relative/Next uncertain D/T" to find the next occurrence. If such a line is already the current line when you use that function, it will clear this bit. H: High priority. The data type has been set either by the user, or by ReSource when it was quite certain that it set the data type correctly. This does not mean that it cannot make mistakes, it simply means that if some operation attempts to set the data type for this byte, it will NOT override the currently set data type. This will not ever stop the user from redefining the data type, however. C: This line is code. dddd: Data type hasn't been set yet ddDd: Data type is bytes dDdd: Data type is words dDDd: Data type is longwords Dddd: Data type is bytes, within a BSS hunk or uninitialized data area. DddD: Data type is ASCII. DDDd: Data type is words, within a BSS hunk or uninitialized data area. DDDD: Data type is longwords, within a BSS hunk or uninitialized data area. 2.2.7.3 DISPLAY/Titlebar info/Accumulator: The third field of the title bar will display information representing the contents of the ACCUMULATOR. This is a 240 byte buffer, used as a central number and string processor, which will find most of its uses within macros. Only the first 30 characters or so can be shown in the title bar. However, often the string will not be longer than that anyway. For more information on the accumulator, see the functions within the "STRINGS" menu. 2.2.8 DISPLAY/Wrap/: With wrap on, any lines longer than the current display width will be shown on several lines, much the same way that text editors allow you to use word wrap. Otherwise, any lines longer than the current display width will be truncated. 2.2.9 DISPLAY/Block-fill: Some background information is required here: ReSource internally keeps a stack of cursor locations. The current cursor location is "pushed" onto this stack with any use of the following functions: CURSOR/Remember CURSOR/Absolute/End of file CURSOR/Absolute/Start of file CURSOR/Absolute/Forward reference CURSOR/Absolute/Second forward reference CURSOR/Absolute/Backward reference To "pop" a cursor location, you use the function "CURSOR/Absolute/Previous location". The stack is cleared when you load a new file. The stack is NOT stored within ".RS" files. Block-fill uses the cursor location stored on the top of this location stack, finds out what the data type at that location has been set to, and copies that data type to all locations between there and the current cursor location. It has several disadvantages, and should be used only when special display effects are required. For example, if you wish to display a file as bytes throughout, even though much of it is actually code or ASCII, this function may come in handy. 2.2.10 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. 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 a 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 appropriately. All of this is done on the first pass. On the second pass, the length of each line is set. This is particularly useful where there are large areas of ASCII. This function should always be used before saving a file as source code. 2.2.11 DISPLAY/Fill-in D/T Fwd: Similar to the above function, except that both passes will start from the current cursor location, and NOT the start of the file. Also, the action of this function will stop at the end of the current section, OR the end of the file, whichever occurs first. Useful if you need to make changes to data and BSS areas towards the end of the file. 2.2.12 DISPLAY/Set counter: If cursor address has been set to "relative", the current offset in a file is shown in the title bar, in hexadecimal. This is normally 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". If cursor address has been set to "absolute", it will correctly display the current address of the cursor, regardless of this function. 2.2.13 DISPLAY/Reset counter: Similar to the above function, except that the cursor position is assumed to be at the start of the file. 2.2.14 DISPLAY/Flip case - code: If code is currently being displayed using upper case, it will be instead shown in lower case, and vice versa. Note that all searches are case sensitive. 2.2.15 DISPLAY/Flip case - data: If data is currently being displayed using upper case, it will be instead be shown in lower case, and vice versa. 2.3 SYMBOLS 1/: Some background information is required here: When you assemble a program, you will use symbols such as "_LVOAllocMem", "MEMF_CHIP", "Open", "MODE_OLDFILE", etc. When you disassemble a program, you see only the numbers that equate to the symbols that you used. To convert these numbers back into strings, you basically tell ReSource what the "symbol base" is, and it will do the rest. For example, in the following line: JSR -$0228(A6) the number "-$0228" could be interpreted in many different ways. If you happened to know that the A6 register at that point in the program was pointing to the Exec library base, you would interpret that line as: JSR _LVOOpenLibrary(A6) To make ReSource do this automatically, you would scroll so that this line became the cursor line, and then select the function "SYMBOLS 1/Libraries/ Exec", or "SYMBOLS 2/E-G/Exec library". There are hundreds of other symbol bases that are available, including libraries, devices, structures, parameters, and error code names. 2.3.1 SYMBOLS 1/Set Source/dest/: Examine the following line of code: MOVE.L #-$0228,$0022(A6) If you wished to create a symbol for the second number on this line, "$0022", you should first select "Destination". The setting of "Set Source/dest" will go back to "Source" with virtually any function you use, therefore when creating a symbol for the second field in a line of code, use "SYMBOLS 1/Set Source/dest/Destination" only just prior to actually creating the symbol. 2.3.2 SYMBOLS 1/Object/: By default the number, or object, used to find the string will come from the cursor line. You can instead have ReSource get the number from the accumulator, by selecting "Accumulator". In this case, the output string will be placed back into the accumulator. To set it back, select "Cursor". 2.4 SYMBOLS 2/: Some special symbol bases are in the "SYMBOLS 1" menu, mostly different library bases. The remainder are in alphabetical order in the "SYMBOLS 2" menu. 2.5.1 CURSOR/Remember: ReSource keeps a stack of cursor locations internally. Using this function will "push" the current cursor location onto the top of this stack. Other functions that call this function are: CURSOR/Remember CURSOR/Absolute/End of file CURSOR/Absolute/Start of file CURSOR/Absolute/Forward reference CURSOR/Absolute/Second forward reference CURSOR/Absolute/Backward reference To "pop" a cursor location, you use the function "CURSOR/Absolute/Previous locations". The stack is cleared when you load a new file, or when you select "CURSOR/Clear loc stack". The stack is NOT stored within ".RS" files. 2.5.2 CURSOR/Clear loc stack: See above function. 2.5.3.1 CURSOR/Relative/Next byte: The cursor location is incremented. If at the last location within the current file, a macro "fail" will result. 2.5.3.2 CURSOR/Relative/Previous byte: The cursor location is decremented. If at the first location within the current file, a macro "fail" will result. 2.5.3.3 CURSOR/Relative/Next line: Scroll forward one line of code/data. If at the last line of code/data in the file already, a macro "fail" will result. The speed at which this scroll is done is set by the "CURSOR/Scrolling speed" settings. 2.5.3.4 CURSOR/Relative/Previous line: Scroll backwards one line of code/data. If at the first line of code/data in the file already, a macro "fail" will result. The speed at which this scroll is done is set by the "CURSOR/Scrolling speed" settings. 2.5.3.5 CURSOR/Relative/Next label: Move cursor to the next location that has a label attached to it. If one cannot be found, a macro "fail" will result. 2.5.3.6 CURSOR/Relative/Previous label: Move cursor to the previous location that has a label attached to it. If one cannot be found, the start of the file will become the new cursor position. 2.5.3.7 CURSOR/Relative/Next symbol: Move cursor to the next location that has a symbol attached to it. If one cannot be found, a macro "fail" will result. Note that this location may be in the middle of a line of code. Where the actual operand is stored will become the new cursor position. 2.5.3.8 CURSOR/Relative/Previous symbol: Move cursor to the previous location that has a symbol attached to it. If one cannot be found, the start of the file will become the new cursor position. Note that this location may be in the middle of a line of code. Where the actual operand is stored will become the new cursor position. 2.5.3.9 CURSOR/Relative/Next section: Move cursor to the start of the next section (hunk). If this is the last section in the file, a macro "fail" will result. 2.5.3.10 CURSOR/Relative/Previous section: Move cursor to the start of this section (hunk). If already at the start of a section, move to the start of the previous section. 2.5.3.11 CURSOR/Relative/Next reloc32: Move cursor to the start of the next relocated longword. If one cannot be found, a macro "fail" will result. Note that this may be in the middle of a line of code. 2.5.3.12 CURSOR/Relative/Previous reloc32: Move cursor to the start of the previous relocated longword. Note that this may be in the middle of a line of code. If one cannot be found, the start of the file will become the new cursor position. 2.5.3.13 CURSOR/Relative/Next page: Move cursor forward 24 lines. 2.5.3.14 CURSOR/Relative/Previous page: Move cursor backwards 24 lines. 2.5.3.15 CURSOR/Relative/Skip forward: Move cursor forward approximately 4K. 2.5.3.16 CURSOR/Relative/Skip backward: Move cursor backward approximately 4K. 2.5.3.17 CURSOR/Relative/Next unparsed code: Move cursor forward to the next location that satisfies both of the following conditions: 1. The data type has been set to CODE 2. This location has NOT been scanned for forward references previously. This function is useful when combined with the "LABELS/Create multiple/All" function. 2.5.3.18 CURSOR/Relative/Next D/T change: Move cursor to the next location that has its data type set differently than the data type at the current cursor location. 2.5.3.19 CURSOR/Relative/Previous D/T change: Move cursor to the previous location that has its data type set differently than the data type at the current cursor location. 2.5.3.20 CURSOR/Relative/Next uncertain D/T: Move cursor forward to the next location that has the "Uncertain" bit set in the attribute table. This bit indicates that ReSource really wasn't sure of the data type of this byte. 2.5.3.21 CURSOR/Relative/Next backward reference: Once you have used the "CURSOR/Absolute/Backwards reference" function, you can use this function to get to other backward references. 2.5.4.1 CURSOR/Absolute/End of file: Move cursor to the start of the last line of the file. 2.5.4.2 CURSOR/Absolute/Start of file: Move cursor to the start of the file. 2.5.4.3 CURSOR/Absolute/Forward reference: If there is a reference to a position in the current file within the current line of code, move cursor to the location being referenced. If there are two forward references within the current line, the first is used. 2.5.4.4 CURSOR/Absolute/Second forward reference: If there are two references to a position with the current file, within the current line of code, move cursor to the second location being referenced. If there are less than two forward references, a macro "fail" will result. 2.5.4.5 CURSOR/Absolute/Backward reference: Starting from the start of the file, search for references to the cursor location. If there are several references, you can use "CURSOR/Relative/Next backward reference" to get to successive references. 2.5.4.6 CURSOR/Absolute/Previous location: "Pop" the cursor location from the top of the cursor location stack. If the stack is empty, a macro "fail" will result. 2.5.4.7 CURSOR/Absolute/Specify offset: You will be asked to supply an offset representing how far from the start of the file, the cursor location should be. The number may be specified in hexadecimal, decimal, or binary. If hexadecimal, the string must start with "$", if binary, it must start with "%". If the given offset is not within the current file, this function will fail. 2.5.4.8 CURSOR/Absolute/Specify label: You will be asked to supply the name of a label. If the label is used within the current file, its location will become the new cursor location. Note that this may be in the middle of a line of code. 2.5.4.9 CURSOR/Absolute/Specify symbol: You will be asked to supply the name of a symbol. If the symbol is used within the current file, its location will become the new cursor location. Note that this may be in the middle of a line of code. Also note that if there is more than one symbol of that name, ReSource will pick the one that was defined first. 2.5.4.10 CURSOR/Absolute/Specify percentage: You will be asked to supply a decimal percentage of the current file, where the cursor will be positioned. In this case 0 is the beginning of the file and 99 is the end. Note that this may be in the middle of a line of code. The actual positioning will not be exact. It will generally be placed a little before the required percentage. 2.5.5 CURSOR/Copy/: 2.5.6 CURSOR/Paste/: 2.5.7 CURSOR/Swap/: Some background information is required here: ReSource has 3 internal cursor "clipboards". You can copy a cursor location to any of these, and then later "paste" one of these locations, which in effect moves the cursor to where it was when you used the "copy" function. Also, you can swap cursor locations, between the current, and a stored cursor location. The contents of these cursor "clipboards" are cleared when you load a new file, or restore the current one. 2.5.8 CURSOR/Scrolling speed/: Whenever you use either "CURSOR/Relative/Next line" or "CURSOR/Relative/ Previous line" functions, the text on the display will move N number of display lines (NOT text lines) at a time. This is how most text editors, word processors, etc., scroll text. Scrolling Lines Speed Scrolled Notes --------- -------- ----- Very fast 8 Exceptionally fast scrolling, good for scanning through a file. Fast 4 Reasonably fast scrolling, allows scanning, but difficult to read. Normal 2 Reasonably smooth scrolling, allowing you to read text fairly easily WHILE it is scrolling. Slow 1 Extremely smooth scrolling, allowing you to easily read text WHILE it is scrolling. Very Slow 1 w/delay Exceptionally smooth scrolling, and is excellent for slowly browsing through a file. 2.5.9.1 CURSOR/Normal search/Set search string: You will be asked to supply a string, which will be used in future searches. Like all other string requests, you may instead supply a two byte string, starting with escape, and followed by either another escape character, or a letter a-m, representing a string buffer where the string should be copied from. If you supply escape-escape as the string, the string currently in the accumulator will be copied into the search string buffer. 2.5.9.2 CURSOR/Normal search/Find next occurrence: Using the currently defined search string, search forward for the next occurrence of that string. The string is searched for as-is, including question marks, asterisks, etc., which in a pattern search take on special meaning. 2.5.9.3 CURSOR/Normal search/Find previous occurrence: Similar to the above function, except that the search proceeds backwards. 2.5.9.4 CURSOR/Normal search/Find nearest occurrence: Similar to the above function, except that the search proceeds in both directions at the same time. The search is done line-for-line, and the first line that contains the search string, whether it be before the current cursor or after, will become the new cursor location. This function is handy when you know that a string is somewhere close, but you're not sure whether it may be just past, or just before, the current cursor location. Note that you may NOT use this function to find the second occurrence of a string; it will keep finding the same two closest occurrences. 2.5.9.5 CURSOR/Normal search/Search this line: This function is useful in macros, for determining whether a given string is within the current line. If the search string is not found in the current line, a macro "fail" will result, and unless your macro has prepared for this condition with an "End conditional" directive, the macro will abort. 2.5.9.6 CURSOR/Normal search/Search accumulator: Similar to the above function, except that the accumulator is searched. 2.5.10 CURSOR/Pattern search/: These functions are identical to their counterparts above, except that "Set search pattern" is used instead of "Set search string" and ARP wildcard characters are expanded (not used literally). 2.6.1.1 LABELS/Create single/End-of-line comment: You will be asked to supply a string of less than 240 characters, which will become a comment to be attached to the end of the cursor line. Only one end- of-line comment is allowed per line; if you create one on a line that has already got one, it will replace the old comment. 2.6.1.2 LABELS/Create single/Full-line comment: You will be asked to supply a string of less than 240 characters, which will become a comment to be attached to the start of the cursor line. Multiple full-line comments are allowed, and successive comments will be displayed AFTER previously defined full-line comments. Normally, full-line comments will be displayed starting with a semicolon (";"). However, if you start the string with a semicolon, the logic is reversed, and it becomes an extra line of code/data. Thus, you can insert extra lines of code/data, even before saving the source code to a text file. By creating a label that starts with a semicolon for a given line, when that code is assembled, that line of code/ data is effectively treated as a comment only, therefore you can both insert and effectively remove code/data using ReSource, during the disassembly process. 2.6.1.3 LABELS/Create single/Label: You will be asked to supply a string of less than 240 characters, which will become a label to be attached to the cursor line. Duplicate labels are NOT allowed, unless they start with a semicolon (";"), an asterisk ("*"), or a number directly followed by a "$". This last case is useful for creating local labels, but be careful. They are not checked for duplication and if used imprudently may make your assembler very unhappy. In the first two cases, they effectively make the rest of the line a comment. If this function is used within a macro, duplicate labels WILL be accepted. 2.6.1.4 LABELS/Create single/Label - fwd ref: 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 (unless it has already been set), and create a label at that offset (unless a label has already been defined for that location). This new label will be immediately used for all references to that location, which of course includes the reference within the current line. If there are 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. 2.6.1.5 LABELS/Create single/Symbol: You will be asked to supply a string, which will replace the first encountered number in the current line. For example, if you supplied the string "MyColdStartData", the following line: MOVE.L D0,4(A0) would become: MOVE.L D0,MyColdStartData(A0) If there is more than one number mentioned in the current line, the first is used. If there are no numbers in the current line, a macro "fail" will result. 2.6.1.6 LABELS/Create single/Symbol - dest: Similar to the above function, except that the second number in the current line will be replaced with the string that you supply. If there is only one number, or if there are no numbers in the current line, a macro "fail" will result. 2.6.2 LABELS/Edit single/: Similar to their above counterparts, except that if there is already a label/ symbol/comment defined, you will have the chance to edit that string, rather than type the entire new string into the requester. Note that, as far as ReSource is concerned, in the example "$0022(A1)", "$0022" is a number, NOT a symbol, unless YOU have defined it previously. If you try to edit it, you will be presented with an empty requester. Like all requests for a string, you can use indirection, so that ReSource gets the string from either the accumulator, or from one the buffers A-M. See the section on the STRINGS menu for more details. 2.6.3.1 LABELS/Replace single/Label: Create a "shop" label at the cursor position. A "shop" label is one that is 9 characters long, begins with "lb", has the data type immediately following, and ends with the code offset. It may also be of some other length, and end with ".MSG". 2.6.4.1 LABELS/Remove single/Label: Removes the label from the cursor position. 2.6.4.2 LABELS/Remove single/Symbol: Removes any symbols in the current line. 2.6.4.3 LABELS/Remove single/End-of-line comment: Removes the end-of-line comment from the current line, if any. 2.6.4.4 LABELS/Remove single/Full-line comment: Removes the first full-line comment attached to the current line. 2.6.4.5 LABELS/Remove single/All: Removes any label, symbols, comments from the current line. Also, the data type for the current cursor position is set to 'undefined', and the 'start of line' bit is cleared. This is useful when a bogus reference was made, as when ReSource (or you) thought code was being scanned, and it was actually data or ASCII. 2.6.5.1 LABELS/Create multiple/Reloc32: For each reloc32 pointer within the current file, determine and set the data type being referenced, and create a label at that location. This function will be called automatically whenever you load a load file that has at least one reloc32 pointer, unleass you override this option. 2.6.5.2 LABELS/Create multiple/All: Starting at the current address, the "LABELS/Create single/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. 2.7 LOCAL MACROS/: 2.8 GLOBAL MACROS/: Much background information is required here: The macro facilities available in ReSource are quite extensive. There are a maximum of 38 macros available on line at one time. These are divided into two banks of 19 macros, called "LOCAL MACROS" and "GLOBAL MACROS". The idea being that the 'local' macros are for your own personal use, and global macros are meant to be distributed to others. Therefore, you can load a 'global macros' file, and use them, but still have access to your own personal macros. The 19th local macro is special, in that it is executed when you first run ReSource, after the first file is loaded. This macro will often contain functions to set the various options to your personal taste, but may contain anything you care to put into it. When first creating a macro, you will be asked to supply a name for it. This name will be shown in the MACRO menu immediately after, and if you save that bank of macros to a file, the names of the macros are also saved. The functions "LOCAL MACROS/Execute/-unused-" and "GLOBAL MACROS/Execute/- unused-" are used to give macros in either bank a name. These names are also saved when you save a bank of macros, and when you load the macro file later, these names will immediately appear in the menus, making it much easier to remember what previously created macros did. The size of a macro is limited only by how much memory you have. To create a macro, select one of the sub-items in "LOCAL MACROS/Create/End/" or "GLOBAL MACROS/Create/End/". If the current name for the macro is "-empty-", you will be asked to supply a new name for the macro. If you create a macro of zero length, the name for that macro will revert to "-empty-". To execute the macro, simply select the appropriate sub-item in "LOCAL MACROS/Execute/" or "LOCAL MACROS/Execute/". You have control over the speed at which macros execute. The following chart indicates whether there will be a delay, and for how long, and whether the display will be refreshed between executing functions within the macro. Speed Selected Delay Refresh -------------- ----- ------- Very Fast No No Fast No Yes Slow .1 sec Yes Very Slow .5 sec Yes To have complete control over execution of the macro, select "LOCAL MACROS/ Execution speed/Wait on mouse". With this selected, you must press and release the left mouse button for each and every function within the macro to be executed. This is an excellent way to find bugs in a macro that you (or someone else) has created. Macros may be nested within macros, provided that the nesting depth does not exceed (approx.) 30. While you are creating a macro, you might find that you have to execute some functions to continue the macro definition, but you don't want them included in the macro itself. When this occurs, select "LOCAL MACROS/Suspend learn/ suspend", select the various functions that need to be done, then select "LOCAL MACROS/Suspend learn/Normal" to continue the macro definition. There are many functions that will make a macro fail, when it is executed. For example, using a cursor movement function that would place the cursor outside of the current file, will cause a macro 'fail'. A failed search will also cause a macro 'fail'. When executing a macro, if ReSource detects a macro 'fail', it searches forward in the macro definition for a "Conditional end" directive. Is none is found, all macro processing aborts immediately. If one IS found, macro processing continues normally from that point in the macro definition. If, while searching for a "End conditional" directive, a "Start conditional" directive is found, the next "End conditional" is skipped. Thus, conditional macro processing may be nested. There are five macro labels available. These are placed into the macro definition, and you can insert "goto previous macro label" and "goto next macro label" directives into the macro definition, which when found, will start a search either forward or backward, for the appropriate macro label. When found, macro processing will proceed normally from that point forward. Thus, you can loop a macro. If a search is made backwards for a macro label that is non-existent, macro processing will continue from the start of the macro definition. If a search is made forward for a macro label that is non- existent, the macro will exit, possibly to another macro that called this one. For example, the following macro will continuously scroll forward to the end of the file, then scroll backwards, one line at a time, to the start of the file, then forward to the end of the file again, etc., indefinitely, stopping only when you select "PROJECT/Abort": LOCAL MACROS/Set macro label/#1 CURSOR/Relative/Next line LOCAL MACROS/Previous macro label/#1 LOCAL MACROS/Directives/End conditional LOCAL MACROS/Set macro label/#2 CURSOR/Relative/Previous line LOCAL MACROS/Previous macro label/#2 LOCAL MACROS/Directives/End conditional LOCAL MACROS/Previous macro label/#1 Notice that the directive "Start conditional" was not required in the above example, as conditional sections were NOT nested. When you are creating a macro, and you are asked for a string (even the name of a file to load), if you select "okay" or press return after supplying a string, the string will be stored in the macro definition, and will be used when the macro is later executed, unless at the time that you execute the macro, "LOCAL MACROS/Interactive/" has been set to "ON". In this case, you will be prompted for any strings that are requested during the execution of the macro. Normally, this will not be required, but it does give you more control over an executing macro, especially if it was created by someone other than yourself. If, when creating a macro, you are asked for a string, and you want to force the user to input a string during the execution of the macro, you should select the "cancel" gadget in the string requester. Any string that you typed into the requester will still be used while creating the macro, however when the macro is executed, the user is forced to input a new string each time, even though 'Interactive' may be set to "OFF". Instead of actually supplying a string literal to a string requester, you may instead use indirection, to force the string to get copied from either the accumulator, or from one of the buffers A-M. For example, if the accumulator contains the string "MOVE", and you wish to create a label called "MOVE", select "LABELS/ Create single/Label", and when asked for the label name, press the escape key twice, and select the "okay" gadget, or press "return". If the required string was in buffer C, instead of pressing the escape key twice, you would press it once, followed immediately by "C". Buffers A-M are simply 13 separate 240-byte string buffers, in which you can store any strings that you like. A more appropriate name might be 'text registers'. Buffers L and M are special, in that if you select "STRINGS/ Define string/M", if buffer L is not empty, the string contained in it will be used as the prompt, in the requester. This is handy during macros functions where you want to get a string from the user. The user can then see what the string is required for. Normally, every function you put into a macro definition will be executed. This does not always have to be the case. The "LOCAL MACROS/Commentary/" functions sets the commentary level. When creating a macro, if you set the commentary level to "None", it is like specifying "The functions following are absolutely essential to the execution of this macro". If you set the commentary level to "Full" during the creation of a macro, you are specifying "The functions following are by no means required, they are simply running commentary, perhaps explaining what is happening in the macro at this point". Thus, by setting the commentary level during the creation of a macro, you are letting ReSource know how important the functions are, that follow. The commentary level may be changed many times during a macro, and for tutorial macros, such as showing someone how to disassemble/zap a particular program, the commentary level should be set appropriately. When it comes time to execute the macro, if the commentary level is set to "Full" by the user before the macro starts executing, ALL functions within the macro will be executed normally. If the commentary level was set to something other than "Full", only those functions in the macro that were set to a commentary level lower than that presently set, will be executed; the rest will be skipped over. Examine the following example macro: LOCAL MACROS/Commentary level/Full CURSOR/Relative/Next line LOCAL MACROS/Commentary level/Heavy CURSOR/Relative/Next line LOCAL MACROS/Commentary level/Normal CURSOR/Relative/Next line LOCAL MACROS/Commentary level/Light CURSOR/Relative/Next line LOCAL MACROS/Commentary level/None CURSOR/Relative/Next line If you set the commentary level to "None" and execute this macro, the cursor will move down one line. If you set the commentary level to "Light", and execute this macro, the cursor will move down two lines. If you set the commentary level to "Full" and execute this macro, the cursor will move down five lines. Using the "SPECIAL FUNCTIONS/Dos command" function, you can use the "SAY" command, to add speech to macros, to give excellent running commentary to tutorial macros. While executing a macro, if you have set the execution speed to "Wait on mouse", you can use other functions, perhaps to scroll backwards or forwards, to see what effect the last function had on the file. When you press the left mouse button to single-step the next function in the macro, the cursor address is restored in case you didn't return the cursor to the appropriate place within the file. If this was not done, macro processing would not proceed normally from that point on. When you load a macro file, only one bank of macros is affected. If the macro file only contains one macro, then only the one macro in that bank will be overwritten, and the rest will remain untouched. Thus, it is possible for a macro in the "LOCAL MACROS" bank to load other local macro files, giving an "overlay" effect. 2.9.1.1 STRINGS/Get/Label: If there is a label defined at the cursor location, it will be copied to the accumulator. 2.9.1.2 STRINGS/Get/Symbol: Copy the first symbol on the current line to the accumulator. 2.9.1.3 STRINGS/Get/Symbol - dest: Copy the second symbol on the current line to the accumulator. 2.9.1.4 STRINGS/Get/Symbol value: Get the value of the first number on the current line, and write text to the accumulator, representing that value in hex, decimal, or binary, as set by the "STRINGS/Accumulator/" options. The 'operand size' will be set by this function. 2.9.1.5 STRINGS/Get/Symbol value - dest: Get the value of the second number in the current line, and write text to the accumulator, representing that value in hex, decimal, or binary, as set by the "STRINGS/Accumulator/" options. The 'operand size' will be set by this function. 2.9.1.6 STRINGS/Get/End-of-line comment: Copy the end-of-line comment attached to the current line to the accumulator. 2.9.1.7 STRINGS/Get/Full-line comment: Copy the first full-line comment attached to the current line to the accumulator. 2.9.1.8 STRINGS/Get/Search string: Copy the current search string to the accumulator. 2.9.1.9 STRINGS/Get/Filename: Copy the current filename to the accumulator. 2.9.1.10 STRINGS/Get/Save .asm name: If the current file has already been saved as source code (to a ".asm" file), copy the filename used to the accumulator. If the current file has not already been saved, the name will be the same as the current filename, with ".asm" appended. 2.9.1.11 STRINGS/Get/Save .RS name: If the current file has already been saved to a .RS file, copy the filename used to the accumulator. If the current file has not already been saved, the name will be the same as the current filename, with ".RS" appended, unless ".RS" is already appended. 2.9.1.12 STRINGS/Get/Macros filename: Copy the current macros filename to the accumulator. 2.9.1.13 STRINGS/Get/Keytable filename: Copy the current keytable filename to the accumulator. 2.9.1.14 STRINGS/Get/Cursor longword: Write the data where the cursor is to the accumulator in hexadecimal. This may be a byte, word, or longword, depending on the setting of 'operand size'. 2.9.1.15 STRINGS/Get/Cursor offset: The currently displayed cursor location is written into the accumulator in hexadecimal as a longword (the "operand size" is set to longwords). 2.9.1.16 STRINGS/Get/Accumulator length: The length of the string currently in the accumulator is written into the accumulator in hexadecimal. The 'operand size' setting is not affected, but is used to decide how many leading zeroes to use. 2.9.1.17 STRINGS/Get/Partial save size: The number representing the difference between the partial save end and the partial save start is written into the accumulator in hex, decimal, or binary, as set by the "STRINGS/Accumulator/" options. The 'operand size' is set to longwords. 2.9.1.18 STRINGS/Get/File: You will be asked to supply the name of a file, of which up to 240 characters will be copied into the accumulator. The data is copied "as-is", no hex to ASCII translation is performed. 2.9.1.19 STRINGS/Get/Attribute bits: The attribute bits for the current location are copied into the accumulator, using the current numeric base (hex/decimal/binary). The definitions for these bits are described under "DISPLAY/Titlebar info/Attributes". 2.9.2 STRINGS/Put label: If the string within the accumulator is not used as a label anywhere within the current file, it will be used as a label on the current line. If it is already used as a label, then a digit is appended to it, and again it is tested to see if a label already exists of that name. This continues until a unique label is created, then that label is attached to the current line. This is a safe way of creating labels during macros. 2.9.3 STRINGS/Put attributes: If the accumulator contains a valid number, that number will overwrite the attributes for the current location. The definitions for these bits are described elsewhere. 2.9.4.1 STRINGS/Edit functions/Clip start: You will be asked to supply a string. Starting from the left, each character in the supplied string is compared to the character in the accumulator at that position, and if they are equal, the next character is compared, and so on. When either the end of one of the strings is found, or when a mismatch is found, the characters in the accumulator that matched are deleted. The question mark ('?') is used as a wildcard, and you can use the asterisk once only, to "delete everything until and including" the following character. Examples follow: Accumulator User-supplied string Resulting accumulator ----------------------------------------------------------- MOVE.L M OVE.L MOVE.L MUVE.L OVE.L MOVE.L MOV.L E.L MOVE.L move.l MOVE.L MOVE.L M?V E.L MOVE.L ??? E.L MOVE.L *. L MOVE.L *M OVE.L MOVE.L ?MOVE.L OVE.L _LVOAllocMem _LVO AllocMem $00000004 $000000 04 2.9.4.2 STRINGS/Edit functions/Clip end: Similar to the above function, except clipping is performed on the end of the accumulator string. The question mark is still used as a wildcard, but the asterisk does not have a special meaning in this function. Examples follow: Accumulator User-supplied string Resulting accumulator ----------------------------------------------------------- MEMF_PUBLIC ?PUBLIC MEMF MEMF_PUBLIC ??? MEMF_PUB MEMF_PUBLIC ?LC MEMF_PUBLI meMcollAOVL_ OVL_ meMcollA 2.9.4.3 STRINGS/Edit functions/Prepend: You will be asked to supply a string, which will be prepended to (added to the beginning of) the accumulator, providing that the resulting string is no longer than 240 characters. Examples follow: Accumulator User-supplied string Resulting accumulator ----------------------------------------------------------- PUBLIC MEMF_ MEMF_PUBLIC AllocMemSUB _ _AllocMemSUB PUBLIC CHIP CHIPPUBLIC 2.9.4.4 STRINGS/Edit functions/Append: You will be asked to supply a string, which will be appended to (added to the end of) the accumulator, providing that the resulting string is no longer than 240 characters. Examples follow: Accumulator User-supplied string Resulting accumulator ----------------------------------------------------------- PUBLIC MEMF_ PUBLICMEMF_ AllocMemSUB _ AllocMemSUB_ PUBLIC CHIP PUBLICCHIP AllocMem SUB AllocMemSUB 2.9.4.5 STRINGS/Edit functions/Reverse: The contents of the accumulator are reversed. Examples follow: Accumulator Resulting accumulator ---------------------------------------- PUBLIC CILBUP AllocMemSUB BUSmeMcollA AllocMem meMcollA 2.9.4.6 STRINGS/Edit functions/Lower case: Any upper case characters in the accumulator are changed to their lower case counterparts. Examples follow: Accumulator Resulting accumulator ---------------------------------------- PUBLIC0123 public01243 All0cMemSUB all0cmemsub All0cMem all0cmem 2.9.5 STRINGS/Operand size/: Some background information is required here: Some functions in ReSource require to know whether to work at the byte, word, or longword level. For example, "STRINGS/Get/Cursor value" could get a byte, word, or longword from the cursor position, and this is your way of specifying at which level you wish those functions to work. Generally, they specify the size of the numeric operand in the accumulator. Some functions that write a numeric value into the accumulator will set the operand size themselves, others that get the value out of the accumulator need to know the operand size. 2.9.6 STRINGS/Accumulator/: Options control whether to write the results of any maths functions to the accumulator in hex, decimal, or binary. 2.9.7.1 STRINGS/Maths functions/Increment: Some background information is required here: All maths functions make some change to the number within the accumulator. If the string within the accumulator is not a valid number (hex, decimal or binary), the function will fail. Some functions are immediate, others will ask the user for a required operand, such as what to add to the accumulator. The increment function adds one to the accumulator. If the resulting number develops a carry (using the current operand size), a macro 'fail' will result. Thus, loops in macros can exit after a given number of iterations, rather than a failed search, etc. 2.9.7.2 STRINGS/Maths functions/Decrement: Similar to the above function, except that one is subtracted from the accumulator. If a carry results, a macro 'fail' will occur. Thus, loops in macros can exit after a given number of iterations, rather than a failed search, etc. 2.9.7.3 STRINGS/Maths functions/Add: You will be asked for a number, to be added to the accumulator. If a carry results, a macro 'fail' will occur. 2.9.7.4 STRINGS/Maths functions/Subtract: You will be asked for a number, to be subtracted from the accumulator. If a carry results, a macro 'fail' will occur. 2.9.7.5 STRINGS/Maths functions/Multiply: You will be asked for a number, to be multiplied by the number within the accumulator. If a carry results, a macro 'fail' will occur. Full 32-bit multiplies are supported, however the setting of 'operand size' is used when determining the size of the operands. 2.9.7.6 STRINGS/Maths functions/Divide: You will be asked for a number. The contents of the accumulator will be divided by the number that you specify. The divide function does NOT operate on 32-bit operands, but otherwise will work at the currently set operand size. If the current operand size is set to longwords, the divide will be performed on the lower 16 bits only. 2.9.7.7 STRINGS/Maths functions/Negate: 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: 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: 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: 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. 2.9.7.11 STRINGS/Maths functions/Exclusive OR: 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.8 STRINGS/Define string/: 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.9 STRINGS/Swap with buffer/: The contents of the accumulator is swapped with the contents of the buffer that you select. 2.9.10 STRINGS/Input buffer/: The Input and Output buffers can be used to buffer textual information between a file and the accumulator within ReSource. To transfer information into ReSource, you load the input buffer, using "Load", and transfer a line at a time to the accumulator, using "Read line". Each time you read a line from the input buffer, it replaces the contents of the accumulator. Successive uses of "Read line" will get successive lines from the input buffer. A line means all text up to a line feed, to a maximum of 240 characters. The line feed is NOT transferred, as the line will be null terminated within the accumulator. To start reading lines from the start of the buffer again, use "Restart". For example, you may have a list of labels that you wish to put into the current file. Use "Load" to get the list of labels into the input buffer, then create a macro something like: CURSOR/Relative/Next label STRINGS/Input buffer/Read line STRINGS/Put label LOCAL MACROS/Previous macro label/#1 The first function will advance the cursor to the next label. The second function reads the next label to use into the accumulator. The third function will replace the current label with the one in the accumulator. The last function ("LOCAL MACROS/Previous macro label/#1") is optional. It will make the function repeat for the entire file, or the entire list of labels, whichever ends first. 2.9.11 STRINGS/Output buffer/: The output buffer is used to hold information that you wish to save from ReSource. The idea here is that you append the contents of the accumulator to the end of the output buffer, and eventually save the entire contents of the output buffer to a file. For example, you might wish to create a list of labels for the current file (see "STRINGS/Input buffer/:"). The following macro will do this: Note: Prior to actually running this macro, you should ensure that the cursor is at the start of file, and use the function "STRINGS/Output buffer/Clear", to ensure the output buffer is empty. CURSOR/Relative/Next label STRINGS/Get/Label STRINGS/Edit functions/Append STRINGS/Output buffer/Append accumulator LOCAL MACROS/Previous macro label/#1 The first line will move the cursor to the next label in the file. The second function will put the current label into the accumulator. The third function will prompt you for a string to append to the accumulator. A line feed (ASCII value 10) is required here, to do this, first click inside the requester string gadget, hold down the ctl key, and press "J", then press return or click on the "OKAY" gadget. The fourth function, "STRINGS/Output buffer/Append accumulator", will add the current contents of the accumulator to the end of the Output buffer. Memory is dynamically allocated for the output buffer, so maximum size is only determined by how much memory you have. The fifth function is optional, use it if you want the macro to loop until all labels in the current file are added to the list. Once this is done, use "STRINGS/Output buffer/Save" to save the current contents of the output buffer. You will be asked for a filename to use. In practice, most people will probably combine several pieces of information for each line that gets appended to the output buffer, such as label, followed by its offset from the start of the file, or its data type, etc. 2.10.1 SPECIAL FUNCTIONS/Repeat last command: Repeat the last menu function used. Functions bound to keys may be used without resetting the last menu function. For example, suppose you access a symbol base from the "SYMBOLS 2" menu. You then define some labels, using whatever KEY that function is bound to. Finally, you use the "Repeat last command" KEY. This will invoke the "SYMBOLS 2" function, rather than repeating the last KEY used. Cursor movement functions are NOT repeated, except the search functions. This function should be bound to a high- priority key, such as the space bar, for best effect. 2.10.2 SPECIAL FUNCTIONS/Dos Command: You will be asked for a string, which will be given as the operand to the Dos "execute" function. Anything that you normally type into a CLI window, you can give as a command. Any output will go to the CLI window from which you started ReSource, unless you redirect the output elsewhere. The "Run" command must be in your C: directory. 2.10.3 SPECIAL FUNCTIONS/Zap: You will be asked for a number/string, which will overwrite the byte/word/ longword/characters at the cursor position. The current setting of 'operand size' is used. Using PROJECT/Open binary file, then this function, followed by "SAVE/Save binary image/ALL", you can quickly modify a program, without having to go through the disassemble/edit/reassemble/link cycle. However, when using this method of modification, you are restricted as to the size of changes that may be legally made. For example, you cannot insert extra code or data, nor can you delete it. You may "NOP" it instead, though. If the string that you supply starts with a single quote ("'"), the following characters are treated as a string, and are copied to the cursor position "as-is". If the string that you supply starts with "$", the following number is assumed to be hexadecimal. If the string that you supply starts with "%", the number that follows is assumed to be binary, otherwise it is assumed to be a decimal number. 2.10.4 SPECIAL FUNCTIONS/Screen/: "Front" moves ReSource's screen in front of all other screens. "Back" moves ReSource's screen behind all other screens. 2.10.5 SPECIAL FUNCTIONS/Set task priority: You will be asked for a number, representing the priority at which to set the current task. For example, if you have a program being assembled in the background, and you don't want it to slow down the operation of ReSource, you might set the task priority to one or two. Negative numbers are not supported. Sorry! However, "$FF" will effectively mean "-1" with this function. 2.10.6 SPECIAL FUNCTIONS/Origin/: There is sometimes a requirement to disassemble a block of code, as if it is loaded to some particular area of memory, other than that to which it is now loaded. For example, if you disassemble Kickstart(TM), and save the binary image, then later load this into ReSource, it will not disassemble properly unless ReSource "thinks" that its origin is $FC0000. To do this, load the file, then use the "Specify" option. Both the "Specify" and "Set" set the origin to an absolute address; the "Set" option is the same as "Specify", except that it assumes that the current loading address is to be used. These options are really only useful if the file is loaded as a binary image, or from track, or memory. If loaded from an executable, the reloc32 information will ensure that proper relocation is done where needed. It is because no reloc32 information is available when loading files other than load files, that this function is required. To remove the origin, so that it uses whatever actual address the file is loaded to, use the "Clear" option. 2.10.7 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 frequently 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 lbB00011E,A4 ;scanning has already been done LEA 0(A4),A1 MOVE.L $000C(A4),D0 ... ;rest of code SECTION test00011E,DATA lbB00011E dc.b 'dos.library',0 dc.l $00010001 END In the above example program, the A4 register points to the start of the data segment. There are three ways to tell ReSource where the A4 register points; 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, supplying a parameter of "$11E". Basically, with this function you are telling ReSource where the A4 register can be assumed to be pointing, relative to the start of the program. After you do this, any effective address that involves a word offset to the A4 register, will be shown symbolically. If you have selected "Convert xx(A4) EA's/Absolute", the effective addresses will be shown as absolute addresses. Thus, the example program above will appear as: SECTION test000000,CODE LEA lbB00011E,A4 LEA lbB00011E,A1 MOVE.L lbL00012A,D0 ... ;rest of code SECTION test00011E,DATA lbB00011E dc.b 'dos.library',0 lbL00012A dc.l $00010001 ;This label will be created after END ;left-Amiga mouse-button is used. On the other hand, if you had selected "Convert xx(A4) EA's/Relative", the effective addresses would be shown as symbolic word offsets, and our example program would look like this: SECTION test000000,CODE LEA DT,A4 ;Note the new base label "DT" LEA lbB00011E-DT(A4),A1 MOVE.L lbL00012A-DT(a4),D0 ... ;rest of code SECTION test00011E,DATA DT lbB00011E dc.b 'dos.library',0 lbL00012A dc.l $00010001 ;This label will be created after END ;left-Amiga mouse-button is used. The advantage here is that labels can automatically be created where they could not before. After more iterations, our code could look like this: SECTION test000000,CODE LEA DT,A4 LEA DOSName-DT(A4),A1 MOVE.L Mem_Parms-DT(a4),D0 ... ;rest of code SECTION test00011E,DATA DT DOSName dc.b 'dos.library',0 Mem_Parms dc.l MEMF_CLEAR!MEMF_PUBLIC END 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, during the link process. 2.10.8 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 (Effective Address) 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 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, use the "SYMBOLS 1/Set Source/dest/Destination" function first. 2.10.9 SPECIAL FUNCTIONS/Data type set/: These functions affect how the "SPECIAL FUNCTIONS/Convert specific EA's" functions work. When the data type must be determined, it can be automatic, or you can force it to be set to Bytes, Words, Longwords, ASCII, Code. 2.10.10 SPECIAL FUNCTIONS/Convert to../: The setting here will determine the type of symbol created when the "SPECIAL FUNCTIONS/Convert specific EA's" functions are used, either an Absolute or Offset value. 2.10.11 SPECIAL FUNCTIONS/Reloc32/: Use these functions to specifically delocate or relocate the current file. This is only useful if file was loaded from an executable, where reloc32 information is present. Be aware that relocation is performed immediately after the "PROJECT/O'lay binary image" function, when a file is actually loaded. 2.11.1 SAVE/O/P Directory: You will be asked to supply the name of a directory. Whenever you are asked to supply the name of a file to save source code to, the name will have this directory name prepended to it. For example, if you supply the string "RAM:" as the output directory name, and the current filename is "c:stack", when you select "SAVE/Save .asm/ALL", the new name to save to will be "RAM:stack.asm". 2.11.2.1 SAVE/Partial save/Set start: For any partial saves, the current cursor position (as it is NOW) will be where the save will start from. By default, this position is equivalent to the start of the file. 2.11.2.2 SAVE/Partial save/Set end: For any partial saves, the current cursor position will be where the save will end. If this happens to be the last line in the file, any partial save will include the last line. Normally, the partial save will NOT include the line where the partial save end is set. 2.11.3 SAVE/Save binary image/: Save the current buffer contents "as-is", to a file. If the file was loaded with "PROJECT/Open load file", and was NOT loaded as a binary image file, the resulting saved file will NOT be the same as that originally loaded, because the loader information, and relocation information, has been stripped. If you wish to load a file, and then save it exactly as it was loaded, you must use "PROJECT/Open binary file". Even though you may have disassembled memory directly, or read tracks from a floppy disk, it does NOT stop you from saving the binary image. Once something is loaded into ReSource, it can be saved as source code, as a binary image file, directly to memory, or it can be written directly to a floppy disk, to a specific sector or track. This gives fantastic flexibility for general hacking, for as little as one byte of the current buffer can be saved to memory, to a binary image file, or as source code. Track writes must be in multiples of 512 bytes. However the clipping is done for you. Save "Partial" is similar to the above function, except only the data between the partial save start and the partial save end is saved. 2.11.4 SAVE/Save .asm/: You will be asked to supply the name of a file to save source code to, for the entire current buffer contents. The output will be very similar to how you see it on the display. Save "Partial" is similar to the above function, except only the code/data between the partial save start and the partial save end is disassembled. 2.11.5.1 SAVE/Calculate .asm size/ALL: Calculates the size of the source code file that would result if you had used the "SAVE/Save .asm/ALL" function. 2.11.5.2 SAVE/Calculate .asm size/Partial: Calculates the size of the source code file that would result if you had used the "SAVE/Save .asm/Partial" function. "Start" and "End" must have been set previously. 2.11.6 SAVE/Save to memory/: You will be asked to supply a memory address to save the contents of the current buffer. The buffer will be saved "as-is"; it is NOT disassembled. Care should be taken with this function, as a system crash will likely result if you supply the wrong address. By finding out where the current buffer is in memory, it is possible to copy one part of the current buffer to another part. Save "Partial" is similar to the above function, except that only the data between the partial save start and the partial save end is saved. 2.11.7 SAVE/Save tracks/: You will be asked for a string representing where to start writing tracks. The first parameter you give must be either "DF0:", "DF1:", "DF2:", or "DF3:". The second parameter is the starting cylinder to save to. The third parameter is optional, and represents an offset, in sectors, where the track write is to start. For example, to save the sector #3 on cylinder 5 on DF2:, the parameters required would be "DF2: 5 3". To save to the first sector on DF0:, the parameters required would be "DF0: 0". Whole sector writes ONLY are done, clipping is performed automatically. Save "Partial" is similar to the above function, except that only the data between the partial save start and the partial save end is saved. Furthermore, only even multiples of 512 bytes will be written. For example, if the partial save size is 1027 bytes, only two sectors (1024 bytes) will be written to the disk. 2.11.8 SAVE/Tabs/: Use to select between real tabs (ASCII value 9) and spaces being used in the output source code as separators. 2.11.9 SAVE/Symbol table/: When creating symbols, either automatically or manually, if the setting of this function is to something other than "None", the value and name of the symbol is stored, so that when the source code is saved, an equate table, or XREF table can be generated. If this function is set to "EQUate", a symbol table similar to the following will precede the source code in the output file: AG_OpenLib EQU $00030000 AO_DOSLib EQU $00008007 AT_Recovery EQU $00000000 _LVOAlert EQU $FFFFFF94 _LVOClose EQU $FFFFFFDC _LVOCreateProc EQU $FFFFFF76 _LVOCurrentDir EQU $FFFFFF82 If, instead, this function is set to "XREF", a symbol table similar to the following will preceed the source code in the output file: XREF AG_OpenLib XREF AO_DOSLib XREF AT_Recovery XREF _LVOAlert XREF _LVOClose XREF _LVOCreateProc XREF _LVOCurrentDir 2.12.1 OPTIONS 1/Show offsets/: For lines displayed without labels, the current offset (relative from the start of the file) will be displayed where the label is usually displayed. If "DISPLAY/Set counter" is used, offsets will be relative to where the counter was set. 2.12.2 OPTIONS 1/Display beep/: Many functions demand attention from the user, and a display beep is used for this purpose. Normally, this will make the screen flash. However, if you have run the program "addbeep", or a similar DisplayBeep() replacement, you will hear an audible "beep" instead. If you don't appreciate the beep, then switch it off. 2.12.3 OPTIONS 1/User feedback/: Many functions will give informative messages, to let the user know what is happening internally. If you don't appreciate the feedback, then switch it off. 2.12.4 OPTIONS 1/Feedback Delays/: If you have User feedback set to "OFF", then the setting of this function is irrelevant. If feedback is ON, you may occasionally find that feedback message are being displayed too fast for you to read them. This is especially so when opening a load file, since as many as thirty informative messages can be displayed in between raster scans, which means that you don't actually get to see any of the messages at all. If normal text rendering were used, rather than using the special rendering routines in ReSource, this would probably not be a problem, as the writing of the text itself would be done much slower, and you would probably get time to read at least some of the messages. If you set feedback delays to "ON", there will be a one second delay after each message is displayed, which should be plenty of time to read each message. While you hold the menu button down, feedback messages are skipped altogether. 2.12.5 OPTIONS 1/Labels/: If this option is set to ON, labels will be displayed. This is the default. 2.12.6 OPTIONS 1/Hidden labels/: If this option is set to ON, hidden labels (labels attached to a byte in the middle of a line of code/data) will be displayed. This is the default. 2.12.7 OPTIONS 1/Symbols/: If this option is set to ON, symbols will be displayed. This is the default. 2.12.8 OPTIONS 1/End-of-line comments/: If this option is set to ON, end-of-line comments will be displayed. This is the default. 2.12.9 OPTIONS 1/Full-line comments/: If this option is set to ON, full-line comments will be displayed. This is the default. 2.12.10 OPTIONS 1/Chip-load info/: If this option is set to ON, where a section statement is displayed, and that section either is forced to load into chip memory, or is forced to load into fast memory, a ",CHIP" or ",FAST" will be appended to the section statement. Not all assemblers support this parameter for the section statement, so you may want to switch this option OFF if your assembler can't handle it. 2.12.11 OPTIONS 1/Section statements/: If this option is set to ON, section statements will be displayed. This is the default. 2.12.12 OPTIONS 1/End statement/: If this option is set to ON, the "END" statement will be displayed as the last line in the file. This is the default. 2.12.13 OPTIONS 1/DCB statements/: If this option is set to ON, "dcb" type statements will be used where appropriate. This is NOT the default. For example, the following data: dc.b 0 dc.b 0 dc.l 7 dc.l 8 dc.l 8 dc.l 8 dc.l 8 dc.l 8 dc.l 8 will be shown as: dcb.b 2,0 dc.l 7 dcb.l 6,8 This is useful for shrinking the required .asm file size, especially where there are large areas of zeroes. 2.12.14 OPTIONS 1/Reference recognition/: If this option is set to ON, references to memory locations within the current file are recognized. For example, assuming that the absolute address of the start of the current file is at $200000, the following lines might be displayed with Reference recognition ON: dc.l $48638335 dc.l START+$1097 dc.l START+$3086 whereas if reference recognition was OFF, it would be displayed as: dc.l $48638335 dc.l $201097 dc.l $203086 Reference recognition is ON by default. If any pointer (32 bits) is in a reloc32 area, the reference will be recognized regardless of the setting of this option. 2.13.1 OPTIONS 2/ASCII longs/: If this option is set to ON, where longword operands are recognized as all ASCII characters, such as 'KICK', they will be displayed as such. This is the default. By using the "DISPLAY/Set numeric base/ASCII", lines such as: MOVE.L #'DOS'<<8,(A2) MOVE.L #'KICK',(A2) or virtually any lines containing valid ASCII characters may be independently displayed as ASCII, despite the setting here. 2.13.2 OPTIONS 2/Short branches/: If this option is set to ON, any short branches will be displayed as such, with the ".S" appended to the opcode. This is the default. Note that this option will NOT show you all POSSIBLE short branches, only those that are already present in the code that's being disassembled. 2.13.3 OPTIONS 2/Separate labels/: Under normal conditions, if a label is longer than 20 characters, it is broken at that point, and the remainder is shown on the next line. This option forces the entire label to be shown on one line. 2.13.4 OPTIONS 2/Label colons/: This option will display colons ,":", after all labels. 2.13.5 OPTIONS 2/Leading zeroes/: Use these options to specify whether or not you wish the leading zeroes on hex values to be shown, e.g., "$0000003A" versus "$3A". 2.13.6 OPTIONS 2/Assembler/: Use these options to specify for which assembler the output should be suitable. Metacomco output currently works with CAPE(TM) as well, although smaller files will result with CAPE(TM) output. Currently, "dc.b" will be shown as "db", "dc.w" is shown as "dw", and "dc.l" is shown as "dl", if CAPE is chosen. 2.14 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, however there is just one function that makes no sense to rebind, and that is the "PROJECT/Abort" function. Both Amiga-keys are supported, you may use shift, alt, ctrl, lAmiga, rAmiga, shift-alt, shift-ctrl, alt-ctrl, or shift-alt-ctrl in combination with any non-qualifier key, as a distinct key to which to bind a function. 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.). If a keytable file is loaded, ALL current key bindings will be overwritten by the bindings present in the keytable. If you don't load any keytable, and ReSource couldn't find "S:RS.Keytable" when you first ran it, some keys will still be bound: right-Amiga Q PROJECT/Quit right-Amiga O Open load file up arrow CURSOR/Relative/Next line down arrow CURSOR/Relative/Previous line right arrow CURSOR/Absolute/Fwd reference left arrow CURSOR/Absolute/Previous location shift-up arrow CURSOR/Relative/Previous page shift-down arrow CURSOR/Relative/Next page To rebind a key, select "KEY BINDING/Rebind key", and follow the prompts in the title bar. Index [The index is only in the printed manual. Sorry! JL] ***************************************************************************** Bug Fixes and Changes Since V3.05 --------------------------------- V3.06 (April 1989): 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. Attempts to set the data type to ASCII or CODE in a BSS or unitialized 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 unitialized data area will *always* show as "ds.b", "ds.w" or "ds.l". Holding down the left mouse button during macro execution no longer temporar- ily sets the execution speed to "Slow". This was previously causing some minor multitasking difficulties. 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 disp- layed. 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. When a data type other than code is set manually, previously this would some- times cause reloc32 areas to be shown as bytes or words. This will no longer happen. 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 most notice- able when strings are displayed. 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. 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 words, effective- ly preventing the overlap. 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. When the left mouse button is held down, as well as the ctl key, symbols and full-line comments are now temporarily disabled. This allows you to quickly see the value of any symbols present in code. When a user-defined label is created, the "internally produced" bit in the attributes table is now cleared. 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. The "DISPLAY/Block fill" function had some severe limitations, namely: 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 problems have been fixed. It is now possible to abort from an "Open load file" operation. 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. 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 particular condition occurs during the save, and the totals are displayed continuously. 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). There is a new function, "SAVE/Save screen". It 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 other file. Note that this can be used at the completion of a "save .asm", to get a printout of the source code profile. 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. Tab characters 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. 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. The "LABELS/Create multiple/Reloc32" function now checks the validity of reloc32 pointers before attempting label creation. It is now possible to append to files when saving, rather than simply replac- ing 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 requested for a filename, you would type "*>ram:MySavedFile". This is valid for *any* file save, including screen saves, binary image saves, etc. 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. When the result of a "STRINGS/Maths functions/Logical OR" was zero, a macro fail should have resulted, but didn't. Fixed. If a label longer than 19 bytes was displayed as a "hidden" label, a system crash was likely. Fixed. 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. 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. It was sometimes difficult to abort from an executing macro, especially if the macro execution speed was set to "wait on mouse". Fixed. 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. 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. 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. 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. 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 CODE hunk. Using the "SAVE/Save binary image/" functions would sometimes save less than what it should have saved. This would happen if there was at least 4 null bytes at the end of the current file. Fixed. 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. 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,A4" will also work. There is a new option; "OPTIONS 2/Assembler/CaPatch". Source code produced for this assembler uses the "DX" directive, to support unitialized 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 previously only available to "C" programmers. There is a new hilite option; "Unitialized data". When selected, any uninit- ialized data areas will be hilited. When the selected assembler type is "Cape" or "CaPatch", the directives "bnryonly", "exeobj" and "objfile" are used where appropriate. When supplying a string 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 must start with an "escape" character (decimal value 27, 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 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 where the required string is attached to. Another escape character is required immediately following the number, as a delimiter. You are then free to either supply more "normal" text, or you may use indirection several times within a single string specification. Because the escape character is not normally displayable, the following example will use a "^" character where the escape character is really meant to be: lbW000140 dc.w 6 dc.w 8 dc.w 12 lbC000146: RTS lbC000148: MOVEQ #0,D0 RTS lbC00014C: MOVEQ #1,D0 RTS In the above program, 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 happen to be 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 It has been possible to use the "SPECIAL FUNCTIONS/Convert specific EA's" functions to make the creation of these symbols easy. However, there has always been a problem; if you later change the label "lbC000148" to "ClearValue", or any other label, the symbol "lbC000148-lbW000140" will cause an assembly error. Now, by using dynamic indirection, whenever the symbols at label "lbW000140" are displayed, it will use whatever labels are in use at that moment. 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 requested by the "LABELS/Create single/Symbol" function (remember that the "^" is actually an escape character, press the escape key). This dynamic indirection is now also used internally in ReSource, where it seems required. 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 raw string will be used. Dynamic indirection was meant to be used in symbols. It is possible to use in labels and comments, however some problems may arise if care is not taken. For example, duplicate labels can 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 are symbols, that refer to labels, and therefore do not require to be EQUated or XREF'd. In revision 5, a macro fail resulted if an attempt was made to display an operand as ASCII, if an invalid ascii character was encountered. This created a problem when macro execution speed was set to "Very fast", as displaying was disabled at the time the ASCII attribute was set, and the macro fail did not result until some later time, perhaps when running some other macro. When invalid ascii characters are encountered in an operand, it will still show as hex, but a macro fail will no longer result from this. 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. When using "SAVE/Save .asm/Partial" or "SAVE/Calc .asm size/Partial", no EQUate or Xref table will be created. 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. If data type "word", "longword" or "code" is selected at an odd address, a display beep is now generated. 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, representing the start of each of these lines. Thus, after using one of these functions, use "CURSOR/Absolute/Previous location" to go directly to each of these erroneous lines. This is an excellent way to quickly ensure that the source code that you create will assemble properly. ReSource now remembers the presence of any "AFLINE" macros, after saving/ reloading a ".RS" file. The "CURSOR/Absolute/Forward reference" and "CURSOR/Absolute/Second forward reference" functions normally allow you to reference a label only. It is now possible to forward-reference on a symbol, even if the symbol is actually a combination of two or more labels, and even if it was created using dynamic indirection. If the user creates a symbol which is currently also defined as a label, a display beep will be generated. When creating labels from forward references, if ReSource detects that a reference to an odd address is coming from code, a display beep will be generated, and also a macro fail will result. If using "LABELS/Create multiple/All", the scan will stop. 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. Several values in the "CIA Resource" symbol base were incorrect. Fixed. The "LABELS/Create multiple/All" function now uses a different algorithym to detect when it should stop creating labels. The chance of it mistaking ascii for code is now much decreased. 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". While a macro is executing, if the "CANCEL" gadget is selected for a requester, the macro will now abort. 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. The start and end for partial saves now default to the start and end of the current file. There is two new functions, "SAVE/Partial save/Reset start" and "SAVE/Partial save/Reset end". Selecting these will reselect the default values. 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. A number of "SYMBOL" functions were giving bad symbols when the value for which a symbol was required, was greater than $FFFFFF. Fixed. 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. The functions "STRINGS/Output buffer/Append accumulator" had problems when more than 4K or information was put into it. Fixed. 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. When using the functions "CURSOR/Absolute/Label" and "CURSOR/Absolute/ Symbol", if required label/symbol was at the start of the file, the function used to fail. Fixed. =eof=