$VER: COP Doc 1.10 ***************************************************************************** ** ** ** ___________ ** ** \ */ ** ** /----------- ####### ####### ######## ** ** | ^ | ## ## ## ## ## ## ** ** | _\ ## ## ## ## ## Version 1.57 ** ** | | ## ## ## ######## ** ** | --| ## ## ## ## ** ** +-----/ ## ## ## ## ## ** ** | | ####### ####### ## (c) 1993-1997 THOR-Software ** ** ** ** ** ** A Low Level Debugger for all Amiga Systems ** ** ** ***************************************************************************** by _______ _____ _____ __ _ / / / / / / / \/_/ //_/_ / /____/ / / /____/ ___ / ____// / _ __ / / / / / / \ / /|/ / / / /_/ / /\_/_/ / / / /____/ / / _/__/_/ /__/|_/_/_/ /_/_/ /_ / +-----------------------------------------------------------------------+ | | | This release of COP is full FREEWARE... | | ...but possibly the next release won't. | | | | You are free to copy this program, as long as: | | | | - All files in this drawer are included. | | - ALL COMERCIAL USE IS STRICTLY PERMITED : | | DON'T SELL WITHOUT PERMISSION OF THE AUTHOR ! | | DON'T INCLUDE IN COMERCIAL PRODUCTS OR ARCHIVES WITHOUT | | PERMISSIONS OF THE AUTHOR ! | | | | This program is provided "as is" without warranty of any kind. | | The entire risk of using it is to the user himself. In no event I | | 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 must not use COP. | | | +-----------------------------------------------------------------------+ _____________________________________________________________________________ The THOR-Software Licence This License applies to the computer programs known as "COP". The "Program", below, refers to such program. The programs and files in this distribution are freely distributable under the restrictions stated below, but are also Copyright (c) Thomas Richter. Distribution of the Program by a commercial organization without written permission from the author to any third party is prohibited if any payment is made in connection with such distribution, whether directly (as in payment for a copy of the Program) or indirectly (as in payment for some service related to the Program, or payment for some product or service that includes a copy of the Program "without charge"; these are only examples, and not an exhaustive enumeration of prohibited activities). However, the following methods of distribution involving payment shall not in and of themselves be a violation of this restriction: (i) Posting the Program on a public access information storage and retrieval service for which a fee is received for retrieving information (such as an on-line service), provided that the fee is not content-dependent (i.e., the fee would be the same for retrieving the same volume of information consisting of random data). (ii) Distributing the Program on a CD-ROM, provided that the files containing the Program are reproduced entirely and verbatim on such CD-ROM, and provided further that all information on such CD-ROM be redistributable for non-commercial purposes without charge. Everything in this distribution must be kept together, in original and unmodified form. Limitations. THE PROGRAM IS PROVIDED TO YOU "AS IS," WITHOUT WARRANTY. THERE IS NO WARRANTY FOR THE PROGRAM, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. IF YOU DO NOT ACCEPT THIS LICENCE, YOU MUST DELETE ALL FILES CONTAINED IN THIS ARCHIVE. _____________________________________________________________________________ I) Who should use COP ? ------------------------ - If you prefer working with the workbench or if you write programs in pascal or (ARGH) basic, if you do not know how to use an assembler or are not familiar with bits and bytes, if you hate command interpreters and like funny gadgets and colorful menus, if you do not know the ASCII character codes by heart : **======================================================** || FORGET IT ! STOP NOW ! YOU WON'T BE HAPPY WITH COP ! || **======================================================** To make it short: COP is intended to be used by REAL MEN ! (-; (or WOMEN...) (Read also: "Real men don't eat quiche" available on in good networks...) II) COP Features ---------------- Let's start with the bad ones: o) it looks like an old-time debugger and feels like it, too o) there's no graphic user interface o) it's based on a command interpreter o) it's hard to learn o) it supports the MMU only partially, although this is getting better. The MC68040 and up MMU is completely unssupported as I have no documents about it. (STOP HERE IF YOU DO NOT KNOW THE WORD "MMU" !) o) it should support almost all MC68xxx, although I haven't tested it o) some features are available only with additional hardware, e.g. a MC68010 or higher or an external terminal o) some commands are available only with the 2.0 roms or better o) the build-in terminal emulation isn't a fast one and does use non-standard command sequences o) it does not handle fragmented memory models in a good way, although it's getting better o) there is no trackdisk or harddisk support and there never will o) it does not use task switching, but busy-waits (ARGHH!) Some of the points WILL change in the future, I promise... ...and now the good ones: o) it does support all members of the MC68000-family, at least it should... (MC680000 thru MC68060 including FPUs, but not yet the MMU of the MC68040 and MC68060 - sorry....) o) it provides a break key that can be assigned to all (well, almost all) keys on the keyboard and that breaks almost everthing everytime. o) it uses hardware resources as less as possible (e.g. no blitter acesses, no copper on request) o) COP can be used to remote-debug a system over a serial connection, leaving the display and keyboard hardware to other programs o) COP catches almost all system crashes ("GURUs") o) COP can be used to debug almost all code, even interrupts are NO problem (is there a second debugger who can ?) o) it can be made resident to debug startup code o) it supports symbols in its own language and the symbols in object modules. Source level debugging, however, is not supported. o) it has a funny documentation in broken english (speak you english ?) o) this new release supports printers, connected either to the parallel port of your Amiga or to an external terminal, provided it supports the new COP 5 terminal standard (see terminal.doc in this archive for more information) o) it can be loaded to a memory position of your choice, although the arguments are a bit tricky o) it's free, at least this release... o) it steps thru everything, even interrupt code and supervisor programs. YES, exec's task scheduler is NO PROBLEM AT ALL. o) it can be used as a shell calculator and as a label database. o) it supports symbols in standard overlay segments (which other debugger does ?) o) it supports debugging of CLI/WB progs in C and BCPL thru a simplified interface o) it works in really almost all situations, even with execbase broken... o) it supports the ShapeShifter o) it is compatible to the Enforcer if used with a MC68020 or MC68030. It does, however, not support the CyberGuard, at least I had no chance to test it. ...and if I say "almost all" I mean: more than any other debugger can, but I am honest: There are situations where COP CAN crash, but they are VERY rare. III) Before you start, you need to provide... ----------------------------------------------------------------------------- (or, in other words: NOT included in this package...) - a lot of good will and your brain. COP is not easy to use... - this manual. Or to make it clear : READ THIS FIRST BEFORE YOU START PLAYING WITH COP. There's a good chance you'll crash your system. - an amiga computer with at least 512K. The more memory, the better. - If you want that magic break feature : A processor MC68010 or higher would be fine. The break key does not work in all situations with the standard MC680000. - If you need all commands (e.g. task capture and task freeze), you need commodore's 2.0 roms or better. - If the program to debug needs the display subsystem, you need at least an external serial tty terminal. - If you want a fancier and better user interface, the external terminal should understand type-3 terminal commands or better. Cause this is a private format, there are not many... :-) You may write your own terminal, or use the one supplied in this package, see "terminal.doc". - If you need printer output, you need either a printer connected to the parallel port of your Amiga or a printer connected to an external type-5 terminal or tty-terminal with printer-support. Any printer will do, COP outputs only plain 7-bit ASCII, but laser printers that need an ASCII FF (formfeed) command to start printing are not supported. Use the following configuration for your printer: o) data input from parallel interface o) Auto-LF on, CR disabled (Auto-CR does not care) This is, however, the most common setting, so just try. The normal setting will work in most situations without any change. If you MUST use the Amiga parallel port, use the command line switch BUILDINPRT or the IOCD.Q command to disable external printing. IV) Installing COP in your system ----------------------------------------------------------------------------- If you want to remote-debug your system: connect an external ASCII-terminal to the serial plug. Set the external terminal to the following parameters: 9600 baud, 8 bit, 1 stop bit, no parity, no auto LF, no auto CR, non-erasing BS If your external terminal supports printers, connect the printer to THIS terminal, not to the Amiga; if not, connect the printer to the parallel port of the Amiga and use the IOCD.Q command or the command line option BUILDINPRT to tell COP to use the build-in printer-routines. Copy the COP file to the C:-drawer of your system disk and, if you like to start COP from the workbench, copy the COP-icon anywhere you want (it is not necessary, only a nice feature ). Copy the shell scripts "Debug","WBDebug" and "Calc" to the S: drawer, put this file in a save place wherever you want. If you have commodore's V40 includes, copy the default data description table "Startup.DDT" to S:. You might want to modify it a bit, for example to correct the pathes. This file currently expects the FD files in a device FD:, and the includes in INCLUDE: If you want to run COP with the shapeshifter, copy the file "Mac.DDT" to S:, too. Insert in your startup-sequence DIRECTLY FOLLOWING to the "SetPatch"-command (this is the second line for most systems) a command like the following: COP keymap usa display resident ddt s:startup.ddt What does this mean: -The build-in terminal uses the keymap "usa". If you prefer a different keymap, change "usa" to your favourite keymap that must be present in the DEVS:keymaps drawer of your system. YOU CAN'T CHANGE THAT KEYMAP WITH A "SETMAP" or "SETKEYBOARD" or the PREFERENCE PROGRAM LATER ! COP OPERATES INDEPENDED FROM THE REMAINDING SYSTEM ! -The "display" command tells COP to use the build-in terminal instead of an external one. You can debug programs with the amiga keyboard on the amiga monitor. If you want to remote-debug, use "serial" instead. If you've got an external tty, I would suggest to do so. -The "resident" keyword tells COP to stay resident even after reset. If you do not need this feature: drop this argument. -The "ddt" keyword loads the standard labels placed in the ddt-file and commodore's include files into COP. If you don't have them: Never mind, just delete the the last two arguments. More about the command argument line later... (chapter XI) You should also start the workbench with the "-debug" option to have COP ready in all situations. Save the modified startup-sequence and reboot your system. Not much to see ? O.K., that's normal. COP is NOT a standard debugger and is only INSTALLED by the command line, but not STARTED. V) How to start COP ----------------------------------------------------------------------------- There are many ways to begin a debug session with COP: -Double-click the COP-Icon, if you copied it to your system. -Enter in the shell the command: COP go -Select the "ROMWack" (or "Debug") menu of the workbench. COP replaces the old wack completly, if there was one installed in your ROM. (Commodore removed the old ROM-Wack from the 3.1 Roms and replaced it with the SAD debugger.) -Press the BREAK-key. In the build-in terminal - if you supplied the "display" argument above - this is the decimal dot of the numeric key- pad. On external terminals, it's ESC. However, you may change that key with an additional argument, see chapter XI. -Use the shell-scripts "Debug" and "WBDebug" to load programs, symbols and start a debug session like with every other debugger. Up to eight arguments are allowed here as CLI arguments, resp. one as an extended selection icon "clicked" with the main icon. -The least pleasant way : Your system crashes and COP is entered auto- matically. There are NO GURUs any longer, COP catches them all ! If you supply a data description file (see below), you even get the guru codes in a readable language. VI) How to leave COP ----------------------------------------------------------------------------- Enter GOPG in the COP command line and press RETURN. This should start the program interrupted. If you entered COP by a guru, you should first debug the system or will get just another guru in mostly all cases. There's no good strategy to accomplish this task.... You may also start the old ROMWack from inside COP with the EXIT command. Starting with ROM versions 3.0, the system debugger has changed to the (more primitive ? different ?) SAD. See the autodocs how to use this thing... VII) A word about COP-terminals ----------------------------------------------------------------------------- You will normally use COP's build-in terminal to debug code, but this terminal will, of course, need some of the hardware systems - the display system, i.e. the copper and the display DMA channels (not the blitter), and the keyboard, also the parallel port if you want to print. I tried to implement the terminal as best as possible, but this may conflict with other programs which want to use the same hardware resources. For this reason COP can also be used to debug a system via the serial port. All you need - for the minimum configuration - is an external ASCII-terminal,e.g. a second amiga with a standard terminal program will do it. In this case, choose the following transfer options: 9600 baud, 8 bit, 1 stop bit, no parity no auto CR, no auto LF, nonerasing BS However, things are much easier if you use a terminal program providing COP's private terminal formates, here called type-3 or better terminals. The terminal transfer standard is documented in the "Terminal.doc" file in this drawer, if you want to write your own program. There are only two ready made programs supporting this standard: -THOR's "Terminal" program for all Amigas provides a type-4 terminal emulation and is included in this drawer. Enable the "COP Terminal Emulation" from the menu Settings/Protocol. You also need to supply a zero-modem connector, but you should know how to build one... -THOR's "DASB" terminal is a full type-4 terminal, working on Atari 800XL computers with a serial interface box. Freaks may order it from me (see address below). There are no settings to be made, DASB is written only to communicate with COP, but does not support a printer. This drawback arises from the Atari XL hardware. If you want to write a COP terminal on your own (e.g for a C64) you are welcome ! Please send me a mail in this case. The build-in terminal for non-remove debugging is of course a full type-5 terminal. Here, a word about the keyboard processor of the build-in terminal: I tried to write a keyboard parse code not conflicting with other applications, i.e. it does not read the IRQ-registers of the CIA- chips and is able to work even with all interrupts disabled. However, there are "some" drawbacks of this magic stuff : Sometimes a key may leak thru the keyboard parser to other applications. Because the corresponding key-up event is missing, the keyboard device will then activate the auto-repeat loop and generate many key-events. If this happens, leave COP and press the repeating key to stop it. Even worse, you wouldn't recognise this bug if the affected key is a control key like "Ctrl" or "Shift". If, after leaving COP, the key- board seems to be out of order, try pressing all this keys first to send their key-up events. I tried hard to fix this bug, but it looks like there's no better way to write a magic keyboard parser. If you want to use COP the professional way, you should work with an external terminal anyhow. VIII) How to enter commands, the line editor ----------------------------------------------------------------------------- Once you've entered COP, it presents you the prompt "COP >" and is ready to accept debug commands. Below the special keys used for line editing: -The backspace key erases the last character entered and moves the cursor backwards one line ("Delete" on some terminal). On some terminals, Ctrl-H must be used as a substitution. -The delete key ("rub-out" on some terminals, Ctrl-Backspace with DASB, not available on all terminals) deletes the character under the cursor and scrolls the rest of the line backwards -The return key starts the execution of the command ("Enter" on some keyboards) -Ctrl-C aborts the execution of a command. -Ctrl-U re-displays the last command entered - there's only a two-line history for commands, identical and empty lines will not go to the history. -The decimal dot on the numeric keypad (for the build-in terminal) or the ESC-key on external terminals stops execution of code and enters COP. However, this break feature wouldn't work if all interrupts are disabled or, if you use the MC68000, the interrupt vectors are messed up. -The cursor-forward-key moves the cursor forward one character (only type-3 or higher terminals) -The cursor-backward-key moves the cursor backwards one character (only type-3 and better) -The cursor-up key moves the cursor to the begin of the line (type-3 and better only) As a replacement, Ctrl-A can be used for this task with TTY-terminals. -The cursor-down key moves the cursor to the end of the line (type-3 and better only) A replacement for this key is Ctrl-E. -The Alt-Del key or Ctrl-Clear (with DASB) erases the whole line (type-3 only). This feature is available with Ctrl-B on all ASCII terminals. -The TAB-key has a special meaning while entering data sequences and is described below. IX) The COP commands and expressions ----------------------------------------------------------------------------- Each COP command looks like the following: - a four character command base name or a one character abbreviation - optionally a dot and an extension that determinates a specific sub-command of a larger command class - optionally arguments each separated by space ALL numbers accepted by COP MUST BE GIVEN IN HEXADECIMAL, all arguments may contain simple calculations with numerical operators. This will be called an EXPRESSION in the following, abbreviated with . Here all supported operators, listed by their priority from low to high (higher priorities are evaluated FIRST, please note that the priorities differ from C!): $ trap operator a$b returns a if b is faulty, else a. NOTE: You cannot enclose $ in brackets, so expressions like (2$a+b)-3 are ILLEGAL ! The reason for this is that COP can't continue to evaluate expressions with illegal syntax that will be trapped by $ ?,: C-style condition operator: a?b:c returns b if a is not equal, else c =,<> equal, not equal: returns -1 if expressions to the right and left are equal (resp. not equal) or 0 otherwise. >,>=,<,<= signed greater, greater equal, smaller, smaller equal. Returns -1 if the condition is true. | binary or ! binary or ^ binary exclusive or (XOR) & binary and +,- addition, subtraction >>,<< shift left or right. The left expression is shifted times the right expression *,/,% multiplication, integer division, modulo [..] indirect operator: the value is the (long) content of the address specified by the expression between the braces, e.g. [4] is ExecBase. [..].l same as [..] [..].w indirect operator, returns the (sign extended) value of the word at the address in braces [..].b indirect operator, returns the (sign extended) value of the byte at the given address [..].o the operator size is determinated by the instruction under the program counter. NOTE: There is a slight difference if you read a word or a long from an even or odd address. Reading from an even address is only ONE memory access, but reading from an odd one are TWO or FOUR accesses. While not a problem to normal memory, this is a difference for hardware registers ! (..) normal brackets: expression in the brackets is evaluated first - unary minus, i.e. change of sign ~ unary not > unary greater. This symbol contains the last address affected by COP and is called the "here" address pointer. It is affected by almost all commands and can be used for saying the new command should "work on the same address" as the last one. * unary star. This symbol contains the program counter of the CPU and is equivalent to ".pc" .b,.w,.l,.o Sign extension operators. Will interpret the preceding ex- pression as byte, word or long and sign-extend it. So $ff.b is -1, but $ff.w is $000000ff. The .o is again the sign-extension to the operator size of the instruction under the PC. There is a small, but noticeable difference between [adr].b and ([adr]).b ! The first will read only ONE BYTE from memory, the later FOUR BYTES but throwing away three of them. This DOES make a difference if you read a hardware-register ! .reg or 'reg The content of the CPU register .reg or Valid registers are .d0 to .d7 for CPU data registers, 'reg' .a0 to .a7 for address registers - note that the meaning of .a7 changes with the supervisor bit - .ssp and .usp for the two stack pointers .pc (same as *) for program counter and .sr for the status register (there is NO .ccr, use proper masking). Also, there are 16 COP internal counter registers .c0 to .cf. They are incremented each time they are read and can be used to implement counter breakpoints. For some commands .fp0 to .fp7 are valid and address the eight FPU registers, if a FPU is installed and used by the program debugged. .sr,.se,.so .dr,.de,.do These pseudo registers refer to the source and destination effective address of the command under the program counter. .sr is the contents of the source register under the PC, if available .se is the effective address of the source operand, if available .so is either the content of the source register or the CONTENT of the effective source address .dr,.de,.do Same for destination effective address You may alter all these registers to effect the source or destination operand of an instruction. Although not causing an error, changing .se and .de does nothing usefull. Additional, all supervisor registers of the 680x0 series can be viewed, as long as your CPU does support them. In this release of COP, the MMU registers can be changed, but won't be written back... A new special register .vvbr has been introduced in release 1.32: The .vbr register refers always to the VBR of the CPU, but since COP needs this register to operate proberly, you should not change VBR this way. Whenever possible, check the value of VBR, and if it is changed, write the new value not to the VBR, which will confuse COP, but write it to VVBR, and restore VBR to the value of the label COPVBR. COP will then filter out its own exceptions and pass the unused ones back to the system thru VVBR as if the VBR has been set. The change of VBR will now be detected by COP if the interupt check (ENVI.I) is turned on, and the VBR register can be restored by SETR.V. The autovector table can be rebuild automatically using the IRQ-copyback mode, enabled with the ENVI.C command. \character The ASCII-code of the character following $ Unary $. The number following is given in hexadecimal AS THIS IS THE DEFAULT, THIS SYMBOL DOES NOTHING # The number following is given in decimal, i.e. #16=$10=10 % The next number is a binary number, i.e. %1000=$4=#4=4 label A known label will be evaluated. As default, there are only four labels: AbsExecBase will contain the value 4, thus is pointing to the pointer of the system library. Version Will contain the version of COP as Version<<16+Revision COPVBR will contain the interal vector base setup by COP. VBR should contain this value. DO NOT ALTER COP's vector base, use VVBR instead. COPVVBR will contain the default position of COPs virtual vector base. Some read-only expressions follow: (Not starting with a dot -> Not a (pseudo) register -> not alter- able !) l0 Left button of mouse or fire on joysticks connected to port 0, returns 0 if released or -1 if pressed l1 same for port 1 l0 and l1 might be quite useful as conditions in breakpoints r0,r1 Right button of mouse in port 0 or 1 m0,m1 Middle button of mouse in port 0 or 1 WARNING ! Some hardware limitation cause that it takes max. 20 msec to read r0,r1,m0,m1. This COULD be made somewhat faster, but nevertheless r0,r1,m0,m1 ARE NOT FAST ENOUGH TO BE USED IN CONDITIONED BREAKPOINTS. This also cause the POTGO-hardware register to be trashed. There is no way to save this register back, although there is a POTGO-read register - this is a hardware limitation. su,sr Information about addressing mode under the PC. su and du are du,dr TRUE if the source resp. destination operator of the actual instruction is used, sr and dr return TRUE if it is a register and FALSE if it is in memory. op Data type of the instruction under the PC, returns 0 for byte, 1 for word or 2 for long, so 1< Dump memory. If is omitted, then the "here" pointer is used as address, otherwise change "here" to the given . without extension Dump memory in the last mode used DUMP.B dump memory as bytes DUMP.W dump memory as words DUMP.L dump memory as longs DUMP.G dump a sequence of hardware bytes. The memory manager is beeing overridden by this. ! This might be somewhat danger- ous, if you read some toggle registers ! DUMP.H dump hardware word DUMP.I dump hardware long DUMP.Q dump as quad word (=8 bytes) DUMP.Z dump as single precision IEEE-numbers. You need a FPU to do this. DUMP.D dump as IEEE double precision DUMP.X dump as MC68881 extended precision DUMP.P dump as MC68881 packed decimal DUMP.O dump memory as size of instruction under PC DUMP.C Dump memory as characters. All unprintable characters are transcribed with a backslash and the numerical hex value followed. DUMP.S Dump memory as strings. All unprintable characters are displayed as a dot. After dumping a few lines, COP stops and asks you to press RETURN or SPACE to continue. You may press here Q or Ctrl-C to abort dumping. EDIT E B,W,L,C,G,H,I,Z,D,X,P,O Edit memory or hardware. If is omitted, then edit the address given by the "here" pointer. Else use the as address and save it to "here". In the edit mode, COP presents you the old contents of the address given. This value is now ready to be changed with the edit keys in the last chapter. Press RETURN to accept the changes made or press TAB to undo the changes. Press Ctrl-C to abort editing. Without extension use the last edit mode used EDIT.B edit memory as bytes EDIT.W edit memory as words EDIT.L edit memory as longwords EDIT.Z edit as IEEE single precision (FPU needed) EDIT.D edit as IEEE double precision EDIT.X edit as MC68881 extended precision EDIT.P edit as MC68881 packed decimal EDIT.O edit memory as size of instruction under PC EDIT.G set hardware as bytes EDIT.H set hardware as words EDIT.I set hardware as longwords The difference between the first group and the second is that the hardware edit commands do NOT read the hardware registers prior to the user change. Instead, a zero is always beeing displayed. Node that this is necessary cause some hardware registers are WRITE ONLY. In all the modes presented above, you may enter a full as well as a numeric constant as a new value, although the length of the is limited. EDIT.C edit memory as characters Here, you may edit the memory as ASCII-characters. You may use the backslash followed by a hex number to enter values not available on the keyboard. EVAL = none Evaluate the expression given and print the result. The result might be a simple number, but also very complex expressions including labels are valid. UNAS = none Unassemble code starting with address and set "here" to this value. If is missing, disassemble at address contained in "here". The disassembler knows the obcodes of all members of the Motorola MC68000 family, but the non-MC68000 codes are marked. FPU obcodes are disassembled as well, and if a FPU is available in your system, then numerical constants are displayed as decimal floating point expressions. If opcode is illegal, it is marked as well. Depending on your enviroment settings - see the ENVI comand - some of the addresses will be expanded in the known labels. NOTE: I was unable to test the correct disassembly of the MMU and MC68040 codes, although it SHOULD work. NOTE: There's one MC68040 code I was unable to find in any documentation. The code F518 is now disassembled as "illegal opcode" If the address beeing disassembled is the PC, this line is marked with an asterisk *; if it's the "here" pointer, the line is marked with ">". If the address is affected by a break point, a "B" is inserted. NODE N none Display the node at address . If is not present, use the "here" pointer, otherwise set "here" to the address of the node. The node's name and its type is displayed. This command will be enhanced in the next releases. LIST L M,R,D,I,L,P,T,S,Q,B Dump contents of exec-type lists. No extension Dump the list at given address, set "here" to this address. If is omitted, use the "here" pointer. B Same as without extension, but the list is traversed from the last element to the first. This is sometimes useful if parts of the list are broken. M Print exec memory list R Print resources D Print loaded devices I Print software interrupts L Print libraries P Print ports T Print tasks S Print semaphores Q Print hardware interrupts FILL F M , Fill memory with byte sequence starting with first and to last , exclusive. If one of the is missing, then "here" is used. Then "here" is set to the first . without extension Enter the byte pattern the memory should be filled with. Press TAB to finish one byte, press RETURN to finish the whole sequence and to start filling. M Fill memory thru mask (stencil fill operation). Enter first the byte sequence as described above, then enter the mask bytes. Each bit set to zero in the mask will protect the corresponding memory bit from a change. You may press Ctrl-C anytime to abort the operation. FIND G M,I Find byte pattern, masked, or find instruction starting with given address or "here". Set "here" to given expression afterwards. without extension Enter the byte pattern byte for byte pressing TAB after each byte and RETURN to finish the sequence you are searching for. M Find masked memory. Enter first the byte pattern you are searching for and then the mask. Each bit left to zero in the mask will disable the comparision of the corresponding bit in the sequence, i.e. the corresponding bit in the byte pattern will be ignored and will match always. I Find instruction. Enter the instruction or part of instruction you want to search for and press RETURN to start the search. Case and extra spaces will be ignored. You should note that all known labels will be expanded by COP unless the enviroment is changed. So you should enter the label-name instead of the address if you look for an access to a defined label ! You may press Ctrl-C to abort the searching anytime. MOVE M none ,, Move source memory block starting with first and ending with second argument exclusive to destination given by last . If any of the is missing, "here" will be used. Afterwards, "here" is set to the start of the source memory block. Overlapping memory blocks will be handled correctly. TASK ! F,W,S Task commands: display,freeze and warm tasks, send signals. without extension Display information about the task if is omitted and execbase is valid, the active task will be displayed. F Freeze the given task (exclude from execution). If the task to be freezed is the active one, this command will work with Kickstart releases 2.0 or higher only. W Warm the given task (include a previously freezed task to task switching). S Send signal to a task. You need to supply two arguments, FIRST the signal to be send and SECOND the task affected. SETR S F,E,D,V ,reg Set to given CPU register. without extension Move given expression to destination register. Valid destination registers are .d0 to .d7, .a0 and .a7, .ssp,.usp,.pc and .sr, and the COP internal counter registers .c0 to .cf. Note that the meaning of .a7 depends on the supervisor bit in the status register and is identically with .usp or .ssp. Starting with release 1.31, all other CPU supervisor registers can be set as well, but the MMU-registers are not written back (SIGH). If you need to change the vector basis register VBR of 68010 or above, you should change COP's virtual VBR called .vvbr instead to keep COP's exception vectors untouched. F Load FPU register, if FPU is available and in use by the program beeing debugged. In this case, is a floating point number in the usual notation (e.g. 3.1415 or 3E8 ...). E With MC68020 or higher: enable all caches. No arguments need to be supplied. D With MC68020 or higher: disable all caches. No arguments taken. V With MC68020 or higher: Set the virtual vector base address to VBR, setup VBR to point to COPs interrupt vector table. This command should be given (if it isn't already too late...) if a program changes the VBR to give back control to COP. STEP Z none Enter trace mode, start tracing at given address or use PC if is omitted. How the trace mode works, depends highly on the terminal type used to debug. On pure ASCII-terminals the command at the PC is beeing disassembled and dumped to the terminal; on type-3 or type-4 terminals however, an entire page of commands is printed. The command at the PC is marked with an asterisk and is beeing highlighted on type-4 terminals. With both types of terminals, COP is now ready to accept one of the following step commands by pressing the desired key: Q or Ctrl-C Abort trace mode and return to normal command line. S or SPACE Step the command at the PC. If this is a subroutine call, the subroutine itself will be entered in trace mode and can be stepped thru. T Trace the next command. The only difference between S and T is how subroutines are handled. With the T command, the subroutine is called as it and will be exe- cuted as whole without beeing stepped thru. N Next command. Almost like T, but works different with branches. The next command starts the program at the current PC and COP regains control only if the statement IMMEDIATLY FOLLOWING the traced statement is beeing executed. This will be the same as T for all commands but branch and jump commands. You may use N to step thru a loop as whole if you press N for the end condition branch of a loop. WARNING !! If this loop has a second exit point, the command after the end condition may never be executed and COP is never entered again. WARNING !! The next command works ONLY IF THE STATE- MENT IS IN RAM CODE and DOES CHANGE parts of the code by setting an internal breakpoint. See BRKP-section for a list of caveats of breakpoints. M Trace until. Almost like T, but the mecanism how COP regains control after a subroutine call is different. The 'T' trace changes the return address to COP's entrypoint. Sometimes this is bad, cause this address might get used by the called procedure. If you use 'M' instead, the called procedure will be stepped thru in 'S'-like behaivor using the CPU's trace-bit. Of course, 'M' will be much slower and should not be used if some piece of hardware is accessed or timing is vital. O Skip command. Do not execute the command at the PC and switch PC to the command following. WARNING !! Make shure that the command skipped does not anything important and watch out for side effects, e.g. skipping a "push long to stack" could be dangerous if the corresponding stack cleanup command is not skipped too. G Start program at current PC, activate all breakpoints. R Dump registers to terminal. B Set breakpoint at current PC address. Note that commands with a breakpoint on it are marked with a "B". Further, a breakpoint under the current PC is "delayed", i.e. that it is not beeing activated until the PC leaves its address. The breakpoint set by "B" will be an unconditioned type (see BRKP for more about breakpoints) A Alter display. If working with the build- in terminal, the COP display is hidden and the display of the program is brought to the monitor. The "A" command is like the "IOCD" command without extension, read this chapter to find more about COP displays. If you use the remote-debug feature, this command does nothing. F Set cop to foreground mode, i.e. COP does not hide its display if the program beeing debugged re- gains control. Press F again to activate the normal display swapping. This command works mostly like the "IOCD.F" command, read the "IOCD" section for more information about COP foreground and background mode. Some caveats about tracing are: ------------------------------- - COP does not depend on exec-like task switching, it is NO PROBLEM to step thru exec's task switching procedure. (This is not a caveat !) On the one hand a nice feature, on the other hand a problem if you want to debug a SPECIFIC task. Therefore, you should trace (T command) over a Wait() or Signal() call of exec- base. Next (N command) will work too, but if the same code is used by two tasks - think about the trackdisk code - you may catch a different task afterwards. Same goes for the 'M' command, but let me remind you again that 'M' is SLOW ! -The second problem with task switching is, that if an exec task looses control by stepping thru the task-switch routine, exec will save its status register with the trace bit on. If the task is reactivated later, COP will regain control over this task. While not a problem to COP, this behaviour might somewhat confusing to you, if COP is suddenly (probably after hours...) reentered - and not by a guru. -There's one extra problem with the trace (T) command : This commands works by altering the return-address of a subroutine call. Some programs use this return address to fetch data following the subroutine call and adjust the return address afterwards. Cause changed by COP, this will cause a nice crash of your system. So, if you find funny code behind a subroutine call, e.g. many illegals or the like, STEP thru this procedure or use 'M'. -Since stepping thru a procedure is much slower than executing one, there may arise timing problems in some critical IO-procedures. You should trace this kind of subroutines to avoid such problems. This goes again for the 'M' command, since this is nothing but "automated stepping". (That looks like a lot of "features" of this debugger, but they are typically for this class of programs. However, most authors handle them as "undocumented features", but I don't. :-) ) BRKP B A,D,C,R,S,O Breakpoint commands. The address affected is given by or by "here", if omitted. without extension If no breakpoint is set at supplied address, a unconditioned breakpoint is set there. If a breakpoint is set at this address, the breakpoint is removed. Note that COP supports up to 32 breakpoints. It is further important to note that after setting a breakpoint, it is not yet active, i.e. causes a COP inter- cept. The breakpoints are activated each time a program is restarted, e.g. with the GOPG command; they will get de- activated each time COP is entered again to prevent an endless loop if a breakpoint is set in interrupt code. However, the breakpoints can be activated by hand, although this is not recommended. BRKP.A Remove all breakpoints (no arguments accepted) BRKP.D Display all set breakpoints with conditions, no arguments accecpted. BRKP.C Clear breakpoint at given address BRKP.R Reset all COP counter registers .c0 to .cf to zero. BRKP.S Set breakpoint at given address and condition, if any. If the condition is omitted, then an unconditioned breakpoint is set. If a counter register is included in the condition, it is beeing re- seted to zero. With a conditioned breakpoint COP is entered on a BREAK hit only if the condition is true, i.e. not zero. You should remember that a counter register is incremented each time it is accessed, so you may use this feature to implement counter breakpoints, e.g. ".c0>=5" will stop execution after the 5th BREAK-hit. BRKP.O Activate all breakpoints (no arguments accepted). Note that this operation might somewhat dangerous if a breakpoint in an interrupt procedure gets activated. In this case, COP will display its "COP crashed" message... have fun. Some extra features of breakpoints are the "delay" of breakpoints and the automatic removal of them: -If you set a breakpoint under the current PC, this breakpoint won't get active if you start the program, but gets activated AFTER the PC leaves the statement. This is useful cause you usually never want to break on a command you already broke on. You will enter COP when the program reaches the breakpoint again. -If an already activated breakpoint is beeing written over by a program (e.g. the memory is freed and another task re-uses this area), this breakpoint is REMOVED automatically on the time COP is entered again. This is done to prevent programs from crashing by dangling breakpoints of a program that is no longer in memory. WARNING ! The breakpoint IS NOT removed, if it is not active at the time it is beeing written over. This MAY cause problems if the program changes and the breakpoint is re-activated later, e.g. the breakpoint may change the address part of a jump-instructions, possible resulting in a nice fireworks display... WARNING ! Active breakpoints change the code at their address to the ILLEGAL obcode. For this, BREAKPOINTS DO NOT WORK IN ROM. Second, if the code is changed, possibly some check- sums (for libraries or resident code) will change and things won't work later. For this reason, use the T S or M STEP subcommands to step thru this part of code, they DO NOT ALTER the code and work in RAM as well as in ROM. GOPG G U,T , without extension Start interrupted program at given address or at PC if is omitted. If any breakpoints are set, activate them first. A second argument is not accepted. U Go until Set a breakpoint at the first given and start the program at the address given by the second argument, or the PC if omitted. Read the breakpoint section about caveats of breakpoints ! T Trace until Step thru the program until the PC reaches the first expression. The second expression will be loaded into the PC if given. As the 'M' subcommand of STEP, this will be very slow ! CAPT C S,N,C [,] Capture a task, i.e. start debugging it. no extension Capture the task with task structure at supplied address. If is omitted, "here" is used. Afterwards, "here" is set to the affected task address. If the task uses the FPU, this capture command will work only with Kickstart release 2.0 or later, due to the exec private stack frame. S Like capture without arguments, but the first argument you supply is a signal mask which is send to the task before trying to capture it. The second argument is the address of the task structure. N Capture the next task beeing started. No argument must be supplied with this sub- command. Note that you might find the new task in the private dos startup code you have to step thru first. C Capture next command beeing started from the shell. This command works only with Kickstart 2.0 or later. IOCD O S,C,B,F,R,Z,L,M,V,P,Q,I,E Input / output commands, terminal commands (rather a lot of them...) without extension (does not take any arguments) If you work with COP's build in terminal, toggles between COP's display and the display of the program beeing de- bugged. This is not done by intuition or the like, but by PURE HARDWARE. For this reason, COP need to know the address of the copper list of this program, and with the ECS-chipset, the BEAMCON0 value. While both is available in the graphics library, you must set them by hand if execbase is destroyed or the program beeing debugged uses the hardware register to setup its display. While COP can almost always establish its screen, it is sometimes impossible to restore the programs screen completely - some hardware registers are write-only. In this case, you MUST use remote-debugging. If foreground or background mode has been active (see below) they are deactivated by the IOCD command. IOCD.S (does not take arguments) Toggle between build-in terminal and remote-debugging. If you switch to an external terminal, you should make clear that this terminal is online, or you might fail to enter a second IOCD.S to switch back to the build-in one. Everytime the terinal is changed, COP retries to get the terminals type to setup type-3 or type-4 communication. For more information about COP's internal terminal format and auto-identification read the "Terminal.doc" file included in this drawer. IOCD.C Set the address of the copper list of the user-program to re-establish the user's display. If is omitted, the "here" pointer is used. You won't need this command if you debug programs that use the "standard" graphic system, since COP extracs the address out of gfxbase itself. But if the user's program uses the hardware registers directly, COP does not recognize this change of the copper list. In this case, search with the FIND command for a write to the hardware register and set this value as user-copperlist with IOCD.C . It is seldom easy to find it, so good luck... If you have problems with programs using custom copper lists, you should try the interrupt driven display using the IOCD.I command (then you get trouble with interrupts instead of copper lists... ;-) IOCD.I (does not take arguments) Toggle between copper list driven display and interrupt driven display. The standard way for COP to display information is to setup a copper list and to load it into the hardware. Later on, if the program is started again, the system copperlist, which can be set by IOCD.C, will be loaded back. This will, of course, cause trouble if the program changes the copper list on its own. The best solution is of course to change to remote de- bugging using IOCD.S, but startig with release 1.30 COP can be forced to use a different method of display. The interrupt driven display does NOT use copper-lists, but uses the vertical blank interrupt to write the hardware registers. COP tries its best to keep the programs setting valid, e.g. if the program disables the interrupt, COP excludes the user VBI from running. However, this is really a bit tricky and may fail. A second drawback is, that the display produced by interrupts is much simpler and does, for example, not support line highlighting. IOCD.B (does not take arguments) Set COP to background mode, i.e. COP's display is never setup and the users display is kept active. However, you are still ready to enter commands. This mode is somewhat impracticable since you don't see what you write. IOCD.F (does not take arguments) Set COP to background mode, i.e. COP's display is not removed from the monitor (only execption: a GOPG command or the G subcommand of the STEP-command). Use this command to avoid that flicker, that occurs if the screen changes. There's one caveat with this command and the STEP-command: Since the displays are not swapped, the user program may destroy COP's display by writing to a hardware register or may get unexepected results reading a register while COP's display is active. So watch out and disable the foreground mode if you want to step this type of commands. IOCD.R (does not take arguments) Disables foreground and background mode and restores normal display swapping. IOCD.Z Set the screen size of the build-in terminal to lines. If is omitted, the actual display size will be used. The standard screen size is 28 (=$1C, remember COP always thinks in HEXADECIMAL !) lines, but this might be to large for some monitors. To prevent you grabbling at your monitor, this command can be used to setup a fitting display size. However, the screensize is limited to 8 to 28 lines and will always be centered. IOCD.L Setup the number of lines until COP presents its ***more*** message to ask for continue. This number is more an approximate value as some outputs can't be broken up into lines (for example the register display does never generate a ***more*** message). If is not given, the command uses the last value. (Remember that COP thinks in HEX, so 10 is not TEN but SIXTEEN !) IOCD.M Set the value to be written to BEAMCON0 if user display should be rebuild. This command is not necessary until an application uses the hardware registers directly. See IOCD.C and IOCD for more information about this feature. If possible, COP tries to build a NTSC-display, cause it is less flickering than a PAL screen. I think there should be no problems with this feature, even commodore's @#!?!-monitor does support 60Hz displays and most european TVs will do so too. If there are problems, use the next option to use a PAL display instead, or use the PAL command line option (see below). IOCD.V (does not take arguments) Toggles between PAL and NTSC display, if possible (ECS or better is required for this function) IOCD.P (does not take arguments) Toggles printer output. Not all commands cause a printer output, e.g. the edit and step commands do not, since they are interactive. IOCD.Q (does not take arguments) Toggles printer support via the build-in printer driver thru the parallel port of the amiga or the terminal connected to COP (this is the default). If you use the build-in terminal emulation, this command will make no difference at all, but with an external type-5 terminal COP will either print itself or tell the external terminal to start or stop printing. The later method is of course the better one, it does not take over the parallel port hardware. All IO-commands but the L,S,P and Q subcommand don't make sense in a remote-debug session and don't do anything in this case. IOCD.E (does not take arguments) This command does not take any arguments. It will send a FORM FEED control character to the connected printer, to eject the paper. This might be needed by some laser or deskjet printers. ENVI V R,L,I,B,X,E,M,F,D,C Enviroment settings, mode settings and so on. without extension Not valid. This command MUST be extended. ENVI.R (does not take arguments) Enter raw mode. In this mode, execbase is not used at all. There are much consequences of entering the raw mode: The display copper list and beamcon0 must be set by hand (with IOCD.C and IOCD.M), interrupts are disabled if COP is entered, all list commands depending on exec-lists, all task commands and all capture commands refuse to work. The EXIT command is not available, too. There is no message if these commands are still entered. All exceptions except interrupts cause now COP to inter- cept, even if there is an exception handler installed in the active task - normally it's no problem to run COP parallel to a "normal" debugger, but in RAW-mode COP will capture even its breakpoints. If you've entered the raw mode once, there's NO WAY TO SWITCH IT OFF LATER except a power up, so be careful ! You should use the raw mode if you MUST debug a program that uses the hardware directly. In most cases, it is necessary to use remote debugging too. If you must use the chip-mem buffer, you are REQUESTED TO USE the raw mode too, or you will run into BIG TROUBLE with task switching activity. ENVI.L Add memory section. Cause COP does not use the exec memory list, COP tries to find the memory portions in your system on startup, i.e. chip mem, fast mem and the kickstart ROM. However, COP cannot handle "too complicate" memory models, e.g. fast mem that is split in several blocks or memory that is not aligned to 64K borders. To fit your needs, you may add a memory chunk of your choice to COP's list. The first argument specifies the start address of the block, the second the (exclusive) end address, if both are equal, this memory block will be removed from COP's private list. This memory list is used for the FIND and FILL commands, memory is beeing scanned for all addresses in it. NOTE: Normally, the memory in an Amiga is typically not organized in a linear way, some memory parts are mirrored to others and the memory is possibly split into some chunks, e.g. if you have a memory expansion card in an old Amiga 2000B with ranger-memory (slowmem). In this case, your fast mem will fill the addresses 0x00020000 to ? and 0x000c8000 to 0x000d0000. In this case COP will search the total area from 0x00020000 to 0x00d00000, including some hardware registers in between. In this release, COP can not handle such complicated memory models, maybe later... (This is even better than pre-1.17 releases, which were un- able to work with A4000 memory models....) ENVI.I (no arguments) Disable the checking of changes of IRQ-vectors. Under normal conditions, COP checks the consistency of the MC68000 autovector table, used by COP to allow trace and breakpoint commands. If one of the entries are changed, you will be prompted by a message if it's O.K. to undo the change, to accept it (in this case COP writes the change back to its second vector table, which can be used by ENVI.F), or to ignore one or all changes. This change could be done by a faulty program, or by a program that wants to regain control over the whole system. In the first case it's better to answer U(ndo), in the later C(hange). If you use a MC68000, the address in the trace and illegal trap vectors are vital, and any change of them will prevent COP from beeing able to step thru programs. Also, COP needs at least one interrupt that occurs "often enough" to check the status of the break key. With a MC68010 or higher things are not that worse, cause COP uses the VBR register to move the autovector table to a different part of the memory. However, changes to the old table will be respected, although COP does not yet notice the change of the VBR register. In a case you notice that the VBR has been changed, set it back to the old value which can be found in the label COPVBR and place the new value in the virtual vector base called VVBR. If you disable the IRQ-checking, all changes to the autovector table are ignored. ENVI.C (no arguments) Enables the IRQ copy back mode. Instead of watching the low-memory vector base, COP keeps an eye on its own vector offset and copies the changed vectors on request to the virtual vector base. This option should be choosen if you want to debug a program that directly writes to the vector base, like ShapeShifter. The command line option "MacMode" enables this automatically. Be warned: Enabling the copy back mode disables the check for the low memory vector table, which normally used be the amiga OS. This check can be disabled with the ENVI.I switch described above and works of course only for the mc68010 or better. ENVI.B (no arguments) Toggles the ChipMem backsave buffer. The display build up by COP's internal terminal emulation needs some chip memory that might be occupied by the program you want to debug. If you want to prevent COP from overwriting this area, you must: o) provide a backsave area using the BUFFER keyword on the command line when COP is installed (usually in the startup-sequence) o) enter the ENVI.B command to enable this buffer o) you SHOULD use the Raw-mode to prevent conflicts with multitasking If the buffer is enabled, COP will backup the occupied memory area each time it builds its own display and will restore it, if the program's display is restored later. However, this backup mechanism is not (yet) fully trans- parent to other parts of COP, but the UNAS and DUMP commands keep care. It will therefor be convienent to place COP's CHIP hunk an uninteressting part of memory, e.g. the display buffer of the debugged program would be fine. To prevent problems with the blitter, COP will wait for the blitter beeing finished before swapping the memory. In all other cases the blitter will just be stopped. ENVI.X (no arguments) Affects the way the disassembler handles the indexed indirect mode with label generation. The default is, that the address which is used for label generation is given by the base register plus the index. This is most com- fortable if, for example, all entries of an indexed table have labels associated to them. If, however, you want to reassemble a part of code, this would be fatal since all assemblers calculate the displacement, which will be replaced by the label, as a distance to the base register without the index. So if you switch out the index inclusion, you will only see labels associated to the base of a indexed table. ENVI.E (no arguments) Toggle the label generation. If you do not want to see labels, for example in a search process looking for a instruction with specific address, you can switch out the label generation at all using ENVI.E ENVI.M (no argument) Toggle the build-in memory manager. This part of code in COP protects you from writing into hardware and non- existing memory, as well as it does the memory re- mapping for the chipmem-buffer. If, for special purposes, you want to disable this feature, use ENVI.M ENVI.F (no argument) Toggle the place where the exception vectors are stored. The default location is at address 0, but since this is chip memory, exception handling gets slow. If you use ENVI.F, the vector base will be located in the fast-memory. Warning ! ENVI.F does NOT change the vector base register at all, since it is pointing to COP's own vector base at any time. Instead, it says COP where to look for the system vectors, so changes only the virtual vector base VVBR. Warning ! ENVI.F will overwrite the virtual vector base register VVBR of COP in order to work ! So do not use this command if you setup your own VVBR. This command only takes effect if running under a MC68010 or better, since the plain MC68000 does not have a VBR. ENVI.D (no argument) Toggle the default input radix, with is set up as hex, to decimal and back. SPLT / C This command is available ONLY if you use the build-in terminal or an external type-3 or type-4 terminal. It won't work with a raw ASCII-terminal. COP has the ability to split of a part of the screen for displaying some information permantly. This information in then updated each time you enter a command or COP looses or regains control over the system. For example, splitting the screen and displaying the register set in the upper part of the screen while tracing is highly use- ful and is nowadays standard for all debuggers. Cause COP is "a little" different from that ones, you must enable this feature, and due to the raw display system, it's not available in general - a raw ASCII terminal can't split the screen. without extension COP displays a new prompt and you should enter a command that shall be executed each time the display must be updated. The output of this command is then displayed in a separated part of the display. It is possible to execute more than one command if you separate all commands by colons. The argument following the SPLT-command determinates the approximate size of the split-off part of the display (in lines; remember that all numerical values are HEX- VALUES by default !). If there's not enough room, not all commands will be executed. There are a few caveats to remember when using the SPLT- command: -Not all commands are splitable, e.g. the SPLT and the STEP commands. -Some commands are splitable, but it's not very useful to split them, cause they get executed each time the display is updated, e.g. the GOPG and the EXIT commands. -Almost all commands change the "here"-pointer. This is NOT true for commands executed in the split-window, i.e. they can READ "here", but do not change them. This is somewhat useful since, while tracing, the "here" pointer contains the address of the first command of the lower window, e.g. splitting the command "d.w" will dump the obcodes of the program in hex. Some useful commands for splitting: REGS will present a auto-updating register dump NODE .a6 will print the name of the library pointed to by a6 DUMP.L .a0 will dump the memory pointed to by a0. (display will change if a0 changes, of course) (Remeber that you need to supply a dot in front of the register names to distinguish between registers and addresses) Remember that you can execute more than one command once, e.g. REGS:NODE .a6 SPLT.C (no arguments accepted) Remove the split window and return to normal operation. SKTB T Stack traceback. Search the stack at the given address or at the address given by the active stack pointer for data- and code addresses. This will be useful if you want to find out, which part of code called a faulty procedure. COP TRIES to find out if the data on the stack is yust garbage (which won't be printed) or a pointer to data, or a returnaddress to a piece of code. XI) COP arguments to the command line and ToolTypes for the Workbench --------------------------------------------------------------------- Here a list of arguments COP acceptes as arguments when getting started from the shell. However, it's possible to start COP from the workbench and to supply the same arguments as tooltypes. Create simply for each argument a tooltype of the same name. KEYMAP Set the keymap COP should use for the build-in terminal. Please note that you CAN NOT change this keymap with the SetMap or SetKeyboard command. This keymap is of course not used for remote debugging. The keymap file is searched in the DEVS:keymaps drawer (not in KEYMAPS: cause this logical device is not standard with Kickstart 1.2 or 1.3) or in the keymap.resource. You need to supply AT LEAST AT STARTUP a KEYMAP argument to define the keymap COP shall use. (There's no default in this release, a missing keymap argument will result in an unusable build-in terminal) SERIAL Choose remote debugging DISPLAY Choose build-in terminal for debugging Note that you MUST supply the DISPLAY argument if you want to enter COP by a shell command or COP will switch to remote-debugging. LINES Set the number of lines of the build-in terminal screen, the default is 28. This argument will be ignored if COP is already loaded, use the IOCD.Z command instead. BREAKKEY Set the keycode (NOT the ASCII-value !) of the BREAK-key. This value will be used only by the internal terminal emulation and will be ignored under remote debugging. Some useable keys (in other words: You MAY use the return key, but...) are: 93 the asterisk on the numeric key pad 90 the braket-left key on the pad 91 the braket-right key nearby 74 the minus key on the pad 94 the plus key underwards 60 the dot on the key pat this is the DEFAULT. You may also use hex numbers if you place a $ or a 0x in front of them. RESIDENT Load COP resident into memory, i.e. COP will survive a reset if execbase is still o.k. and need not to be reloaded. This option is useful if you want to debug startup-code. REMRESIDENT Remove COP from the resident list and free all its memory. Cause COP can not be removed completely, RESTART YOUR COMPUTER IMMEDIATLY AFTER EXECUTING THIS COMMAND. Some code may write over COP's still installed interrupt code resulting in a fireworks display or a crashed harddisk (oh what a fun...). GO Start a debug session using COP. BUILDINPRT Use the build-in printer support thru the parallel port of the Amiga instead of the external terminal printer support. This option works like the IOCD.Q command. TERMINALPRT The counterpart of BUILDINPRT: Use the printer pro- vided by the terminal connected to COP. If you choose the build-in terminal emulation, this won't make any difference. However, if you debug with an ex- ternal terminal, the printing will be done thru its port and not thru the amiga parallel port. IRQDISPLAY Select the buildin-terminal emulation, switch to interrupt driven display. This acts like the IOCD.I command. COPPERDISPLAY Select the copper driven display as default. IRQCOPYBACK Select the IRQ copyback mode: COP does not watch the low-memory interrupt vector table, but its own vector table and will copy changes to the virtual vector base. This is the command-line counterpart of the ENVI.C setting. NOIRQCOPYBACK The default operation of COP: Watch the standard interrupt vector table, which is located at address 0 and up. Both checks can be disabled with the ENVI.I switch. MACMODE This macro switch enabled some options and settings required for COP to run safely under the shapeshifter Macintosh emulator. SET60 Say COP that a MC68060 processor is in your system, although exec.library does not know. The standard Amiga OS 3.1 does NOT recognize a '60 processor, the correct flags are usually setup later by a tool provided by the hardware manufacturer. If you want to run COP prior to these tools, specify the SET60 option. This flag DOES NOT change the processor flags in the exec.library! The next two options contol the video mode used by COP for its own display: NTSC Use a NTSC screen for the debugger screen. This has been the default for versions up to 1.56. PAL Use a PAL screen instead. This is, however, more flickering. Now some options that tell COP where to place itself in memory. They do not work if COP is already loaded ! CODE where Tell COP where to place its CODE segment. where might be: FORWARD Allocate memory from the beginning of the memory area, so COP is placed at LOW addresses. This is impractical in most cases. REVERSE Allocate memory from the end of the memory, so COP is placed at HIGH addresses. This was the default up to release 1.18. address Place COP at an absolute address, given in decimal or in hex if preceded by $ or 0x. This memory area must be available, as long as you do not use the FORCE option. DATA where Tell COP where to place the DATA section. The argument is the same as above. BSS where ...same for BSS section CHIP where ...same for CHIP section. If you use an absolute address here, make shure it is in chip mem ! LABEL where ...same for LABEL section, which is needed if you give a DDT (see below) and containes the names and addresses of DDT labels. BUFFER where Tell COP to use a chip-memory backup buffer and place it according to the argument. You MUST provide this argument if you want a chipmem backup area, or the ENVI.B command won't work. RESIDENTSTRUCT where Tell COP where to place the resident structure that is needed for COP to keep resident over resets. This argument is only useful if you use the RESIDENT switch too. FORCE Tell COP to use the specified memory, even if it is occupied by another program. WARNING ! YOU SHOULD BE REALLY SHURE WHAT YOU ARE DOING if you MUST use this option ! Portions of code of other programs might get overwritten by COP, causing a fantastic crash ! FLUSH Flush labels loaded as symbols from a segment, e.g. loaded by CLIDEBUG or WBDEBUG. This is done automatically every time if you specify CLIDEBUG or WBDEBUG. However, the labels defined in the DDT file are left alone. FLUSHALL Flush all labels, even those defined in a DDT file. The system labels AbsExecBase, Version COPVBR and COPVVBR survive. CLIDEBUG Debug a program using the Shell interface. If you want to give arguments to the program to debug, INCLUDE THE COMMAND AND ITS ARGUMENTS by double qoutes. Since a colon and an asterisk is interpreted by COP as the beginning of a comment, you MUST enclose these characters in an additional pair of single quotes. To simplify this, you might use the DEBUG script. CLIDEBUG always flushes the labels. WBDEBUG Debug a program thru the workbench interface. If you want to support a second icon which is simulated to be clicked with the main program's enclose THE MAIN AND THE SECOND ARGUMENT IN DOUBLE QUOTES. DO NOT ADD ANY .INFO TO THE NAME, even if you load an icon of project type. The responsible program will be found and be loaded. WBDEBUG always flushes the labels. SYMBOL Add the symbols of the given binary file to the label buffer. To do so, you MUST support the base address of the segment using SEGMENT or FIRSTHUNK. Adding of additional labels might be necessary if you debug an overlayed program. COP cannot load all labels on startup, since it is not clear where the overlay nodes will be placed in memory. Remember the base address of the program if loaded; Later on, if the overlay nodes are present, reload the symbol table by FLUSH SYMBOL FIRSTHUNK addr. The FLUSH should be added to avoid adding the labels twice. Though possible, this is a waste of memory. FIRSTHUNK Give the APTR to the first byte of the first hunk to which the labels to be loaded belong. Either FIRSTHUNK or SEGMENT MUST BE USED as an additional argument if you use SYMBOL. SEGMENT Give the BPTR, as available from LoadSeg(), of the segment to which the labels to be loaded by SYMBOL belong. Either this or FIRSTHUNK IS NECESSARY with SYMBOL. CALC Calculate the expression given. Everything COP's EVAL command can evaluate is valid here, even defined labels. So to read the value of ExecBase using the Shell is quite easy: COP CALC [AbsExecBase] Note that this allows using COP as a symbol data- base, e.g. to remember the system entry points. COP CALC OpenLibrary will give the offset of the OpenLibrary system call, provided you added it using a DDT. The only caveat is that COP will assume all numbers are in decimal unless preceeded by $. or $, independend of the radix switch. The $ notation, however, may conflict with shell variables, so enclose the argument, also if it contains spaces, in double quotes. If you want to build an icon to start COP from the workbench, use for example the following tooltypes: DISPLAY MUST be present to prevent COP from remote- debugging mode. GO MUST be present if you want to start COP. DDT file Setup COP's labels using a data description table. The syntax of this file is descripted below, and a default table "startup.ddt" is included in this drawer. If you want to run COP together with the macintosh emulator, you should specify the macintosh-version of the ddt file called MAC.ddt and the MACMODE command line switch. You should use this option in your startup- sequence to load all default labels. It is fine to call COP again with this option if you want to add some labels, however, if you want to reload the table, you should flush all the old labels with the FLUSHALL option. Of course, if COP is already present, the code loaded will get started and will not be loaded again (and therefore, some options are useless in this case !) If you want to debug a Shell program, this command line would be nice: COP CLIDEBUG "c:copy s:Startup-Sequence to '*'" will debug the copy command in copying the startup-sequence to the console. Please note the necessary quotes around the command line and the star. To debug a Workbench progam, say the Shell-Icon, type: COP WBDEBUG "SYS:Shell" Debugging overlayed programs is a bit tricky. First load the program itself, e.g. with COP CLIDEBUG "overlaydemo" Now write down the address of the breakpoint when COP is entered. Step thru the code until a new overlay segment is loaded. To do so, set a breakpoint in the overlay manager, which will always be the first hunk of the program. Then, load the symbols of the overlay code using COP FLUSH SYMBOL "overlaydemo" FIRSTHUNK 0x where addr is the address of the breakpoint you wrote down before. One caveat using overlays is, that the structure of the overlay table depends on the overlay manager the program uses. There are quite a lot of them, however, COP only knows the default one supplied with the linker BLink or SLink. As an example, the overlay structure of DPaint II or COP (yes, that's me...) is private and is not supported by COP. In this case, you cannot load symbols which are placed in the overlay nodes, sorry. If you want to use COP with the shapeshifter macintosh emulator, I suggest the following command line: COP FASTVBR MACMODE DDT S:Mac.ddt plus your prefered keymap and display settings. COP can be entered from the macintosh finder interface thru the hot key, as usual. Once entered, the hardware traps are captured by COP, not by the MacOs. However, the system failures (except those generated by hardware traps) are still left to the Os. This might change in a future release. XII) Syntax of a data description table ----------------------------------------------------------------------------- The data description table contains information about labels, that are litaral names given to addresses to make code more readable. COP intro- duces a new concept of label creation not available with any other de- bugger. The labels are sorted by "type", as there are: - absolute labels, refering to one static address in memory. This is the only type of label most debuggers support. - equates. Those are simply names for numerical constants and are never used in actual disassembling. You may use it, how- ever, in expressions (and, in a release to come, in the microassembler) Typical equates are offsets of fields in structures. - node relative labels. If COP finds a specific base pointer points to a named exec-node structure (e.g. a library), this type of label is used to generate a name for the offset from the base of the node to the piece of memory which is addressed. A typical case is a entry point in a library, but also the full structure of a library can be addressed like that. So the default ddt includes the whole structure of execbase and gfxbase. Since the linking is done in the run time, it is not necessary to open these nodes, and the nodes even does not need to exist in memory while creating the labels. - address relative. This type is currently not used, but is useful if a base register is setup to point to the data region of a program. Typically, this will be a5 or a4. - a guru equate. This special type is used for giving readable names to guru meditations and is never used by the disassembler, but by the REGS.G instruction. - bit definitons. Useful for giving readable names to bits, but not used by the disassembler (there are way to many of them). - New with version 1.52 of COP, lineA-emulators can be named, too. These traps are never used by the AmigaOs, but function as Os- calls under a macintosh or Atari-ST emulation. The syntax of a ddt file is a strange mixture of the syntax of the CBM .fd-files and assembler include files, so you can use your .FD-files and include files WITHOUT ANY CHANGE, provided you use the CBM macros defined in exec/types.i and provided that you do not use forward references, as they are not supported. Entries in the DDT are i) COPDDT-commands, a superset of the commands in the .fd files. COPDDT-commands are preceeded by two hashmarks and MUST be placed in the very first row. ii) Pure labels and function entries are given by their names and must placed in the first row of the file, like labels in assembly language. As a special case, a label might be followed by a EQU or SET opcode. The first produces an equate label with a given value, and the second is ignored by COP since it is only used to keep track of the include files. If no value is given for a label, the contents is taken from the offset-counter which can be set by ##offset or ##bias. The type of the labels can be set by a COPDDT command pre- ceeding the label, except for labels defined by EQU, which will always be equates. A pure label without EQU will always increment the ##offset counter by a size which can be set by ##increment. iii) Pseudoassembler commands which are named like the default CBM- macros in the exec/types.i file. They mostly define a label of a type defined by some COPDDT command above, and the value is also taken from the ##offset counter. However, the increment depends on the pseudoassembler command. iv) Comments are introduced by a colon or an asterisk like in assembly language. Here the COPDDT-commands: ##node name Setup the next labels as labels relative to the node with the given name. Should be used for library offsets. ##guru Setup the next labels as numbers of guru-meditations ##absolute Setup the next labels as absolute addresses. Never used with the Amiga-Os, since there is only one fixed address (AbsExecBase), which is already defined as a label. However, this type is used for the low-memory variables of the macintosh Os (what a horror !) ##relative Setup the next labels as offsets to the address given by , which need not to be a number, and may contain other evaluable labels. However, forward references are not supported. ##equate Setup the next labels as pure equates. ##linea Setup the next labels as line-a traps, as used by the MacOs and atari ST. Useless for amiga. ##offset Set the offset of the next labels to come to their base. With amiga only useful for labels of ##node, ##relative or ##equate type, since there is only one fixed absolute address in the amiga and no line-A emulators. Useful for ##absolute and ##linea under MacOs and Atari ST. ##bias Set the negative offset of the next labels. Will be used by .fd files to set library entries and is identical to ##offset except that the value of is inverted (sign-changed). ##increment Sets the default incrementation value of the offset counter. Should be set to -6 prior to including .fd files, since each entry takes up 6 bytes, and libraries grow to lower addresses. If you want to define a table of LONGs, set the increment to 4. This value is added to the ##offset counter every- time a pure label without a size gets defined. Function entries in a .fd file are "pure labels" in the sense of COPDDT. ##base name Define the name of a library base. Used by the .fd files. Will define a label of offset zero. ##include name Include another file in the ddt. There is NO check for cyclic dependence, so WATCH OUT ! If the name contains spaces, include it in double quotes. ##end End an ddt file. Also used by .fd files. ##private Quietly ignored by COP, only used in fd-files ##public Also ignored. Empty lines or lines starting with a colon or a star are read as comment- lines and are ignored, too. Label definitions: A "pure" label is defined by giving only its name starting in the first row of a line, like this: ##absolute 8 ; Labels are of absolute type ##increment 1 ; Set the increment of pure labels mylabel ; comments are welcome ! This label gets the value 8 nextlabel ; and this one 9, since the increment is 1 The value of the label to be defined is contained in the offset counter, and it will be incremented by the value in ##increment every time. Since fd-files contain functions and arguments, a (pure) label name is cut in the first occurance of a left bracket: myFunc(foo)(a0) ;this label gets called "myFunc" and got the value 10 Labels can be set to given values using the EQU pseudoassembler directive. These "unpure" labels neither need the offset counter nor increment it. All labels generated by this syntax are of equate type, regardless of the previous COPDDT command. TRUE EQU 1 ; an equate. Can be evaluated, but is ; not used by the disassembler ; also, the offset counter is untouched The set directive of assembly language is known, but will be ignored without any checking ARGC SET § ;in assembly language syntactically wrong, ;but completely ignored by COP. The same goes for lines between a MACRO and a ENDM directive, since COP does not support macros (and I think never will..). Pseudoassembler commands: They are called "pseudoassembler commands" cause they define labels in assembly style, rather than .fd style. All macros in exec/types.i are "emulated". The type of labels generated by them depend on the pre- ceding COPDDT command, like ##absolute will generate absolute labels. The value of the labels is given, as above, by the offset counter. This counter can be set with the ##offset COPDDT command or the STRUCTURE directive, and will be incremented by a value determinated by the directive, unlike pure labels, which cause the value of ##increment to be added. Pseudoassembler directives MUST NOT start at the beginning of a line, but MUST be preceded by spaces or TAB characters, like in assembly language. Known directives are: STRUCTURE name, Define a new label of given name as the base of a structure. The offset counter will be initialized by , that is, the structure containes unnamed field in the beginning of the size given by offset. The value of the label defined will be zero relatively to a base, which can be setup by ##node or ##relative. Defining an absolute structure does not make much sense in this system. STRUCT name, Define a substructure in a structure, that is, generate a label of given name with the value as the value of the offset counter, and of type given by a preceding COPDDT command. The offset counter is incremented by the value of afterwards. LABEL name Define a label with the value of the offset counter, which is not incremented at all. UBYTE name[,] Define one single byte, or array of bytes by generating a label. Its value is given by the offset counter, and its type is given by a preceding COPDDT command. The offsetcounter is incremented by 1, if the expression is ommited, or 1x to generate an array. BYTE name[,] Same as byte. UWORD name[,] Define one single word, or array of words. Works like BYTE, but the offset counter is incremented by 2 or 2x. If the offset counter is odd, it is rounded to the next even number. WORD name[,] Same. BOOL name[,] Same. ULONG name[,] Defines one long word, or array of longwords. Increments by 4 or 4x and alignes offset counter. LONG name[,] Same. APTR name[,] Same. CPTR name[,] Same. FPTR name[,] Same. FLOAT name[,] Same. DOUBLE name[,] Defines a IEEE-double precision entry or array. Increments the offset counter by 8 or 8x and alignes it. UQUAT name[,] Same. QUAT name[,] Same. EXTENDED name[,] Introduced into COP, defines MC68881 extended precision entry or array. Increments the offset by 12 or 12x and aligns it. ALIGNWORD Explicitly aligns the offset counter to the next word. ALIGNLONG Align the offset counter to the next long word. ENUM [] Initializes the ENUM-counter by the given value. Does not generate any label. ENUMITEM name Generate a label of equate type. The value is given by the equate counter, which will be incremented by one after the definition. BITDEF pre,post, Generate two (!) labels. The first is of bit-type and will be named "preB_post" and will have the value given by . The second will be named "preF_post", is of equate type and has the value of 1 << . IFD,IFND,ENDC Ignored by COP INCLUDE Ignored by COP. To include something, use the COPDDT command ##include. This was mainly done to avoid unnecessary includes and to give the control what will be included to the main DDT-file. LIBINIT LIBDEF Also ignored by COP MACRO ... ENDM Lines between MACRO and ENDM are ignored by COP, since it does not support macros. As noted above, the set of supported commands was choosen in that way, such that all orignal CBM-includes and .fd files can be used without a change. Support of other style assembly include files (like DevPac's rs-counter) are not supported and never will. It is, however, sometimes necessary to explicitly define labels on one's own. This happens mostly if the orginal include file defines useful constants that should be relative to a base as equates. An example is the definition of DOSBase in dos/dosextens.i. Since you cannot make all labels relative to DOSBase, one must take this definition out of the file. Defining DOSBase as equates and not as node relative is of course not illegal in COP, but will be of no use for the disassembler, since it ignores equates (there are to many of them to be of any use). This was, as a second example, necessary in defining the hardware offsets. Originally given as equates, they are now relative to the base of the custom chip set. See the included example ddt file. XIII) Shell scripts ----------------------------------------------------------------------------- Three shell scripts are provided with COP, to simplify work: -Debug Accepts a program name (full path required) and its arguments to be debugged by COP. Will load the program as if started from the Shell and set a breakpoint on the first hunk. -WBDebug Accept a workbench program and, optionally, a secondary selection, without .info. Starts the program and supplies the arguments thru a WBStartup message, as if started from the workbench. -Calc Evaluates the supplied argument. Labels are welcome, and the radix defaults to decimal. However, problems may arise if you use hex numbers, cause the $ can cause conflicts with defined shell variables. In this case, enclose the argument in double quotes. XIV) COP and the Enforcer ----------------------------------------------------------------------------- COP 1.56 supports the Enforcer program if run on a MC68020 or MC68030. I plan to add support for the MC68060, but don't have enough documentations about this processor and the Enforcer replacement "CyberGuard". There are two ways to run the enforcer together with COP, depending on which output you need. Method I): Start the enforcer first, then run COP. Don't remove the Enforcer later. This will redirect Enforcer hints directly to COP. Faulty programs will cause a bus error exception, and you're now able to debug these programs directly. The enforcer won't cause any ouput, running "Sushi" is not necessary. DO NOT SUPPLY THE FASTVBR COMMAND LINE SWITCH IN THIS CASE as this will over- write the Enforcer exception table. Besides that this exception table is already in FASTMEM, so this option is unnecessary. Method II): Start COP first, then load the Enforcer. It is possible to remove the Enforcer later on, however. The enforcer will work as usual with this setting, COP won't interfere in this case. XV) Plans ----------------------------------------------------------------------------- - Making the chip-buffer more transparent - Better memory chunk support - better disassembler, parts are already working - a microassembler (in preparation) - wildcards in node matching - bitdefs should really be relative to something, but system includes do not give the information - more macintosh support, thru a mac INIT. In the next time, there won't be... - a floppy or harddisk support. There are so many filing systems and device drivers and I think using the 20K or more needed to implement this stuff can be used a better way. - a MMU support, cause I do not plan to invest any money into my #"&$!@ computer, I'll better buy a new one (which will be a more stable one, so no AMIGA anymore...) XVI) Final remarks ----------------------------------------------------------------------------- COP should not be crunched or compacted, since COP uses an internal overlay format to load the debugger code if needed. To enter COP later with a COP DISPLAY GO or equiv. the startup segment is loaded to memory only. I wrote COP three years ago (1993) to find the reason of many crashes that occured in my system. I found that most debuggers I knew were not able to debug a system with execbase out of order or input.device beeing crashed. The first debugger I used to accomplish this task was the ROMWack, a very simple, but nevertheless useful one. I needed a year to complete the first release of COP, so I can appreciate a programmers work and you should do so, too. Please use COP to find bugs in your own code only, whenever every other debugger fails, e.g. interrupt code or reset resident code. Use COP to find the reason of system crashes that crash normal debuggers, but PLEASE DO NOT USE COP TO FUMBLE IN FOREIGN CODE, since this will prevent people from writing good programs. Not everthing is public domain today. This program is decidated to all the bubling idiots that debug own code up to 4 a.m. in the morning ("It MUST work..."). Thank goes to: -Oliver Spaniol for letting me debug this proggy on his '60. If you like this program, if you have any suggestions, if you want to get a newer release of COP, write to: Thomas Richter Rühmkorffstraße 10 A D-12209 Berlin Germany ------- or send electronic mail thru internet to thor@einstein.math.tu-berlin.de - or - thorj@granit.cs.tu-berlin.de There's also a web site you should try: WWW: http://www.math.tu-berlin.de/~thor/thor/index.html It might be possible that COP does not work on YOUR Amiga, some parts of the code are very tricky and hardware dependent. I tried to avoid such problems, but one can never know. If COP fails on your computer, send me a mail and descripe as best as possible your problems. However, debugging by mail is a complicate task.... Thank you for reading and have a good time... THOR (July 1997)