-------------------------------------------------------------------------------- ================================================================================ -------------------------------------------------------------------------------- * * **** Retargetable Replay v0.6 **** * * -------------------------------------------------------------------------------- ================================================================================ -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- installing/configuration -------------------------------------------------------------------------------- you might want to add the directory where you installed rr.exe to your search path so you can run the rr-program from any directory. set PATH=c:\tools\rrcon;%PATH% also make the environment variable RRPATH point to the directory where the rr-executeable resides. ie set RRPATH=c:\tools\rrcon (linux peeps probably know how to translate this into proper *nix commands ;=P) please look at the supplied .ini files for some comments about config- uring the rr-program.... atleast, enter the correct name and address for your port device in rr.ini. to make sure everything is right, go to a different directory than RRPATH, run rr --show-config and see if everything looks ok. -------------------------------------------------------------------------------- preparetions -------------------------------------------------------------------------------- before you are able to use the remote-debugging functionality of the rr program(s) you have to start a suiteable debug stub on the target (besides having configured the toolchain right ;)). How to do this is beyond the scope of this document, please have a look at the target specific README. -------------------------------------------------------------------------------- command-line options: -------------------------------------------------------------------------------- usage: rr [options] running rr without any arguments starts the debugger help -? -h --help this help --version print program version --show-config show active configuration --show-supported show architectures --cpu [type] set target cpu -t --target [system] set target system drop --drop [filename start entry] drop stub on target patch --patch [patchname start end] apply smart patch --disable-autopatch don't apply default patches --enable-autopatch apply default patches load --load [filename start end offset] load prg-file loadbin --loadbin [filename start end offset] load bin-file save --save [filename] [start] [end] save prg-file run --run [filename] [start] load prg-file and run flash --flash [filename] flash target debug rom jump --jump [address] jump to address peek --peek [address] read byte peekw --peekw [address] read word peekl --peekl [address] read longword poke --poke [address] [byte] write byte pokew --pokew [address] [word] write word pokel --pokel [address] [long] write longword fill --fill [start] [end] [byte] fill memory with byte dbg --debugger debugger mon --monitor monitor con -c --console console/fileserver mode term --terminal simple terminal mode dump --terminal-dump terminal dump/test mode --remote work in remote mode sim --sim work in simulator mode ice --ice work in ice-breaker mode -s --silent silent mode -v --verbose verbose mode -W --warn enable some warnings --exit exit commandline the commandline is processed from left to right. all numeric values may be either decimal (1234), hex (0x1234, $1234) or bin (%1011). short options may change, please use long options in scripts. -------------------------------------------------------------------------------- The Debugger -------------------------------------------------------------------------------- to enter the debugger, run rr.exe without arguments. keyboard-layout: F1 show Help F2 toggle auto-update for active window F3 update active window (re-read from target) F8 save (download) File F9 load (upload) File these two accept a simelar syntax as the monitor l/s commands... for example [F9] then "foo 8000" loads file "foo" to 0x8000 [F9] then "r,foo 8000" loads file "foo" as raw binary to 0x8000 [F9] then "l,foo" loads labels from file "foo" [F8] then "foo 8000 8010" saves file "foo" from 0x8000 to 0x8010 [F8] then "r,foo 8000 8010" saves file "foo" as bin from 0x8000 to 0x8010 ... and so on (see monitor l/s etc for details, just notice the difference with r/l, the comma, and the string :)) F10 enter Monitor F11 enter Console F12 enter Terminal ESC Quit X,Q,ctrl+d -> also Quit Cursor-Keys + Page Up/Down Scroll in Windows Space display next page (same as Page Down) Tab Toggle active Window (Top/Bottom) 1...0 select slot + toggle doublesize mode d enter adress + switch to disassembly mode f fill memory g enter adress, set pc to address and run target i enter adress + switch to screencode mode j enter adress + switch to text mode l load file ll load labels lr load raw binary m enter adress + switch to data mode (8bit) mw enter adress + switch to data mode (16bit) ml enter adress + switch to data mode (32bit) s save file sr save binary file sl save label file t transfer memory -> for more read the monitor description, in particular read the note on the command parser at the end of the monitor reference! Enter edit active Window in edit mode: ------------- TAB or Escape: leave edit mode Cursor-Keys + Page Up/Down move around Enter: - in hex mode: set other window to address under cursor S toggles source of address (aligned or unaligned to current access width) T toggles size of value (either equals current access width or target address width) notice that any edited values are written back to memory *immediatly*. (be aware of that if you accidently hit the wrong key on a certain sensible controller register you will get what you deserve for it :=P) -------------------------------------------------------------------------------- The Monitor -------------------------------------------------------------------------------- This is a classic machine language monitor, with the command set trying to imitate the c64 action replay monitor. available hotkeys: F1/F2 Freeze/Unfreeze Target available commands: ? print help a enter assembly commands c compare memory co enter console mode d disassemble f fill memory g
jump to address h hunt memory for pattern the pattern may be either a string or one or more >bytes< (you have to break down 32bit values yourself! :)). .h 1000 2000 "foo" .h 1000 2000 de ad be af in binary and/or hex numbers you may use wildcards like: .h 1000 2000 1? 2? 22 34 .h 1000 2000 %11??1100 %101010?? note: since the pattern is scanned differently than the usual numeric values (to implement the wildcards) symbols do not work in the pattern (nor do extended expressions). i dump memory as screencode j dump memory as text l load file lr load raw binary file ll load symbols from a file ls list symbols m dump memory as hexcode mw dump memory as 16bit words ml dump memory as 32bit words n do calculations calculates an extended expression and prints its value. note that the expression is scanned differently than other numeric values, you dont need the otherwhise necessary braces around the expression, but in turn *must* prefix hex numbers by either 0x or $ ! (8000 is decimal here!) r show registers s save file sr save raw binary file sl save symbols to a file t transfer memory x exit :
... write memory @ execute shell command pressing any key pauses whatever lengthy output. (pity for those with no scrollback buffer terminal :=P) note on the command parser: --------------------------- the command parser of the rr monitor and the rr debugger just as the command set tries to immitate the c64 action replay and thus by default threatens the input in a not so strict way which leads to some whicked behavior that you should be aware of :) 1) the first one or two non blank characters of the input are the actual command 2) right next to the command may follow arguments. arguments may, but do not HAVE to be seperated by either spaces or commas. two types of arguments are supported: a) literal strings - "this is a string" b) numeric values numeric values can be any of a plain number, an expression , a symbol or a combination of those. the actual value is formed like this: 1) command specific processing have a look at the command list, some commands (must) use a different threatment than it is described here to implement certain special features. 2) check for special symbols currently one special symbol exists: - (the minus sign): the value will be equal to the highest possible address of your target. eg: .m 0x1000 - 3) check for extended expression an extended expression must be enclosed in braces and may contain binary, decimal, hexadecimal numbers, symbols and calculations. for example .m(__main+0x1000) .d(__start) .s"foo" 0x1234 (0x1234+0x1000) etc numeric formats supported inside extended expression: decimal (1234) hex (0x1234,$1234) binary (%0101) 4) check for simplified hexadecimal number(s) since hexadecimal number is what its all about in a ml monitor, the commands by default expect hexadecimal numbers without any prefix. for example .m 1000 2000 furthermore, the command parser will break down a number that is larger than the targets address width into subsequent arguments. for example on a target with 16bit address space .m10002000 means the same as the previous .m 1000 2000 -------------------------------------------------------------------------------- The Console -------------------------------------------------------------------------------- accepts debug-printing from the Target and features a fileserver. to enter console/fileserver mode, enter "rr con" on the commandline, or press F11 in the debugger main screen. available Hotkeys: F1-Help F11-Toggle Fileserver messages F12-Toggle Fileserver/Console emulation mode ESC-Exit console currently supported fileserver emulations are: - generic/rr - serial slave - cbm/retroreplay -------------------------------------------------------------------------------- The Terminal -------------------------------------------------------------------------------- just a dumb Ascii Terminal, mostly useful for testing-purposes. to enter terminal mode, press F12 in the debugger main window or enter "rr term" (or "rr dump" for even more verbose testing) on the commandline. available Hotkeys: ESC-Exit Terminal -------------------------------------------------------------------------------- for bug-reporting and suggestions email groepaz@gmx.net -------------------------------------------------------------------------------- * additional tools - rrdis - analyzing disassembler -=> see $RRPATH/docs/rrdis.txt - rrasm - simple line assembler -=> see $RRPATH/docs/rrasm.txt - rred - assembler code editor -=> see $RRPATH/docs/rred.txt - rrdump - file dumper -=> see $RRPATH/docs/rrdump.txt - rrview - file viewer -=> see $RRPATH/docs/rrview.txt - rrlink - binary linker -=> see $RRPATH/docs/rrlink.txt * additional info -=> see $RRPATH/docs