----------------------------------------------------------------------------- S.I.M. System-Independent Monitor Version 1.72 Copyright © 1990/1991/1992 by Stefan Walter ALL RIGHTS RESERVED ----------------------------------------------------------------------------- The User Manual, refering to version 1.72 of S.I.M. WARNING ======= This version of SIM is not really official. It was released because some developers and programers have requested it and because it currently serves for debugging Amiga Mach. It is beta test ware and not complete by any means. A completely rewritten version is halveway finished and will be out soon. SIM will now work on all existing Amigas running with MC60000 or MC68020/30/40, on later with some limitations. It works now on both PAL and NTSC machines with OCS/ECS/AGA. This program is still shareware, only Amiga Mach developers and owners of NOG2 automatically become registered users. No warranty for functionality is given. CONTENTS ======== 1. Introduction -------------------- 1.1 Welcome to SIM 1.3 Disclaimer 1.2 About this Documentation 2. Getting used to SIM --------------------------- 2.1 What Is SIM? 2.2 Who Can Use It 2.3 Qualifications, Requirements and Limitations 2.4 The 68020+ Version 2.5 Configuring SIM 2.6 The SIM Program 3. Some words about... --------------------------- 3.1 The Display 3.2 Breakpoints 3.3 Trace 3.4 The Keyboard 3.5 Disk Access 3.6 Files 3.7 Breaking 3.8 The Actual Address 3.9 The matchbuffer 3.10 Command History 3.11 Traps 3.12 Function Keys 3.13 SIM and the Hardware 3.14 The Colors Red and Yellow 3.15 Printer Support 3.16 Memory Managing 3.17 Screen Blanker 3.18 Effective Address Calculation 3.19 Symbols 3.20 PAL/NTSC 3.21 Interrupt Lockup 4. Communication between YOU and SIM ----------------------------------------- 4.1 The SIM Environement 4.2 The Monitor 4.3 The Commands and their Syntax 4.4 The Debugger Window 4.5 Debugger Window Shortcuts 5. Additional Information ------------------------------ 5.1 Assembler Usage 5.2 Calculator Usage 5.3 Data Line 5.4 The Debug Server Entrance 5.5 The SIM Base 5.6 Errors 5.7 Footer Messages 6. Appendix ---------------- 6.1 Acknowledgements 6.2 Registered Users 6.3 Contacting Me ***************************************************************************** 1. Introduction ***************************************************************************** 1.1 Welcome to SIM ====================== Congratulations dear user. You have just obtained the third release of 'S.I.M.', a high performance monitor and debugger for the Commodore Amiga. 'S.I.M.' is a shareware product. This means that it can be used, copied and distributed freely, provided that: 1) No fee is charged for copying and distribution. 2) It is distributed ONLY in its original, unmodified state. 3) This document is copied along with the program. If you copied this program from somebody else and you like it and keep using it, you are asked to send a little contribution of 15 US$ to the author in order to get registered and to obtain support and the final version when it's finished. 1.2 Disclaimer ================== This program is provided "as is" without warranty of any kind. The entier risk of using it is to the user himself. In no event I (the author) will be liable for direct or indirect damage, loss of data or criminal actions done due to the use of this program. If you do not agree with this, you may not use SIM. 1.3 About this Documentation ================================ You should carefully skim this documentation if you are not used to SIM yet. SIM bases on a concept that especially programers lacking detailed knowledge of assembly language or C will first need to get used to. ***************************************************************************** 2. Getting used to SIM ***************************************************************************** 2.1 What Is SIM? ==================== SIM is a very powerful debugger and monitor. It was designed to work under all circumstances and especially to supervise rather unconventional programs which do not make much use of the operating system or do completely disable it for more or less long time. SIM works below the operating system and does not interact with any of its facilities or routines. It disposes of ways to enable you relatively comfortable debugging of any piece of machine language. Be it a task list manipulating routine, an interrupt or direct access on hardware like disk drives or the blitter, routines you can't monitor with an ordinary system based debugger. There are practically no limits. You can invoke SIM at any moment and it will pop up and work properly. SIM will do as less changes to the software and hardware (ram, custom/cia registers) as it can. When you exit SIM, it will try to leave everything the way it was when SIM was started. SIM does neiter use blitter nor copper, so any 'interrupted' program can continue to run with no defects due to a call to SIM, no matter when it was stopped. 2.2 Who Can Use It ====================== SIM was written to be used by both serious programers of nice and clean applications, who follow the guide lines of Commodore, as well as by the socalled 'democoders' who write programms which directly access the hardware and disable multitasking (and who lately have become deprived to do so by Commodore :). It was originally mainly intended for the later, but it has proven to be very useful for debugging applications too. It is distributed with the neccessary utilities to apply it on any kind of program that need to be debugged at a given time. They are not too comfortable yet, intuition based 'V36+ only' versions are planned. SIM will be very useful for you if you need to debug programs which temporarily disable multitasking. If you only need to debug 'ordinary' programs with no critical or nonmultitasking routines, you are better served with a full system debugger. There are plenty of good debuggers of that kind available, also in the Public Domain. 2.3 Qualifications, Requirements and Limitations ==================================================== To use SIM efficiently, detailed knowledge of the Amigas hardware, the 680x0 processors and assembly language is ABSOLUTELY neccessary. If you lack this knowledge, get Commodores 'Amiga Technical Reference Series' and Motorolas documentations of the 68000 family. SIM is completely independent of the OS the Amiga uses. There is a certain support for the normal OS, but no dependancy. SIM does several things by directly accessing the hardware, especially the part that deals with the display. This however is no longer allowed by Commodore and will probably cause SIM not to work on Amigas of the next generation(s). If an incompatibility occurs, an update will be released. You should not invoke SIM while doing any kind of timed access to hardware, i.e. serial transfer. Because SIM shuts down everything, data transfer will be interrupted. You should also not invoke SIM from within a level 2 interrupt before it has dealt with keyboard events or keystrokes will be lost. 2.4 The 68020+ Version ========================== The 68020+ version is only an 68000 version with the neccessary changes to get it working on better CPUs. Special features of these processors (additional exception vectors, instructions, registers, etc.) are not supported yet if not absolutely neccessary. There is currently no version working on 68010 Amigas because I have no access on any machine to try out any adaption to this CPU. If anybody out there feels she/he needs a version of SIM for 68010 and is willing to do some beta testing, I will write a 68010 version. The 68020+ version however works only with some limitations: - VBR must be at a known position. Default location $0, if vectorbase is not at 0, the real location must be stored in the base of SIM (offset 264). The tools supplied with SIM do this before they invoke SIM. - The 'v' command can only push stackframes back, not generate artificial ones. - The disassembler and assembler do not support any instructions added in the 68010+ processors, except Bcc.B/W/L and EXT.B. - MMU activities are not dealt with yet. SIM deactivates the MMU by default. You can activate the MMU again, SIM will then install a primitive bus error handler which prevents craches in case of a tree containing illegal descriptors. 2.5 Configuring SIM ======================= You can't use SIM right away, you need to configure a copy to your Amiga first, that is for the CPU and the memory configuration it uses. Therefore you have to use 'SIMConfig'. This program configurates SIM for your machine and your personal needs. The program is selfexplaining except when it comes to define the memory pages. Here you shall make no mistake or the copy generated will not work properly. First think about what must be viewable. That is: - All memory - Kickstart image Get all start- and end addresses and sort them from lowest to highest. If neccessary use some system information tool to get the start and end addresses of all your memory blocks. If you can merge pages then do so for same memory types. Do not define overlapping pages. Pages must also start and end at even addresses. The program 'SIMConfig' does not check for correctness of what you enter. If you define incorrect pages, SIM may crash later. In case you do not want any memory managing enter $1000000 as first page end address for the 68000 version, $80000000 for the 68020+ version. You can exit this program anytime by entering 'exit'. 2.6 The SIM Program ======================= SIM is not an executable (it has no hunkstructure, so you cannot simply start it from the CLI or workbench) but a simple PC-relative file that can be loaded somewhere into the memory or included in one of your own programs. SIM is a nonmultitasking debugger. When it is activated, Multitasking is immediately stopped, much like by Disable(). ***************************************************************************** 3. Some words about... ***************************************************************************** 3.1 The Display =================== The display creates some of the more tricky problems for SIM and you. 20480/$5000 bytes of graphic memory are needed for a 640*256 bitplane. But at a certain moment, there may be no 20480 bytes graphic memory available. The solution is the backup. When you have an area of $5000 free graphic memory that will stay free for sure (that means it is allocated with AllocMem() or will never be used), you simply set the display address to the start of that area and the backup address to zero (this means no backup). SIM will then concider these $5000 bytes its own and use it as display. When you enter SIM, the data in this area are then destroyed. In case there is not enough free graphic memory or it will be used entierly in near future and you have enough (that is $5000 bytes) unused other memory that won't be used for sure, you set the backup address to the start of a free $5000 bytes block of other memory and the display address just to somewhere in the graphic memory. When SIM is activated, It copies the content of the $5000 bytes display- to the backup memory and uses the display memory. When you leave SIM again, it copies the $5000 bytes back from the backup- to the display memory. That way, the graphic memory is unchanged. The memory manager claimed to be missing in earlier versions is now integrated in several functions. If you have defined a backup area the memory manager automatically fades it in at the location of the display. Because the interrupt vectors are used, you may not specify a display below $70 or above the end of the graphics memory minus $5000. Both the display- and the backup address are entered in the SIM basearea before starting SIM or set by the 's' command while working. NTSC users please note that although a 640*200 plane only uses 16000 bytes, you too need $5000 display memory because it is also used as MFM buffer for all disk operations. 3.2 Breakpoints =================== A breakpoint is basically a change in the program that is monitored which stops it and gives control to the debugger that set it. In other terms, you can run the program at full speed until it executes a certain instruction. This is a very important feature when you have to control the flow of a program. Therefore the breakpoint system of SIM is very sophisticated. SIM can handle three kinds of breakpoints: - ILLEGAL breakpoints - JSR breakpoints - STACK breakpoints Each kind is used for different problems and has its advantages and disadvantages. SIM is able to handle 16 different breakpoints at a time. When you enter SIM, it removes the breakpoints from the memory, so the memory looks like it would look with no breakpoints set. That enables you to change instructions that are at a breakpoint without first removing the breakpoint before changeing and putting it back afterwards. A critical situation occurs when the breakpoint is overwritten by a program (i.e. by a copyroutine). Such a breakpoint is in 'modified' state When SIM removes the breakpoints at entry, it checks if they are still there. Modified breakpoints are not removed and not restored, when you leave SIM again. If you want to have the modified breakpoint set again, you must first remove it (SIM simply frees the place in the breakpoint list but does not put the original opcode or words back). Then you can set it again. You cannot set breakpoints everywhere. SIM tests if there is ram at the location where you want to set a breakpoint. If there is none, this causes an error. SIM also prohibits to set breakpoints in the SIM codesegment. 1. ILLEGAL breakpoints ---------------------- Illegal breakpoints are normally the most used ones and offer the most possibilities. When you set an ILLEGAL breakpoint at a certain instruction, SIM replaces the opcode word of that instruction by the ILLEGAL opcode $4afc. When the ILLEGAL instruction is executed instead of the original instruction, an ILLEGAL INSTRUCTION exception happens. Therefore it is neccessary that the ILLEGAL INSTRUCTION vector somehow jumps to SIM, either directly, set by the 'w' command, or indirectly via the task traphandle, set by 'SIMBug' or another SIM-loader. If this is not so, your machine crashes. Illegal breakpoints have the advantage that they can be 'conditioned'. This means that this breakpoint only forces entry when one or one of several conditions are fullfilled. The following criterias can decide whether or not the breakpoint forces entry: - condition term: You can specify a term that is calculated each time when the program arrives at the breakpoint. When the result of the term is zero, the program continues, if it is nonzero, SIM is entered. You can use that feature to i.e. break a program at a certain point if a register contains a certain value. The use of SEA, TEA, SX and TX is allowed, but you must first toggle on EA calculation using the AMIGA-Z shortcut. - counter breakpoint: A counter breakpoint will enter SIM if the program has passed the breakpoint a certain number of times. This way you can i.e. break a subroutine after it was called a certain number of times. - button breakpoint: When the program arrives at a button breakpoint, SIM will look if the left or right mousebutton or the firebutton of a joystick in port 1 is pressed and enter SIM if one is pressed. You can specify what buttons are concidered. Button breakpoints can i.e. be set in a vertical blanking interrupt. every fiftieth/sixtieth of a second, SIM can check if you want to enter or not. Additionally you can make resident illegal breakpoints. A nonresident breakpoint will be removed after it caused entry. A resident breakpoint will stay active until it is removed. A resident breakpoint can be used in situations when you want to stop a program several times at the same address. SIMs breakpoint system enables to combine all these elements, to make resident breakpoinst that break at SEVERAL conditions. You can set a resident breakpoint at $70000 that either breaks when d3 is 3245 or the left or right mousebutton is pressed and that is limited to 1000 passes. The command line to set that breakpoint would look like that: 'b 70000 * ?d3=3245 lr 1000'. SIM uses the TRACE vector to skip a resident or conditioned breakpoint if it has not caused entry into SIM. This means that you must not only set the ILLEGAL INSTRUCTION vector but also the TRACE vector. This is neccessary as soon as you have set a conditioned or a resident breakpoint. 2. JSR breakpoints ------------------ The second type of breakpoint is a rather a 'heavy duty' one. When you set a JSR breakpoint, SIM remembers the 6 bytes at the breakpoint address and puts a JSR instruction there that jumps absolutely into SIM (i.e. 'JSR $c50726'). When the breakpoint is reached, the program jumps directly into SIM which then puts back the 6 bytes. This breakpoint has two advantages. The first is that you do not need any vectors to be set. The second is that a JSR breakpoint can be transfered. When you have an illegal breakpoint in a routine and that routine is transfered to another location and the breakpoint is reached in the copied routine, SIM will not know that that illegal is a breakpoint because it is not at any of the addresses at which a breakpoint was set, so it will not be replaced by the original opcode. JSR breakpoints are recognized at their entrance, because each of the 16 possible JSR breakpoints has another entrance. That way, SIM can recognize that breakpoint whereever it is. But be carefull, never enter SIM by these entrances on your own. You must also see to it that after the transfered breakpoint forced entry and was removed, the original one is NOT reached too. Because of these two advantages, you can use JSR breakpoints in delicate situations, where you are not sure if the vectors are not changed, i.e. in routines accessed by multiple tasks or places where the illegal vector or task traphandle is changed. A disadvantage of JSR breakpoints is that they use not one but three words. The minimum size for an instruction is a word, an illegal breakpoint can be set at any instruction because the instruction ILLEGAL uses one word. A JSR breakpoint may replace three instructions. Therefore you have to set the JSR breakpoint in a 'linearly' executed part of the program. Here are two examples where the JSR breakpoint is not set correctly. The breakpoint is always set at the label 'bkpt': 1. . . . bsr.s label ;this will cause problems! bkpt: bra.s label2 ;JSR opcode label: nop ;HIword of entrance nop ;LO word of entrance . . . 2. . . . bkpt: moveq #1,d0 ;JSR opcode label: moveq #0,d1 ;HI word of entrance rts ;LO word of entrance . . . moveq #-1,d0 bra.s label ;again in the middle... 3. Stack breakpoints -------------------- Contrarily to the illegal and JSR breakpoint, the Stack breakpoint is not a change in the program but a change on the stack. When SIM sets a Stack breakpoint, it replaces a returnaddress on the stack by the address of an entrance of SIM. When the appropriate rts, rtr or rte that would return to that address is reached, it returns to SIM instead. SIM sets the pc to the returnaddress and replaces the SIM entrance address on the stack (should now be at a7-4 for rts!) by the original address for security. For SIM, it does not differe, if the Stack breakpoint is set in the supervisor or userstack (in earlier versions it did, this is no longer so). Use this feature wisely! SIM cannot test if the Stack breakpoint you set is put in a stack and is taken off stack by a 'Return From ...' instruction. Its upon you to set Stack breakpoints at the right position. Stack breakpoints are also used by for the nextstep and the leave subroutine command. 3.3 Trace ============= Tracing is the second way of keeping a program under control. SIM can singlestep a program. Therefore you must see that the TRACE exception caused by that somehow ends up in SIM, either set it directly or set the tasktraphandle. It can also let a program run step by step and stop when one or several conditions are fullfilled, much like the illegal breakpoints: - condition term: You can specify a term that is calculated after each step. When the result of the term is zero, the trace continues, if it is nonzero, SIM is entered. You can use that feature to i.e. break a program as soon as a certain register is changed. The use of SEA, TEA, SX and TX is allowed, but you must first toggle on EA calculation using the AMIGA-Z shortcut. - counter trace: You can specify a maximum number of steps to do. When that amount of steps is done, SIM is entered. Counter trace is mostly use to just get back after a routine is done. - button trace: After each step, SIM will look if the left or right mousebutton or the firebutton of a joystick in port 1 is pressed and enter SIM if one is pressed. You can specify what buttons are concidered. Button trace can i.e. be used for stoping a program by hand at any moment. - trace breakpoint: You can define an address that is compared to the PC after each step. If the program has arrived at that address, SIM is entered. This feature is used when you cannot use breakpoints for some reasons. - 68020 emulation: This is also a condition. SIM is only entered when a change in the flow would happen, this means that the pc points on a BRA, JMP etc. SIM uses the trace flag to do single steps. What some people do not know is that you can trace over some instructions that may clear that flag. These are RTE MOVE to SR ORI #x,SR EORI #x,SR ANDI #x,SR Additionally you can enter the TRAP #x exception routines with the trace. Tracing has one weak spot: if you are tracing and an interrupt happens that somehow causes entry in SIM (i.e. by a breakpoint), SIM loses the control over the trace. When you exit SIM again and the interrupt ends, a TRACE exception happens. You must then start to trace again or clear the trace flag by hand. Some words about the speed: It is clear that the more conditions you allow, the slower the program runs. Additionally some conditions cause longer delays than others. Condition trace is slower than button trace because it has to call the calculator which is relatively complex and slow. 3.4 The Keyboard ==================== The most difficult problems are imposed by the keyboard. The Amigas keyboard hardware cannot tell you which keys are pressed at a certain moment, it reports only key changes. This makes it difficult for systemindependent programs. When you press a key under system and release it in a program that has its own keyboardhandler, the system will never know that you released that key, it will report repeats of that key all the time until you press another key. To prevent this, SIM will look that all keys are in the same state when you leave SIM as they were in when you entered SIM. When you leave SIM and a key is not in the same state, SIM will ask you to either press that key or to release it. Therefore, in the headline you will find the keys rawkey number and if in the keymap there is a printable character, that character too. You can only exit SIM if you press or release all keys that it wants you to. If you leave SIM by accident (hit wrong key?) and you are requested to press/release a key, you can do the following operation to return to the monitor: - Press another key that is not a qualifier (SHIFT etc.), not 'r', 'e', 't', 'u', 'n' or one that you must press to exit (esc is a good choice). - Release all other keys. - Type 'return'. - Release the keys you pressed for that operation. If you are tired to press keys again and again to exit, you can use the flush keystatefield shortcut. SIM will then clear the internal list of keys that were pressed when SIM was activated. The keyboard can store upto ten rawkeys on its own if the CPU has no time or need to get keyboard events. It is possible that several key hits are waiting to be replied. When SIM is activated then, it would recieve all those old keys that may invoke shortcuts or commands that are not desired. Similar problems occur when you link SIM in the CIA-A interrupt and it is invoked before the key is replied. The keyboardbuffer killer is used to reply to all possibly waiting keys and to flush the keyboard buffer. This feature can be toggled on or off and is off by default. 3.5 Disk Access =================== Because ram is a too transitory datacarier, SIM can read and write DOS-tracks and sectors. It does this by directly accessing the hardware. If you are using disk commands, make sure a disk is always inserted or the drive motor will be stoped after the command has completed although it was on. This is because SIM needs a disk to be inserted in a drive to find out if its motor is turning. When SIM is writing or reading, the display is used as buffer. You still see it, but it contains chaos. The top line is used to give you status information about the track that is operated or errors occured. When an error occures, you can either break with CTRL, retry with SHIFT or ignore the error with ALT (when file operation, ALT=CTRL). When a track is not correct, SIM tries to read it three times. Then it reports the error but displays also which sectors were okay. It is possible that only one sector is damaged, press SHIFT several times, SIM may find some sectors more that are okay and simply were after the damaged sector last time. SIM is tollerant concerning the integrity of the sectors. Checksums are calculated and SIM reports an error if one is wrong, but it decodes the sector anyway. This enables SIM to repair partially destroyed tracks. 5 1/4" and HD drives as used in the A4000 are not supported yet. 3.6 Files ============= You can load any files of an OFS DOS disk to memory. You can list the files and their length contained in any directory. And you can save any area of memory as a file on a disk. The file save system is quite sophisticated. It writes files in a way that they can be loaded and listed fast. Info- and extension blocks are located on track 79 and higher, data blocks from 79 down to 0 and from 159 to 79. Additionally, SIM will first look if a file fits the disk before it begins to save. The bad sideeffect of this is that saving takes some time. One thing you must remember is to be carefull with saving files when you work with the normal operating system afterwards. When you save a file, the bitmap on the disk is changed. The system keeps its own copy of the bitmap of a disk in memory. When it accesses that disk again, it possibly discovers a totally different bitmap. When it comes to the worst, the DOS crashes with the guru 07000007 (bitmap corrupt). To prevent this, you simply remove that disk from its drive and put it back again. The DOS then rereads the bitmap and everything's okay. 3.7 Breaking ================ In certain situations, it may be neccessary to break a command or to pause it. SIM can do both. You can break the dump commands, find and compare by shortly hitting CTRL. If you press it longer, SIM only pauses and continues when you release CTRL. When you press SHIFT-CTRL or additionaly hit the SHIFT key when you pause, SIM locks until you release, press and relese CTRL again. This enables you i.e. to make notes without holding CTRL all the time. While locked or paused, you can press the ALT key. When you release CTRL (if locked, press it first), SIM breaks th command execution also. This is used when you have paused and want to stop immediately. ALT-CTRL is used to break command execution in general. Before SIM looks for a new command in a command line, it tests for ALT-CTRL. If that's so, it breaks. This enables you to break a command line like 'P0:X' since you cannot break the 'P' and 'X' commands. An exception to this rules are the disk operation and the list directory command. These commands can only be broken. Therefore simply keep the CTRL key pressed. 3.8 The Actual Address ========================== The dump and edit commands share a default address variable that is used each time, you do not give a start address. This address has the name '@' for the calculator. It contains the end address of the last dump or edit command or it is set by find and compare. 3.9 The matchbuffer ======================= The matchbuffer is used to collect addresses. You can force the find and compare commands to send addresses to this buffer. You can also also specify under what conditions an address is put in the buffer or one that is already in buffer stays there. There are three possible conditions: - old: If an address that was already in buffer did not match with any reported by the find or compare command, it only stays in the buffer when you enable old ones. - match: If an address that is reported is already somewhere in the buffer, it stays only when you enable matches. - new: If an address is new, it is only put in the buffer when you enable new ones. You can combine the three conditions in any way (there are eight possible), some may make not much sence. This feature is mainly integrated to search for counters. To show the addresses in the buffer, the 'k' command is used. An example: You are searching for the address of a counter. You know that the counter is currently 10: 1. Define matchbuffer, i.e. 'k c00000 c10000' 2. Search for 10, i.e. 'f 0 20000 !n 0a' 3. Exit, perform any neccessary operation to change the counter to another known value, i.e. 15 4. Search for 15, i.e. 'f 0 20000 !m 0f' 5. List addresse(s) in matchbuffer, i.e. 'k 0' if more than one address stays in the buffer, go to step 3 and search again until one address stays. 3.10 Command History ======================= SIM remembers the last commands executed in the monitor. 128 bytes are reserved for that. These 128 bytes contain the last command lines. If you get an old command line back by the command history shortcuts and execute it, it is not remembered as the newest executed command. 3.11 Traps ============= The traps are one of the major connections between SIM to the outer world. They are used for breakpoints and to handle crashes. You can set the ten basic exception vectors directly. When you enter SIM, it puts back the original vectors, so you can edit them. When exited, SIM sets the set traps again. Problems occur when the program that is debugged sets the traps itself. When the program changes a vector previously set by SIM, this is handled the same way as it is done with changed breakpoints. Additionally you can force SIM to set traps again if they are modified by toggeling 'Auto Unmodify Traps' on. If traps set by SIM are changed, the display color of SIM turns yellow in order to inform you of this. While working under operating system, it is not recomended to set the exception vectors directly to SIM, except if it becomes neccessary due to breakpoints in library vectors or other places where multiple tasks access. 3.12 Function Keys ===================== The ten function keys can be loaded with a text or command line. If you define a text, it is copied at the location of the cursor when you press the function key. If you define a command line, it is executed directly. The ten function keys are partially allready defined in the original SIM version. These are the definitions: F1: z@ For easy tracing. F2: u@ " " F3: i@ " " F4: f@ For repeated finding. F5: c@ For repeated comparing. F8: v:X@ When an exception vector is set and an exception of that kind happens and has to be dealt with by the original vector. F9: dm0 m0@ For finding disassembly without using the debugger window. Initially deselected: F10: r:dpc pc@ For tracing without using the debugger window. Initially deselected. 3.13 SIM and the Hardware ============================ SIM does only use a very limited part of the hardware registers, the ones that are indispensable or must be set on fix values to provide security. Some of these registers can be read, some not. The values of the readable ones are remembered in a special part of SIM called 'SIM base' when SIM is activated. The SIM base is located, as its name says, at the start of SIM. In chapter 6.1 you find the structure of the base. These are the registers that are read out and stored in the base at entry. When you exit SIM, it copies the remembered values back: DMACON INTENA INTREQ *) CIA-A: CRA CIA-A: CRB CIA-B: CRA CIA-B: CRB CIA-A: PRA write buffer CIA-A: PRB write buffer CIA-A: DDRA CIA-A: DDRB CIA-B: DDRA CIA-A: SR write buffer VPOS **) *) This register is handled in a special way. While SIM is active, it leaves the disk-DMA switched on. If it wouldn't, this would possibly destroy your disks. Since the disk-DMA is left on, remember that when the disk-DMA is terminated, bit 1 in the INTREQ is set. This may happen during SIM is active because the DMA was still transfering when the INTREQ was read. Therefore you will find only the interrupt requests in the backup that were waiting when SIM was activated. If you want to know about the actual contents, you must read out INTREQ using the calculator command '?[$dff09c].w'. When you exit and didn't edit the INTREQ backup, SIM does not restore the bits EXTER, DSKSYN, RBF, AUDX, DSKBLK and TBE from the backup. If you edited the backup, the bits that are changed are restored , even if they contain some of the bits named above. **) This value is not written back. SIM rather waits for the rasterbeam to be aproximately at that position that it was on when the register was read. The register is read at a late point of time when SIM is activated, quite some instructions have been executed then, so it is not very precise. hopefully this can be improved. All these registers are used by SIM when working. If you have to know what vaule was in one of those, you have to look in the SIM base where SIM remembered them. If you need to change one of them, you must change the value stored in the base. As quoted, some of the custom register contain information that is lost because SIM cannot read from these registers. For the more important ones, SIM disposes of an editable list of 'reentry' values which are put back when SIM exits. Those registers are: DIWSTRT DIWSTOP DDFSTRT DDFSTOP BPLCON0 BPLCON1 BPLMOD1 COLOR00 COLOR01 BEAMCON0*) *) The BEAMCON0 register is only accessed under ECS or AGA. Unter OS, this register is only updated at calls to LoadView(), not in the copperlist. You may need to concider that if you are using an advanced resolution (i.e. VGA) on your Workbench screen and don't access SIM via SIMBug or PostSIM which both update the BEAMCON0 reentry value to the value used by the OS. These registers all concern the display. In most cases, they are reset anyway by a copperlist. If not, you have to look in the program where it sets them for the initial value and enter it in the base or decide on your own what value to use. Some of the registers are modified but do not have a reentry value, because they are either too temporary (DSKPTX for example) or completely unimportant (BPL1PTX). If it becomes neccessary, you can edit some with the 'e' command: CLXDAT DSKBTR *) DSKPTX *) DSKLEN *) DSKSYNC *) BPL1PTX BPL1DAT SPRXDATA/B CIAA: ICR state and mask *) These registers are only used and changed when you read or write from or to disk. If AGA is present, SIM also writes directly to some undocumented registers to build up its display: $DFF106: $0c40 $DFF1E4: $0000 $DFF1FC: $0000 3.14 The Colors Red and Yellow ================================= When you start to use SIM quite often and in critical situations, it may happen that the text color of SIM, which normally is green, turns red. This means that the SIM code has been partially changed. SIM calculates a checksum over its main code segment and looks if it is the same each time. If not, it changes the color to red. When the color is red you must be rather carefull. SIM seems to run well but it may crash when you execute a certain command or do something else. If you can, load a new copy and don't keep using the destroyed one. A yellow text color means that one or more of the traps set have been modified and overwritten. In that case you should either reset the vectors that have been changed or remove then. 3.15 Printer Support ======================= SIM allows you to send all output on the monitor to the printer. Therefore it simply sends the text as ASCII codes to the parallel port. This should allow you to use practically any parallel printer. If you want to send ESC codes (to select NLQ, reset etc.), you can do this by entering CTRL-[ and the rest of the ESC code as a command and press return. Remember to use the printer specific codes and not the AMIGA specific ones. Printer support does not work quite right with laser printers and certain other non-matrix printers which need a FF before printing or which demand both LF and CR. 3.16 Memory Managing ======================= SIM now disposes of the memory manager that was missing in v1.51. It controls memory access by certain commands and forbids read and write accesses to addresses where no memory is located: - It fades in the backup of the display at the location of the display. If there is no backup the display is zeroed. - At VBR+$68 and VBR+$6c it inserts the level 2 and level 3 interrupt vectors. - It handles five pages of memory that can be read and written to. Other areas are zeroed. The memory manager is currently not supported by all functions. Only the 'm', 'a', 'd', 'p' and 'l' commands (and the corresponding debugger window output forms), 'c', 't', 'o', 'P', 'H', 'L', 'S', 'e', 'n' and 'q' commands use it, the rest still doesn't. 3.17 Screen Blanker ====================== When you do not press any key during 10 minutes and SIM is not doing any operation, it automatically darkens the monitor. To continue to work, press any key, best would be a qualifier. 3.18 Effective Address Calculation ===================================== SIM can calculate effective addresses. The source EA of the command at the PC is displayed below A6 of the small register list, the destination EA below A7. In the large register list, the last line contains a 6 byte hexdump of both the asource and destination EA. EAs can be used in calculator terms. The source EA is named 'SEA', the destination EA is 'TEA'. For both exists also a register 'SX' and 'TX' which is 0 if the corresponding EA is not used by the instruction at the PC, and 1 if it is used. 3.19 Symbols =============== SIM now supports a symbol list generated by an external program. The symbols can't be edited yet or new ones added. Symbols are used in the calculator and the disassembler. The shortcut AMIGA-SHIFT-d toggles use of the symbols. 3.20 PAL/NTSC ================ When SIM is invoked on any PAL/NTSC machine for the first time, it adapts its display to the machine type. If ECS (or AGA) chipset is available, you are allowed to toggle between PAL/NTSC. NTSC users also can use an NTSC overscan display with 28 lines. The shortcuts used to toggle is is AMIGA-L. 3.21 Interrupt Lockup ======================== SIM uses the VB interrupt for its display setup and the PORTS interrupt to handle the keyboard. The concept of the Amiga allows external devices connected to the expansion port or the Zorro bus to generate interrupts. Most harddisk controlers use this feature and generate Level 2 and 3 interrupts. The basic problem for SIM is that if such a device generates an interrupt, it does not neccessarily clear the request by clearing a bit in the INTREQ register. Many devices have their own interrupt request register, located somewhere in the Zorro address space. Only the interrupt handler that is installed when the device is mounted knows about the address of that register. Therefore SIM cannot cancel such an interrupt and the result would be that the machine either locks up or that the device fails. To prevent this, SIM will detect if a level 2 or 3 interrupt was generated by an external device. If it is, SIM will automatically exit, execute the interrupt routine for the pending interrupt and return through the JSR entrance. ***************************************************************************** 4. Communication between YOU and SIM ***************************************************************************** 4.1 The SIM Environement ============================ SIM provides a display of 200|224|256*640 pixels or 25|28|32 lines and 80 rows, depending on the resolution you use. The screens colors are green and dark blue. The screen is devided in header, worktable/debugger window and footer, all separated by a bar of '­' chars. The header normally contains the title and copyright notice but serves also as statusline when accessing disk and at keyboard cleanup. The worktable and the debugger window share 21|24|28 lines. In the worktable, actually the monitor, you can move the cursor around and enter commands. Output of commands is also displayed in this part. The debugger window shows you one or two views of the memory in different forms at different addresses, read more about that feature in the appropriate chapter. The contents of the part of the worktable covered by the debugger window is remembered and restored if the window is removed. The footer contains the cause of SIM's entry, a status and result field and the addresses of SIM itself, the display- and backup address. 4.2 The Monitor =================== On the worktable, several basic features are provided: - What you see on the monitor (the text) is stored in SIM when you leave. it is available again if you enter SIM again, the display will be the same. - SIM has two entier keymaps for not qualified, shifted, alternated and shifted+alternated keys, one one custom and one USA. - CTRL-keys with assigned chars with ascii values from $40-$5f will result in a char with the ascii value from $0-$1f (i.e. CTRL-J (=$4a) => (=$a)) - CTRL-keys with assigned chars with ascii values from $60-$7f will result in a char with the ascii value from $0-$1f. - Cursor keys move the cursor by one step. - SHIFT-Cursors key moves the cursor in the extreme positions. - DEL will delete the char above the cursor and shift all chars right of the cursor one row left, inserting a space at row 79. - BACKSPACE will clear the char left of the cursor and shift all chars above and right of the cursor one row left. - SHIFT-DEL will insert a space at the cursor position and shift all chars above and right of the cursor one row right. - SHIFT-BACKSPACE will clear the char above the cursor move the cursor one row left. - ALT-DEL will clear the visible worktable and put the cursor in the left upper corner next to a period. - ALT-BACKSPACE will clear the line in which the cursor is, put a '.' in row 1 and the cursor in row 2. - HELP prints the first help page, starting in the line below the line the cursor is in actually. - SHIFT-HELP prints the second help page. - F1 to F10 either execute the command line stored or print the text stored. - SHIFT-ESC copies the last executed command in the line of the cursor. - ALT-ESC copies the line of the cursor in the command buffer. It can then be inserted anywhere with SHIFT-ESC. - CR will execute the commands in the line where the cursor is. - ALT-CURSOR UP goes one step back in command history and fill the actual line with the actual command in history. - ALT-CURSOR DOWN goes one step forth in command history. 4.3 The Commands and their Syntax ===================================== The command line contains the different commands to be executed. Its form is as follows: . (: ...) You can enter several commands in one line, separated by a colon. The colon is needed, except if the next char is the same as of the last executed command (i.e. 'mmmm' is allowed and shows $200 bytes at once, starting at the actual address). While working with SIM, you can get a little list of all commands with the two help pages by pressing HELP or SHIFT-HELP: n (s)(i) :assemble | t [s][e][t] :transfer mem | A (s) :set viewstart e (s)(d) :edit mem | o [s][e][d] :occupy mem | w (x) :CPU traps d (s)(e) :disassemble | c (s)(e)(t) :compare mem | v :recreate trap a (s)(e) :show ascii | f (sejd)(m) :find data | h (n) :history m (s)(e) :show hex | f (sej'i'i) :find disasm | g [s] :go sub l (s)(e) :show copper | s (p)(b)(c) :set SIM-adrs | i (n) :leave out p (s)(e) :show text | F (n)(c){@} :edit F-keys | u :next step k (s)(e) :matchbuffer | z (n*n?cb) :trace steps | r (rs):edit regs P (s)(m) :show plane | b (s)(*n?b) :breakpoints | q/Q :quit prog ? (expr) :calculate | T (expr){@} :set linkterm | x/X :exit and go >f(n) :format disk | s [s][s](n) :write secs D?(n) :find head | t [s][t](n) :write tracks K [s] :blockchksum | L [fs](n)(s):load file V (path) :directory | S [f][s][e] :save file R [s] :set range | H [s][e](p) :hear memory In the help page and the explanations, the following shortenings are used for options: s: start address|seek value e: end address i: assembly instructions d: data line n: decimal number x: hexadecimal number r: register p: plane address ?: condition term f: file name t: destination address|track number c: text|command line m: mask|modulo b: backup/breakmode/block j: options|flags Options in '[]' are neccessary. Options in '()' are optional. Chars in '{}' are optional flags. Because space in SIM is limited, these help pages tell only the basic syntax of a command. In the rest of this chapter all commands with all their possibilities and what you can do with them are listed. Dump Commands ------------- m (s)(e) Print memory as hexdump a (s)(e) Print memory as asciidump d (s)(e) Disassemble memory l (s)(e) Disassemble memory as copperlist p (s)(e) Print memory as text Dump commands have all the same options, only the output form changes: command (start address) (end address) If you give both addresses, SIM starts to dump from the start address and stops when the end address is reached or passed over. If you give only the start address, SIM starts to dump from that address and displays eight lines. If you do not give any address, SIM takes the actual address as start address and displays eight lines. Adress spaces which are not defined are read zero. In disassembly, the instructions BSR,JSR and TRAP #x are indented and after the instructions JMP, BRA, ILLEGAL, RTS, RTE, RTR and RESET a separating line of '-' is printed. Additionally, resident breakpoints are marked by an asterix, JSR breakpoints with a plus sign amd normal breakoints with a cross. EXAMPLES: m 0 100 a 100 d l 51236 !+60 p $25364 Edit Commands ------------- e (s)(d) Edit memory n (s)(n) Assemle You can modify the memory with these two commands. They both ignore the memory manager and write directly to memory. The edit command can write data to memory (see chapter 'Data Line' for details) The assemle command can assemble one or several instructions separated by a ',' to memory (see chapter 'Assembler Usage' for info) If you give both start address and data/instructions, SIM writes the data/instructions to memory. If you only give the start address, SIM will start to assemble or edit in a continuous mode where it always prepares the next line for further data or instructions. To stop this simply give no instruction or data. The system is as clever as it recognices if in the line it prepares for a new data or assemble line, there is already a data or assembly line that was prepared for continuous mode. If that is so, it only updates the address but does not clear the line. That enables you to i.e. correct a program assembled in continuous mode and to insert instructions. If you do not give any option, SIM starts to edit/assemble in continuous mode at the actual address. EXAMPLES: e 70000 e>00070000: 0121 e>00070000: n 100 nop Transfer and Occupy ------------------- t (s)(e)(t) Transfer memory o (s)(e)(d) Occupy memory Transfer: This command simply copies a part of the memory to another location smartly. This means that SIM uses as- or descending mode for copying. Memory managing is used, undefined memory is read zero and not written to. t [s][e][t] Transfers memory from s to e to new address t. Occupy: The 'o' command will fill a defined area of memory with a byte pattern. o [s][e][d] Occupy memory from s to e with data d. EXAMPLES: t 0 10000 00c00000 o 12564 !+60 nnop Find and Compare ---------------- f (s)(e)(j)(d)(m) Find data f (s)(e)(j) i (i) Find disassembly c (s)(e)(t)(j) Compare memory k {@}(s)(e) Show/set matchbuffer SIM disposes of sophisticated data search and compare commands. For any of the find or compare commands you can specify the following options after the end address: - +/-n Sets the step rate. Only at every nth address is the data are compared. - '*' Specifies that addresses where nothing was found or two bytes are the same are reported. - '@' When you do not want a list of addresses but to have them reported one by one, set this options. SIM will then execute F9 each time something is reported and put the start of the active view of the debugger window to that address. - '!' If you want to collect and filter addresses with the matchbuffer, set this flag. After the '!', an 'o' specifies that old ones stay, a 'm' that same addresses stay, or a 'n' that new ones stay. Combinations are allowed. Find data: You can search in a defined area in the memory for a certain byte pattern with this command. Depending of how many options you enter, the command does different things: f [s][e](j)[d][m] Starts to find from s to e with the options j for the byte pattern d that is masked by the mask m. Only the bits that are set in m are concidered when comparing. If the mask is shorter than the data, the rest of the mask will be set to $ff. f [s][e](j)[d] Starts to search for data with all bits set in the mask. f [s][e](j) Starts to find for the same data with the same mask as last time in the area from s to e with new options j. f [s][e] Searches again in the area from s to e. f [s] Starts to search from s. f Continues to search after the last address reported. Find disassembly: This command searches an instruction or a fragment of it in a defined area of the memory. Like the 'find data' command, 'find disassembly' does not need all options: f [s][e](j) i [i] Starts to find from s to e with options j for the instruction i. f [s][e](j) Starts to find for the same instruction in the area from s to e with new options j. f [s][e] Searches again in the area from s to e. f [s] Starts to search from s. f Continues to search after the last address reported. The instruction i can be only a fragment like '4(a6)' or '@su*' or an entier instruction like 'moveq #3,d0'. Because the disassembler calculates the addresses of PC relative addressing modes, this command can also be used to track down accesses to addresses. Several rules must be concidered when designing the search text: - If there is a space in your text, SIM will concider what is before the space to be the mnemonic. Because the disassembler leaves an eight chars large field for the mnemonic where the rest is filled with spaces, SIM does tabulate your entries. 'clr.l d0' will internally made to 'clr.l d0'. - The char '*' is used as wildcard. It replaces one char. I.e. '(a*)' searches for all indirect accesses with any address register. - The char '_' is replaced by a space. I.e. '_d0' searches for all accesses on d0 as source ea. - The char '@' at the start or the end of your fragment limits the search on the start or end of the fragment. I.e. '@st' finds only 'st.b d0' but not 'tst.l d3'. Compare: This command will compare two areas of memory and report addresses where bytes differe or are the same: c [s][e][t](j) Compares area from s to e with area t to (t+(e-s)) with options j. c [s][e][t] Compares with no options. c [s][t] Continues to compare from s and t. c [s] Compares from s. c : Continues to compare after last address reported. Matchbuffer: This command allows you to manipulate and view the matchbuffer. Refere to the chapter 'The Matchbuffer' for further information. k [s][e] Locates the matchbuffer from s to e and clears it. k * Clears matchbuffer. k ? Shows the location and number of entries. k @ [s] Shows all matchbuffer entries larger than s by reporting them one by one using F9 and the debugger windows active view. k [s] Lists all entries higher than s k Lists or shows next entries. EXAMPLES: f 0 100 00 f 10000 20000 !nm 05 f 0 20000 @ imoveq #* c 0 100 200 * k 100 k@ 0 Processor Commands ------------------ r (r)(x) Set/view registers w (x) Set/view traps v (x) Create trap Registers: The 'r' command is used to either set a register d0-d7, a0-a7, ssp, usp, pc, sr, m0-m7 and isp/msp or vbr (68020+ only) or to view them: r [r][x] Sets register r vith new value x. r Views registers. r? Views memories m0-m7. Traps: The 'w' command is used to either set or clear the ten basic CPU exception vectors or to view their status: w [x] Sets or clears vector x. w Lists status of all ten vectors. wk Clears all traps. You can set or clear several vectors at a time by separating the vector numbers by kommas. The vector numbers correspond to the exception numbers, 2 for bus error upto $b for linef. Refere to the chapter 'Traps' for further information. Create Traps: The 'v' command is used to simulate the occurence of an exception or to remove one from the stack: v [x] Simulates exception x. v [-x] Removes exception x from stack. v Simulates occurence exception that forced entry. v? Gives information about the trap that forced entry. SIM can simulate exceptions 2 upto $40. When you simulate an address or bus error, SIM takes either the ssw, ir and aa from the last bus or address error or zero for all when none happened yet. When you simulate an exception 2 upto $b, which is set by the 'w' command, SIM takes the old vector as new pc. When you simulate an interrupt, the sr will also contain the interrupt level. The 'v' command without options is used to put an exception back on the stack when i.e. you want the old vector to handle the problem. This works only if SIM was entered due to an exception. You can only remove traps from the stack when you are in supervisor mode. The vector number is only used to know how much has to be taken from the stack (14 bytes when 2 or 3, 6 for the rest). The 'v?' command is used to know more about the exception, especially address and bus errors. In the 68020+ version, the 'v' command can only be called without options and puts the old stackframe back. EXAMPLES: r pc pc+20 r m7 d0 r? w 4,9 wk v 3 v -3 v? Breakpoint and Trace -------------------- b (s)(j) Set/clear and view breakpoints u next step z (j) trace step i (n) leave out instructions Breakpoints: The 'b' command is used to handle breakpoints. When you set an illegal breakpoint, you can specify the trigger conditions after the address. The following conditions are accepted: - 'l', 'r', 'j' Breaks when left, right or joystick button pressed. - [n] Breaks after breakpoint is reached n times. - '?'[n] Breaks when term n is true (<>0). - * Breakpoint is resident. Refere to the chapter 'Breakpoints' for more information. b [s][j] Sets a breakpoint at address s with the options j. b [s] Sets a simple breakpoint at s or clears one. b Lists all breakpoints. bj [s] Sets a JSR breakpoint at s. bs [s] Sets a STACK breakpoint at s. bk Kills all breakpoints. You can set or remove several breakpoints at a time by separating the next address from the previous address or options by a komma. Trace Step: The 'z' command executes trace steps. It either stops after one step or when a certain condition is fullfilled: - 'l', 'r' or 'j' Traces until button pressed. - [n] Traces n steps. - '?' [n] Traces until term n is true (<>0). - '*' [s] Traces until pc=s. - 'c' Emulates 68020 trace steps. Refere to the chapter 'Trace' for more information. z [j] Traces until a condition j is fullfilled. z Does one trace step. Next Step: The 'u' command does either one trace step or when the instruction at the PC is a JSR, BSR or TRAP #x, it does a trace step and then sets a stack breakpoint at a7 (or a7+2 when the instruction was TRAP #x) and exits: u Do one step. Leave Out Instruction: This command simply sets the PC one or n instructions further: i [n] Leaves out n instructions. i Leaves out one instruction. EXAMPLES: b 100 *j100 ?[4]<>$c00276 bj 100,200 bssp z *pc z j n i 2 Flow ---- x Exit X Exit directly q Quit Q Quit directly g [s] Go to subroutine h (n) History Exit: The 'x' or 'X' commands are used to simply continue the program at full speed. 'x' asks first if you are sure, reply with 'y' or 'n'. 'X' simply exits: x Exits, but asks for confirmation first. X Exits directly. Quit: The 'q' or 'Q' commands are used to return control over the program to the debug server. 'q' asks first if you are sure, 'Q' simply returs directly: q Quits, but asks for confirmation first. Q Quits directly. Note the difference between the exit and the quit command. The exit command lets the program continue. The quit command calls the debug server and lets it deal with the situation. The program is not continued. Refere to the chapter 'The Debug Server Entrance' for more information. Go Subroutine: The 'g' command is used to execute a little subroutine from within SIM: g [s] Call subroutine at s. gw [s] Prepare stack for subroutine call but do not exit. When SIM calls a subroutine, it first pushes the old pc on the stack and then the return address for the rts. If the subroutine completes with a RTS instruction, SIM is invoked again. The 'gw' command does only prepare the stack for the operation, that is it pushes the return address and the old PC value on the stack, but does not exit yet. This is i.e. used to trace a subroutine. History: SIM remembers the last five sets of registers as they were when SIM was left for the last five times. The list is also updated after each step when doing conditioned trace and each time a conditioned breakpoint is reached: h [n] Display nth last history. h Display all five history entries. SIM does not only remember the registers d0-a6, usp, ssp (isp/msp), sr and pc but also the instruction at the pc because of selfmodifying code. EXAMPLES: h 3 X q g 100 gw 200 Diskoperations -------------- D (n) Set drive for disk operations t (s)(s)(n) Write tracks s (s)(s)(n) Write sector >f (n) Format disk B (s) Calculate bootblock checksum K (s) Calculate block checksum Set Drive: The 'D' command is used to set the drive number that is used for further diskoperations (tracks, sectors or format, but not for file operations!) or to ask for the actually used drive or to ask for the position of the head of a drive: D [n] Uses drive n (0-3) as actual drive. D Shows actual drive. D? [n] Finds position of head of drive n. D? Finds position of head of actual drive. The headposition is reported as logical track, the sideselect bit will be concidered when calculating the position. In most cases (DOS included) the sideselect bit will be set directly before DMA access and put to an undefined state afterwards. If that is so when you use this command, you must find the side that is used on your own. Read Track: The 't' command writes an area of the memory as logical tracks on disk: >t [s][t][n] Writes n tracks starting with t, data start at s. >t [s][t] Writes one track t, data start at s. This command does not support memory managing yet. Read Sector: With the 's' command you can write single sectors from disk to memory: f' command is used to format and initialize a disk with OFS: >f [n] Formats disk in drive n. >f Formats disk in actual drive. You can't yet enter a name for the disk, it will automatically be 'DATA-DISK'. The creation date is zeroed too. AmigaDOS cannot separate disks with the same name and same date. So never keep two datadisks in two drives simultaneously, or DOS will get into troubble. If you format a disk that was previously in a drive and you return to DOS, remove and reinsert that disk for DOS must know the new name and new bitmap. Bootchecksum: When you want to save a bootblock to a disk, you may have to update the checksum with this command: B [s] Sets new checksum of bootblock that starts at s. Blockchecksum: When you want to save an edited datablock on a disk, you may have to update the checksum with this command: K [s] Sets new checksum of block that starts at s. EXAMPLES: t c00000 0 80 >s 70000 0 2 f 0 B 60000 K 70000 Fileoperations -------------- L [f][s](n)(s) Load file S [f][s][e] Save file V (path) List directory Paths and filenames can either be given plainly or between ' or ". The only devices known are DF0:, DF1:, DF2: and DF3:, disknames are not supported. Refere to chapter 'Files' for more information. Load File: This command loads a file directly into memory: L [f][s] Loads file f to s. L [f][s](n) Loads n bytes from file f to s. L [f][s](n)(o) Loads n bytes from file f to s, o bytes from the start of the file. Memory managing is supported. You still should not load data over SIM. Save File: With this command you can save an area of memory as file to disk: S [f][s][e] Saves memory from s to e as file f This command is also used to delete files. To do so simply save a file with the name of the file you want to delete and the same start- and end address (filelength=0). Memory managing is supported. List Directory: This command is used to list the directory of the root directory of a disk or a user directory: V [path] Lists directory of directory specified by path. V Lists directory of drive used last. SIM reads the directory page by page because the display is used as buffer. If a page is full or the directory is read, it displays it. If there is more to be displayed, SIM writes 'more' in the footer. You can continue and view the next part by pressing . EXAMPLES: L 'df0:c/dir' 60000 S df1:data 0 100 V df0:c Miscellaneous ------------- ? [n]{,}(n) Calculate F (n)(c){@} Define function keys P (s)(m) Start graphic searcher H [s][e](p) Hear sound s (p)(b)(c) Set display, backup and program addresses l* Show copperlist l? (s)(e) Find active copperlist l= [n] Find copperlist one or two R [s] Set range for access scan Calculate: If you need to calculate something, you can do it with the '?' command. SIM will calculate the result of one or several terms and return the result(s) as hexadecimal, signed hexadecimal, decimal and binary number and as ascii chars: ? [n] Calculate result of n. You can calculate the result of several terms at the same time by separating the terms by a komma. Function Keys: The 'F' command is used to set and view the function key definitions: F [n][c] @ Defines key n with command line c that is executed directly. F [n][c] Occupies key n with text c. F [n] Clears key n. F Lists key definitions. When you set a function key, the entier rest of the command line will be taken for the command or text. When you list the function keys, the ones that are locked by Amiga-Fx are marked by an asterix, the directly executables have an '@' at the end. Graphic Searcher: The 'P' command starts the one plane graphic searcher: P [s][m] Starts at address s with modulo m. P [s] Starts at address s with last modulo. P Starts at last address with last modulo. When you have activated the graphic searcher, the following keys are used for display control: Cursor up Scrolls plane one line down. Cursor dn Scrolls plane one line up. Cursor left Scrolls plane one line right. Cursor right Scrolls plane one line left. SHIFT-Cursor up Scrolls plane one screen down. SHIFT-Cursor dn Scrolls plane one screen up. HELP Modulo=modulo+2. DEL Modulo=modulo-2. SHIFT-Help Modulo=modulo+16. SHIFT-Del Modulo=modulo-16. BACKSPACE Modulo=0. CR Switches between hires and lores. CTRL Ends graphic searcher. Since the graphic searcher also supports the memory manager, it is possible not only to look at the graphic memory but at the entier space of addressable memory including other memory and rom image. Because of technical reasons the status bar is now located at the bottom. It has also become neccessary to limit the modulo. It can now range from $ffb2 to $3ffe for a hires and from $ffda to $3ffe for a lores plane. Hear Sound: The 'H' command sends an area of memory as a sample to the audio hardware: H [s][e](p) Hear memory from s to e with period p. H [s][e] Hear memory from s to e with last period. Memory manager is supported. SIM Addresses: The 's' command is used to transfer the display and backup and the SIM code itself: s [p][b][c] New display at p, new backup at b, SIM copied to c. s [p][b] New display at p, new backup at b. s [p] New display at p. s Redraws the display. Be carefull when you transfer the SIM code. SIM does adjust breakpoint and traps to the new address, but a possible debug server will only know about the new location when you quit SIM. The old copy of SIM will still work, but its breakpoint and trap system will be confused. The same problem occurs when the tasktraphandle is set to SIM. Use this command only when the system is dead. SIM does not check the values you enter, make sure that you do not specify locations where i.e. display and SIM would overlay. Copperlist: The 'l' command is basically used to disassemble a copperlist. The following variations are used for different actions: l* Shows the active copperlist. l? [s][e] Starts to search for the copperlist from s to e. l? [s] Starts to search for the copperlist from s to $80000. l? Searches for the copperlist from $70 to $80000. l= [n] Starts to search quickly for copperlist 1 or 2. To end copperlist display or searching, press . When you search quickly, the copperlist you are looking for will be activated. If this one is not the running one, search again for the other to set the other copperlist again. This kind of searching has the risk that you may search for a copperlist that does not exist. The 'l=' function does not work properly on MC68020+ due to some timing problems. Calling it on any MC68020+ may not find a copperlist. Set Scanrange: The 'R' command is used to define the range in which the access scan shortcuts will search for accesses. Default is $10000: R [s] Sets range to s. EXAMPLES: ? 256*5,52*56 F10 r:dpc pc@ F P 12356 52 s 70000 c50000 c40000 l* l=1 l? 20000 R $80000 Debugger Window Support ----------------------- A [s] Set new start address T [s]{@} Set linkterm Start Address: With this command you can directly set the start address of the active view: A [s] Set new start address of view to s. Linkterm: To set a linkterm for a view, you use the 'T' command. SIM will calculate the result of this term and use it as new start address each time it is entered or the AMIGA-r shortcut is pressed: T [s] @ Set smart linkterm for active view. T [s] Set simple linkterm for active view. T Removes linkterm. When SIM calculates a simple linkterm, it takes the result as new start address. The result of a smart linkterm is only used as new start address if it is not in the space currently displayed in the view. Normally this is only used to link a view to the PC. EXAMPLES: A a0+56 T a0+d0 T pc @ 4.4 The Debugger Window =========================== You can switch it on or off by pressing . When you do so, a part of the worktable is locked for the cursor and used to print out the registers and one or two different views of the memory in different forms (disassembly, ascii etc.). The window is updated as soon as you execute a command that may change the memory and at entry of SIM. The two views have two start addresses that are stored in m0 and m1. m1 is unused when you do not splitt the window and use only one view. You can link the two views to two terms, the socalled 'linkterms'. 4.5 Debugger Window Shortcuts ============================= The window and its views are controled with shortcuts that are qualified by either left or right Amiga. If you have splitted the window, you can select the view that recieves the commands by pressing . View Address ------------ Cursor up Decreases the views start address and scrolls the display one line down. Cursor dn Increases the views start address and scrolls the display one line up. Cursor left Decreases the views start address by one byte (two bytes for disassembly and copper dump). Cursor right Increases the views start address by one byte (two bytes for disassembly and copper dump). SHIFT-C up Decreases the views start address and scrolls the display one page up. SHIFT-C dn Increases the views start address and scrolls the display one page down. ALT-C up Decreases the size of the current view by one line. The minimum size is one line. ALT-C dn Increases the size of the current view by one line. The maximum size is as large as there stays one line for the monitor. If the cursor was in a line used by the debugger window, it is moved to the top line in the worktable. SHIFT-Alt-C up Moves the bar separating the two views one line up, which decreases the upper view and increases the lower view one line. SHIFT-Alt-C dn Moves the bar separating the two views one line down, which increases the upper view and decreases the lower view one line. s Splitts the window into two views or unsplitts again and removes the inactive view. r Recalculates the linkterm(s) and sets the views start addresses again. Output Form Selection --------------------- a Selects asciidump for the active view. m Selects hexdump for the active view. l Selects copper disassembly for the active view. m Selects disassembly for the active view. p Selects text for the active view. D Dis-/enables symbols in general. S Allows symbols also for $xxxx(An) either only at the PC or throughout the entier disassembly. Breakpoints ----------- b Sets an unconditioned illegal breakpoint at the start address of the active view. v Sets an unconditioned resident illegal breakpoint at the start address of the active view. B Sets a JSR-breakpoint at the start address of the active view. Flow ---- z Does one trace step. u Does one trace step that does not follow into subroutines. i Puts PC to next instruction. x Exits SIM. q Quits SIM and returns control to debug server. g Leaves a subroutine. Therefore SIM puts a STACK-breakpoint at the actual stackpointer and exits. Do not use this when the subroutine has already put more data on the stack. This corresponds to the command line 'bssp:X'. G Performs an RTS. Basically does 'rpc[sp]:rspsp+4'. j Sets the pc to the start address of the active view. Edit ---- e Starts to edit in continuous mode at the start address of the active view. n Starts to assemble in continuous mode at the start address of the active view. N Replaces the instruction at the start address of the active view with NOP instruction. Indirection ----------- [ Goes to next higher indirection level and takes the longword at the start address of the active view as the new start address and stores the old one. ] Goes to previous indirection level and takes the stored start address as the new one. { Same as AMGIA-[ but the longword will be read as BCPL and multiplied by four. } Goes to next higher indirection level and uses the last address this level pointed at. SHIFT-ALT-C left If the instruction at the PC is a branch of any kind, an indirection to the address of the branch is done. ALT-C If the instruction at the start of the view is a branch of any kind, an indirection to the address of the branch is done. SHIFT-ALT-C right Goes to previous indirection level. ALT-C right Goes to previous indirection level. The indirection commands can have a maximum depth of 8 levels. SIM does never reset to the first level on its own, if you have reached the limit, you must reset it by returning to level 1. Find and Compare ---------------- f Continues to search at the start address of the active view. c Continues to compare. The source address will be the start address of the first view , the destination address the start address of the second view. > Initiates scan for accesses on start address of current view. The range can be set with the 'R' command, default is $10000. SIM will search both upwards and downwards for accesses, the range specifies the maximum distance to test. < Continues scan. Miscellaneous ------------- P Toggles the printer on/off. The printer can only be activated if there is one connected to the parallel port and it is selected. H Makes a hardcopy of the actual display by printing it as text. You do not have to activate the printer first. k Toggles between US keymap and custom keymap. ! Flushes keystatefield, see chapter 'The Keyboard'. ? Toggles keyboard buffer killer, see chapter 'The Keyboard' + Toggles fully printable charset. When switched on (full), the chars $0-$1f and $80-$9f are not replaced by a period in asciidump, hexdump etc. Switch it off (semi) when using the printer. \ Toggles the auto-unmodify traps feature. When this is switched on, all modified traps are set again when you leave SIM. F1 to F10 Toggles availability of funktion keys. 0 to 9 Takes one of the ten position memories as the start address of the active view. SHIFT-0 to 9 Stores the start address of the active view in one of the ten position memories. Works only with the keypad! L Switches between PAL, NTSC and NTSC overscan if ECS or AGA chipset is available. If not, NTSC users can switch between NTSC and NTSC overscan only. M Toggles the MMU on or off (68020+ only). R Toggles register display mode: Either display MSP or SR flags (68020+ only). ® Toggles register display mode: Either small register list or large. Z Toggles EA calculation for condition breakpoints and trace on/off. If the SEA, TEA, SX or TX register is used in an condition expression, switch this on. ***************************************************************************** 5. Additional Information ***************************************************************************** 5.1 Assembler Usage ======================= SIM contains a full 68000 assembler which allows you to make changes to programs while debugging. It supports the standard optimisations and aliases used by most other assemblers: - ADDI and ADDA can be replaced by ADD. ADDX can also be replaced by ADD if the effective addresses are address register indirect with predecrement. - SUBI and SUBA can be replaced by SUB. SUBX can also be replaced by SUB if the effective addresses are address register indirect with predecrement. - CMP can be used instead of CMPA, CMPI and CMPM. - EOR, OR and AND can be used instead of EORI, ORI and ANDI. - Bcc and DBcc instructions and PC-relative effective addresses use absolute addresses. It is possible to specify the offset directly by puting a '+' or '-' sign in front (but note that the offset is counted from start of instruction plus 2): 00060010: bra $60000 or 00060010: bra -$12 - If no size is given, Bcc will be optimised to short if possible. - If no size given, memory direct effective addresses are optimised to WORD if possible. - If no size given for an instruction, the default size is used which in most cases is WORD. - The interpreter is very tollerant concerning spaces, a line like move.l ( $75 ) ( PC , D7.l ) , ( $4 ).w will be accepted and assembled correctly. 5.2 Calculator Usage ======================== The calculator is one of the central functions of SIM, all numeric input is handled by it. It disposes of several very useful operations and value forms. The following operators are supported, sorted after priority: ( ) Brackets: Correspond to normal brackets. Number of opening and closing brackets must be the same. Maximum nesting is 127. [ ] Memory indirection: The result of the term in these brackets an address and the content of the memory at that address will be read. A size directly after the closing bracket will define if the value will be read as a BYTE, WORD or LONG and extended to LONG. I.e.: [4].l reads out AbsExecBase, [$dff002].w reads out the actual DMACON as a WORD. - Prefix change: Changes a positive value to a negative and vice versa. I.e.: -5 is -5, -0 is 0, --6 is 6. ~ Logical NOT: Inverts all 32 bits of the value. I.e.: ~5 is -6. .s Sizing: Any value will be extended to LONG from the size specified. I.e.: $89.b is $ffffff89. The size of the result is used both for the assembler when using memory direct effective addresses and for data input for the memory edit command etc. If multiple sizing operations occur, the last sizing operation in the lowest bracket level defines the finial size of the result. * / Multiply and divide: Signed LONG multiplication and division. I.e.: -$56*5 is fffffe52, 9/-3 is -3. \ Modulo: Signed LONG modulo. I.e.: 11\4 is 3. + - Addition and subtraction: LONG addition and subtraction. I.e.: 1000-9 is 991. << Shift left: Correspond to a multiplication with 2 to the nth power, whereas n is the numer of bits to be shifted. I.e.: $20<<8 is $2000. >> Shift right: Corresponds to a division by 2 to the nth power, whereas n is the numer of bits to be shifted. I.e.: $2000>>8 is $20. & Logical AND: LONG AND operation. I.e.: $1234&$ff00 is $1200. ! Logical EOR: LONG EOR operation. I.e.: $c1!$54 is $a5. | Logical OR: LONG OR operation. I.e.: $1200|$34 is $1234. <> Not equal: Result of this operation is -1 if values not equal, else 0. I.e.: 5<>6 is -1, 3<>3 is 0. = Equal: Result of this operation is -1 if values are equal, else 0. I.e.: 5=6 is 0, 3=3 is -1. <= Lower or same: Signed comparison, result is -1 if value left of operator is lower or the same than the right value. I.e.: 1<=1 is -1, 6<=5 is 0. >= Greater or equal: Signed comparison, result is -1 if value left of operator is greater or equal than the right value. I.e.: 2=>1 is -1, 0=>5 is 0. < Less: Signed comparison, result is -1 if value left of operator is less than the right value. I.e.: 1<1 is 0, 0<5 is -1. > Greater: Signed comparison, result is -1 if value left of operator is greater than the right value. I.e.: 2>1 is -1, 0>5 is 0. As for the form of values, the following are supported: $x Hexadecimal number: A number in hexadecimal form, consisting of max. 8 digits 0-9 and a-f. I.e.: $badcode1 #x Decimal number: A number in decimal form, consisting of digits 0-9. I.e.: #1992. %x Binary number: A number in binary form, consisting of max. 32 digits 0 and 1. I.e.: %1010001011. ' " ASCII chars: A number consisting of max. 4 ASCII chars. The string must be introduced and ended with the same sign. I.e.: "SIM!", 'DATA', '"MC"'. ! Last result: Stands for the result of the last term calculated. I.e.: To display 16 bytes at $50000 one can enter the command 'm $50000 !+$10'. @ Actual address: Stands for the actual address used by dump commands and edit/assembly commands. I.e.: @-100. SIM SIM start: The program and base address of SIM. D0-D7 ,A0-A7 ,PC ,SP ,SSP ,USP ,SR ,CCR and M0-M7 (MSP/ISP, VBR for 68020+) CPU registers: The calculator can directly use the contents of these registers. SSP is the supervisor stack pointer, USP the userstack pointer, SP and A7 the actual stack pointer (68020+: SSP is the actual supervisor stack pointer, MSP and ISP the master and interrupt stack pointers, VBR the vector base register). M0-M7 are variables, M0 and M1 are used as view start registers. I.e.: pc+10-d0. SEA, TEA, SX, TX The effective address of the source and destination EA of the instruction at the PC. The SX and TX registers are 1 if the instruction has a source/destination EA, otherwise 0 and the corresponding EA register is undefined. I.e.: sea*sx x,\x Symbols: Uses the symbol specified after a '\'. I.e. \start. A term normally ends at a space, a colon, a semicolon, a komma or a carriage return. If you have opened a bracket, you can have spaces between operators and values, but ONLY then. Otherwise, the end of the term will not be there where you wanted it to be. The calculator can work in decimal or hexadecimal mode. In decimal mode you do not have to write the '#' in front of a decimal number, but for hexadecimal numbers, the '$' is neccessary. In hexadecimal mode you do not have to write the '$' for hexadecimal numbers, but for decimal numbers, the '#' is neccessary. Hexadecimal mode is usually used to get addresses and hexadecimal numbers. For the other cases decimal mode is used, also for the assembler. 5.3 Data Line ================= The data line is used to specify data for different commands like find, edit or occupy. The data line consists of four elements: - Hexadecimaly numbers are introduced with or without '$'. They can be as long as neccessary. The number is ended by a char that is no digit. If you enter an odd number of digits, the last digit will be taken as byte, its higher nibble zeroed. Spaces are allowed between digits. - Assembler instructions are initiated by a 'n' character, then the instruction follows. - Calculator terms are initiated by a '?', then the term follows. The size of the result will be considered (LONG=4 bytes,WORD=2 bytes and BYTE=1 byte). - Ascii chars are either initiated by ' or " and closed with the same or a . The string length is only limited by the line length. An example, using all the elements from above. The line: 45,"ABC",njmp $60000,?[$fc0000].w,6666 is interpreted as: 45 41 42 43 4e f9 00 06 00 00 11 11 66 66 |- |------- |---------------- |---- |---- | | | | | 45 "ABC" jmp $60000 [$fc0000].w 6666 A data line ends at a space or an illegal char. Between the komma that separates two datatypes and the next datatype there can be spaces. also between digits (only for the edit command, not for find and occupy). 5.4 The Debug Server Entrance ================================= The debug server entrance is specially concieved for the cooperation between SIM and another debugger or loader, i.e. 'SIMBug'. It enables the debug server to give control over a program to SIM and SIM to return control to the debug server. In a part of the SIM base, there is space to store the registers d0-a6, USP and SSP (ISP/MSP), SR and PC of the program that is monitored. The debug server can fill in this table. Additionally, It can specify a reentry PC, SR, USP and SSP (ISP/MSP). When it enters SIM by the debug server entrance, SIM takes the registers out of the table and copies them into the register buffer. SIM has now the control over the program. The length field indicates how far you have initialised the list from the length field. If you do not fill in the entier structure, the rest will be zeroed. If you want to give control back to the debug server, i.e. to unload the program, you can use the 'q' command (or 'Q' or AMIGA-q). SIM does then copy the registers back into the base area and takes the reentry PC, SR USP and SSP (ISP/MSP) as the actual ones. To be sure that the debug server is still there, SIM looks at the address if the longword $4f4b4159 ("OKAY") is there. If the longword is there, it exits. That way, it returns to the address specified by the reentry PC with reentry stacks and a reentry SR. The registers do not contain sencefull information, appart a6 which contains the base/codeaddress of SIM. In case you transfered SIM, the debug server knows where you put it. The debug server can now read out the table with the registers and use them for itself. 5.5 The SIM Base ==================== At the start of SIM, the different entrances are located, the backups and reentry values and the debug server data structure. The structure of this base is documented here. The offsets described won't be changed in higher versions, I hope, but I feel free to extend it at the upper end: ;--- Base --------- STRUCT toolbase ;+0 The start address of SIM in memory ;--- Display ------ APTR plane ;+0 The start address of the $5000 bytes display ram (must be graphic memory!) APTR backup ;+4 The start address of the backup of the display. When not zero, SIM will copy what is in the memory of the future display to this address when entered and copy it back when left. ;--- Entrances ---- JMP entrance1 ;+8 Entrance for JSR. Here you can simply enter SIM by a 'JSR' to this address. JMP entrance2 ;+12 Entrance for Exec's traphandle. When you want to use SIM as traphandler of your task, write this address to . JMP entrance3 ;+16 Debug server entrance. LONG 0 ;+20 *** RESERVED FOR EXPANSION *** ;--- Traps -------- ;When a trap is set directly, its vector is set to ;the corresponding entrance in here. JMP entrance22 ;+24 Bus error JMP entrance23 ;+28 Address error JMP entrance24 ;+32 Illegal instruction JMP entrance25 ;+36 Divide-by-zero JMP entrance26 ;+40 CHK instruction JMP entrance27 ;+44 TRAPV instruction JMP entrance28 ;+48 Privilege violation JMP entrance29 ;+52 Trace JMP entrance2a ;+56 Op Code 1010 JMP entrance2b ;+60 Op Code 1111 ;--- Signal ------- LONG "SIM!" ;+64 This Long signals that this is SIM LONG version ;+68 Version of SIM as 4 ASCII chars ;--- Backups ------ ;When SIM is entered it backups some customregisters ;and vectors here. WORD dmacon ;+72 $DFF096/002 WORD intena ;+74 $DFF09A/01C WORD intreq ;+76 $DFF09C/01E LONG level2 ;+78 VBR+$68 LONG level3 ;+82 VBR+$6C BYTE ciaacra ;+86 $BFEE01 BYTE ciaacrb ;+87 $BFEF01 BYTE ciabcra ;+88 $BFDE00 BYTE ciabcrb ;+89 $BFDF00 BYTE ciaapra ;+90 $BFE001 BYTE ciaaprb ;+91 $BFE101 BYTE ciaaddra ;+92 $BFE201 BYTE ciaaddrb ;+93 $BFE301 BYTE ciabddra ;+94 $BFD200 BYTE ciaasp ;+95 $BFEC01 LONG vpos ;+96 $DFF004 ;--- Reentry ------ ;Reentry values of things that can't be saved. ;When SIM is left, it inits the registers named ;with the values in this list. WORD $2981 ;+100 DIWSTRT WORD $29c1 ;+102 DIWSTOP WORD $0038 ;+104 DDFSTRT WORD $00d0 ;+106 DDFSTOP WORD $5200 ;+108 BPLCON0 WORD $0000 ;+110 BPLCON1 WORD $0000 ;+112 BPLMOD1 WORD $0000 ;+114 COLOR00 WORD $0000 ;+116 COLOR01 ;--- ICR Special -- ;The ICR data and mask. BYTE lasticr ;+118 $BFED00 read BYTE reentryicrmask ;+119 $BFED00 write ;--- Distances ---- ;Distances to internal structures. LONG disasscalc-base ;+120 Distance to disasscalc module LONG preferences-base;+124 Distance to preferences structure ;--- Debug -------- ;Debug server structure for entrance 3. LONG 0 ;+128 Offset from here to end of inited part LONG "????" ;+132 Sign of server ;--- Program ------ ;The registers of the program that is debugged. LONG 0 ;+136 Register d0 LONG 0 ;+140 Register d1 LONG 0 ;+144 Register d2 LONG 0 ;+148 Register d3 LONG 0 ;+152 Register d4 LONG 0 ;+156 Register d5 LONG 0 ;+160 Register d6 LONG 0 ;+164 Register d7 LONG 0 ;+168 Register a0 LONG 0 ;+172 Register a1 LONG 0 ;+176 Register a2 LONG 0 ;+180 Register a3 LONG 0 ;+184 Register a4 LONG 0 ;+188 Register a5 LONG 0 ;+192 Register a6 LONG 0 ;+196 User stack pointer LONG 0 ;+200 Supervisor stack pointer/ISP LONG 0 ;+204 PC of program WORD 0 ;+208 SR of program ;--- Server data -- LONG 0 ;+210 Reentry routine of server LONG 0 ;+214 Reentry usp of server LONG 0 ;+218 Reentry ssp of server/ISP LONG 0 ;+222 Reentry sr of server ;--- Extension ---- APTR 0 ;+224 Pointer to zero ended list of APTRs that point to zero ended texts. The texts in this list are printed and the pointer is cleared APTR 0 ;+228 Pointer to task structure APTR 0 ;+232 Segmentlist APTR 0 ;+236 Symbollist with labels LONG 0 ;+240 MSP (68020+ only) LONG 0 ;+244 Reentry MSP (68020+ only) LONG 0,0 ; RESERVED LONG sim_size ;+256 Size of SIM BYTE 0 ;+260 CPU information BYTE 0 ;+261 MMU information WORD 0 ;+262 BEAMCON0 reentry value LONG 0 ;+264 VBR ;--- End ---------- ;+268 This is the end of the actual structure 5.6 Errors ============== SIM is a flexible tool. Therefore the user can do many mistakes. In this chapter, all errors are explained. When an error occurs that bases on an error in the command line (which in fact is in most cases so) SIM prints the error text in the line of the cursor and copies the command line in the next line. The cursor is in the line of the copied command line below the char or the word that probably caused the error. Assembler errors ---------------- illegal instruction: The assembler does not know this instruction. illegal value: An number is higher or less than it should be. illegal ea: This addressing mode is not allowed. illegal size: An instruction has either no size at all or does not support this size. illegal operator: An operator is not allowed here. line malformed: Something is undefinably wrong. too few info: Some part of this instruction is missing. illegal sea: An illegal effective address as source. illegal tea: An illegal effective address as destination. illegal char: The character is not allowed here. illegal condition: The condition of a Bcc, DBcc or Scc is inexistent. illegal direction: The direction for bitshifting is neither left nor right. Calculator errors ----------------- bracketerror: The number of brackets opened and closed does not match. overflow: The result is larger than $ffffffff or ±$8000000, or you have divided by zero or you do more than 30 operations. illegal value: The calculator cannot interprete that as a number. illegal operator: This is no operator for mathematical operations supported by the calculator. no value given: You have forgotten to give a term, or the very first value of an expected term is of an unknown type. Disk errors ----------- disk error: Something went wrong with the disk access, either the track that is read is damaged or the disk was writeprotected. In most cases you will get a warning in the statusline of the disk access display. file not found: SIM could not locate the file you want to load or the path given was faulty. not enough space: The file to be saved won't fit on the disk. disk full: That error should not occur. directory error: If something goes wrong while listing the directory of a disk, i.e. bad hashes or disk damaged, this error is returned. illegal path: SIM cannot locate the directory you want to list. Other errors ------------ too much: The start address given for a command is higher than the end address. breakpointerror: SIM has no more breakpoints free or it could not set a breakpoint there, either because ROM is read only or it is not possible to put breakpoints in the memory presently occupied by the SIM code. 5.7 Footer Messages ======================= As mentioned earlier, there is a status field in the footer line. This space is used to transmit messages to the user that are not as important as to be printed in the monitor or serve as additional information. Currently the following texts can appear there due to an event: SIM is awaiting commands. busy As soon as SIM is executing commands this text is printed. This shows you If SIM is working or not. break When you break the execution of a command SIM replies with this message. pause When you pause. lock When you press SHIFT-CTRL to stop all output for some time. error When an error occurs. Fx on/off When you toggle function keys SIM returns the new state to you this way. flushed When you flush the keystatefield. prt err When the printer has troubble (paper out/select...). cnd err When an error occurs while calculating the condition terms of breakpoints or trace, SIM is entered and this text appears. prt on/off When you toggle the printer and it is available. AUT on/off When you toggle the auto unmodify traps feature. US/** kmap When you select the keymap. indir x When you use indirects the current indirect level is shown. returned When you return from the keyboard restoring routine by entering 'return'. KBF on/off When you toggle the keyboard buffer killer. more When the directory of a disk does not fit in the visible monitor part, SIM writes that message to tell you that there is more to see. semi/full Whether or not the full charset is printable. symbols/opcode Symbols are available and used or not (disassembly with symbols or opcode field). $xxxx() Display offset for d16(ax) EAs. label() Display symbol for all d16(ax) EAs. >label() Display symbol of d16(ax) EAs of instruction at PC. Use offset for other instructions. MMU on/off The status of the MMU tree (68020+ version only). MSP/SR flags If the register list shall either display the MSP or the SR flags (68020+ version only). found If the scan for an access address was successful. caln/no EA If or if not the calculation of EAs is allowed while tracing. ***************************************************************************** 6. Appendix ***************************************************************************** 6.1 Acknowledgements ======================== Big thanks must go to all the people who helped me in this project and many others: - Daniel Weber for continuous testing of all new features I inserted, some good and some bad ideas and his mighty ProAsm. Not to forget, for all the cool movies each saturday too. - René Eberhard for more tips, betatesting, exchange of KS 2.0 knowhow and loads of fun at MicroSpot and Feller and everywhere else. - Bryan Ford for many good ideas, betatesting, tons of hints, profreading my documentations and all the cool e-mail chat and much, much more. - André Dietisheim, Oliver Ferlin, Stefan Strasser, Kay Temirel, Ch. Schneider, F. Buergel and Niel Ericson for bugreports and ideas. - Michael Hitch for MC68040 testing. - And to all the registered users. 6.2 Registered Users ======================== Thanks go to the following users who registered and persuaded me that some people use this tool: Daniel Weber (Switzerland) René Eberhard (Switzerland) Kay Temirel (Germany) Niel Ericson (Canada) Roby Leemann (Switzerland) Steve Anderson (Canada) Jörn Körner (Germany) Bryan Ford (USA) Dan Babcock (USA) Gerd Hesina (Austria) Jandl Mario (Austria) 6.3 Contacting Me ===================== If you want to register, if you have bugreports, question, ideas, flames or complaints (constructive criticism is always welcome), or if you just want to contact me, write or send a letter to: Stefan Walter Finsterruetistr. 57 8135 Langnau a./A. SWITZERLAND Because snail mail is slow, you can also contact me by phone or by sending a message to the electronic mail address below (if you call by phone, please concider any possible time differences between your location and mine and don't wake me up in the night :). Phone: Switzerland/(0)1/713-01-46 Internet: avalon.physik.unizh.ch!swalter ----------------------------------------------------------------------------- Stefan Walter, 10.Mar.1993