docs/fingerprint: Add instructions to run firmware tests

BRANCH=none
BUG=b:171422264
TEST=none

Change-Id: I677b1f17a997a21e906674bb4dc9e02a8e207a1f
Signed-off-by: Yicheng Li <yichengli@chromium.org>
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/2552353
Reviewed-by: Tom Hughes <tomhughes@chromium.org>
Commit-Queue: Tom Hughes <tomhughes@chromium.org>

2 files changed, 112 insertions, 0 deletions

diff --git a/docs/fingerprint/fingerprint-firmware-testing-for-partners.md b/docs/fingerprint/fingerprint-firmware-testing-for-partners.md
new file mode 100644
index 0000000000..d82c164874
--- /dev/null
+++ b/docs/fingerprint/fingerprint-firmware-testing-for-partners.md
@@ -0,0 +1,111 @@
+# Fingerprint Firmware Testing Instructions for Partners
+
+This document is intended to help partners (sensor vendors, MCU vendors, etc)
+run the Chrome OS fingerprint team's firmware tests, as part of the AVL process.
+The document assumes that you‘re using Linux to do the development; preferably
+a recent version of Ubuntu or Debian. It may be possible to use a virtual
+machine, but that is not a configuration we test.
+
+[TOC]
+
+## Hardware Requirements
+
+You will need a Chromebook with the fingerprint sensor and fingerprint MCU
+(FPMCU), and a [servo debugger].
+
+### Chromebook with fingerprint sensor
+
+The Chromebook needs to be in [developer mode] and running a test image so that
+the test can ssh into it. The fingerprint firmware tests will run a series of
+bash commands, including flashing the FPMCU firmware and rebooting the
+Chromebook. You do not need [CCD] because servo will handle the firmware write
+protection for you.
+
+### Servo
+
+Servo is a general purpose debug board used in many automated tests in Chromium
+OS. Among other things, servo enables the tests to toggle hardware write
+protect.
+
+While there are multiple versions of servo, for firmware tests we strongly
+recommend [Servo V4] as that's the simplest and most often used in autotests.
+This document will assume you are using Servo V4.
+
+### Hardware Setup
+
+*   Connect the "HOST" side of Servo V4 to your host machine (which should have
+    a Chromium OS chroot).
+*   Connect the other side of Servo V4 to a USB port on the Chromebook with
+    fingerprint sensor.
+*   Connect the "DUT POWER" side of Servo V4 to power supply.
+*   Make sure the USB cable from the host machine to Servo V4 is in data
+    transfer mode (i.e. if there's an LED, it should be yellow instead of green).
+*   Make sure the you can ssh into the Chromebook from the chroot on the host
+    machine.
+
+## Software Setup
+
+### Get the Chromium OS source code.
+
+*   First, make sure you [have the prerequisites].
+*   Then [get the source].
+
+### Build the autotest codebase
+
+```bash
+# from a terminal on your machine
+(outside chroot) $ cd ~/chromiumos/src
+
+# enter the chroot (the flag is important)
+(outside chroot) $ cros_sdk --no-ns-pid
+
+# build autotest for the board to be tested
+(chroot) $ emerge-<BOARD> autotest
+```
+
+### Start servod
+
+```bash
+(chroot) $ sudo servod --board=<BOARD>
+```
+
+At this point the servod daemon should be running and listening to port 9999 by
+default. If it isn't, check the hardware connection.
+
+## Run a Single Fingerprint Firmware Test
+
+Use another terminal and enter the chroot like before:
+
+```bash
+(outside chroot) $ cd ~/chromiumos/src
+(outside chroot) $ cros_sdk --no-ns-pid
+```
+
+To run a single test, use this command in your chroot:
+
+```bash
+test_that --board=<BOARD> <IP> <test name>
+```
+
+For example:
+
+```bash
+test_that --board=nocturne <IP> firmware_Fingerprint.ReadFlash
+```
+
+## Run the Entire Fingerprint Firmware Test Suite
+
+To run the entire suite, use this command in your chroot:
+
+```bash
+test_that --board=<BOARD> <IP> suite:fingerprint
+```
+
+<!-- Links -->
+
+[servo debugger]: https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/master/docs/servo.md
+[developer mode]: https://chromium.googlesource.com/chromiumos/docs/+/master/developer_mode.md
+[CCD]: https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/cr50_stab/docs/case_closed_debugging.md
+[Servo V4]: https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/master/docs/servo_v4.md
+[have the prerequisites]: https://chromium.googlesource.com/chromiumos/docs/+/master/developer_guide.md#Prerequisites
+[get the source]: https://chromium.googlesource.com/chromiumos/docs/+/master/developer_guide.md#get-the-source
diff --git a/docs/sitemap.md b/docs/sitemap.md
index 12f2f14b04..7c9f73a5dd 100644
--- a/docs/sitemap.md
+++ b/docs/sitemap.md
@@ -25,6 +25,7 @@
 
 *   [Fingerprint MCU (FPMCU)](./fingerprint/fingerprint.md)
 *   [FPMCU Development for Partners](./fingerprint/fingerprint-dev-for-partners.md)
+*   [FPMCU Firmware Testing for Partners](./fingerprint/fingerprint-firmware-testing-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)