From 9960b3f0296f23cd700630af7f6050889ca4e347 Mon Sep 17 00:00:00 2001 From: Tom Hughes Date: Thu, 16 Jan 2020 17:16:06 -0800 Subject: [PATCH] docs/fingerprint: Add FPMCU debugging doc The debugging docs describes how to use SWD to perform on-chip debugging of the dragonclaw v0.2 dev board with gdbserver. BRANCH=none BUG=none TEST=view in gitiles Change-Id: I5133613ba10eb2d42936c161079d592789e5df18 Signed-off-by: Tom Hughes Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/2007900 Commit-Queue: Yicheng Li Reviewed-by: Yicheng Li --- docs/fingerprint/fingerprint-debugging.md | 162 ++++++++++++++++++ .../fingerprint-dev-for-partners.md | 38 ++-- docs/sitemap.md | 1 + 3 files changed, 174 insertions(+), 27 deletions(-) create mode 100644 docs/fingerprint/fingerprint-debugging.md diff --git a/docs/fingerprint/fingerprint-debugging.md b/docs/fingerprint/fingerprint-debugging.md new file mode 100644 index 0000000000..f5d9760049 --- /dev/null +++ b/docs/fingerprint/fingerprint-debugging.md @@ -0,0 +1,162 @@ +# Fingerprint Debugging + +This document describes how to attach a debugger with SWD in order to debug the +FPMCU. + +[TOC] + +## Overview + +### SWD + +`SWD` (Single Wire Debug) was introduced by ARM with the Cortex-M family to +reduce the pin count required by JTAG. JTAG requires 5 pins, but SWD can be done +with only 3 pins. Furthermore, one of the freed up pins can be repurposed for +tracing. + +See [CoreSight Connectors] for details on the three standard types of connectors +used for JTAG and SWD for ARM devices. + +## Hardware Required + +* JTAG/SWD Debugger Probe: Any debug probe that supports SWD will work, but + this document assumes that you're using a + [Segger J-Trace PRO for Cortex-M][J-Trace]. +* [Dragonclaw v0.2 Development board][FPMCU dev board]. +* [Servo Micro]. + +## Software Required + +* [JLink Software] (when using [J-Trace] or other Segger debug probes). +* Any tool that supports connecting `gdbserver`. This document will assume + [CLion]. +* Alternatively, you can use [Ozone] a standalone debugger from Segger. + +## Connecting SWD + +The connector for SWD is `J4` on Dragonclaw v0.2. + +*** note +**NOTE**: Pay attention to the location of pin 1 (red wire) in the +photos below so that you connect with the correct orientation. + +`SW2` on the bottom of Dragonclaw must be set to `CORESIGHT`. + +If you want to connect a 20-Pin ARM Standard JTAG Connector (0.10" / 2.54 mm), +you can use the following [adapter][JTAG to SWD Adapter] and [cable][SWD Cable]. +*** + +Dragonclaw v0.2 with 20-pin SWD (0.05" / 1.27mm) on J4. Only half the pins are connected. | +----------------------------------------------------------------------------------------- | +![Dragonclaw with 20-pin SWD] | + +Dragonclaw v0.2 with 10-pin SWD (0.05" / 1.27mm) on J4. | +------------------------------------------------------- | +![Dragonclaw with 10-pin SWD] | + +## Powering the Board + +[Servo Micro] can provide both the 3.3V for the MCU and 1.8V for the sensor. + +Run the following to start `servod`, which will enable power to these rails by +default: + +```bash +(chroot) $ sudo servod --board=dragonclaw +``` + +It's also possible to power through J-Trace, though this can only supply the MCU +with power (3.3V), not a sensor using 1.8V. + +## Using JLink gdbserver + +Start the JLink gdbserver for the appropriate MCU type: + +* Dragonclaw / [Nucleo STM32F412ZG]: `STM32F412CG` +* Dragontalon / [Nucleo STM32H743ZI]: `STM32H743ZI` + +```bash +(outside) $ ./JLink_Linux_V660c_x86_64/JLinkGDBServerCLExe -select USB -device STM32F412CG -endian little -if SWD -speed auto -noir -noLocalhostOnly +``` + +You should see the port that gdbserver is running on in the output: + +```bash +Connecting to J-Link... +J-Link is connected. +Firmware: J-Trace PRO V2 Cortex-M compiled Dec 13 2019 11:19:22 +Hardware: V2.00 +S/N: XXXXX +Feature(s): RDI, FlashBP, FlashDL, JFlash, GDB +Checking target voltage... +Target voltage: 3.30 V +Listening on TCP/IP port 2331 <--- gdbserver port +Connecting to target... +Connected to target +Waiting for GDB connection... +``` + +In your editor, specify the IP address and port for gdbserver: + +``` +127.0.0.1:2331 +``` + +You will also want to provide the symbol file: + +* RW image: `build//RW/ec.RW.elf` +* RO image: `build//RO.ec.RO.elf` + +Also, since we're compiling the firmware in the chroot, but your editor is +running outside of the chroot, you'll want to remap the source code path to +account for this: + +* "Remote source" is the path inside the chroot: + `/home//trunk/src/platform/ec` +* "Local source" is the path outside the chroot: + `${HOME}/chromiumos/src/platform/ec` + +To debug with CLion, you will create a new [GDB Remote Debug Configuration] +called `EC Debug`, with: + +* `'target remote' args` (gdbserver IP and port from above): `127.0.0.1:2331` +* `Symbol file` (RW or RO ELF): `/path/to/build//RW/ec.RW.elf` +* `Path mapping`: Add remote to local source path mapping as described above. + +After configuring this if you select the `EC Debug` target in CLion and +[click the debug icon][CLion Start Remote Debug], CLion and JLink will handle +automatically flashing the ELF file and stepping through breakpoints in the +code. Even if not debugging, this may help with your iterative development flow +since the JLink tool can flash very quickly since it performs a differential +flash. Note that you still need to recompile after making changes to the source +code before launching the debugger. + +## Using Ozone + +Ozone is a free standalone debugger provided by Segger that works with the +[J-Trace]. You may want to use it if you need more powerful debug features than +gdbserver can provide. For example, Ozone has a register mapping for the MCUs we +use, so you can easily inspect CPU registers. It can also be automated with a +scripting language and show code coverage when used with a [J-Trace] that is +connected to the trace pins on a board. Note that the Dragonclaw v0.2 uses an +STM32F412 package that does not have the synchronous trace pins, but the +[Nucleo STM32F412ZG] does have the trace pins. + +[CoreSight Connectors]: http://www2.keil.com/coresight/coresight-connectors +[FPMCU dev board]: ./fingerprint-dev-for-partners.md#fpmcu-dev-board +[J-Trace]: https://www.segger.com/products/debug-probes/j-trace/models/j-trace/ +[JLink Software]: https://www.segger.com/downloads/jlink/#J-LinkSoftwareAndDocumentationPack +[Servo Micro]: ./fingerprint-dev-for-partners.md#Servo-Micro +[JTAG to SWD Adapter]: https://www.adafruit.com/product/2094 +[SWD Cable]: https://www.adafruit.com/product/1675 +[Ozone]: https://www.segger.com/products/development-tools/ozone-j-link-debugger/ +[CLion]: https://www.jetbrains.com/clion/ +[GDB Remote Debug Configuration]: https://www.jetbrains.com/help/clion/remote-debug.html#remote-config +[CLion Start Remote Debug]: https://www.jetbrains.com/help/clion/remote-debug.html#start-remote-debug +[Nucleo STM32F412ZG]: https://www.st.com/en/evaluation-tools/nucleo-f412zg.html +[Nucleo STM32H743ZI]: https://www.st.com/en/evaluation-tools/nucleo-h743zi.html + + + +[Dragonclaw with 20-pin SWD]: ../images/dragonclaw_with_20_pin_swd.jpg +[Dragonclaw with 10-pin SWD]: ../images/dragonclaw_with_10_pin_swd.jpg diff --git a/docs/fingerprint/fingerprint-dev-for-partners.md b/docs/fingerprint/fingerprint-dev-for-partners.md index 8cfd64b5cb..67b22de268 100644 --- a/docs/fingerprint/fingerprint-dev-for-partners.md +++ b/docs/fingerprint/fingerprint-dev-for-partners.md @@ -18,10 +18,10 @@ Development for other [EC]s is often done in a similar manner, but some of them have their own standalone development or evaluation kits that don't require the use of [servo]. -You will need an [FPMCU reference board](#fpmcu-board) and a +You will need an [FPMCU reference board](#fpmcu-dev-board) and a [servo debugger](#servo). -### FPMCU board +### FPMCU board {#fpmcu-dev-board} The Fingerprint MCU (FPMCU) board has the MCU that handles all fingerprint-related functionality (matching, encryption, etc). The fingerprint @@ -32,9 +32,15 @@ This FPMCU board is the Dragonclaw Rev 0.2. | ![Dragonclaw board] | +*** note +**Googlers**: You can pick up the Dragonclaw development board at Chromestop. +**Partners**: You can request a Dragonclaw development board from Google. +*** + *** note Dragonclaw Rev 0.2 needs a [rework](#dragonclaw-rev-0.2-rework) for the FPC -sensor to work while being powered through Servo. +sensor to work while being powered through Servo. All of the boards at Chromestop +have already been reworked. *** This FPMCU board is the Dartmonkey Rev 0.1. | @@ -78,26 +84,8 @@ For more information about Servo Micro, see [Servo Micro Info]. #### Using SWD (Optional) {#servo-micro-swd} -Dragonclaw v0.2 has a connector for SWD (`J4`), which can be used -with a debug probe, such as the [Segger J-Link]. +Instructions for setup are described in [Fingerprint Debugging]. -*** note -**NOTE**: Pay attention to the location of pin 1 (red wire) in the photos below -so that you connect with the correct orientation. - -`SW2` on the bottom of Dragonclaw must be set to `CORESIGHT`. - -If you want to connect a 20-Pin ARM Standard JTAG Connector (0.10" / 2.54 mm), -you can use the following [adapter][JTAG to SWD Adapter] and [cable][SWD Cable]. -*** - -Dragonclaw v0.2 with 20-pin SWD (0.05" / 1.27mm) on J4. Only half the pins are connected. | -------------------------------- | -![Dragonclaw with 20-pin SWD] | - -Dragonclaw v0.2 with 10-pin SWD (0.05" / 1.27mm) on J4. | -------------------------------- | -![Dragonclaw with 10-pin SWD] | ### Servo V2 + Yoshi @@ -540,9 +528,7 @@ https://crbug.com/992082. [Git and Gerrit Intro for Chromium OS]: https://chromium.googlesource.com/chromiumos/docs/+/master/git_and_gerrit_intro.md [Installing Chromium]: https://chromium.googlesource.com/chromiumos/docs/+/master/developer_guide.md#installing-chromium-os-on-your-device [FPMCU documentation]: ./fingerprint.md -[Segger J-Link]: https://www.segger.com/products/debug-probes/j-link/ -[JTAG to SWD Adapter]: https://www.adafruit.com/product/2094 -[SWD Cable]: https://www.adafruit.com/product/1675 +[Fingerprint Debugging]: ./fingerprint-debugging.md @@ -560,8 +546,6 @@ https://crbug.com/992082. [Another image]: ../images/dragonclaw_yoshi_flex_header2.jpg [Connect SWD Debugger]: ../images/servo_v2_jtag_header.jpg [Dartmonkey board]: ../images/dartmonkey.jpg -[Dragonclaw with 20-pin SWD]: ../images/dragonclaw_with_20_pin_swd.jpg -[Dragonclaw with 10-pin SWD]: ../images/dragonclaw_with_10_pin_swd.jpg diff --git a/docs/sitemap.md b/docs/sitemap.md index 8ebbfda22a..c92df06489 100644 --- a/docs/sitemap.md +++ b/docs/sitemap.md @@ -17,6 +17,7 @@ * [Fingerprint MCU (FPMCU)](./fingerprint/fingerprint.md) * [FPMCU Development for Partners](./fingerprint/fingerprint-dev-for-partners.md) +* [FPMCU Debugging](./fingerprint/fingerprint-debugging.md) * [Fingerprint Authentication Design Doc](./fingerprint/fingerprint-authentication-design-doc.md) * [Fingerprint Factory Requirements](./fingerprint/fingerprint-factory-requirements.md)