____ ___ ___ ___ ___ ___ ___ ____ ___ ___ ___  / /__//_ /__ / //_ //__ / //_ / / / //_ //__//_   / / //__ ___//__//__/___//__// / /_/_// // \/__  ------------------------------------------------------------------------------ - FOR ABO'S CONTACT US AT: BP:28 1170 WATERMAEL-BOITSFORT 1 BELGIUM!!... ------------------------------------------------------------------------------ - DON'T SEND ANY DISKS - ------------------------------------------------------------------------------  THE LEGENDARY >> SUBSOFTWARE << IN 87/88/89/90/91!!...  ------------------------------------------------------ ------------------------------------------------------------------------------- ******* **** ****** * * ******* * * * ** ** ** ** ** * * * ***** *** ** *** *** ***** * * *** ** ******* * * *** *** ** ** * ** *** * ** ** ** ** ** ** ** ** * * **** ** ****** ** ** ** ** * System-Independent Monitor Copyright © by Stefan Walter, ALL RIGHTS RESERVED ------------------------------------------------------------------------------- The User Manual, refering to version 1.51 of S.I.M. Released on the 27th of January 1991 -------------- READ IT OR DIE -------------- CONTENTS ======== 1. Introduction 1.1 Welcome to SIM 1.2 About this Documentation 2. Getting aquainted with SIM 2.1 What is SIM? 2.2 Qualifications, Requirements and Limitations 2.3 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 Functionkeys 3.13 SIM and the Hardware 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 Debuger Window 4.5 Debugger Window Shortcuts 5. Additional Information 5.1 Assembler and Calculator Syntax 5.2 Line Forms 5.3 The Debug Server Entrance 5.4 The SIM Base 5.5 Errors 6. Greetings, Thanks, Support and about Future Releases 6.1 Thanks 6.2 Greetings 6.3 Support 6.4 About Future Releases ******************************************************************************* 1. Introduction ******************************************************************************* 1.1 Welcome to SIM ================== Congratulations dear user. You have just become owner of the second release of 'S.I.M.', the high performance monitor and debugger for the Commodore Amiga, probably the best, the mightiest and the only of its kind. Version 0.50 of 'S.I.M.' was freeware. This version of 'S.I.M.' is now a shareware program. 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 don't respect these three rules I wish you all the bad things you'd wish somebody that steals, adds to or misuses something created by yourself in hours of hard work. So be fair! Only happy programers are good programers. If you copied this version from somebody else and you like it and keep using it, you should send me (if you did not yet) 20 SFr or 20DM or 15$ (well, 1g gold or half a barrel of oil will also be accepted) shareware fee. This has for you the advantage that I will send you the final version on another disk as soon as it's finished. Note: The entire risk of using SIM is to the user himself. In NO event will the author be liable for direct or indirect damage or loss resulting from the use of this program. 1.2 About this Documentation ============================ There exist two very good reasons why you must at least have a look at this text: 1. I do not question your qualifications and your knowledge of the Amigas hardware. But SIM bases on a new concept that offers an universe of possibilities but also demands a lot of the user. There are a lot of details that will get important at a certain moment, details you'll never find out about on your own. It is in your own interest if you read this manual. You will then be able to use 90% of the possibilities this program offers (sorry, the only one that knows everything about this tool, that's me). 2. It was fun programming SIM, but it was HELL writing this damn manual. Writing it in german would have been hard enough, but writing it in a foreign language made it a torture. Good old Woodbird (my former english teacher) may forgive me all the bad mistakes I did in this text. So you may honour my sacrifice by reading this, since I do not like to do write manuals that no one reads. ******************************************************************************* 2. Getting aquainted with SIM ******************************************************************************* 2.1 What is SIM? ================ A good question, isn't it? Well, it's not as easy to give a straight answer then to ask the question. As you could read in the title, 'S.I.M.' stands for (S)ystem (I)ndependent (M)onitor. I presume that nearly every programer working on the AMIGA (intromakers excluded) knows what a 'monitor' is (I do not mean the device you stare at in this moment!). There have been several before, like good old C-Monitor, A-Mon, RomCrack and a lot more. During the developement of SIM they served as examples for how to do it and how not to do it and how to do it better. I hope that does not cause any trouble with copyrights and so on. The result of this compiling is an unmatched variety and complexity of commands. This is only a short selection of the more spectacular features of SIM: - comfortable command editing - integrated assembler, disassembler and calculator - very powerfull findmechanisms - superb breakpoint and trace possibilities - parallel printer support - freely defineable functionkeys - exception control - DOS-track and sector read/write operations - one-bitplane graphic searcher - diskformat - file LOAD, SAVE, DELETE and DIR operation - copperlist finder and disassembler Additionally to the monitor commands, this version disposes of what I call 'Debugger Window'. People that are used to Monam2 will welcome it because it provides a similarly easy and effective way to overview a program. So far nothing new. What makes SIM so powerfull is the way it interacts with the AMIGAs hardware and system. SIM tries to be as discreete and as independent as it is possible. On one hand this means that SIM will run under all circumstances. It does not need anything, no exec, no DOS, no nothing. This capability leaves a wide field of usages. You could use SIM as last hope to salvage data from the memory before reset. Or for virus-secure diskoperations since SIM does it without DOS. On the other hand discreetion means that S.I.M. will do as less changes in the software environement (ram, custom registers etc.) as it can. It does neither use blitter nor copper. This 'invisibility' of SIM makes it possible to monitor and track a programs to unknown depthts. You can debug directly into graphic routines, interrupt handlers, diskroutines, task and memory handling routines without any difficulties and resulting problems. I have made some bonebreaking tests with SIM, but it passed them all. There is no absolute protection from SIM, it can only be made very hard to keep control of a program with SIM, but if you are clever enough, you will allways find a way around the problem. 2.2 Qualifications, Requirements and Limitations ================================================ To use SIM efficiently, detailed knowledge of the AMIGAs hardware, the 68000 processor and assembler language is ABSOLUTELY neccessary. SIM is designed to be used by professionals. SIM will work on practically every normal machine, as long as its processor is a Motorola 68ooo/7.14 MHz. Other processors (68010/20/30/...) are not supported yet, I am sorry about that. These processors are much more comlicated in their assembler language and exception handling and I do not have one of them. Different memory configurations and Big/Fat Agnus do not bother SIM. Theoretically you'd not even need a kickstart ROM/WOM to run SIM. I recommend a fastmem memory expansion of at least half a megabyte at $200000 or $c00000. This gets usefull when you want to debug a program that uses the entier chip ram. You can then put SIM in fastram which you have disabled with one of those resetting nofastmems. 2.3 The SIM Program =================== SIM is not a conventional program (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. When you work with SIM you must change your way of thinking. The Amiga has multitasking. Most debuggers are 'taskoriented'. This means that they debug a certain task, and only that one. If another task crashes, they do not notice this. SIM is a monotasking debugger. In the eyes of SIM there is only one program running on your machine. This one program may splitt up into several seperated programs that are 'switched' (the tasks), but it is still one whole program. This concept enables you to debug different tasks at a time, and even newly generated ones i.e. by createproc(). ******************************************************************************* 3. Some words about... ******************************************************************************* 3.1 The Display =============== The display creates some of the more tricky problems for SIM and you. As you know, you need 20480/$5000 bytes of chipmem for a medres bitplane you want to display. SIM uses a medres bitplane for it's display. But at a certain moment, there may be no 20480 bytes chipmem available. The solution is the backup. When you have an area of $5000 free chipmem 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 chipmem or the chipmem will be used entierly in near future and you have enough (that means $5000 bytes) unused fastmem that won't be used for sure (disable fastmem...), you set the backup address to the start of a free $5000 block of fastmem and the display address just to somewhere in the chipmem. When SIM is activated, It copies the content of the $5000 bytes display- to the backupmem and uses the displaymem. When you leave SIM again, it copies the $5000 bytes back from the backup- to the displaymem. That way, the chip ram is unchanged. SIM does not have an memory manager that 'ghosts' the display. This means that when you have a display at $70000 and a backup at $c50000 and you want to change or view memory or find something at $71000, you either transfere the display to another location in the chipmem or you have to look or edit in the backup (at $c51000 in our example). Because the interrupt vectors are used, you may not specify a display below $70 or above $7b000 when you have the normal amount of chipmem (the chipmem is reflected at $80000, except if you have fastmem there). Both the display- and the backupaddress are entered in the SIM-basearea before starting SIM or set by the 's' command while working. 3.2 Breakpoints =============== A breakpoint is basically a change in the program that is monitored that stops it and gives control to the debugger that set it. In other terms, you can run the program at full speed until it arrives at 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 'forget' it (this means that 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 by the task traphandle, set by 'SIM-BUG' 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 follwoing criterias can decide whether or not the breakpoint forces entry: - condition term: You can specify a formula 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. - 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 you remove it. 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'. You may ask the question how to go over a breakpoint. SIM does this in three steps: - remove the Illegal opcode and put back the original one. - do a tracestep to execute the instruction. - remember the (possibly new) opcode and set the $4afc again. As you see, SIM uses the TRACE vector to ignore a breakpoint. 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 breapoints in delicate situations, where you are not sure if the vectors are not 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 bsr would jump in the middle of the breakpoint! 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!) 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 rts. 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 formula 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. - 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. I do not know what this is for, but people like it. 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. 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 char, that char 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. As you know, 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. 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. Unfortunately, I know only one way to find out if a drive is running or not: To activate the drive and look if its on full speed with no delay. This system is only working when the running drives have a disk inserted. If no disk is in a running drive and you access disk, it will be stoped after disk access. 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 sectores 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 reapair partially destroyed tracks. 3.6 Files ========= The capabilitys of SIM to read, list and write files are some of its newest and most usefull features. You can load any files of a DOS disk, also from user directories 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 an operation or to pause it. SIM can 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 take 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 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 commandline 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 until SIM gets it. 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 startaddress. This address has the name '@' for the calculator. It contains the endaddress 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 put the addresses they report into this buffer. Well, this is nothing special. But you can also say under what conditions an address is put in the buffer or one that is allready in buffer stays there. There are three possible conditions: - old: If an address that was allready in buffer did not match with any reported by the find or compare command, it only stays in the buffer when you enable oldies. - match: If an address that is reported is allready 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 enables you to search for counters or changes. To show the addresses in the buffer, the 'k' command is used. An example: you are searching for the livecounter in a game. You have five lives: 1. define matchbuffer, i.e. 'k c00000 c10000' 2. search for 5, i.e. 'f 0 20000 !n 05' 3. exit and die once 4. search for 4, i.e. 'f 0 20000 !m 04' If you are lucky, one address stays in the matchbuffer 5. list addresse(s) in matchbuffer, i.e. 'k 0' 6. if neccessary go to step 3 and search for one live less 3.10 Command History ==================== SIM remembers the last commands executed in the monitor. I reserved 128 bytes for that. These 128 bytes contain the last packed command lines that fit. 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 of 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 occure 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. 3.12 Functionkeys ================= You can define all ten functionkeys with a text or command line. If you define a text, it is copied at the location of the cursor. If you define a command line, it is executed directly. The system used bases much on the one used by the Sharp PC-1500, thanks to Sharp for that. The functionkeys share 300 bytes of 'intelligent' textbuffer with the condition breakpoints and linkterms. 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 *) - Level 2 interrupt - Level 3 interrupt - 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 **) 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. *) 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. Now since the disk-DMA is left on, remember that when the disk-DMA is terminated, bit 1 in the INTREQ is set. But 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 abaout the actual ones, you must read out INTREQR 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. I hope I can improve that. As I 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 it puts back when exiting. Those registers are: - DIWSTRT - DIWSTOP - DDFSTRT - DDFSTOP - BPLCON0 - BPLCON1 - BPLMOD1 - COLOR00 - COLOR01 As you see, 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 compleetely 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. ******************************************************************************* 4. Communication between YOU and SIM ******************************************************************************* 4.1 The SIM Environement ======================== As I quoted in the chapter about the display, SIM provides its own. It is basically used for all output SIM produces (leave alone the printer and disk). You have a PAL display of 256*640 pixels or 32 lines and 80 rows. The screens colors are green and dark blue but may be set by you to any colors you like. The screen is devided in header, worktable/debugger window and footer, all seperated by a line of '­'. The header normally contains the title and copyrights but serves also as statusline when accessing disk and keyboard cleanup. The worktable and the debugger window share 28 lines. - In the worktable, actually the monitor, you can move the cursor around and enter commands and get output. - 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 footer contains the cause of SIM's entry, a status and result field and the addresses of SIM itself, the display- and backupaddresses. 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 and enter again, the display will be the same. - SIM has two entier keymaps for not qualified, shifted, alternated and shifted+alternated keys, one USA and one custom. In the original version, the custom one is Swiss. - Ctrl+chars with ascii values from $40-$60 will cause a char from $0-$20 (i.e. 'J' (=$4a) => (=$a)) - Ctrl+chars with ascii values from $60-$80 will cause a char from $80-$a0 - The cursor can be moved around one char by pressing the cursor keys. - The cursor can be moved to the extreme positions by pressing +cursor keys (i.e. +cursor right => cursor in row 79) - will delete the char above the cursor and shift all chars right of the cursor one row left, inserting a space at row 79 - will clear the char left of the cursor and shift all chars above and right of the cursor one row left. - + will insert a space at the cursor position and shift all chars above and right of the cursor one row right. - + will clear the char above the cursor move the cursor one row left - + will clear the monitor part and put the cursor in the left upper corner next to a point. - + will clear the line in which the cursor is, put a '.' in row 1 and the cursor in row 2. - prints the first helppage, starting in the line below the line the cursor is in actually. - prints the second helppage. - : you can freely define the ten function keys. - + copies the last executed command in the line of the cursor. - + copies the line of the cursor in the command buffer. It can then be inserted anywhere by +. - will execute the commands in the actual line (the one in which the cursor is). - goes one step back in command history and fill the actual line with the actuall command in history. - goes one step forth in command history. You can execute commands by entering them in one line and pressing return. When all commands are executed, SIM looks if a point '.' is in row 0 of the actual line. If so, the cursor is set left of it and the line is not cleared. If no point is found there, SIM puts one there and clears the rest of the line. That way, the point signals wheather or not a line is a previous command line. That enables to use again the commands that have been entered earlier and are still visible on the screen. 4.3 The Commands and Their Syntax ================================= As mentioned earlier, SIM understands a vast number of commands. While working in SIM, you can get a little overview of them in the two helppages: n (s)(i) :assemble | t [s][e][t] :transfer mem | ? [n] :calculate 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 (x) :create 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 r (rs) :edit regs | F (n)(c){@} :edit F-keys | u :next step k (s)(e) :matchbuffer | z (n*n?cb) :trace steps | q/Q :quit prog P (s)(m) :show plane | b (s)(*n?b) :breakpoints | x/X :exit and go and s [s][s](n) :write secs | D (n) :set drive t [s][t](n) :write tracks| B [s] :bootchksum >f (n) :format disk | K [s] :blockchksum S [f][s][e] :save file | V (path) :directory In the helppage and the explanations, the following shortenings are used for options: s: (start)address e: endaddress t: targetaddress/track i: assembler instructions d: dataline c: a text or SIM commands n: decimal number x: hexadecimal number m: mask/modulo r: register p: plane b: backup/breakmode/block ?: condition term f: file j: jokers Options in '[]' are neccessary. Options in '()' are optional. Chars in '{}' serve as sign or flag. Because space in SIM is limited, these helppages tell only the basic syntax of a command. Here comes a short but detailed list of all commands and what they do: Dump Commands ------------- m (s)(e) : print memory as hexdump a (s)(e) : print memory as asciidump d (s)(e) : disassemble memory l (s)(e) : interprete memory as copperlist Dump commands have all the same options, only the output changes: command (startaddress) (endaddress) If you give both addresses, SIM starts to dump from the startaddress and stops when the endaddress is reached or passed over. If you give only the startaddress, SIM starts to dump from that address and calculates an endaddress. That endaddress will be: for 'm': start+128 for 'a': start+512 for 'd': start+32 for 'l': start+32 If you do not give any address, SIM takes the actual address as startaddress. Do not try to dump the customregisters area. In the disassembly, the instructions BSR,JSR and TRAP #x are indented and after the instructions JMP, BRA, ILLEGAL, RTS, RTE, RTR and RESET a line of '-' is printed for seperation. Additionally, breakpoints are marked by an asterix. EXAMPLES: m 0 100 a 100 d l 51236 !+60 Edit Commands ------------- e (s)(d) : edit memory n (s)(n) : assemle You can modify the memory with these two commands. The edit command can write data at a location in the memory (see chapter 'line forms' for details) The assemle command can assemble one or more instructions seperated by a ',' at a location in memory (see chapter 'Assembler and Calculator' for info) If you give both startaddress and data/instructions, SIM simply edits the memory. If you only give the startaddress, SIM will start to assemble or edit in a continuous mode where it allways 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 assemble 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 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, not to destroy the memory: - t [s][e][t] : Transfers memory from s to e at new address t Occpuy: Occupy is generaly used to clear the memory or to fill it with repeated data: - o [s][e][d] : Occupy memory from s to e with data d EXAMPLES: t 0 10000 c00000 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 a sophisticated find and compare system. For any of the three you can specify some jokers: - +/-n : Sets a step, only at every nth address is searched or compared. - '*' : To say that all 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 joker. SIM will then execute F9 each time something is reported and put the active view of the debugger window at that address. - '!' : If you want to collect and filter addresses with the matchbuffer, set this flag. After the '!' you can enter an 'o' to say that old ones stay, a 'm' to say that same addresses stay, or a 'n' to say that new ones stay. Find data: You can search in a defined area in the memory for a certain bytecombination 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 jokers j for the bytes d that are 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 jokers j. - f [s][e] : Searches again in the area from s to e. - f [s] : Starts to search from s to the last e. - f : Continues to find after the last address reported. Find disassembly: You can find an instruction or a fragment of it in a defined are in the memory. Like find data, find disassembly does not need all options: - f [s][e](j) i [i] : Starts to find from s to e with jokers 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 jokers j. - f [s][e] : Searches again in the area from s to e. - f [s] : Starts to search from s to the last e. - f : Continues to find after the last address reported. The instruction i can be only a fragment like '4(a6)' or an entier instruction like 'moveq #3,d0'. Several things must be made right: - When you have entered a space, 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 joker. It says that this char is not compared. 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: You can compare two areas in the memory. Different amount of options for different results: - c [s][e][t](j) : Compares area from s to e with area t to (t+(e-s)) with jokers j. - c [s][e][t] : Compares with no jokers. - c [s][t] : Continues to compare from s with t. - c [s] : Compares from s to last e with last t - c : Continues to compare after last address reported. Matchbuffer: You can read out or define the matchbuffer: - k [s][e] : Defines a new matchbuffer from s to e and clears it. - k * : Clears matchbuffer. - k ? : Shows you where the matchbuffer is. - k @ [s] : Shows all matchbuffer entries larger than s by reporting them one by one over F9. - k [s] : Lists all entries higher than s - k : Lists or shows next entrie(s) EXAMPLES: f 0 100 00 f 10000 20000 !nm 05 f 0 20000 @ imoveq #*,d* 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 or to view them: - r [r][x] : Sets register r vith new value x - r : Views registers - r? : Views memories m0-m7 Trapsetting: 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 vectors - wk : Clears all traps You can set or clear several vectors at a time by seperating the vector numbers by kommas. The vector numbers correspond to the exception numbers, 2 for bus error upto $b for linef. Trapcreating: 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 of same exception that forced entry - v? : Gives information about 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 by one of the exceptions. 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. EXAMPLES: r pc pc+20 r m7 d0 r? w 4,9 wk v 3 v -3 v? Breakpoints and Trace --------------------- b (s)(j) : set/clear breakpoints u : nextstep z (j) : tracestep i (n) : leave out instructions Breakpoints: The 'b' command is used to handle breakpoints. Different options are available: - b [s][j] : Sets a breakpoint at address s with the options: - 'l' or 'r' or 'f' : button breakpoint - [n] : counter breakpoint - '?' [n] : condition breakpoint - '*' : resident breakpoint - b [s] : Sets a simple breakpoint - 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 seperate several breakpoints at a time by seperating the next address from the previous address or options by a komma. Trace: The 'z' command executes tracesteps. It either stops after one step or when a certain condition is fullfilled: - z [j] : Does trace until: - 'l' or 'r' or 'f' : trace until button pressed - [n] : trace n steps - '?' [n] : trace until n not zero - '*' [s] : trace until pc=s - 'c' : emulate 68020 trace - z : Does one tracestep Nextstep: The 'u' command does either one tracestep or when it is done at a JSR, BSR or TRAP #x, it does also a tracestep and sets a stack breakpoint at a7 (or a7+2 when TRAP) and exits: - u : Do one nextstep Leave Out: This simply leaves instructions away: - 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, 'X' simply exits: - x : Exits, but asks for confirmation first - X : Exits directly Quit: The 'q' or 'Q' commands are used to return control 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 Gosub: The 'g' command is used to execute a little program from SIM: - g [s] : goes to subroutine at s - gw [s] : goes to subroutine at s but does not exit yet When SIM goes to subroutine, it first pushes the old pc on the stack and then the return address for the rts. The 'gw' command does only prepare the stack for the operation 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: - h [n] : Print nth last history - h : Print all five histories SIM does not only remember the registers d0-a6, usp, ssp, 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 t (s)(s)(n) : write track s (s)(s)(n) : write sector >f (n) : format disk Set Drive: The 'D' command is used to set the drive number that is used for further diskoperations (tracks, sectors or format, but not fot file operations!) or to ask for the actually used drive or to ask for the position of the head of a drive: - D [n] : Takes 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. Well, 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, analyze the diskroutines. 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 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: - >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. But the DOS cannot seperate disks with the same name and same date. So never keep two datadisks in two drives simultaneously, your machine would crash if you do so. If you format a disk that was previously in a drive and you return to DOS, remove and reinsert that disk for the DOS must know the new name and new bitmap. EXAMPLES: t c00000 0 80 >s 70000 0 2 f 0 Fileoperations -------------- L [f][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. Load File: This command loads a file directly into memory: - L [f][s] : Loads file f to s Just make sure that you don't load files over SIM or the display. Save file: With this command you can save an area of the memory as file: - 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 endaddress (filelength=0). List Directory: This command is used to list the directory of a disk or a user directory. - V [path] : Lists directory of directory specified by path. - V : Lists directory of last drive used for fileoperations. 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 stays stuff to be displayed, SIM writed 'more' in the footer. You can then continue by pressing EXAMPLES: L 'df0:c/dir' 60000 S df1:data 0 100 V df0:c Miscellaneous ------------- ? [n]{,}(n) : Calculate F (n)(c){@} : Define functionkeys P (s)(m) : Start graphic searcher 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 Calculator: 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 seperating the terms by a komma. Functionkeys: The 'F' command is used to set and view the functionkeys functions: - F [n][c] @ : Occupys Fkey n with commandline c that is executed directly - F [n][c] : Occupys Fkey n with text c - F [n] : Clears Fkey n - F : Lists Fkeys When you set a functionkey, the entier rest of the commandline will be taken for the command or text. When you list the functionkeys, the ones that are locked by Amiga-Fx are marked by an asterix, the directly executable have an '@' at the end. Graphic Searcher: The 'p' command starts the graphic searcher: - P [s][m] : Starts at address s with modulo m - P [s] : Starts at address s with last modulo - P [s] : Starts at last address with last modulo When you activated the graphic searcher, several keys are used for display modifications: Cursor up: Scrolls plane one line down Cursor down: 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 down: 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 Return: Switches between hires and lores Control: Ends graphic searcher The graphic searcher should recognize additional chipmem at $80000 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 and SIM copied to c s [p][b] : New display at p, new backup at b and SIM stays where it is s [p] : New display at p, backup and program stay where they are s : Repaints the display The 's command will mostly be used to transfere the display at another location when you want to look at the memory where the display is. 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. The old copy of SIM will still work, but its breakpoint and trap system will be confused. Use it only when the system is dead. Also do not copy SIM below $70! 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? : Starts to search 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. EXAMPLES: ? 256*5,52*56 F10 r:dpc pc@ F P 12356 52 s 70000 c50000 c40000 l* l=1 l? 20000 Debugger Window Support ----------------------- A [s] : Set new startaddress T [s]{@} : Set linkterm These two commands are used to set new startaddresses for the views of the debugger window. Startaddress: With this command you can directly set the startaddress of the active view: - A [s] : Set new startaddress of view to s Linkterm: To set a linkterm for a view, you use the 'T' command. SIM will calculate the result of this formula and use it as new startaddress each time it is entered: - T [s] @ : Set smart linkterm for active view - T [s] : Set simple linkterm for active view When SIM calculates a simple linkterm, it takes the result as new startaddress. The result of a smart linkterm is only used as new startaddress if it is not in the frame of 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 ======================= This is one of the later achievements done. You can switch it on or off by pressing . When you do so, a part of the wortable is locked for the cursor and used to print out the registers and one or two different views of the memory in different forms (hex, 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 startaddresses that are stored in m0 and m1. m1 is unused when you did not splitt the window and use only one view. You can link the two views to two formulas, the socalled 'linkterms'. 4.5 Debugger Window Shortcuts ============================= If you have to deal with the window, you do this by use of shortcuts that are qualified by either left or right Amiga. If you splitted the window, you can select the view that recieves the command by pressing . Window Handling --------------- Decreases the views startaddress and scrolls the content one line down. How much the startaddress is decreased depends on what the window output form is: - disassembly: the length of the instruction above the startaddress. - hexdump: 16 bytes. - asciidump: 64 bytes. - copperdump: 4 bytes. Increases the views startaddress and scrolls the content one line up. How much the startaddress is decreased depends on what the window output form is: - disassembly: the length of the instruction at the actual startaddress. - hexdump: 16 bytes. - asciidump: 64 bytes. - copperdump: 4 bytes. Decreases the views startaddress one or two bytes: - disassembly: two bytes. - hexdump: one byte. - asciidump: one byte. - copperdump: two bytes. Increases the views startaddress one or two bytes: - disassembly: two bytes. - hexdump: one byte. - asciidump: one byte. - copperdump: two bytes. Decreases the views startaddress and moves back to last page, depending on the output form: - disassembly: the sum of instruction lengths of the number of instructions fitting the window back from the actual startaddress. - hexdump: *16 bytes. - asciidump: *64 bytes. - copperdump: *4 bytes. Increases the views startaddress and moves to next page, depending on the output form: - disassembly: sets startaddress to the address of the instruction following the last one visible. - hexdump: *16 bytes. - asciidump: *64 bytes. - copperdump: *4 bytes. Decreases the size of the debugger window by one line. The minimum size is one line. The space that becomes free for the monitor is cleared with spaces. Increases the size of the debugger window by one line. The maximum size is as large as there stays one line for the monitor. If the cursor was in the line now belonging to the debugger window, it is moved to the line below which is then initialized. Works only when you splitted the window. This moves the bar seperating the two views one line up, which decreases the upper view and increases the lower view one line. Works only when you splitted the window. This moves the bar seperating the two views one line down, which increases the upper view and decreases the lower view one line. Splitts or unsplitts the window into two views. When you unsplitt, the startaddress and linkterm of the active view are taken as the one of the now single view, the ones of the inactive view are stored and taken as the ones for the second view when you splitt again. This recalculates the linkterm(s) and sets the views startaddresses again. Output Form Selection --------------------- Selects asciidump for the active view. Selects hexdump for the active view. Selects copperdump for the active view. Selects disassembly for the active view. Breakpoints ----------- Sets a simple Illegal breakpoint at the startaddress of the active view. Sets a resident Illegal breakpoint at the startaddress of the active view. Sets a JSR-breakpoint at the startaddress of the active view. Flow ---- Does a tracestep. Does a nextstep that does not follow into subroutines. Leaves out one instruction/puts pc to next instruction. Exits SIM. Exits SIM and goes back to debug server. Leaves a subroutine. Therefore SIM puts a STACK-breakpoint at the actual stackpointer and exits. Do not use this when the subroutine has allready put more data on the stack. Sets the pc to the startaddress of the active view. Edit ---- Starts to edit in loopmode at the startaddress of the active view. Starts to assemble in loopmode at the startaddress of the active view. Replaces the Instruction at the startaddress of the active view by NOPs. Indirects --------- <[> Goes to next higher indirectlevel and takes the longword at the startaddress of the active view as the new startaddress and stores the old one. <]> Goes to last indirectlevel and takes the stored startaddress as the new one. <{> Same as <[> but the longword will be taken as BCPL and multilied by four. <}> Goes to next higher indirectlevel and takes the stored address of that one as the new startaddress. Find ---- Continues to search at the startaddress of the active view. Continues to compare. The source address will be the startaddress of the first view , the destination address the startaddress of the second view. Miscellaneous -------------

Toggles the printer on/off. The printer can only be activated if there is an active one connected to the parallel port. Makes a hardcopy of the actual display by printing it as text. Toggles between US keymap and custom keymap (originally CH) Flushes keystatefield, see chapter 'the keyboard'. Toggles keyboardbuffer killer, see chapter 'the keyboard' <\> Toggles Auto-Unmodify Traps. When this feature is switched on, all modified traps are set again when you leave SIM. Toggles availability of funktionkeys. <0-9> Takes one of the ten position memories as the startaddress of the active view. Works only with the keypad! Stores the startaddress of the active view in one of the ten position memories. Most of these shortcuts are only functioning when the debugger window is activated. Only ,

,,,,,,,, and are allways functioning. ******************************************************************************* 5. Additional Information ******************************************************************************* Assembler and Calculator Syntax =============================== The assembler used in SIM is entierly home-made and is fully motorola compatible. Anyway, some special features have been added to increase userfriendlyness: - You can use 'add' instead of 'addi', 'adda' and 'addx -(ax),-(ay)' This is also valuable for 'sub'. - 'cmpm', 'cmpi' and 'cmpa' can be replaced by 'cmp' - You can use 'eor' instead of 'eori'. This also works with 'and' and 'or' - Bcc xxxx, DBcc Dx,xxxx, xxxx(PC) and xx(PC,Rx) use absoulute addresses. This means that when you want to have a code like 60010: bra $60000 you can enter 'bra $60000'. If you want to give the offset directly, you have to put a '+' or a '-' in front of it: 60010: bra -$12 But remember: The Offset has allways to be: (targetaddress-instructionaddress+2) - If no size is given, Bcc will be short if possible. - If no size given, direct addresses are word if possible. - DC.W or DC.L can be used, but only one value is allowed. - If you do not give an instruction size, the default size is taken, which in most cases is WORD. - The interpreter is very tollerant, even a line like move.l ( $75 ) ( PC , D7.l ) , ( $4 ).w will be accepted and assembled correctly. ------------------- The calculator used in SIM is also entierly home-made. It disposes of several very useful operations and value forms. The calculator is used when you have to enter a number. Just have an overview of the operations supported, sorted by their priority: - - Prefix change: Changes a positive value to a negative and vice versa. ~ - Logical NOT: Changes the state of all 32 bits of the value. For example: ~5 is -6. .s - Size a value: Any value will be extended to LONG from the size you define. For example: $89.b will then be made to $ffffff89. The size given is also important for the assembler when using direct long or short address. [] - A value in these brackets will be used as an address and the content of the memory at that address will be taken. A size directly after the closing bracket will define if the value will be taken as a BYTE, WORD or LONG and extended to LONG. For example: [4].l gets the execbase ($676 or $c00276) [$dff002].w reads out the actual DMACON as a WORD. *,/ - Multiply or divide long, considering if the values are positiv or negativ. For example: -$56*5 is fffffe52. \ - Gets the modulo of a long division. For example: 11\4 is 3. +,- - Addition or Subtraction, allways long. << - Shift value left: this corresponds to a multiplication with 2 to the nth power, whereas n is the numer of bits to be shifted. For example: $20<<8 is $2000. >> - Shift value right: this corresponds to a division by 2 to the nth power, whereas n is the numer of bits to be shifted. For example: $2000>>8 is $20. & - Logical AND. ! - Logical Exlusive OR | - Logical OR <> - Not equal: If the two values are not equal, this returns true (=$ffffffff), otherwise false (=0). = - Equal: If two vales are equal, this returns true. <= - Less or equal: Returns true, if the first value is less than the other or at least equal. => - Higher or equal: Returns true, if the first value is higher than the other or at least equal. > - Higher: Returns true, if the first value is higher than the other. < - Less: Returns true, if the first value is less than the other. As for the forms of values, SIM understands these: $x - Hexadecimal number: A number in hexadecimal form consisting of max. 8 digits 0-9 and a-f. #x - Decimal number: A number in decimal form consisting of digits 0-9. %x - Binary number: A number in binary form consisting of max. 32 digits 0 and 1. "/' - ASCII chars: A number consisting of max. 4 ASCII chars. f.e.: "SIM!" or '!MIS' ! - Stands for the last result. This enables you to do things like: m 61f35 !+39dc = "Show memory from $61f35 to $61f35 plus 39dc". @ - Stands for the actual address. This is the address, SIM uses as standart workaddress for dump commands. SIM - The program and base address of SIM D0-D7,A0-A7,PC,SP,SSP,USP,SR,CCR and M0-M7 - The registers. The calculator can directly use the content of these registers. SSP is the supervisor stack pointer, USP the userstack pointer SP and A7 the actual stack pointer. I.E. when you are tracing a program, and you want to know, what is at the address 56(a0,d7.w), you can use 'm 56+a0+d7.w'. The end of a term is usualy set by a space, a komma, a semikolon, a doubble point or a . Actually, when 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. Not to forget: some 120 brackets are allowed, more than you will ever use. Actually the calcualtor can work in decimal or hexadecimal mode. In decimal mode you do not have to write the '#' before a decimal number, but for hexadecimal numbers, the '$' is neccessary. In hexadecimal mode you do not have to write the '$' before a hexadecimal number, but for decimal numbers, the '#' is neccessary. Hexadecimal mode is usually used to get addresses (s,e,t,b,p) or hexnumbers (x). For all other cases decimal mode is used, also for assembler. 5.2 Line Forms ============== There are two types of lines you have to differe: the command line and the data line. - The command line is the one that contains the different commands you want to execute. This line has usualy that form: . (: ...) You see, you can enter several commands in one line, seperated by a doubble point. The doubble point 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). - The data line is of another kind. Whenever you have to enter datas directly, for edit, find, occupy etc., you enter a data line. This dataline can consist of this four elements, allways seperated by a komma: - Hexnumbers: Are introduced with or without '$'. They can be as long as you want. The hexnumber is ended by a char that is no number and not 'A','B','C','D','E' or 'F' (lower case letters also included) 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', 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 . Now an example, using all the elements from above. You enter: 45,"BDH",njmp $60000,?[$fc0000].w,6666 And the result are these 14 bytes: 45 42 44 48 4e f9 00 06 00 00 11 11 66 66 |- |------- |---------------- |---- |---- | | | | | 45 "BDH" jmp $60000 [$fc0000].w 6666 A dataline ends at a space or an illegal char. Between the komma that seperates two datatypes and the next datatype there can be spaces. also between hexdigits (only when editing, not find and occupy). 5.3 The Debug Server Entrance ============================= The debug server entrance is specially concieved for the cooperation between SIM and another debugger or loader, i.e. SIM-BUG. It enables The debug server to give control over a program to SIM and SIM to return control to the debug server. How this is done? Well, in a part of the SIM base, there is space to store the registers d0-a6, USP and SSP, SR and PC of the program that is monitored. The debug server can fill in this table. Additionally, It can specifie a reentry PC, SR, USP and SSP. When it enters SIM by the debug server entrance, SIM takes the registers out of the table and copies them into the workregister buffer. SIM has now the control over the program. Now, when you are in SIM and want to give control back to the debug server, you can use the 'q' command (or 'Q' or AMIGA-q). SIM does then copy the workregisters back into the base area and takes the reentry PC, SR USP and SSP 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.4 The SIM Base ================ At the start of the SIM program, the differente entrances are located, the backups and reentry values and the debug server datastructure. 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. -------------------------------------------------------------------------------- The S.I.M. Base Structure -------------------------------------------------------------------------------- ;--- Base --------- struct toolbase ;+0 The startadress of S.I.M. in memory ;--- Display ------ aptr plane ;+0 The startaddress of the $5000 bytes display ram (must be chipmem!) aptr backup ;+4 The startaddress for the backup of the display. When not zero, S.I.M. will copy what is in the memory of the future display to this part of memory when entered and copy it back when left. ;--- Entrances ---- jmp entrance1 ;+8 Entrance for JSR. Here you can simply enter S.I.M. by a 'JSR to this address. jmp entrance2 ;+12 Entrance for Exec's traphandle. When you want to use S.I.M. as traphandler of your task, write this address to . jmp entrance3 ;+16 Debug server entrance. long 0 ;+20 *** RESERVED FOR EXPANSION *** ;--- Our 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 S.I.M. long version ;+68 Version of S.I.M. as 4 ASCII chars ;--- Backups ------ ;when S.I.M. 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 $68 long level3 ;+82 $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 S.I.M. 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 preference structure ;--- Debug -------- ;Debug server structure for entrance 3. long 0 ;+128 Offset from base 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 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 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, currently unused aptr 0 ;+232 Segmentlist, currently unused aptr 0 ;+236 Symbollist with labels, currently unused ;--- End ---------- ;+240 This is the end of the actual structure -------------------------------------------------------------------------------- 5.5 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 'effective address' is not allowed. In fact it has not allways to be an effective address for the assembler uses the same routine for all source- and destinationterms. illegal size: An instruction has either no size at all or does not support the one you have given. illegal operator: An operator is not just as it should be. 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 assembler is suprised to find that char. 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: You have opened more brackets than you closed or vice versa. 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. SIM errors: too much: The startaddres given for a command is higher than the endaddress. 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. Diskaccess errors: disk error: Something went wrong with the diskaccess, 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 diskaccess display. file not found: SIM could not locate the file you want to load or a directory in its path. not enough space: When you want to save a file, SIM first checks if the file would fit. If it wouldn't, this error is returned. disk full: That error should not occure. directory error: If something goes wrong in the line of the listing of the directory, i.e. bad hashes or disk damaged, this error is returned. illegal path: SIM cannot locate the directory you want to list. ******************************************************************************* 6. Greetings, Thanks, Support and about Future Releases ******************************************************************************* 6.1 Thanks ========== Big thanks must go to my friend Daniel Weber for continuous testing of all new features I inserted, some good and some bad ideas and severe criticism of all the work I did. Thanks must also go to all the other people who reported me their ideas and gave bugreports: Christian Schneider, André Dietisheim, Oliver Fehrlin, Stefan Strasser. Also to Yello, Depeche Mode, Kitaro, Star Inc., Mike Oldfield, Guru Josh, Enigma, New Order, Vangelis, J.M. Jarre, Harold Faltermeyer, Art of Noise, Alan Parson Project, Die Toten Hosen and Megatron for cool background music. 6.2 Greetings ============= Greetings go to all members of my crew, to my few contacts, to the makers of Amiga Action Replay (especially Lord Olaf), to SCA (for the RomCrack), to Graftgold for converting Rainbow Islands and to all Beerbrewers (for beeing). 6.3 Support =========== The following is a short list of products supporting SIM. - FlyMon (assembler monitor) - NOG2 (trap- and exceptionhandler) - ProAsm (integrated editor/assembler/debugger) - SIMBUG (SIM loader) You are welcome to contact me if you want detailed information about how to support SIM correctly in your own programs. If you code a program that will support SIM, you are also welcome to tell me so, not only because the list would become longer, but also because the tools that may dispose of SIM support are surely of a kind I like and will use. 6.4 About Future Releases ========================= Version 1.51 is definitely not the ultimate release of SIM, there is a lot of room for improvements and new features. My intention is to make a version 2.00, a realy final one that will be PERFECT. Unfortunately, I will not have much time for that until July 1991, it may take quite some time for it to be released. The People who send me the money for this version, and only those, will get it as soon as its finished. If you have questions, bugreports, ideas for new features or complaints or if you simply want to contact me, write to: Stefan Walter Finsterruetistr. 57 8135 Langnau SWITZERLAND Or dial Switzerland/01/713 01 46, from 18.oo to 20.oo. Enjoy! Stefan Walter 27.Jan.1991