rpi3: update jtag debugging details

1. Add Bus Bluster config/usage details
2. The Raspberry Pi 3 allows to enable JTAG on the GPIO via the
enable_jtag_gpio=1 flag in the config.txt, which is more prefarable.
Switch to this method
3. Add physical memory map
4. Change information about usage of Sequitur labs OpenOCD fork to
the uptsteam OpenOCD, as it already has ARMv8 support

Reviewed-by: Joakim Bech <joakim.bech@linaro.org>
Signed-off-by: Igor Opaniuk <igor.opaniuk@linaro.org>
Tested-by: Igor Opaniuk <igor.opaniuk@linaro.org>
Suggested-by: Joseph Pantoga <jp@redballoonsecurity.com>

docs/rpi3.md

@@ -47,7 +47,6 @@ help out making proper upstream patches sooner or later.
 | linux | https://github.com/Electron752/linux.git commit: b48d47a32b2f27f55904e7248dbe5f8ff434db0a | Three things here. 1. The base is a fork itself and should be upstreamed. 2. Apply patch [arm64: dt: RPI3: Add optee node] 3. We have cherry picked the patches from [LSK OP-TEE 4.4] |
 | arm-trusted-firmware | https://github.com/96boards-hikey/arm-trusted-firmware commit: bdec62eeb8f3153a4647770e08aafd56a0bcd42b | This should instead be based on the official OP-TEE fork or even better the official ARM repository. The patch itself should also be upstreamed. |
 | U-boot | https://github.com:linaro-swg/u-boot.git | This is just a mirror of the official U-boot git. The patches should be upstreamed. |
-| OpenOCD | https://github.com/seqlabs/openocd | The patches should be upstreamed. |
 
 # 3. Build instructions
 - First thing to pay attention to the [OP-TEE prerequisites]. If you forget
@@ -222,7 +221,7 @@ $ cd /home/jbech/devel/optee_projects/rpi3/boot/
 # clean previous uboot.env
 $ make u-boot-env-clean
 # generate new
-$ make u-boot-jtag-bin
+$ make u-boot-bin
 ```
 Then you need to copy your newly generated `uboot.env`(it's stored in `../out/uboot.env`)
 to the BOOT partition of your SD card.
@@ -292,19 +291,19 @@ need to reboot the RPi after a rebuild.
 # 6. OpenOCD and JTAG
 First a word of warning here, even though this seems to be working quite good as
 of now, it should be well understood that this is based on incomplete and out of
-tree patches. So what are the major changes that enables this? First [OpenOCD]
-currently doesn't contain ARMv8-A / AArch64 support in the upstream tree. A
-couple of different people have put something together that gets the job done.
-But to get in a shape for upstream, there is still quite a lot left to do. The
-other change needed is in U-Boot, that is where we configure the [RPi3 GPIO
-pins] so that they will talk JTAG. The pin configuration and the wiring for the
-cable looks like this:
+tree patches. There are major changes in our U-Boot fork that add capability to
+load and execute ARM Trusted Firmware binary.
+
+To enable JTAG you need to uncomment the line: `enable_jtag_gpio=1` in
+`rpi3/firmware/config.txt`.
+
+The pin configuration and the wiring for the cable looks like this:
 
 |JTAG pin|Signal|GPIO   |Mode |Header pin|
 |--------|------|-------|-----|----------|
 | 1      |3v3   |N/A    |N/A  | 1        |
 | 3      |nTRST |GPIO22 |ALT4 | 15       |
-| 5      |TDI   |GPIO4  |ALT5 | 7        |
+| 5      |TDI   |GPIO26 |ALT4 | 37       |
 | 7      |TMS   |GPIO27 |ALT4 | 13       |
 | 9      |TCK   |GPIO25 |ALT4 | 22       |
 | 11     |RTCK  |GPIO23 |ALT4 | 16       |
@@ -330,23 +329,38 @@ that we have also connected a USB FTDI to UART cable to a few more pins.
 
 ## 6.2 OpenOCD
 ### 6.2.1 Build the software
-We are using the [Sequitur Labs OpenOCD] fork, simply clone that to your
+Before building OpenOCD, **libusb-dev** package should be installed in advance:
+```bash
+$ sudo apt-get install libusb-1.0-0-dev
+```
+
+We are using the [Official OpenOCD] release, simply clone that to your
 computer and then building is like a lot of other software, i.e.,
+
 ```bash
+$ git clone http://repo.or.cz/openocd.git && cd openocd
 $ ./bootstrap
 $ ./configure
 $ make
 ```
+If a jtag debugger needs legacy ft2332 support, OpenOCD should be
+configured with `--enable-legacy-ft2232_libftdi` flag:
+```bash
+$ ./configure --enable-legacy-ft2232_libftdi
+```
+
 We leave it up to the reader of this guide to decide if he wants to install it
 properly (`make install`) or if he will just run it from the tree directly. The
 rest of this guide will just run it from the tree.
 
 ### 6.2.2 OpenOCD RPi3 configuration file
-In the OpenOCD fork you will find the necessary [RPi3 OpenOCD config]. As you
-can read there, it's prepared for four targets, but only one is enabled. The
-reason for that is simply because it's a lot simpler to get started with JTAG
-when running on a single core. When you have a stable setup using a single core,
-then you can start playing with enabling additional cores.
+Unfortunately, the necessary [RPi3 OpenOCD config] isn't upstreamed yet into the
+[Official OpenOCD] repository, so you should use the one stored
+here `rpi3/debugger/pi3.cfg`. As you can read there, it's prepared
+for four targets, but only one is enabled. The reason for that is simply
+because it's a lot simpler to get started with JTAG when running on a single
+core. When you have a stable setup using a single core, then you can start
+playing with enabling additional cores.
 ```
 ...
 target create $_TARGETNAME_0 aarch64 -chain-position $_CHIPNAME.dap -dbgbase 0x80010000 -ctibase 0x80018000
@@ -362,7 +376,14 @@ and [Bus Blaster] successfully. To start an OpenOCD session using a J-Link
 device you type:
 ```bash
 $ cd <openocd>
-$ ./src/openocd -f ./tcl/interface/jlink.cfg -f ./pi3.cfg
+$ ./src/openocd -f ./tcl/interface/jlink.cfg \
+-f <rpi3_repo_dir>/build/rpi3/debugger/pi3.cfg
+```
+
+For Bus Blaster type:
+```bash
+$ ./src/openocd -f ./tcl/interface/ftdi/dp_busblaster.cfg \
+-f <rpi3_repo_dir>/build/rpi3/debugger/pi3.cfg
 ```
 
 To be able to write commands to OpenOCD, you simply open up another shell and
@@ -450,6 +471,17 @@ will be a bit upset when continue running after triggering a breakpoint in
 secure world (rcu starving messages etc). If you have suggestion and or
 improvements, as usual, feel free to contribute.
 
+## 6.7 Physical memory map
+
+|Physical address|Component|
+|----------------|------|
+| 0x0            | Stubs + U-boot, U-boot self-relocates to high memory |
+| 0x80000        | Linux image        |
+| 0x01700000     | Linux DTS          |
+| 0x08000000     | Non-secure SHM     |
+| 0x08400000     | BL31               |
+| 0x08420000     | BL32 (OP-TEE core) |
+
 [buildroot]: https://buildroot.org
 [Bus Blaster]: http://dangerousprototypes.com/docs/Bus_Blaster
 [J-Link debuggers]: https://www.segger.com/jlink_base.html
@@ -462,8 +494,8 @@ improvements, as usual, feel free to contribute.
 [Raspbian]: https://www.raspbian.org
 [README.md]: ../README.md
 [RPi3 GPIO pins]: https://pinout.xyz/pinout/jtag
-[RPi3 OpenOCD config]: https://github.com/seqlabs/openocd/blob/armv8/pi3.cfg
+[RPi3 OpenOCD config]: https://github.com/OP-TEE/build/blob/master/rpi3/debugger/pi3.cfg
+[Official OpenOCD]: http://openocd.org/
 [Sequitur Labs]: http://www.sequiturlabs.com
-[Sequitur Labs OpenOCD]: https://github.com/seqlabs/openocd
 [SMP]: https://en.wikipedia.org/wiki/Symmetric_multiprocessing
 [xtest instructions]: https://github.com/OP-TEE/build#78-load-tee-supplicant

rpi3.mk

@@ -38,7 +38,7 @@ ARM_TF_BOOT             ?= $(ARM_TF_OUT)/optee.bin
 
 U-BOOT_PATH		?= $(ROOT)/u-boot
 U-BOOT_BIN		?= $(U-BOOT_PATH)/u-boot.bin
-U-BOOT_JTAG_BIN		?= $(U-BOOT_PATH)/u-boot-jtag.bin
+U-BOOT_RPI_BIN		?= $(U-BOOT_PATH)/u-boot-rpi.bin
 
 RPI3_FIRMWARE_PATH		?= $(BUILD_PATH)/rpi3/firmware
 RPI3_HEAD_BIN			?= $(ROOT)/out/head.bin
@@ -61,9 +61,9 @@ ifeq ($(CFG_TEE_BENCHMARK),y)
 all: benchmark-app
 clean: benchmark-app-clean
 endif
-all: rpi3-firmware arm-tf optee-os optee-client xtest u-boot u-boot-jtag-bin\
+all: rpi3-firmware arm-tf optee-os optee-client xtest u-boot u-boot-rpi-bin\
 	linux update_rootfs
-clean: arm-tf-clean busybox-clean u-boot-clean u-boot-jtag-bin-clean \
+clean: arm-tf-clean busybox-clean u-boot-clean u-boot-rpi-bin-clean \
 	optee-os-clean optee-client-clean rpi3-firmware-clean head-bin-clean
 
 -include toolchain.mk
@@ -111,11 +111,11 @@ u-boot: $(RPI3_HEAD_BIN)
 u-boot-clean:
 	$(U-BOOT_EXPORTS) $(MAKE) -C $(U-BOOT_PATH) clean
 
-u-boot-jtag-bin: $(RPI3_UBOOT_ENV) u-boot
-	cd $(U-BOOT_PATH) && cat $(RPI3_HEAD_BIN) $(U-BOOT_BIN) > $(U-BOOT_JTAG_BIN)
+u-boot-rpi-bin: $(RPI3_UBOOT_ENV) u-boot
+	cd $(U-BOOT_PATH) && cat $(RPI3_HEAD_BIN) $(U-BOOT_BIN) > $(U-BOOT_RPI_BIN)
 
-u-boot-jtag-bin-clean:
-	rm -f $(U-BOOT_JTAG_BIN)
+u-boot-rpi-bin-clean:
+	rm -f $(U-BOOT_RPI_BIN)
 
 $(RPI3_HEAD_BIN): $(RPI3_FIRMWARE_PATH)/head.S
 	mkdir -p $(ROOT)/out/
@@ -261,7 +261,7 @@ filelist-tee: filelist-tee-common
 	@echo "file /boot/Image $(LINUX_IMAGE) 755 0 0" >> $(GEN_ROOTFS_FILELIST)
 	@echo "file /boot/optee.bin $(ARM_TF_BOOT) 755 0 0" >> $(GEN_ROOTFS_FILELIST)
 	@echo "file /boot/uboot.env $(RPI3_UBOOT_ENV) 755 0 0" >> $(GEN_ROOTFS_FILELIST)
-	@echo "file /boot/u-boot-jtag.bin $(U-BOOT_JTAG_BIN) 755 0 0" >> $(GEN_ROOTFS_FILELIST)
+	@echo "file /boot/u-boot-rpi.bin $(U-BOOT_RPI_BIN) 755 0 0" >> $(GEN_ROOTFS_FILELIST)
 	@cd $(MODULE_OUTPUT) && find ! -path . -type d | sed 's/\.\(.*\)/dir \1 755 0 0/g' >> $(GEN_ROOTFS_FILELIST)
 	@cd $(MODULE_OUTPUT) && find -type f | sed "s|\.\(.*\)|file \1 $(MODULE_OUTPUT)\1 755 0 0|g" >> $(GEN_ROOTFS_FILELIST)
 	@echo "file /boot/bootcode.bin $(RPI3_STOCK_FW_PATH)/boot/bootcode.bin 755 0 0" >> $(GEN_ROOTFS_FILELIST)

rpi3/firmware/config.txt

@@ -2,7 +2,8 @@ enable_uart=1
 arm_control=0x200
 kernel_old=1
 
-kernel=u-boot-jtag.bin
+kernel=u-boot-rpi.bin
+#enable_jtag_gpio=1
 
 disable_commandline_tags=1