Added some basic usage documentation

Signed-off-by: Alistair Popple <alistair@popple.id.au>

1 files changed, 125 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7d2fc7b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,125 @@
+# PDBG
+
+pdbg is a simple application to allow debugging of the host POWER
+processors from the BMC. It works in a similar way to JTAG programmers
+for embedded system development in that it allows you to access GPRs,
+SPRs and system memory.
+
+A remote gdb sever is under development to allow integration with
+standard debugging tools.
+
+## Usage
+
+The BMC must first be put into debug mode to allow access to the
+relevant GPIOs:
+
+ipmitool -H <host> -U <username> -P <password> raw 0x3a 0x01
+
+Usage is straight forward:
+
+$ ./pdbg --help
+Usage: ./pdbg [options] command ...
+
+ Options:
+        -c, --chip=chip
+        -t, --thread=thread
+        -h, --help
+
+ Commands:
+        getcfam <address>
+        putcfam <address> <value>
+        getscom <address>
+        putscom <address> <value>
+        getmem <address> <count>
+        getgpr <gpr>
+        getnia
+        getspr <spr>
+        stopchip
+        startchip <threads>
+        threadstatus
+
+### Probe chip and processor numbers
+$ ./pdbg probe
+
+Probing for valid processors...
+        Processor-ID 0: 0x220ea04980000000
+                Chiplet-ID 2 present
+                Chiplet-ID 3 present
+                Chiplet-ID 4 present
+                Chiplet-ID 5 present
+                Chiplet-ID 6 present
+                Chiplet-ID 8 present
+                Chiplet-ID 9 present
+                Chiplet-ID 10 present
+                Chiplet-ID 12 present
+                Chiplet-ID 13 present
+                Chiplet-ID 14 present
+        Processor-ID 3: 0x220ea04982000000
+                Chiplet-ID 1 present
+                Chiplet-ID 2 present
+                Chiplet-ID 5 present
+                Chiplet-ID 6 present
+                Chiplet-ID 9 present
+                Chiplet-ID 10 present
+                Chiplet-ID 11 present
+                Chiplet-ID 12 present
+                Chiplet-ID 13 present
+                Chiplet-ID 14 present
+
+Chiplet-IDs are core/chip numbers which should be passed as arguments
+to -c when performing operations such as getgpr that operate on
+particular cores. Processor-IDs should be passed as arguments to -p to
+operate on different processor chips.
+
+### Read SCOM register
+$ ./pdbg getscom 0xf000f
+0xf000f: 0x220ea04980000000
+
+### Write SCOM register on secondary processor
+$ ./pdbg -p 3 putscom 0x8013c02 0x0
+
+### Read GPR on core/chip 2
+$ ./pdbg -c 2 getgpr 2
+r2 = 0xc00000000174fd00
+
+### Read SPR 8 (LR) on core/chip 2
+$ ./pdbg -c 2 getspr 8
+spr8 = 0xc000000000011824
+
+### Stop thread execution on core/chip 2
+$ ./pdbg -c 2 stopchip
+Previously active thread mask: 0x00
+Thread 0 is STOPPED
+Thread 1 is STOPPED
+Thread 2 is STOPPED
+Thread 3 is STOPPED
+Thread 4 is STOPPED
+Thread 5 is STOPPED
+Thread 6 is STOPPED
+Thread 7 is STOPPED
+
+### Get execution state on core/chip 2
+$ ./pdbg -c 2 threadstatus
+Thread 0 is STOPPED
+Thread 1 is STOPPED
+Thread 2 is STOPPED
+Thread 3 is STOPPED
+Thread 4 is STOPPED
+Thread 5 is STOPPED
+Thread 6 is STOPPED
+Thread 7 is STOPPED
+
+### Restart thread execution on core/chip 2
+
+The first parameter is the active thread mask returned when stopping
+the chip.
+
+$ ./pdbg -c 2 startchip 0x00
+Thread 0 is RUNNING
+Thread 1 is RUNNING
+Thread 2 is RUNNING
+Thread 3 is RUNNING
+Thread 4 is RUNNING
+Thread 5 is RUNNING
+Thread 6 is RUNNING
+Thread 7 is RUNNING