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 <tomhughes@chromium.org>
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/2007900
Commit-Queue: Yicheng Li <yichengli@chromium.org>
Reviewed-by: Yicheng Li <yichengli@chromium.org>

3 files changed, 174 insertions, 27 deletions

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/<board>/RW/ec.RW.elf`
+*   RO image: `build/<board>/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/<username>/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/<board>/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
+
+<!-- Images -->
+
+[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
@@ -33,8 +33,14 @@ This FPMCU board is the Dragonclaw Rev 0.2. |
 
 
 *** 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].
-
-*** 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]   |
+Instructions for setup are described in [Fingerprint Debugging].
 
-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
 
 <!-- Images -->
 
@@ -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
 
 <!-- If you make changes to the docs below make sure to regenerate the JPEGs by
      appending "export/pdf" to the Google Drive link. -->
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)