Amiga ISO Collection

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

/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Misc / rs60-1.dms / rs60-1.adf / ReadMe < prev next >

Wrap

Text File | 1994-04-24 | 50.1 KB | 1,119 lines

***************************************************************************** * ---==== Introduction for New ReSource Users ====--- * ***************************************************************************** April 1994 Dear ReSource Owner, Thank you for purchasing ReSource! We hope that you enjoy using it and that you find it a useful tool. Here are some things you should know: ReSource runs on any 680x0 CPU, but automatically detects the presence of an 020/030/040 CPU and runs faster routines if possible. ReSource will allow you to create source code in either traditional 68K syntax, or the new Motorola M68000 Family assembly language syntax, and is fully compatible with the Macro68 assembler. By selecting the appropriate option, the output can be made compatible with CAPE, Metacomco, DevPac or ArgAsm assemblers. You may choose either "strict" or "relaxed" syntax. For example, when an address register is the destination, "MOVEA" is the proper instruction, but may be displayed as simply "MOVE" by not using "strict" mode. A powerful online help facility featuring hypertext word indexing is included. This enables you to get in-depth help about any function at the touch of a key. An Intuition disassembler and a Copper list disassembler are included in this release. These programs can provide a lot of information about the structures used to create a GUI, as well as making your own interface layouts easier. ERRATA: In the In-Depth Tutorial, starting on page 5-1 of the manual, "kp9" is referred to when creating labels. This is incorrect. The correct key to use when creating labels is "kp*". UPDATE POLICY: In order to clear up any confusion in this area, be aware that it is the policy of The Puzzle Factory to *not* send out update notices for minor bug fixes that would not affect the majority of ReSource owners. If you are having a problem, please contact The Puzzle Factory or your distributor to find out if a later version of ReSource is available. PLEASE register! If there are any serious problems, we need to know how to get in touch with you. Fill out the registration card and mail it today! ***************************************************************************** * ---==== Introduction to ReSource Version 6.00 ====--- * ***************************************************************************** This file comprises documentation on the changes to ReSource since release V5.10. It is not intended to be a substitute for the ReSource V5 manual. If ReSource is new to you, please read the manual first! For all those loyal fans who have used and appreciated ReSource through the years, thanks! We hope you like what you see. The greatest areas of development have been to make ReSource more productive, more system compatible, and to give it a better GUI. In some ways, these last two goals are similar. Please notice that the menu strip is much smaller, and more manageable, and that important functions have their own interface windows. The main improvements to this release are summarized below: + Added PROGDIR: support for most support files and all libraries. + No more ARP and associated cache problems with advanced processors. + ReSource is now compatible with Intuition, and provides a public screen. You may now run your favorite utilities on ReSource's screen. + New command line and Workbench option flags include a Screen Mode requester. + The displayable character set now includes all printable characters. from the Latin1 character set. This includes the copyright symbol and International ASCII characters. + We removed the hundreds of Symbols menu items, and developed a 3-part, scrollable Symbol Requester. The built-in symbol bases now correspond completely with the 39.108 Include.i release. + Support for multiple symbols in the same base that resolve to the same value (unions, etc.) has been added. For example, if given the number "8", in the symbol base "DosPacket", you may now choose from "dp_Type" and "dp_Action". This makes your source code clearer. + Macro creation and execution, environmental Options, and the old, confusing search items have all been removed from the menus and given their own requester windows. All of these windows, as well as the Symbol Requester may be freely opened, closed, moted, and depth arranged as you do your work. + Release 6 completely disassembles the entire MC68000 family including: 68000, 68010, 68020, 68030, and 68040 CPUs 68881, 68882, and 68040 FPUs 68851, 68030, and 68040 MMUs + Full support of floating point code, including 4 new data types, and a special floating point library. + Online help has been updated to include all the new features. You can now use the help system to get information about all the OS V39 System Library functions. This includes the name, a one-line function synopsis, and register usage. + The "zap" function has a new requester window that includes data type and size gadgets, and a mini-assembler for code modifications. Please read this file carefully. Many things have changed. Whether you are a long time ReSource user or a new user, you will need to know both what is different and what is new in order to take full advantage of the power built into ReSource Release 6. Sincerely, Jeff Lavin Thg Puzzle Factory ***************************************************************************** * ---==== INSTALLATION ====--- * ***************************************************************************** ReSource Release 6 requires V37 (2.04) or higher of the Amiga OS. It will not be possible to use this release otherwise. Because of the size of the support files for Release 6, ReSource will no longer be useful on a system with 1 megabyte of ram. Merely running this release without loading a file requires close to 400K. We suggest at least 2 megabytes of ram to do useful work. For the same reason, we no longer support installation to floppy disk. -----------------/----------------- There has been a change in where ReSource looks for its support files. For non-system libraries, it looks in these places, in order: PROGDIR:libs/, libs:, libs:ReSource/, ReSource:, and ReSource:libs/ For RS.Keytable and RS.Macros, when first started, it looks in these places, in order: CurrentDir, PROGDIR:, and S: All other locations mentioned in the manual are NO LONGER VALID! -----------------/----------------- There are 2 different ways to install ReSource. In the historical installation, everything goes into your SYS: partition, and all files are always global. This can create problems for people who have a small SYS: partition. In order to support Commodore's installation guidelines, we have provided an alternative installation procedure. In the PROGDIR installation, everything is installed in one directory, usually on the Work: partition. All file accesses are relative to this directory, but instead of being able to type 'run ReSource', you must enter 'run <PROGDIR>/ReSource' or its equivalent. All this typing may be eased by the use of an alias. At this point you can run the supplied script (located on ReSource_3:) to install ReSource, which will do the PROGDIR installation, or you can choose to do it yourself by following the directions below. Note that these instructions do not install the include files, or anything not essential to the operation of ReSource itself. -----------------/----------------- The Historical Installation =========================== You will need approximately 810K of total free space for all these files. 1. Copy all executables to somewhere in your executable path: > Copy ReSource_1:ReSource SYS:Tools/ ;For example > Copy ReSource_1:ReSource.info SYS:Tools/ > Copy ReSource_1:ShowMacros SYS:Tools/ > Copy ReSource_1:ShowMacros.info SYS:Tools/ > Copy ReSource_1:ShowKeys SYS:Tools/ > Copy ReSource_1:ShowKeys.info SYS:Tools/ 2. Copy the data files to S: > Copy ReSource_1:RS.Macros S: > Copy ReSource_1:RS.KeyTable S: 3. Copy the library files to libs: > Copy ReSource_1:libs/ReSourcehelp.library libs: > Copy ReSource_1:libs/ReSourcesyms.library libs: > Copy ReSource_1:libs/ReSourceutil.library libs: > Copy ReSource_1:libs/simpleasm.library libs: > Copy ReSource_1:libs/fpsupport.library libs: or create a directory in libs: named "ReSource": > makedir libs:ReSource > Copy ReSource_1:libs/ReSourcehelp.library libs:ReSource/ > Copy ReSource_1:libs/ReSourcesyms.library libs:ReSource/ > Copy ReSource_1:libs/ReSourceutil.library libs:ReSource/ > Copy ReSource_1:libs/simpleasm.library libs:ReSource/ > Copy ReSource_1:libs/fpsupport.library libs:ReSource/ 4. Copy the doc files wherever you wish: > Copy ReSource_1:ReadMe <somewhere>/ > Copy ReSource_1:ReadMe.info <somewhere>/ > Copy ReSource_2:Docs/ShowMacros.doc <somewhere>/ > Copy ReSource_2:Docs/ShowMacros.doc.info <somewhere>/ > Copy ReSource_2:Docs/ShowKeys.doc <somewhere>/ > Copy ReSource_2:Docs/ShowKeys.doc.info <somewhere>/ 5. If your version of asl.library is <39.4 you may optionally copy asl.library V39.4 to your libs: directory. This will allow you to use the screen mode requester if you wish: > Copy ReSource_1:libs/asl.library libs: 6. If you wish to use the RCL functions (see the doc file), then: > Copy ReSource_2:CFuncs.rcl libs: 7. Done. ReSource is installed and ready to work. There are also other utilities, doc files, and system files on the disks. Take a look at what is available, and decide if you want these available on your hard drive. Skip to the next section. -----------------/----------------- The ProgDir Installation ======================== 1. Create a directory somewhere on your hard drive. You will need approximately 810K of free space on this partition. For purposes of discussion we will call this directory "Work:RS", but you can locate it anywhere you like. > makedir Work:RS Make another directory named "libs" inside RS: > makedir Work:RS/libs ;MUST be named "libs" 2. Copy all this stuff into the directories you just created: > Copy ReSource_1:ReSource Work:RS/ > Copy ReSource_1:ReSource.info Work:RS/ > Copy ReSource_1:ReadMe Work:RS/ > Copy ReSource_1:ShowMacros Work:RS/ > Copy ReSource_1:ShowKeys Work:RS/ > Copy ReSource_1:RS.Macros Work:RS/ > Copy ReSource_1:RS.KeyTable Work:RS/ > Copy ReSource_1:libs/ReSourcehelp.library Work:RS/libs > Copy ReSource_1:libs/ReSourcesyms.library Work:RS/libs > Copy ReSource_1:libs/ReSourceutil.library Work:RS/libs > Copy ReSource_1:libs/simpleasm.library Work:RS/libs > Copy ReSource_1:libs/fpsupport.library Work:RS/libs > Copy ReSource_2:Docs/ShowMacros.doc <somewhere>/ > Copy ReSource_2:Docs/ShowMacros.doc.info <somewhere>/ > Copy ReSource_2:Docs/ShowKeys.doc <somewhere>/ > Copy ReSource_2:Docs/ShowKeys.doc.info <somewhere>/ 3. If your version of asl.library is <39.4 you may optionally copy asl.library V39.4 to your libs: directory. This will allow you to use the screen mode requester if you wish: > Copy ReSource_1:libs/asl.library libs: 4. If you wish to use the RCL functions (see the doc file), then: > Copy ReSource_2:CFuncs.rcl libs: 5. Done. ReSource is installed and ready to work. Remember, when you want to use ReSource, you must type: > run Work:RS/ReSource ;For example A finger-saving alternative to this is to enter the following into your Shell-Startup: Alias rs Work:RS/ReSource ;For example There are also other utilities, doc files, and system files on the disks. Take a look at what is available, and decide if you want these available on your hard drive. ***************************************************************************** * ---==== ABOUT THE INTERFACE ====--- * ***************************************************************************** NOTE WELL: Most commands, with the exception of Abort (Right-Amiga A) will be ignored while any ReSource functions, including macros, are being executed. This means you can't: + Change options flags + Select new menu functions + Select new requester functions + Close requester windows While we realize that this is not particularly good programming practice, we are also forced to maintain backward compatibility with previous versions of ReSource, to a certain extent. At this point in time, changing the functionality of ReSource either to lock out new input while it's busy, or to queue events, would slow down the program to the point that trying to do useful work would be painful. ReSource will display the busy pointer in any active window, other than visitor windows, when it's busy. Selecting new functions while ReSource is busy will have effects ranging from none at all, to doing unintended things to your disassembly. One of the more common effects may be gadgets and menus temporarily getting out of phase with the internal program state. We don't want to make this sound worse than it is. It is unlikely that you will experience any serious problems with this. However, we ask you to please consider the above a small price to pay for the productivity of the new GUI, and when you ask ReSource to do something, wait until it's done before giving it more input (with the exception of the Abort function). ***************************************************************************** * ---==== ABOUT REQUESTER WINDOWS ====--- * ***************************************************************************** Requester windows have taken the place of literally hundreds of former MenuItems. Requester windows may be opened at will, and used for one or many functions, and closed or left displayed. Note that all requesters are "live". This means that when you press a requester gadget, you are executing that function in real time. In some cases there may be a delay while the selected function executes. This is because the gadgets must work in the same way as the many MenuItems they replaced in previous versions in order to maintain backward compatibility. Most MenuItems and bound keys will work "through" the requester windows, meaning you don't have to be concerned about where the mouse pointer is located--the commands will still work even if a requester window is active. There are two exceptions to this: 1. When a string gadget in a requester window is active, it will eat most keyboard events. 2. You will not be able to use Left-Button + Left-Amiga to create new forward referenced labels if the mouse pointer is over a requester window when the button is first pressed. Some comments about the new requesters are in order: Screen Gadgets ============== There are 7 gadgets along the bottom of the ReSource screen. Each gadget causes a requester window to open. If a particular requester window is already open, selecting that gadget causes the requester window to be brought to the front. All requester windows may be dragged. Closing a requester window saves the screen coordinates of that window, so that it will appear in the same location the next time it is opened. Symbol Requester ================ You will see a window with 3 ListView gadgets. ListView 1 corresponds to Include file directories. ListView 2 corresponds to Include files, and ListView 3 shows all the symbol bases in the selected Include file. The symbol bases correspond to the V39.108 Includes (located on ReSource_3:), and will mostly be found in the same order as those in the include files. This is designed to help beginners get used to the include files more quickly. If you are not familiar with the V39.108 Includes, we suggest you keep a copy nearby for quick reference as to which symbols are in which symbol bases. The USE gadget will not be available until you have selected a valid symbol. If you change your mind and want to back out, select the CANCEL gadget. The LOAD gadget is for loading a User-Symbol base, and won't be available until you have selected one. You may Double-Click on the ListView entry in the 3rd column and it will be treated the same as USE. Note that if the entry you select is a User-Symbol base, and it is empty, nothing will happen. If you select a symbol base that contains more than one symbol with the same value (see intuition.i/NewWindow for an example), the Multi-Symbol Requester will appear, and you will be given a choice of which symbol to use. The USE gadget will not be available until you have selected a valid symbol. If you change your mind and want to back out, select the CANCEL gadget. You may Double-Click on the ListView entry in the Multi-Symbol Requester and it will be treated the same as USE. Currently, the Multi-Symbol Requester only works with structures and normal equates--it won't work with bitdefs that have multiple symbols that resolve to the same value. Note that unlike the other requester windows, the Multi- Symbol Requester blocks until a selection is made, or CANCEL is selected. A new feature in ReSource V6 is System Library function synopses. When using keys bound to symbol bases or by using the symbol requester, you can get a list of function synopses for the selected library by the following actions: Select Help (from the menu or press the Help key). Either: Select a key bound to a system library symbol base. or Select "Lib offsets" from the 1st column of the Symbol Requester. Select a library, device or resource from the 2nd column. Select the symbol base from the 3rd column. See the section "ABOUT SYMBOL BASES" for more info on new symbol bases. Search Requester ================ The radio buttons select the type of search. Notice when you push them, some of the other gadgets become ghosted. All of the search choices are not appropriate or available under all the search types. If the option is currently available, it will become unghosted. If the option is ghosted, it is not available in that search type. The 3 cycle gadgets determine the behavior of searches. These will be ghosted when not applicable. Not all modes are applicable to all searches. Case sensitivity is only applicable to Normal, Pattern and Buffer searches. Alignment is only applicable to Binary searches. FROM CURRENT/START/END is applicable to all searches except Label and Symbol. The case sensitivity in Normal and Pattern searches is new, as is the FROM gadget. The other 2 cycle gadgets are spares and are not in use at this time. The FROM gadget will begin the next search from the start or end of the file or from the current position. FROM START only works in the FORWARD direction and FROM END only works in the BACKWARD direction. If you want to find the first instance of a string, select FROM START. When you select FORWARD, the file will be searched from the beginning. After the search, the FROM gadget will revert to CURRENT so that you can search for the next instance. If you select FROM START and then BACKWARD, a normal backward search will be done from the current position. The FROM END selection works much the same except searching starts at the end of the file when you select BACKWARD. If you select FROM END and then FORWARD, a normal forward search will be done from the current position. The NEAREST, THIS LINE, and ACCUMULATOR searches ignore the FROM gadget. After using FROM START or FROM END, your old position wll be found on the position stack, and may be recalled by the Remember function (normally bound to the Left-Arrow key). Enter your search string in the string gadget. The string will not be set, from ReSource's point of view, unless you press return after entering the string. (We do know that it is possible to have a program accept the string even if return is not pressed, but it can't be done in this case. Sorry.) Remember to select pattern search if you enter a pattern. Otherwise the string will be interpreted literally. All pattern searches now use standard AmigaDOS regular string expressions. The "*" wildcard ("#?" substitute) will only function if you have it switched on in dos library. See the section "ABOUT SEARCHING" for more information. The search will actually be done when you select the FORWARD, BACKWARD, NEAREST, THIS LINE, or ACCUMULATOR gadget, not when the string is entered. Entering the string only sets the string for that type of search, and only after pressing return. If you don't press return, ReSource will search for the previously entered string. The Search Requester will remember what type of search and options you selected the last time you used the requester, and set it up the same way for your next use. Macro Requesters ================ There are 3 MACRO gadgets corresponding to 3 Macro Requesters. Select the MACRO gadget of your choice. Select the desired macro, and then select CREATE or EXECUTE. The CREATE gadgets of any open Macro Requesters will be ghosted during macro creation because macro creation may not be nested. Likewise, the EXECUTE gadget of the Macro Requester that the Create Macro was started from will be ghosted while the macro being created is selected, because a macro being created may not be executed. However, macros themselves may be nested, so you may select a different macro from that requester, or another macro requester, to execute. After finishing creating a macro, select End Macro from the Macro Menu. We are not currently planning to support Double-Click selection in Macro requesters because it is too dangerous to accidentally select the wrong macro. It's fairly easy to change the symbol, if an incorrect base was selected, but the wrong macro can mess up a lot of work, and be very difficult to fix. -----------------/----------------- Over the years as we have talked to ReSource users, we have discovered that the macro functions are underused or overlooked by a large number of people who could benefit from their power to eliminate repetitive work. Our discussions have led us to believe that some people felt intimidated by the complexity and lack of good examples. The RS.Macros file distributed with ReSource Release 6 has a number of macros that can be useful in their own right. However, the primary goal when writing this macro file was to illustrate how to write a variety of different types of macros so as to take advantage of this time-saving feature. The source code for the macro file is heavily commented. If you aren't conversant with these tools, we hope you will take this opportunity to explore them further. Options Requesters ================== There are 2 Options Requesters roughly corresponding to the old Options 1 and Options 2 MenuItems. These allow you to set most of the environment used by ReSource. These options will be saved when you select "PROJECTS/Save Config". Note that in previous version of ReSource, all set option switches were _always_ saved by "PROJECTS/Save Config". This is no longer true. Only options selected that are different than the default settings will now be saved. This should generally make for a much smaller macro file. -----------------/----------------- The base register used in converting base-relative effective addresses, in the special functions menu, no longer always defaults to register A4. It will now be saved as set when "PROJECTS/Save Config" is selected. -----------------/----------------- One of the side effects of making ReSource Intuition-compatible is that the TitleBar takes much longer to render now than it used to. This had the effect of greatly slowing down functions, such as searches, that updated the TitleBar frequently. A new function was added to the OPTIONS 2 requester to cope with this problem. The function is called Delayed Refresh, and it has the effect of speeding up those functions that were slowed down by the TitleBar rendering. When "OPTIONS 2/Delayed Refresh" is set, the TitleBar will only be updated 2 times per second. If a message needs to be displayed, or the TitleBar needs to be refreshed for other reasons, it will be refreshed in any case. We think you will generally want this switch on, but may want to turn it off under special circumstances when you want to see all the offsets while ReSource is working. This switch defaults to OFF for purposes of backward compatibility. ***************************************************************************** * ---==== ABOUT SEARCHING ====--- * ***************************************************************************** In order to be as backwards compatible as possible and also be compatible with the new OS V2.0 pattern matching routines, several changes have been made in the way search strings work. In previous versions of ReSource, when you entered a search string through one of these functions: CURSOR/Normal search/Set search string CURSOR/Pattern search/Set search pattern CURSOR/Buffer search/Set search string ReSource set up both the normal and pattern search buffers for Normal, Pattern and Buffer searches. There was a great deal of confusion concerning the use of wildcards and which functions they were appropriate in. In order to clear up the confusion, there are now separate facilities for Normal and Pattern searches, and a separate set of rules for each one. RULE 1: For Normal searches, you are always entering literal strings. These are used for Normal and Buffer searches only. RULE 2: For Pattern searches, you are always entering pattern search strings. They are used in Pattern searches only. The following rules apply to pattern searches: + Literal token rules for all searches are now enforced. If you enter "(a0" as the search string, it will no longer be accepted. You must enter "'(a0". The tick tells the pattern matching routines that the parenthesis is to be treated as a literal character. + If you want to use "*" as a universal wildcard, the "wildstar" bit in dos library must be switched on. "StarBurst", a utility to set this bit, is included. + Note that ReSource will append a "#?" to the end of your search string automatically, so that you can find strings in the middle of a line. Don't add another "#?" or a "*" to the end of the search string. + You do not have to specify a pattern. If you specify a normal string, it will be treated literally in a Pattern search. See the AmigaDOS users manual for more information on pattern matching. -----------------/----------------- NOTE: The function for setting Pattern strings is new, and any macros that use the "Normal search/Set search string" function _and_ then call a Pattern search function will fail because the Pattern search string will _not_ be changed. Only the Normal search string will be entered for the "Normal search/Set search string" function, and only the Pattern search string will be entered for the "Pattern search/Set pattern string" function. The reverse is true as well: The "Pattern search/Set pattern string" function will not set the Normal search string. To fix this problem in existing macros, use the utility ShowMacros with output redirection to a file: ShowMacros >ram:temp.asm Put the resulting file in your text editor and search for: dc.w $0077 ; CURSOR/Normal search/Set search string When you find one, determine if the string being used includes a pattern and a Pattern search. If it uses a pattern, change the line to: dc.w $0677 ; CURSOR/Pattern search/Set pattern string If the search string does not include a pattern, change the search function to a Normal search function. I.E., if the search function was: dc.w $0078 ;CURSOR/Pattern search/Find next occurrence change it to: dc.w $01AA ;CURSOR/Normal search/Find next occurrence Reassemble the file according to the instructions in ShowMacros.doc, and install it as S:RS.macros or <progdir>/RS.macros. -----------------/----------------- NOTE: The NoCase option was only available for Buffer searches, and not for Normal or Pattern searches, in previous versions of ReSource. This may be a problem in old macros that relied on case sensitivity being set a particular way for buffer searches, but did not explicitly set it up. To fix this problem in existing macros, follow the directions above, and look for either of these lines: dc.w $0077 ; CURSOR/Normal search/Set search string dc.w $0677 ; CURSOR/Pattern search/Set pattern string Determine if the NoCase bit must be set before the search string is set, in each case. If it does, insert this line before the set string function: dc.w $0381 ; CURSOR/Search/Ignore case New macros will always explicitly set all non-default conditions shown in the Search Requester. -----------------/----------------- The way control characters in search strings are displayed has also been slightly changed, although this will not affect their use. Because you can't enter control characters into string gadgets in some cases, ReSource has allowed the use of escape strings, starting in V5. Previously, if you entered "\t" (or another escape string) in a string gadget, and later edited that gadget you would see a rectangle where the "\t" had been. This is because the font does not contain information for control characters. Now, when you enter escape sequences (or control characters, when possible) into a string gadget, if you later edit the string, you will see that the escape sequence is still there (or substituted for the control characters). ***************************************************************************** * ---==== ABOUT SYMBOL BASES ====--- * ***************************************************************************** All the Library, Device and Resource bases have been moved to "Lib Offsets". If you want "CoolCapture", for instance, select: Lib Offsets/Exec offsets/Exec offsets NOTE: The following symbol bases have been removed. Macros that used any of these symbol bases will fail. 111,Clist offsets 121,Cstrings offsets 315,Refresh modes - These are now, and in fact have always been, contained in the symbol base 335,Intuition/Intuition/Window flags Due to symbol name clashes with V37 and later includes, the following symbol bases have been removed. ARP Library offsets is still valid, however. 608,ARP/EnvLib 609,ARP/AnchorPath 610,ARP/Anchor 611,ARP/Wildcards 612,ARP/Directory Entry 614,ARP/DateTime 615,ARP/DefaultTracker 617,ARP/ProcessControlBlock 618,ARP/Process Memory 619,ARP/Resident List 620,ARP/ResidentProgNode 621,ARP/ResidentProgTag 622,ARP/Tracked Resources 623,ARP/TrackedItemTypes 625,ARP/ZombieMessage 657,Expansion Int 659,RomBoot Base 674,Rexxsyslib - These are now, and in fact have always been, contained in the symbol base 654,Lib Offsets/RexxSysLib offsets. NOTE: The following symbol bases have been changed or moved. Macros that used any of these symbol bases may fail. 300,Intuition/Preferences/Parity - Used to contain the 1.3 handshake bits also. Now only contains the parity bits. Handshake bits are in their own symbol base 1387,Handshake. 375,Trap Vectors is now found in Hardware/Traps/Trap Vectors. This file is not found in the include files, but we thought it might be useful. Note that 'AbsExecBase' is in this symbol base. 376,RawKey codes is now found in Devices/KeyMap/RawKey codes. This file is not found in the include files, but we thought it might be useful. 196,MouthReadBlock (MRB) 197,Narrator Driver IORB (NDI) 290,Narrator error codes - These files were removed from the V39 includes. The versions here will be found in Devices/Narrator, and come from the V37.4 Includes. 330,Translator error codes - These files were removed from the V39 includes. The versions here will be found in Libraries/Translator, and come from the V37.4 Includes. 1656,ScreenTypes - The symbols in this base are all the screen types (values < $10) that were previously part of Screenflags. The remaining screen flags are still in 318,Screenflags. ***************************************************************************** * ---==== ABOUT THE MINI-ASSEMBLER ====--- * ***************************************************************************** Included with ReSource Release 6 is a new Zap function "Zap2", found on the Special Functions menu. The new Zap function is designed to make modifying code easier by no longer requiring the user to laboriously look up instruction templates in a table to find the proper bit patterns to enter. This is accomplished by including a simple, one-line assembler in the new Zap function. When you call "Zap2", it tries to make an educated guess about whether it's looking at code or data, and if data, the appropriate size. It then puts the code/data into the string gadget, and waits for you to either edit the string, or change the mode/data type. If the Mode=CODE, the assembler will try to assemble the string. If the Mode=DATA, ReSource will attempt to convert the string to binary. Any problems will be reported, and you will be given a chance to edit the string, or abort the zap. In data mode, only as much of the binary data as defined by the Data Size gadgets will be written to the file. If you define the size as Byte and edit the string as "$12345678", only $78 will be written. If the Data Type is set to ASCII, the data will be copied literally to the string gadget buffer until a null is reached, for up to 127 bytes. If the data wasn't really text, this will be difficult to read. When the OK gadget is selected, the entire string, exactly as shown including 1 null byte, will be written back to the file. This implies that you may not use the ASCII Type to edit data that includes null bytes. All of the following comments refer to the new Zap function when used in the "Code" mode. Because this assembler has a slightly different kind of job to do than a normal assembler, and also because of previously existing limitations, there are a number of restrictions inherent in its use. If you find a problem when using the assembler, please refer to the following guidelines before submitting a bug report. 1. The assembler is designed to handle 68000-68030 CPUs, 68851 & 68030 MMUs, and 68881 & 68882 FPUs. It does not handle 68040 code. 2. The entire source input line may be up to 127 character in length. 3. Instructions may be entered as old or new syntax, except for '020 addressing modes, which do not have an old syntax. Thus: move.b MP_SIGBIT(a0),d0 movea.l SysBase,a6 and move.b (MP_SIGBIT,a0),d0 movea.l (SysBase),a6 are both acceptable. Please note that in some instances, old syntax may be unclear as to the actual intent. For example, in "SysBase.w" is the ".w" part of the symbol? We strongly recommend that you switch to new syntax. It really isn't difficult, and you will experience fewer problems with typographical errors in your code. 4. Do not include a label or a comment in the source input line. If a label and/or comment are present in the displayed line, they will not be disturbed. However, if the new instruction is longer than the existing instruction, the comment may no longer be visible. 5. When modifying an existing instruction, ReSource will warn you if the new instruction is of a different size than the existing instruction. You may then choose to replace the instruction, or abort. 6. If the instruction is unsized, the assembler will always choose the shortest addressing mode. For example: For absolute references ($1234) will always be assembled as ($1234).w ($1234).l will be assembled as ($1234).l For relative references bra *+$4A will always be assembled as bra.b bra.w *+$4A will be assembled as sized bra.l *+$4A4A4A4A will also be assembled as sized If the instruction is required to be a certain length, if used in a table for instance, then specify the size on the input line. Note that ".b" is a byte sized branch, ".w" is a word sized branch, and ".l" is a longword sized branch. ".s" was _never_ legal, even though many assemblers supported it. 7. Symbols and references to labels may be freely used in source input. However, due to the way parsing is done, a symbol or referenced label must start with one of the following characters: [a-z][A-Z]._ and must contain only these characters in the remainder of the symbol or referenced label: [a-z][A-Z]_[0-9]$ Please note that "." and ":" are not legal characters in this context, although they are legal in ReSource and many assemblers. The symbol or referenced label may be any length, within the constraint of Rule 2, above. 8. Opcodes and register names may be any case. Thus `nop', `NOP', and `NoP' are recognized as the same opcode. 9. The Operand follows the opcode field, separated by at least one whitespace character. The contents of the operand field(s) is interpreted by each instruction. In general, it may be a constant, symbol or an expression. 10. Constants are constructed as: 'ASCII characters' for example: 'A' = byte 'RQ' = word 'HELP' = longword $ followed by hexadecimal constant @ followed by octal constant % followed by binary constant digit 0-9 decimal constant 11. Expressions may consist of symbols, constants or the character '*' (denoting the current value of the program counter) joined together by one of the operators: +-*/%&|!^. The operators, except for !, are the same as in the C language. The entire expression is treated as one Operand field so no white space is permitted in the expression. Expression Operators + add - subtract * multiply / divide % remainder after division & bitwise and | or ! bitwise or ^ bitwise exclusive-or Special Expression Symbol * current value of PC Expressions are evaluated left to right and there is no provision for parenthesized expressions. Arithmetic is carried out in 32 bit signed twos-complement integer precision. 12. The assembler is not able, at present, to correctly parse values greater than a longword. Although you may enter instructions that take quadword, double, and extended operands, these will not be parsed correctly. Also, there are currently no provisions for entering floating point operands. In both these instances, we suggest that values be entered one longword at a time. 13. The simpleasm.library, which is required for assembly language input, will only be opened if the "Zap2" function is called, and then only if actual code is entered. 14. If simpleasm.library is not available, or can't be loaded, the "Zap2" requester may still be used for data, if preferred over the original "Zap", but not for assembly language input. There will be no warning message displayed if the library can't be opened. This is intentional so as to avoid your having to respond to multiple requesters if your system is low on memory. ***************************************************************************** * ---==== ABOUT FLOATING-POINT CODE ====--- * ***************************************************************************** Included with this version of ReSource is the ability to display floating- point numbers as real floating-point values. In addition, 4 new data types have been defined: Single, Double, Extended and Packed. 'Single' functions in much the same way as Long does currently, in that symbolic names may be assigned to values. Double, Extended and Packed data types behave in a slightly different manner than the other data types: The floating-point values may not be assigned symbolic names, and they may only be shown in their native format--that is, you may not change the number base. When referenced as data, the 4 new floating-point data types are disassembled in a similar manner to integer data. ReSource will attempt to set the data type to whatever size is appropriate to the instruction. However, in some circumstances, such as the one shown below, the data type may not be correctly set. If a floating-point number is displayed as integer data, you may explicitly set it to the correct data type. This may usually be inferred by the type of reference: lea (lbL000124,a5),a0 fmove.s (a0),fp0 lbL000124 dc.l $3F000000 implies that this data is a single (.s) and can be converted by selecting "DISPLAY/Set data type/Single". The instruction will then be shown as: lbS000124 dc.s 0.5 When floating-point numbers are converted into values, the following rules apply: 1. If the floating-point value is "not-a-number", it will be displayed as "NaN". 2. If the floating-point number is positive or negative infinity, it will be displayed as "Inf" or "-Inf". The above conventions comply with Motorola's document MC68881UM/AD. However, the resulting code won't reassemble correctly. For example, if you used "DISPLAY/Set data type/Double" on this data: lbL01362A dc.l $7FF00000 dc.l $00000000 you would get: lbL01362A dc.d Inf If you will need to see the numeric data later, so that you may reassemble the code, convert back to longwords. In the case of immediate data, the data type will be set for you: fmove.d #Inf,fp0 If you will need to reassemble the code in this case, the procedure will be slightly more complicated. Because ReSource sets the data type for you here, you will need to temporarily change the data type from CODE to LONG to be able to see the number value. If you have not changed the default key mapping, position the cursor line at the problem code. Press and hold Left-MouseButton, and then press and hold Left-Alt+Shift+Ctrl. This will temporarily display the binary data as LONGWORDS without changing the data type: dc.l $F23C5400 ;The instruction dc.l $7FF00000 ;The value of "Inf" dc.l 0 Then, either write down, or remember the values, and save them as a comment: fmove.d #Inf,fp0 ;$F23C5400,$7FF00000,$00000000 When you do reassemble the code, you will need to code the instruction by hand: dc.l $F23C5400,$7FF00000,$00000000 or find out why this value was being used, and do something slightly more intelligent. 3. All legal floating-point numbers will be converted with the precision of a Double data type. Note that some very large and very small Extended numbers are outside this range. In that case, Extended floating-point numbers will only be converted if they are within the range of a Double. Otherwise they will be shown as hex data. ;Denormalized extended number dc.x $00000000,$00000000,$FEDCBA98 Note that the resulting code won't reassemble correctly until the number is converted back to longs by using "DISPLAY/Set data type/Longs". 4. The fpsupport.library, which is required for converting floating-point numbers, will only be opened if there is a call for it to do conversions. If no FPU is available, or if the CPU is a 68040 and the software emulation code is unavailable, then the mathieeedoubbas.library will also be opened at this time. 5. If one of the following is true, then all floating-point numbers will be shown as hex data. No warning message will be displayed. This is intentional so as to avoid your having to respond to multiple requesters if your system is low on memory. a. fpsupport.library is not available, or can't be opened, or b. no FPU is available, or the CPU is a 68040 and the software emulation code is unavailable, and the mathieeedoubbas.library can't be opened ***************************************************************************** * ---==== MISCELLANEOUS NOTES ====--- * ***************************************************************************** 1. There is a new key function in Help. Alt-UpArrow has always allowed you to go to top of file. Alt-DownArrow now goes to bottom of file. 2. Icon ToolTypes LACEFLAG and NOLACEFLAG are actually in ReSource now, just like it says on page 3-4 of the manual. We wonder why no one ever complained about this... Additionally, there is a new option flag for Screen Mode requester. From the command line: > run ReSource <file> -R From Workbench there's a new tooltype: REQMODE=ON It is recommended that if you want a different screen mode than the one that the system is using, you use the new screen mode requester option rather than the old "lace" (-I) and "nolace" (-N) options. This is because some screen modes don't understand the concept of "lace", and other screen modes will not work if you specify "nolace" (it's required for some modes). Note well: ReSource will not be usable in all possible screen modes. Some screen modes are not compatible with other screen modes, on some monitors, using some versions of the graphics chips, and some versions of the OS. 3. The ReSource screen is now a Public Screen. The public names for the ReSource screen are: "ReSource" ;1st instance "ReSource N" ;More incarnations of ReSource, where N is a number ;equal to or greater than 2. Thus, the 3rd ReSource screen opened will be called "ReSource 3". Please note that the screen may not be properly refreshed if you drag a visitor window around on it while ReSource is busy. 4. When mouse-scrolling, the deflection from the starting point has always been the same for both interlaced and non-interlaced screens. This has made fine control of mouse-scrolling too difficult for interlaced screens. When using an interlaced screen, the deflection factors are now doubled. 5. There appears to be a misunderstanding in the case of using ReSource to disassemble ROM code. A number of users have reported that ReSource causes enforcer hits when a ROM image is saved to a .RS file, and that file is loaded into ReSource at a later time. The reason for this is that the origin is always saved along with a .RS file in order for all references to be resolved properly. When the .RS file is loaded at a later time, this may cause references to protected or even non-existant memory for various reasons. That said, here is one way of sidestepping the problem: Start ReSource Select "PROJECT/Dismble memory" <start> <end> Select "SAVE/Save binary image" to <name>.bin Select "PROJECT/Open binary file" <name>.bin -> File is now delocated. Don't do any work on the file -> until you reach this point. It will be wasted effort. Select "PROJECT/Save .RS/" to <name>.RS 6. When you select "*/Origin/Specify", the requester now contains either the previously specified origin (set automatically when you load a binary file), or the address of the executable buffer, if the origin was unset. 7. The file location displayed in the TitleBar will normally be the relative offset from the start of the file. If you have selected "DISPLAY/Cursor address/Absolute", the address of the executable buffer plus the current offset will then normally be displayed. Now, if the file origin has been previously set, by you or ReSource, the origin plus the current offset will be displayed. This change has no effect on the "STRINGS/Get/Cursor offset" function. 8. As of this writing, some floating-point instructions, and end-of-line comments do not line up properly on screen. This will be fixed in a future update. 9. We believe ReSource will now work with third party graphics boards. Unfortunately, we had no way of actually testing this during development. If you have a third party graphics board, and experience problems with the display, and you are in a position to help in this regard, please contact us as soon as possible. -----------------/----------------- To our valued customers: You program in assembly language, right down to the metal, and you want and need absolute accuracy and reliability. We realize this, and strive hard for perfection. However, you know from hard experience that with programs of this size and complexity, bugs do creep in. As you use ReSource, if you find that the program doesn't appear to work properly for any reason, please don't hesitate to contact us directly, rather than getting upset about the perceived poor quality of the software. We put a high priority on customer support, and want to make ReSource the best program of its kind available for any platform, at any price. The Puzzle Factory, Inc. P.O. Box 986 Veneta, OR 97487 Voice: (503) 935-3709 BBS: (503) 935-7883 V.32bis 24hr. Internet: jlavin@cie.uoregon.edu BIX: jblavin ***************************************************************************** * ---==== CREDITS ====--- * ***************************************************************************** Thanks to Roger Wharmby of Helios Software for the incredible blitter assisted scrolling code. We couldn't have added all the new, system compapible features and still kept a reasonable display speed without these routines. Thanks to Doug Sears of Snappy Software for the floating-point conversion routines that made fpsupport.library possible. Excellent job Doug! Thanks to Jim Cooper of The Software Distillery for much help with the single-line assembler, and many, many other things too numerous to list. Much thanks to all the beta testers who contributed greatly to the accuracy and stability of ReSource Release 6. We couldn't have done it without you! =eof=