1## Compare execution using reference GDB
2
3This directory contains script comparing Renode execution with a given reference using GDB.
4
5### Requirements
6
7To install required python packages run:
8```
9    python3 -m pip install -r tools/gdb_compare/requirements.txt
10```
11
12### Usage
13
14```
15usage: gdb_compare.py [-h] -r REFERENCE_COMMAND -c COMMAND -s RENODE_SCRIPT -p REFERENCE_GDB_PORT [--renode-gdb-port RENODE_GDB_PORT] [-P RENODE_TELNET_PORT]
16                      -b DEBUG_BINARY [-x RENODE_PATH] [-g GDB_PATH] [-f START_FRAME] [-i IPS] [-S STOP_ADDRESS]
17
18Compare Renode execution with hardware/other simulator state using GDB
19
20optional arguments:
21  -h, --help            show this help message and exit
22  -r REFERENCE_COMMAND, --reference-command REFERENCE_COMMAND
23                        Command used to run the GDB server provider used as a reference
24  -R REGISTERS, --register-list REGISTERS
25                        Sequence of register names to compare. Formated as ';' separated list of register names. Eg. 'pc;ra'
26  -c COMMAND, --gdb-command COMMAND
27                        GDB command to run on both instances after each instruction. Outputs of these commands are compared against each other.
28  -s RENODE_SCRIPT, --renode-script RENODE_SCRIPT
29                        Path to the '.resc' script
30  -p REFERENCE_GDB_PORT, --reference-gdb-port REFERENCE_GDB_PORT
31                        Port on which the reference GDB server can be reached
32  --renode-gdb-port RENODE_GDB_PORT
33                        Port on which Renode will comunicate with GDB server
34  -P RENODE_TELNET_PORT, --renode-telnet-port RENODE_TELNET_PORT
35                        Port on which Renode will comunicate with telnet
36  -b DEBUG_BINARY, --binary DEBUG_BINARY
37                        Path to ELF file with symbols
38  -x RENODE_PATH, --renode-path RENODE_PATH
39                        Path to the Renode runscript
40  -g GDB_PATH, --gdb-path GDB_PATH
41                        Path to the GDB binary to be run
42  -f START_FRAME, --start-frame START_FRAME
43                        Sequence of jumps to reach target frame. Formated as 'addr, occurence', separated with ';'. Eg. '_start,1;printf,7'
44  -i IPS, --interest-points IPS
45                        Sequence of address, interest points, after which state will be compared. Formated as ';' spearated list of hexadecimal addresses.
46                        Eg. '0x8000;0x340eba3c'
47  -S STOP_ADDRESS, --stop-address STOP_ADDRESS
48                        Stop condition, if reached script will stop
49```
50
51#### Examples
52
53##### Comparing Renode with QEMU
54
55```
56python gdb_compare.py \
57    -r 'qemu-system-riscv64 -nographic -M my_board -kernel firmware.elf -s -S' \
58    -c 'info registers' \
59    -s my_board.resc \
60    -p 1234 \
61    -b firmware.elf \
62    -g riscv64-zephyr-elf-gdb \
63    -f 'main,1;printf,5'
64```
65
66##### Comparing Renode with OpenOCD
67
68```
69python gdb_compare.py \
70    -r 'openocd -f my_board.cfg' \
71    -c 'info registers' \
72    -s my_board.resc \
73    -p 3333 \
74    -b firmware.elf \
75    -g arm-zephyr-eabi-gdb \
76    -f 'main,1;printf,5'
77```
78
79##### Comparing Renode with Renode
80
81```
82python gdb_compare.py \
83    -r 'renode my_board.resc --console --disable-gui -e "machine StartGdbServer 1234"' \
84    -c 'info registers' \
85    -s my_board.resc \
86    -p 1234 \
87    -b firmware.elf \
88    -g arm-zephyr-eabi-gdb \
89    -f 'main,1;printf,5'
90```
91