.TH PDBG "8" "October 2021" "pdbg" "System Administration Utilities" .SH NAME pdbg \- PowerPC FSI Debugger .SH SYNOPSIS .B pdbg [options] command ... .SH DESCRIPTION .B 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. .SH OPTIONS .TP .B -p, --processor=\fI<0-63>\fP|\fI\fP|\fI\fP .TP .B -c, --chip=\fI<0-23>\fP|\fI\fP|\fI\fP .TP .B -t, --thread=\fI<0-7>\fO|\fI\fP|\fI\fP .TP .B -l, --cpu=\fI<0-63>\fP|\fI\fP|\fI\fP Requires device (-d) to be set to p8|p9 .TP .B -P, --path=\fI\fI .TP .B -a, --all Run command on all possible processors/chips/threads (default) .TP .B -b, --backend=\fIbackend\fP Several backends are supported depending on which system you are using : .RS .IP cronus A backend based on cronus server .IP sbefifo A backend using sbefifo kernel driver .IP fsi An experimental backend that uses bit-banging to access the host processor via the FSI bus. .IP i2c The P8 only backend which goes via I2C. .IP kernel The default backend which goes the kernel FSI driver. .RE .TP .B -d, --device=\fIbackend-device\fP For I2C the device node used by the backend to access the bus. .br For FSI the system board type, one of p8 or p9w .br Defaults to \fI\,/dev/i2c4\/\fP for I2C .TP .B -s, --slave-address=\fIbackend-device-address\fP Device slave address to use for the backend. Not used by FSI and defaults to 0x50 for I2C. .TP .B -D, --debug=\fI\fP 0:error (default) 1:warning 2:notice 3:info 4:debug .TP .B -S, --shutup Shut up those annoying progress bars .TP .B -V, --version .TP .B -h, --help .RE .SH COMMANDS .TP .B getgpr \fI\fP Read General Purpose Register (GPR) .TP .B putgpr \fI\fP \fI\fP Write General Purpose Register (GPR) .TP .B getspr \fI\fP Get Special Purpose Register (SPR) .TP .B putspr \fI\fP \fI\fP Write Special Purpose Register (SPR) .TP .B getring \fI\fP \fI\fP Read a ring. Length must be correct .TP .B start Start thread .TP .B step \fI\fP Set a thread instructions .TP .B stop Stop thread .TP .B htm core|nest start|stop|status|dump|record Hardware Trace Macro .TP .B probe .TP .B getcfam \fI
\fP Read system cfam .TP .B putcfam \fI
\fP \fI\fP [\fI\fP] Write system cfam .TP .B getscom \fI
\fP Read system scom .TP .B putscom \fI
\fP \fI\fP [\fI\fP] Write system scom .TP .B getmem \fI
\fP \fI\fP [--ci] [--raw] Read system memory .TP .B getmempba \fI
\fP \fI\fP [--ci] [--raw] Read system memory .TP .B getmemio \fI
\fP \fI\fP \fI\fP [--raw] Read memory cache inhibited with specified transfer size .TP .B putmem \fI
\fP [--ci] Write to system memory .TP .B putmempba \fI
\fP [--ci] Write to system memory .TP .B putmemio \fI
\fP \fI\fP Write system memory cache inhibited with specified transfer size .TP .B threadstatus Print the status of a thread .TP .B sreset Reset .TP .B regs [--backtrace] State (optionally display backtrace) .TP .B gdbserver Start a gdb server .TP .B istep \fI\fP \fI\fP|0 Execute istep on SBE .RE .nh .SH Usage .PP Several backends are supported depending on which system you are using and are selected using the \fB\fC-b\fR option: .PP POWER8 Backends: .RS .IP \(bu 2 i2c (default): Uses an i2c connection between BMC and host processor .IP \(bu 2 fsi: Uses a bit-banging GPIO backend which accesses BMC registers directly via /dev/mem/. Requires \fB\fC-d p8\fR to specify you are running on a POWER8 system. .RE .PP POWER9 Backends: .RS .IP \(bu 2 kernel (default): Uses the in kernel OpenFSI driver provided by OpenBMC .IP \(bu 2 fsi: Uses a bit-banging GPIO backend which accesses BMC registers directly via /dev/mem. Requiers \fB\fC-d p9w/p9r/p9z\fR as appropriate for the system. .IP \(bu 2 sbefifo: Uses the in kernel OpenFSI & SBEFIFO drivers provided by OpenBMC .RE .PP When using the fsi backend POWER8 AMI based BMC's must first be put into debug mode to allow access to the relevant GPIOs: .PP \fB\fCipmitool -H -U -P raw 0x3a 0x01\fR .PP On POWER9 when using the fsi backend it is also a good idea to put the BMC into debug mode to prevent conflicts with the OpenFSI driver. On the BMC run: .PP \fB\fCsystemctl start fsi-disable.service && systemctl stop host-failure-reboots@0.service\fR .PP Usage is straight forward. Note that if the binary is not statically linked all commands need to be prefixed with LD_LIBRARY_PATH= in addition to the arguments for selecting a backend. .SS Target Selection .PP pdbg has commands that operate on specific hardware unit(s) inside the POWER processor. To select appropriate hardware unit (commonly referred as \fBtarget\fP), pdbg provides two different mechanisms. .SS Select processor(s) / Core(s) / Thread(s) using -p/-c/-t/-a/-l .PP Many commands typically operate on hardware thread(s) or CPU(s) as identified by Linux. .RS .IP \(bu 2 all threads (\fB\fC-a\fR) .IP \(bu 2 core 0 of processor 0 (\fB\fC-p0 -c0\fR) .IP \(bu 2 all threads on processor 0 (\fB\fC-p0 -a\fR) .IP \(bu 2 all threads on core 1 of processor 0 (\fB\fC-p0 -c1 -a\fR) .IP \(bu 2 thread 2 on core 1 of processor 0 (\fB\fC-p0 -c1 -t2\fR) .IP \(bu 2 thread 0 on all cores of processor 0 (\fB\fC-p0 -t0 -a\fR) .IP \(bu 2 threads 1,2,3,4 on cores 1,3,5 of processor 1 (\fB\fC-p1 -c1,3,5 -t1-4\fR) .IP \(bu 2 CPUs 15 and 17 as identified by Linux (\fB\fC-l15,17\fR) .RE .PP Note: \fB\fC-l\fR option is only available when running \fB\fCpdbg\fR on the host. .SS Select targets based on path using -P .PP To select any target in a device tree, it can be specified using \fB\fC-P\fR\&. The -P option takes path specification as an argument. This path specification is constructed using the \fIclass\fP names of targets present in a device tree. .PP Some of the targets currently available for selection are: .RS .IP \(bu 2 \fB\fCpib\fR .IP \(bu 2 \fB\fCcore\fR .IP \(bu 2 \fB\fCthread\fR .IP \(bu 2 \fB\fCadu\fR .IP \(bu 2 \fB\fCfsi\fR .IP \(bu 2 \fB\fCchiplet\fR .RE .PP Path specification can be either an individual target or a \fIpath\fP constructed using more than one targets. .RS .IP \(bu 2 all threads (\fB\fC-P thread\fR) .IP \(bu 2 core 0 of processor 0 (\fB\fC-P pib0/core0\fR) .IP \(bu 2 all threads on processor 0 (\fB\fC-P pib0/thread\fR) .IP \(bu 2 all threads on core 1 of processor 0 (\fB\fC-P pib0/core1/thread\fR) .IP \(bu 2 thread 2 on core 1 of processor 0 (\fB\fC-P pib0/core1/thread2\fR) .IP \(bu 2 thread 0 on all cores of processor 0 (\fB\fC-P pib0/thread0\fR) .IP \(bu 2 threads 1,2,3,4 on cores 1,3,5 of processor 1 (\fB\fC-P pib1/core[1,3,5]/thread[1-4]\fR) .IP \(bu 2 chiplet at address 21000000 (-P \fB\fCchiplet@21000000\fR) .IP \(bu 2 all adus (\fB\fC-P adu\fR) .IP \(bu 2 First FSI (\fB\fC-P fsi0\fR) .RE .SH Examples .PP .RS .nf $ pdbg --help Usage: pdbg [options] command ... Options: -p, --processor=processor-id -c, --chip=chiplet-id -t, --thread=thread -a, --all Run command on all possible processors/chips/threads (default) -b, --backend=backend fsi: An experimental backend that uses bit-banging to access the host processor via the FSI bus. i2c: The P8 only backend which goes via I2C. kernel: The default backend which goes the kernel FSI driver. -d, --device=backend device For I2C the device node used by the backend to access the bus. For FSI the system board type, one of p8 or p9w Defaults to /dev/i2c4 for I2C -s, --slave-address=backend device address Device slave address to use for the backend. Not used by FSI and defaults to 0x50 for I2C -V, --version -h, --help Commands: getcfam
putcfam
[] getscom
putscom
[] getmem
putmem
getvmem getgpr putgpr getnia putnia getspr putspr start step stop threadstatus probe .fi .RE .SS Probe chip/processor/thread numbers .PP .RS .nf $ pdbg -a probe proc0: Processor Module fsi0: Kernel based FSI master (*) pib0: Kernel based FSI SCOM (*) chiplet16: POWER9 Chiplet eq0: POWER9 eq ex0: POWER9 ex chiplet32: POWER9 Chiplet core0: POWER9 Core (*) thread0: POWER9 Thread (*) thread1: POWER9 Thread (*) thread2: POWER9 Thread (*) thread3: POWER9 Thread (*) chiplet33: POWER9 Chiplet core1: POWER9 Core (*) thread0: POWER9 Thread (*) thread1: POWER9 Thread (*) thread2: POWER9 Thread (*) thread3: POWER9 Thread (*) ex1: POWER9 ex chiplet34: POWER9 Chiplet core2: POWER9 Core (*) thread0: POWER9 Thread (*) thread1: POWER9 Thread (*) thread2: POWER9 Thread (*) thread3: POWER9 Thread (*) chiplet35: POWER9 Chiplet core3: POWER9 Core (*) thread0: POWER9 Thread (*) thread1: POWER9 Thread (*) thread2: POWER9 Thread (*) thread3: POWER9 Thread (*) chiplet17: POWER9 Chiplet eq1: POWER9 eq ex0: POWER9 ex chiplet36: POWER9 Chiplet core4: POWER9 Core (*) thread0: POWER9 Thread (*) thread1: POWER9 Thread (*) thread2: POWER9 Thread (*) thread3: POWER9 Thread (*) chiplet37: POWER9 Chiplet core5: POWER9 Core (*) thread0: POWER9 Thread (*) thread1: POWER9 Thread (*) thread2: POWER9 Thread (*) thread3: POWER9 Thread (*) ex1: POWER9 ex chiplet18: POWER9 Chiplet eq2: POWER9 eq ex0: POWER9 ex chiplet40: POWER9 Chiplet core8: POWER9 Core (*) thread0: POWER9 Thread (*) thread1: POWER9 Thread (*) thread2: POWER9 Thread (*) thread3: POWER9 Thread (*) chiplet41: POWER9 Chiplet core9: POWER9 Core (*) thread0: POWER9 Thread (*) thread1: POWER9 Thread (*) thread2: POWER9 Thread (*) thread3: POWER9 Thread (*) ex1: POWER9 ex chiplet19: POWER9 Chiplet eq3: POWER9 eq ex0: POWER9 ex chiplet44: POWER9 Chiplet core12: POWER9 Core (*) thread0: POWER9 Thread (*) thread1: POWER9 Thread (*) thread2: POWER9 Thread (*) thread3: POWER9 Thread (*) chiplet45: POWER9 Chiplet core13: POWER9 Core (*) thread0: POWER9 Thread (*) thread1: POWER9 Thread (*) thread2: POWER9 Thread (*) thread3: POWER9 Thread (*) ex1: POWER9 ex chiplet46: POWER9 Chiplet core14: POWER9 Core (*) thread0: POWER9 Thread (*) thread1: POWER9 Thread (*) thread2: POWER9 Thread (*) thread3: POWER9 Thread (*) chiplet47: POWER9 Chiplet core15: POWER9 Core (*) thread0: POWER9 Thread (*) thread1: POWER9 Thread (*) thread2: POWER9 Thread (*) thread3: POWER9 Thread (*) chiplet20: POWER9 Chiplet eq4: POWER9 eq ex0: POWER9 ex chiplet48: POWER9 Chiplet core16: POWER9 Core (*) thread0: POWER9 Thread (*) thread1: POWER9 Thread (*) thread2: POWER9 Thread (*) thread3: POWER9 Thread (*) chiplet49: POWER9 Chiplet core17: POWER9 Core (*) thread0: POWER9 Thread (*) thread1: POWER9 Thread (*) thread2: POWER9 Thread (*) thread3: POWER9 Thread (*) ex1: POWER9 ex chiplet21: POWER9 Chiplet eq5: POWER9 eq ex0: POWER9 ex ex1: POWER9 ex chiplet54: POWER9 Chiplet core22: POWER9 Core (*) thread0: POWER9 Thread (*) thread1: POWER9 Thread (*) thread2: POWER9 Thread (*) thread3: POWER9 Thread (*) chiplet55: POWER9 Chiplet core23: POWER9 Core (*) thread0: POWER9 Thread (*) thread1: POWER9 Thread (*) thread2: POWER9 Thread (*) thread3: POWER9 Thread (*) proc1: Processor Module proc2: Processor Module proc3: Processor Module proc4: Processor Module proc5: Processor Module proc6: Processor Module proc7: Processor Module Note that only selected targets (marked with *) and targets in the hierarchy of the selected targets will be shown above. If none are shown try adding '-a' to select all targets. .fi .RE .PP Core-IDs are core/chip numbers which should be passed as arguments to \fB\fC-c\fR when performing operations such as getgpr that operate on particular cores. Processor-IDs should be passed as arguments to \fB\fC-p\fR to operate on different processor chips. Specifying no targets is an error and will result in the following error message: .PP .RS .nf Note that only selected targets will be shown above. If none are shown try adding '-a' to select all targets .fi .RE .PP If the above error occurs even though targets were specified it means the specified targets were not found when probing the system. .SS Read SCOM register .PP .RS .nf $ pdbg -P pib getscom 0xf000f p0: 0x00000000000f000f = 0x222d104900008040 (/proc0/pib) p1: 0x00000000000f000f = 0x222d104900008040 (/proc1/pib) .fi .RE .SS Write SCOM register on secondary processor .PP \fB\fC$ pdbg -P pib1 putscom 0x8013c02 0x0\fR .SS Get thread status .PP .RS .nf $ pdbg -a threadstatus p0t: 0 1 2 3 c22: A A A A c21: A A A A c20: A A A A c19: A A A A c15: A A A A c14: A A A A c07: A A A A c05: A A A A p1t: 0 1 2 3 c23: A A A A c22: A A A A c21: A A A A c20: A A A A c19: A A A A c18: A A A A c17: A A A A c16: A A A A .fi .RE .SS Stop thread execution on thread 0-4 of processor 0 core/chip 22 .PP Reading thread register values requires all threads on a given core to be in the quiesced state. .PP .RS .nf $ pdbg -p0 -c22 -t0 -t1 -t2 -t3 stop $ pdbg -p0 -c22 -t0 -t1 -t2 -t3 threadstatus p0t: 0 1 2 3 c22: Q Q Q Q .fi .RE .SS Read GPR on thread 0 of processor 0 core/chip 22 .PP .RS .nf $ pdbg -p0 -c22 -t0 getgpr 2 p0:c22:t0:gpr02: 0xc000000000f09900 .fi .RE .SS Read SPR 8 (LR) on thread 0 of processor 0 core/chip 22 .PP .RS .nf $ pdbg -p0 -c22 -t0 getspr 8 p0:c22:t0:spr008: 0xc0000000008a97f0 .fi .RE .SS Restart thread 0-4 execution on processor 0 core/chip 22 .PP .RS .nf pdbg -p0 -c22 -t0 -t1 -t2 -t3 start pdbg -p0 -c22 -t0 -t1 -t2 -t3 threadstatus p0t: 0 1 2 3 c22: A A A A .fi .RE .SS Write to memory through processor 1 .PP .RS .nf $ echo hello | sudo pdbg -p 1 putmem 0x250000001 Wrote 6 bytes starting at 0x0000000250000001 .fi .RE .SS Read 6 bytes from memory through processor 1 .PP .RS .nf $ sudo pdbg -p 1 getmem 0x250000001 6 | hexdump -C 0x0000000250000000: 68 65 6c 6c 6f 0a $ sudo pdbg -p 1 getmem 0x250000001 6 --raw | hexdump -C 00000000 68 65 6c 6c 6f 0a |hello.| 00000006 .fi .RE .SS Write to cache-inhibited memory through processor 1 .PP .RS .nf $ echo hello | sudo pdbg -p 1 putmem --ci 0x3fe88202 Wrote 6 bytes starting at 0x000000003fe88202 .fi .RE .SS Read from cache-inhibited memory through processor 1 .PP .RS .nf $ sudo pdbg -p 1 getmem --ci 0x3fe88202 6 --raw | hexdump -C 00000000 68 65 6c 6c 6f 0a |hello.| 00000006 .fi .RE .SS Read 4 bytes from the hardware RNG .PP .RS .nf $ lsprop /proc/device-tree/hwrng@3ffff40000000/ ibm,chip-id 00000000 compatible "ibm,power-rng" reg 0003ffff 40000000 00000000 00001000 phandle 100003bd (268436413) name "hwrng" $ sudo pdbg -p 0 getmem --ci 0x0003ffff40000000 4 --raw |hexdump -C 00000000 01 c0 d1 79 |...y| 00000004 $ sudo pdbg -p 0 getmem --ci 0x0003ffff40000000 4 --raw |hexdump -C 00000000 77 9b ab ce |w...| 00000004 $ sudo pdbg -p 0 getmem --ci 0x0003ffff40000000 4 --raw |hexdump -C 00000000 66 8d fb 42 |f..B| 00000004 $ sudo pdbg -p 0 getmem --ci 0x0003ffff40000000 4 --raw |hexdump -C 00000000 fa 9b e3 44 |...D| 00000004 .fi .RE .SS Hardware Trace Macro (HTM) .PP Exploitation of HTM is limited to POWER8 Core from the powerpc host. .SS Prerequisites .PP Core HTM on POWER8 needs to run SMT1 and no power save, so you need to run this first: .PP .RS .nf ppc64_cpu --smt=1 for i in /sys/devices/system/cpu/cpu*/cpuidle/state*/disable;do echo 1 > $i;done .fi .RE .PP Also, using HTM requires a kernel built with both \fB\fCCONFIG_PPC_MEMTRACE=y\fR (v4.14) and \fB\fCCONFIG_SCOM_DEBUGFS=y\fR\&. debugfs should be mounted at \fB\fC/sys/kernel/debug\fR\&. Ubuntu 18.04 has this by default. .SS How to run HTM .PP pdbg provides a \fB\fChtm\fR command with a variety of sub-commands. The most useful command is \fB\fCrecord\fR which will start the trace, wait for buffer to fill (~1 sec), stop and then dump the trace to a file (~5 sec). eg. .PP .RS .nf pdbg -l 0 htm core record .fi .RE .PP pdbg -l allows users to specify CPUs using the same addressing as scheme as taskset -c. This can be useful for tracing workloads. eg. .PP .RS .nf taskset -c 0 myworkload sleep 1 pdbg -l 0 htm core record .fi .RE .PP There are also low level htm commands which can also be used: - \fB\fCstart\fR will configure the hardware and start tracing in wrapping mode. - \fB\fCstop\fR will still stop the trace and de-configure the hardware. - \fB\fCdump\fR will dump the trace to a file. .SS GDBSERVER .PP At the moment gdbserver is only supported on P8 while the cores are in the kernel. .PP To run a gdbserver on a P8 machine from a BMC running openbmc: .PP Stop all the threads of the core you want to look at $ pdbg -d p8 -c11 -a stop .PP Run gdbserver on thread 0 of core 11, accessible through port 44 $ pdbg -d p8 -p0 -c11 -t0 gdbserver 44 .PP On your local machine: $ gdb (gdb) set architecture powerpc:common64 (gdb) target remote palm5-bmc:44 .PP Debugging info: (gdb) set debug remote 10 .PP Notes: 1. DON'T RUN PDBG OVER FSI WHILE HOSTBOOT IS RUNNING. Weird things seem to happen. 2. If you want to view the kernel call trace then run gdb on the vmlinux that the host is running (the kernel needs to be compiled with debug symbols). .SH Submitting patches .PP Development and patch review happens on the mailing list at: .PP pdbg@lists.ozlabs.org .PP Patches are tracked through patchwork: .PP https://patchwork.ozlabs.org/project/pdbg/list .PP Pull requests via Github are also acceptable if you are not familiar with email based patch submission.