| |
--------------------------------------------------------------------------------
================================================================================
--------------------------------------------------------------------------------
* * **** 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 <start> <end> <byte> 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 <filename> <startaddr> load file
ll <filename> load labels
lr <filename> <startaddr> 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 <filename> <start> <end> save file
sr <filename> <start> <end> save binary file
sl <filename> save label file
t <start> <end> <dest> 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 <startaddr> <command> enter assembly commands
c <start> <end> <dest> compare memory
co enter console mode
d <startaddr> <endaddr> disassemble
f <startaddr> <endaddr> <byte> fill memory
g <address> jump to address
h <start> <end> <byte(s)> 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 <startaddr> <endaddr> dump memory as screencode
j <startaddr> <endaddr> dump memory as text
l <filename> <startaddr> load file
lr <filename> <startaddr> load raw binary file
ll <filename> load symbols from a file
ls list symbols
m <startaddr> <endaddr> dump memory as hexcode
mw <startaddr> <endaddr> dump memory as 16bit words
ml <startaddr> <endaddr> dump memory as 32bit words
n <expression> 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 <filename> <start> <end> save file
sr <filename> <start> <end> save raw binary file
sl <filename> save symbols to a file
t <start> <end> <dest> transfer memory
x exit
: <address> <byte>...<byte> write memory
@ <command> 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
|
| |