From 8dad00ef321768188b0cee3ffbc02c55348c47ca Mon Sep 17 00:00:00 2001
From: Peter Wu <peter@lekensteyn.nl>
Date: Tue, 1 Mar 2016 16:53:20 +0100
Subject: README.md: explain how to use gdb

Note that our "present" program still contains a bug.
---
 README.md | 106 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 106 insertions(+)

diff --git a/README.md b/README.md
index 371cd4d..ff13a28 100644
--- a/README.md
+++ b/README.md
@@ -11,3 +11,109 @@ To build the `present` binary, run:
 To start debugging it, run:
 
     make run-present
+
+# Example debugging session
+This section shows how to debug using GDB.
+
+    exercises$ make run-present
+    qemu-arm -g 1337 present &
+    arm-none-eabi-gdb -q -ex 'tar rem localhost:1337' present
+    Reading symbols from present...done.
+    Remote debugging using localhost:1337
+    _start () at present.S:58
+    58          ldr r0, =input
+
+Step a single instruction:
+
+    (gdb) stepi
+    59          ldr r1, =sbox
+
+Press "Enter" to repeat the last command (stepi):
+
+    (gdb) 
+    60          bl  sub_block
+
+Examine 16 bytes of memory from the address in register `$r0` (our "input"):
+
+    (gdb) x/16b $r0
+    0x2000: 5       1       2       3       4       5       6       7
+    0x2008: 8       9       10      11      12      13      14      15
+
+Examine 16 bytes of memory as hex from the address in register `$r1` (our "sbox"):
+
+    (gdb) x/16x $r1
+    0x2010: 0x0c    0x05    0x06    0x0b    0x09    0x00    0x0a    0x0d
+    0x2018: 0x03    0x0e    0x0f    0x08    0x04    0x07    0x01    0x02
+    (gdb) stepi
+    sub_block () at present.S:30
+    30          eor r3, r3
+
+Set a breakpoint on line 38, continue until that breakpoint:
+
+    (gdb) break 38
+    Breakpoint 1 at 0x1014: file present.S, line 38.
+    (gdb) c
+    Continuing.
+
+    Breakpoint 1, sub_block_loop () at present.S:38
+    38          and r4, #15
+
+List the source code around the current line:
+
+    (gdb) l
+    33          bge sub_block_loop_end
+    34
+    35          // c = input[i] (r4 is low, r5 is high)
+    36          ldrb r4, [r0, r3]
+    37          mov r5, r4
+    38          and r4, #15
+    39          lsr r5, #4
+    40
+    41          // sbox[c_lo]
+    42          ldrb r4, [r1, r4]
+
+Print the contents of some register (normally in decimal, using the `/x`
+specifier it becomes hexadecimal):
+
+    (gdb) p $r0
+    $1 = 8192
+    (gdb) p/x $r0
+    $2 = 0x2000
+    (gdb) p/x $r3
+    $3 = 0x0
+    (gdb) p/x $r4
+    $4 = 0x5
+    (gdb) x/b $r0+$r3
+    0x2000: 0x05
+
+A quick overview of all registers:
+
+    (gdb) info registers
+    r0             0x2000   8192
+    r1             0x2010   8208
+    r2             0x0      0
+    r3             0x0      0
+    r4             0x5      5
+    r5             0x5      5
+    r6             0x0      0
+    r7             0x0      0
+    r8             0x0      0
+    r9             0x0      0
+    r10            0x0      0
+    r11            0x0      0
+    r12            0x0      0
+    sp             0xf6fff5e0       0xf6fff5e0
+    lr             0x1044   4164
+    pc             0x1014   0x1014 <sub_block_loop+16>
+    cpsr           0x80000010       -2147483632
+
+Exiting the debugger:
+
+    (gdb) quit
+    A debugging session is active.
+
+            Inferior 1 [Remote target] will be killed.
+
+    Quit anyway? (y or n) y
+
+    QEMU: Terminated via GDBstub
-- 
cgit v1.2.1