Enigma Amiga Life 109

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

/ Enigma Amiga Life 109 / EnigmaAmiga109CD.iso / software / sviluppo / cop / cop.doc < prev next >

Wrap

Text File | 1999-12-20 | 141KB | 2,847 lines

$VER: COP Doc 1.23 (25.11.99) (c) THOR ***************************************************************************** ** ** ** ___________ ** ** \ */ ** ** /----------- ####### ####### ######## ** ** | ^ | ## ## ## ## ## ## ** ** | _\ ## ## ## ## ## Version 1.83 ** ** | | ## ## ## ######## ** ** | --| ## ## ## ## ** ** +-----/ ## ## ## ## ## ** ** | | ####### ####### ## (c) 1993-1999 THOR-Software ** ** ** ** ** ** A Low Level Debugger for all Amiga Systems ** ** ** ***************************************************************************** by _______ _____ _____ __ _ / / / / / / / \/_/ //_/_ / /____/ / / /____/ ___ / ____// / _ __ / / / / / / \ / /|/ / / / /_/ / /\_/_/ / / / /____/ / / _/__/_/ /__/|_/_/_/ /_/_/ /_ / +-----------------------------------------------------------------------+ | | | 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 COMMERCIAL PRODUCTS OR ARCHIVES WITHOUT | | PERMISSION 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 (v2, 24th June 1998) This License applies to the computer programs known as "COP". The "Program", below, refers to such program. The "Archive" refers to the the original and unmodified package of distribution, as prepared by the author of the Program. The Program and the data in the archive are freely distributable under the restrictions stated below, but are also Copyright (c) Thomas Richter. Distribution of the Program, the Archive and the data in the Archive 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 a) the Archive is reproduced entirely and verbatim on such CD-ROM, including especially this licence agreement; b) the CD-ROM is made available to the public for a nominal fee only, c) a copy of the CD is made available to the author for free except for shipment costs, and d) provided further that all information on such CD-ROM is redistributable for non-commercial purposes without charge. Redistribution of a modified version of the Archive, the Program or the contents of the Archive is prohibited in any way, by any organization, regardless whether commercial or non-commercial. Everything 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 THE PROGRAM, THE ARCHIVE AND ALL DATA OF THESE ARCHIVE FROM YOUR STORAGE SYSTEM. YOU ACCEPT THIS LICENCE BY USING OR REDISTRIBUTING THE PROGRAM. Thomas Richter _____________________________________________________________________________ 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...) (Suggested: "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 one, too o) there's no graphic user interface o) it's based on a command interpreter o) it's hard to learn 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 uses 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 be 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, and MMUs) o) it supports the MMU partially. o) it provides a break key that can be assigned to any (well, almost any) key 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 that 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 and SegTracker if used with a MC68020 or MC68030, and to "MuForce" for all processors. It might be compatible to Cyberguard, even though I won't recommend this program. o) supports the "Picasso96" graphics system. It's currently in the "works fine for me" state, feedback welcome. ...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 MC68000. - 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 requires the display subsystem, you need at least an external serial tty terminal - this is the recommended way to debug programs anyways. - 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. 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. The current version of COP is not able to debug a program via the parallel port, though. It's exclusively reserved for printer output. If your program requires the serial port, use the build-in terminal emulation. 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 (this is not required, 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 paths. 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 pre s:startup.pre If you own a 040 or 060 based system, you should specify the "NOMMU" and "NOEMU" options as well. What does this mean: -The build-in terminal uses the keymap "usa". If you prefer a different keymap, change "usa" to your favourite keymap - it 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. Loading COP as resident program has the advantage that you can debug boot code. -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. -The "pre" keyword instructs COP to build a pre-compiled image of the "ddt" file on first startup - they are faster to load and speed up booting. If you're low on disk space, drop this argument. -The "nommu" keyword for 040 and 060 systems tell COP not to touch the MMU unnecessary. The MMU is required for these systems to guarantee reliable DMA access. - The "noemu" keyword avoids catching of emulator traps for unimplemented 040 and 060 FPU instructions. 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. For professional debugging, you should also install "MuForce" by the same author, and "SegTracker" and "MungWall", all by Michael Sinz. "MuForce" is supported by COP, bus errors are routed thru COP, though. The "SegTracker" is used by COP to find the segment/offset information of a crashed program. 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 gave 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 "shift-selected" 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 ! (Well, almost all... A special DOS crash isn't routed thru the standard system requesters and can't be captured by COP - sigh.) If you supply a data description file (see below), you even get the guru codes in a readable language. If you installed "SegTracker", too, COP will also present the name, the segment number and the segment offset of the code that crashed. 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 formats, 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 null-modem connector, but you should know how to build one... -THOR's "DASB" terminal is a full type-5 terminal, working on Atari 800XL computers with a serial interface box. It's included in the package. There are no settings to be made, DASB is written exclusively 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 an email in this case (address below). 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 parser 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 a stream of key-events. If this happens, leave COP and press the repeating key to stop it. Even worse, you won'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 enter 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 semicolon ";" followed by a comment, or - a four character command base name or a one character short-cut - optionally a dot and an extension that determinates a specific sub-command of a larger command class - optional arguments each separated by space(s) - optionally a semicolon followed by a comment 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 <expr>. 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 - in special the shift operators): $ 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 noticable 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. All other CPU/MMU/FPU registers are available in the same way, with one tiny exception for the MMU "root pointer" registers. These two registers are 64 bit wide for the 68020/68851 and 68030 CPU/MMU and only the lowest long word containing the base address of the MMU table is read. If any of the MMU root pointers are written to, the high long word is set to $80000002, i.e. to setup a short descriptor MMU table. This is the standard way how the MMU is used and I haven't seen any program that uses MMU tables with long descriptors. .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. (Note: This feature is not yet implemented). Additional, all supervisor registers of the 680x0 series can be viewed, as long as your CPU does support them, and will be written back as well as soon as you restart the program. However, read the special caveats about the MMU root pointers above. (Except that you shouldn't mess with the MMU anyways except you're perfectly sure what you're doing.) 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 properly, you should not change VBR this way. Whenever possible, check the value of VBR, and if it has changed, write the new value not to VBR. Use the VVBR instead, and restore VBR to the value of the label COPVBR. COP will then filter out its own exceptions and pass the unused 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. By 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 msecs 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. Reading them causes also 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. (This is actually not yet implemented) op Data type of the instruction under the PC, returns 0 for byte, 1 for word or 2 for long, so 1<<op is the size in bytes of the operator. (This is actually not yet implemented) X) List of all commands ----------------------------------------------------------------------------- Long command Short command possible extensions arguments HELP ? none none prints all COP commands to the active terminal EXIT X none none If execbase valid, COP is terminated and the ROMWack is entered. Note that ROMWack works ONLY with an external terminal (if there is one... it has been removed from the 3.1 - V40 roms). REGS R G,E,C,A none Register dump commands Without extension: Dumps all common CPU registers to the screen, dumps fpu registers if FPU is available and in use. REGS.G Dumps the guru number and the address that generated the crash. If COP was entered the normal way, the guru number will be zero. If a data description table was loaded and gurus were defined, the full name of the guru will be printed. If the "SegTracker" is available, COP will print the name of the crashing program and the segment/offset location of the PC within this program. REGS.E Dumps special purpose registers of newer members of the MC68000 family as cache-control and MMU-registers. FPU registers will be included if the FPU is available and in use. REGS.C Dumps the COP-internal counter registers (without being incremented) REGS.A Dumps effective address of instruction under PC and memory contents, if available. DUMP D B,W,L,C,S,G,H,I,Q,Z,D,X,P,O <expr> Dump memory. If <expr> is omitted, then the "here" pointer is used as address, otherwise change "here" to the given <expr>. 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 gets overridden by mode. ! 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. 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 <expr> Edit memory or hardware. If <expr> is omitted, then edit the address given by the "here" pointer. Else use the <expr> 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 (see the last chapter). Press RETURN to accept the changes made or press TAB to undo the changes. Press Ctrl-C to abort editing. BE WARNED! The string "d0" means "contents of register d0" not the value "d0", like everywhere in COP. To enter the value "d0", you've to type "$d0". Quite for the same reason we've "cf" as "contents of counter #f, increment it when read" and not "the number $cf". The later is "$cf". 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 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 gets displayed. Node that this is necessary because some hardware registers are WRITE ONLY. In all the modes presented above, you may enter a full <expr> as well as a numeric constant as a new value, although the length of the <expr> 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 <expr> Evaluate the expression given and print the result. The result might be a simple number, but very complex expressions including labels are valid, too. UNAS = none <expr> Unassemble code starting with address <expr> and set "here" to this value. If <expr> 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 numerical constants will be disassembled as decimal floating point expressions. Illegal opcodes or opcodes that can't be used on the Amiga (like the TAS instruction) get marked as well. Depending on your enviroment settings - see the ENVI comand - some of the addresses will be expanded to known labels. NOTE: I was unable to test the correct disassembly of the MMU and MC68040 codes, although it SHOULD work. If the address being 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 L <expr> Display the node at address <expr>. If <expr> is not present, use the "here" pointer, otherwise set "here" to the address of the node. No extensions The name of the node and its type is displayed. L Dump the node as before, but print additional information COP can gain about that node. COP knowns most node types defined in the Os and will print additional information contained in the data attached to the node. LIST L M,R,D,I,L,P,T,S,Q,B <expr> Dump contents of exec-type lists. No extension Dump the list at given address, set "here" to this address. If <expr> 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 <expr>,<expr> Fill memory with byte sequence starting with first <expr> and to last <expr>, exclusive. If one of the <expr> is missing, then "here" is used. Then "here" is set to the first <expr>. without extension Enter the byte pattern the memory should be filled with. Press TAB to complete one byte, press RETURN to complete the whole sequence and to start filling. Again, "d0" is the register, not the value. The number is entered as "$d0". 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 any time to abort the operation. FIND I M,I <expr> Find byte pattern, masked, or find instruction starting with given address or "here". Set "here" to given expression afterwards. The found values are either dumped in the last mode used by the "dump" command, or disassembled with the "I" mode. Furthermore, if the display is split, COP stops the search as soon as something is found and updates the top window of its screen, with the "here" pointer set to the found address. This is most useful for displaying a large area around the found bytes, and can be optained by displaying the output of a command like "d >-8" in the top window. To remind you, ">" is the name for the "here" pointer. More about display splitting is found below. without extension Enter the byte pattern byte for byte pressing TAB after each byte and RETURN to complete the sequence you are searching for. See above for caveats! "d0" is a register, not a number! M Find masked. Enter 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 names instead of the address if you look for an access to a defined label ! You may press Ctrl-C to abort the searching at any time. MOVE M none <expr>,<expr>,<expr> Move source memory block starting with first <expr> and ending with second argument exclusive to destination given by last <expr>. If any of the <expr> 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. You may press Ctrl-C to abort the operation. TASK ! F,W,S <expr> Task commands: display,freeze and warm tasks, send signals. without extension Display information about the task if <expr> 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 in task switching). S Send a signal to a task. You need to supply two arguments, FIRST the signal to be send and SECONDLY the task affected. SETR S F,E,D,V <expr>,reg Set <expr> to given CPU register. without extension Move given expression to a destination register. All CPU registers are valid destinations, but only the low long word of the 64 bit wide MMU registers of the 68851/68030 will be set, their high-longword will be set to $80000002 always. This word is just a dummy for the 68040 and 68060, but used to identify the size of the descriptors and a "limit" value for the 68851/68030. However, I don't remember any program that makes actually use of these extensions. 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 being debugged. In this case, <expr> 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. Warning: Don't touch the cache for 68040 or 68060 systems, at least don't try to activate it by force if it is not activated. DMA related device I/O might break by enabling the cache in an I/O operation. D With MC68020 or higher: disable all caches. No arguments taken. Cache finetuning, if required, should be done by modifying the cacr register directly. 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 <expr> Enter trace mode, start tracing at given address or use PC if <expr> 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 being disassembled and dumped to the terminal; on type-3 or type-4 terminals however, an entire page of instructions is printed. The command at the PC is marked with an asterisk and is highlighted on type-4 terminals. Lines with breakpoints are marked with a "B". The current position of the "here" pointer is marked by ">". 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 gets 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 unwise 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 sure 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. it isn't activated unil the 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 being 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 actually 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. The 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. If changed by COP, this will cause a nice crash of your system. Thus, 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 <expr> Breakpoint commands. The address affected is given by <expr> 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 reset 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 fifth 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" or "Other Task 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 getting written over by a program (e.g. the memory is freed and another task re-uses this area), this breakpoint is REMOVED automatically at 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 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. (Trick for MMU owners if you need to do this: Enable the MMU bypass and set the breakpoint in the mirrored RAM.) 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 <expr>,<expr> without extension Start interrupted program at given address or at PC if <expr> 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 <expr> 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. This will be very slow, like the 'M' sub- command of STEP. CAPT C S,N,C [<expr>,]<expr> Capture a task, i.e. start debugging it. no extension Capture the task with task structure at the supplied address. If <expr> 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 private exec stack frame which has been changed in Rev. 2.0. 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 getting 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 getting 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 <expr> 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, toggle between COP's display and the display of the program being de- bugged. This is not done by intuition or the like, but by PURE HARDWARE. For this reason, COP needs 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 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 terminal 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 <expr> Set the address of the copper list of the user-program to re-establish the user's display. If <expr> 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 <expr>. 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 program 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 type. 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 the 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 <expr> Set the screen size of the build-in terminal to <expr> lines. If <expr> 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 too 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 <expr> 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 <expr> is not given, the command uses the last value. (Remember that COP thinks in HEX, so 10 is not TEN but SIXTEEN !) IOCD.M <expr> Set the value to be written to BEAMCON0 if user display should be rebuild. This command is not required unless 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 because it is less flickering than a PAL screen. I think there should be no problems with this feature, even commodore's @#!?!-monitor supports 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). Some flicker fixers might have problems with the long/short frame toggling of the NTSC display, COP offers the PAL60 option. IOCD.V (does not take arguments) Toggles the display mode between NTSC, PAL and PAL60. 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,U,O <expr> 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. The SegTracker interface will be disabled, 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 or a reboot, 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 <expr> <expr> 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 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 at all....) 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 being 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 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 is normally used by 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 be therefore 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 to complete before swapping the memory. In all other cases the blitter will be just 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 on or off. 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 it 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. ENVI.U (no argument) Toggle the MMU bypass. All COP memory accesses usually by- pass the MMU of the 68020 or higher processors, so you see the true physical addresses. This can be disasterous if COP is used on an A3000 because disabling the MMU disables the image of the OS, too. Use ENVI.U to tell COP not to touch the MMU. That will have, however, certain consequences: First, all addresses shown in COP will be logical addresses, not the pure physical addresses. Reading or writing non-existant or pure system addresses with MuForce enabled will cause COP to crash by a bus error (that's harm- less for COP, but you won't be able to alter these addresses at all). The command line option NOMMU can be used to enable this option by default. In any case, be careful with it. ENVI.O (no argument) This is a 060/040 specific setting. It selects whether COP should bypass the non-implemented instruction exceptions to the 68060/68040 library or capture them itself. The command line option NOEMU does quite the same, namely enabling the bypass. It is, however, not yet clear if this option works or makes any difference at all. *sigh* SPLT / C <expr> 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 off 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 "the common debugger", you must enable this feature by hand, 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 the 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 (since that doesn't make sense at all...) -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 should 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 Another idea about splitting is to use it when searching. COP halts now searching as soon as something is found and refreshes the split-off command, with the "here" pointer set to the found command. Thus, splitting the screen with a command like "u >-8" will disassemble the region around the found byte everytime the search succeeds. SPLT.C (no arguments accepted) Remove the split window and return to normal operation. NOTE: This command is always executed if a part of COP causes a crash. Mainly because this part could be the split-off command, creating an infinite loop of crashes when re- freshing the screen after the crash-message. SKTB T <expr> 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 just garbage (which won't be printed) or a pointer to data, or a return address to a piece of code. In the later case, it tries to find a label near that code address, to provide you with the name of the calling routine. LABS A E,S,B,G,T,V,A,U,L,F [name] Dump labels. This command prints informations about label definitions loaded into COP. A line dumped by this command will look like the following: label name : value (+ base) (flags) Some labels are either relative to a base, which is printed in hex if so, or relative to an exec node. It's name is printed in this case. The characters in the brackets specify the type of the label: A absolute address E equate. An easy to remember expression representing a number. N an address relative to a node, thus, an offset. V a function vector of a library or a device. R an offset relative to an absolute base. S a size of something. Currently not supported. B a bit definition. L A lineA trap definition (not required by the Amiga-OS, but by the Mac OS) s A COP internal (system) label. There are currently only four system labels. r A read-only label. k A resident label, can't be removed with FLUSHALL t A temporary (so, user) label. Can be removed with FLUSH. The "name" argument specifies the label you'd like to know information about. Wildcars are welcome here, COP knows only two wildcards, '?' for one unknown character and '*' for a sequence of unknown characters. If you don't give a name, COP selects "*" for you as default, i.e. will show all label. The extensions specify the type of labels in the list: LABS.E [name] Dump equates only. LABS.S [name] Dump only sizes. LABS.B [name] Dump bit definitions. LABS.G [name] Dump gurus. LABS.T [name] Dump line-A traps. LABS.V [name] Print function vectors. LABS.A [name] Print addresses. Absolute, relative or node relative. LABS.U [name] Print all user defined (temporary) definitions. LABS.L [name] Print all definitions. LABS [name] Print all user defined addresses. LABS.F <expr> Find the label nearest to and behind the given address. This is useful if you know only the absolute address in memory and want to relate it to the name of a subroutine of your program. SEGM Q <expr> Find segment offsets. This command takes a memory address and tries to find out the program this memory belongs to. If successful, COP will print the segment (=hunk) number of that program, and the offset within that hunk the given address belongs to. Michael Sinz' "SegTracker" must be active for this service! 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. Simply create a tooltype of the same name for each keyword. KEYMAP <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 <number> 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 <number> 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. If used together with MuForce, you might want to give the "RESTOREVBR" keyword as well, see below. 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. RESTOREVBR Instruct COP to re-install its own vector base register. This keyword is needed if COP is made resident and used in con- junction with "MuForce". Since "MuForce" installs its own vector base table on top of COP, a resident copy of COP won't be able to capture enforcer hits any more. Use this option to restore the VBR of COP, right after installing MuForce. MACMODE This macro switch enabled some options and settings required for COP to run safely under the "ShapeShifter" Macintosh emulator. SET60 Tell 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, mostly the 68060 library. 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! NOMMU Disable the MMU bypass. COP won't touch the MMU and keep it active all the time - as needed for amiga models that use the MMU to load an OS image or to guarantee reliable DMA operations, as the 040 and 060 based Amigas. Disabling the MMU in this case will crash the system because the OS will vanish. This keyword is identical to the ENVI.U instruction. MMU The default. COP bypasses the MMU for memory access, all addresses will be physical addresses. This is somewhat dangerous if the MMU is required for system operation, as for '060 and '040 systems or if the MMU is used to map in a different version of the OS. NOEMU Instruct COP to bypass the 060/040 emulator traps to the 68060.library or 68040.library - which must be installed and running at the time COP is launched. These exceptions are generated if the 68060 detects an instruction that is not supported by the CPU directly but has to be emulated in software. It is, however, not quite clear if this option makes any difference at all, or if it works - simply because I don't own a '060 for testing. EMU The opposide and default setting. COP captures all emulator traps as software failures. The next three 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 but required for some TVs. PAL60 This is a display mode half between PAL and NTSC. It uses the base frequency of NTSC, 60Hz, but does no long/short line toggling, like PAL. This mode might be required to display 60 Hz with some oldish flicker fixers. PICASSO Tell COP that the "Picasso96" graphics system and a graphics card is installed. COP will then try to saveback the status of the RTG system and to bring the native amiga display to front. This option requires the "picasso96" installed, most important the "rtg.library". I don't know how well this works, though, it's currently a bit "hackish". NOPICASSO Disable the use of the Picasso96 graphics software. DARKEN Darken the native Amiga display upon initialization of COP. This is useful for graphics board software that leaves the native Amiga screen white. This option is currently a bit "hackish". 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 SURE 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 in 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 <progname> FIRSTHUNK addr. 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 REQUIRED for 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 $. (Different to how expressions are handled usually!) 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. PRE file Provide or create a precompiled version of a DDT file. If this argument is given, COP tries first to read the label database from the "pre" file. If this file is not available, COP will read the usual DDT file and create a "PRE" file for you. The ad- vantage of precompiling "DDT" files is that they are parsed much faster. Their format is, however, private. 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 "SetVNC" 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 "SetVNC" FIRSTHUNK 0x<addr> 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 NOMMU 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 - And therefore every time COP is entered by a crash. - 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 for a macintosh or Atari-ST emulator. 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 column. ii) Pure labels and function entries are given by their names and must placed in the first column 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 included 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 are always 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. ##vectors name Identical to ##node, except that it defines function vectors. The label values should be negative. ##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 <expr> Setup the next labels as offsets to the address given by <expr>, 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 the Amiga. ##offset <expr> Set the offset of the next labels relative 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 <expr> 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 <expr> is negated (sign-changed). ##increment <expr> 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 ; the offset counter is untouched, too 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,<expr> Define a new label of given name as the base of a structure. The offset counter will be initialized by <expr>, 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,<expr> 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 <expr> afterwards. LABEL name Define a label with the value of the offset counter, which is not incremented at all. UBYTE name[,<expr>] 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<expr> to generate an array. BYTE name[,<expr>] Same as byte. UWORD name[,<expr>] Define one single word, or array of words. Works like BYTE, but the offset counter is incremented by 2 or 2x<expr>. If the offset counter is odd, it is rounded to the next even number. WORD name[,<expr>] Same. BOOL name[,<expr>] Same. ULONG name[,<expr>] Defines one long word, or array of longwords. Increments by 4 or 4x<expr> and alignes offset counter. LONG name[,<expr>] Same. APTR name[,<expr>] Same. CPTR name[,<expr>] Same. FPTR name[,<expr>] Same. FLOAT name[,<expr>] Same. DOUBLE name[,<expr>] Defines a IEEE-double precision entry or array. Increments the offset counter by 8 or 8x<expr> and alignes it. UQUAT name[,<expr>] Same. QUAT name[,<expr>] Same. EXTENDED name[,<expr>] Introduced in COP, defines MC68881 extended precision entry or array. Increments the offset by 12 or 12x<expr> and aligns it. ALIGNWORD Explicitly aligns the offset counter to the next word. ALIGNLONG Align the offset counter to the next long word. ENUM [<expr>] 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,<expr> Generate two (!) labels. The first is of bit-type and will be named "preB_post" and will have the value given by <expr>. The second will be named "preF_post", is of equate type and has the value of 1 << <expr>. 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 a 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 too 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) Precompiled files ----------------------------------------------------------------------------- The 1.60 version of COP introduces the option to "precompile" DDT files for faster startup. If you give a name of a pre-file on the command line with "PRE filename", additional to the "DDT" keyword, COP will try first to load all labels from this pre-compiled header. If successfully, the DDT keyword will be ignored. If the "PRE" file is not available, COP will parse the "DDT" file as usual and will create this "PRE" file afterwards so it is available for later use. The main advantage of precompiled "DDT" files is that they are way faster to load, no parsing and no syntax check is required. The data format is completely internal, please do not touch these files - they are purely for COPs use and maintained completely by COP itself. One caveat of "PRE" files is that they aren't updated automatically if you change the original "DDT" file and there can be ONE and ONLY one "PRE" file for the complete set of macros. Writing a partial set of label definitions in a pre-file isn't possible. Either all or nothing! The consequence is that you: - should delete the "PRE" file manually if you made changes to the source DDT file. COP will then re-create the "PRE" file the next time it is required. - should only precompile the first DDT file that is loaded, that is the "startup.ddt" file. Since this is the only DDT file in most applications, that's not a restriction. DO NOT TRY to write PRE files for DDT files you include afterwards - as they will not only contain the label definition in the additional DDT file but in ALL DDT files. Loading these labels later on might confuse COP. As a rule of thumb: Only the Startup.DDT file should be precompiled. XIV) 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 at 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. XV) COP and MuForce/Enforcer/Cyberguard ----------------------------------------------------------------------------- COP 1.56 and up supports the Enforcer program if run on a MC68020 or MC68030, it supports MuForce on any processor. It *might* support the Cyberguard, too, but the 040 exception handler of this program is faulty and I won't recommend this program for that reason. There are two ways to run these tools together with COP, depending on which output you need. Method I): Start MuForce first, then run COP. Don't remove it later. This is the recommended way. 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. If you made COP resident, the COP invokation line in the startup-sequence should contain the "RESTOREVBR" keyword, too. This is needed because the order of installation will be different once COP is resident - MuForce will now install on top of the resident copy of COP, hence, messing COP's vector base register. This option will re-direct the vector base to COPs interal base. Do NOT use the CAPTURESUPER option of MuForce, and add the NOGURUPATCH option. This will keep MuForce out from vectors required by COP. Method II): Start COP first, then load MuForce. It is possible to remove MuForce later on, however. The MuForce will work as usual with this setting, COP won't interfere in this case. However, as soon as COP is entered, it will complain about its vector base being messed up by MuForce. You might want to simply ignore this warning. MuForce and the FASTVBR option. -------------------------------- That's a story of its own. If you want to run COP before MuForce, the FASTVBR option IS REQUIRED. This is simply due to the fact that otherwise COP will locate the virtual vector base in the first 1K/4K of memory as usual - and this memory isn't available with MuForce. Quite the same goes for keeping COP resident - it's in this case already present when MuForce gets loaded, so FASTVBR is mandatory, too. There's actually little reason NOT to use the FastVBR option except to keep some badly written programs - mostly games - working. XVI) COP and the 68060 / 68040 ----------------------------------------------------------------------------- The 1.61 release of COP should be able to support the 68060 processor - however, as most of the support code is untested, it is not quite clear if everything works as expected. The following rules apply to COP and the 68060: ----------------------------------------------- - Add the SET60 keyword to the command line option. That tells COP explicitly that it has to deal with the '060 processor. The execbase "AttFlags" flags field does not necessarely monitor the '060 processor correctly. - Add the NOMMU keyword. The MMU operation is vital for '060 and '040 based systems, to mask certain regions of memory as "non-cacheable" as needed for DMA transfer and other reasons. - Add the NOEMU keyword. COP will try to bypass the emulator traps to the 68060 library. It is, however, not quite clear if this works as expected. - Load the 68060 library BEFORE COP is run. This is usually done by the 68060.library that gets loaded by SetPatch. - Start COP after CyberGuard or Enforcer. This is the recommended way, but it is not yet quite clear if this works like it should. COP has to emu- late the access to the AbsExecBase location at address four, and this emulator code is quite tricky for the 68060. Even though I tried my best to test it with my 68030, it is not clear whether it works like it should. - Add the FASTVBR option if you want to run COP before Enforcer/CyberGuard, or if you want to keep COP resident. Do not specify it otherwise. COP and the 68040 ----------------- - Add the NOMMU keyword. It is required for proper DMA operation of '040 systems. - Add the NOEMU keyword. COP will try to bypass the emulator traps to the 68040.library. - Run COP after MuForce. Don't use the Enforcer because its design is too static to allow proper operation. Don't use CyberGuard because its exception handler is not working properly. - Run COP after loading the 68040.library. This is usually done by the SetPatch command anyways. - Specify the FASTVBR keyword if you run COP before Enforcer, or if you want to keep it resident. Do not specify it otherwise. XVII) 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. - a MMU table lister ? 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. XVIII) 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 six 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 crashed. The first debugger I used to accomplish this task was the ROMWack, a very simple, but nevertheless useful one. It took a year to complete the first release of COP, so I can appreciate a programmer's 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, support the good work and buy software. This program is decidated to all the bubbling idiots that debug own code up to 4 a.m. in the morning ("It MUST work..."). P.S.: The reason for the crashes, if anybody cares, is the broken expansion port in my A2000. Replacement motherboards are no longer accepted, because I got a replacement now... (-; Thank goes to: -Oliver Spaniol for letting me debug this proggy on his '060. -Mark Watson for his help with the '060 code. -Werner Müller for providing a 040 and a (working) 6.2 motherboard for a bargain. 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 to thor@math.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 (December 1999)