docs/fingerprint: Add details on using fingerprint with Chrome OS build

BRANCH=none
BUG=none
TEST=view in gitiles

Change-Id: Icedacbe7897d8aaf441e7d76be50e440f46c5a54
Signed-off-by: Tom Hughes <tomhughes@chromium.org>
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/2017576
Commit-Queue: Craig Hesling <hesling@chromium.org>
Reviewed-by: Craig Hesling <hesling@chromium.org>

2 files changed, 97 insertions, 1 deletions

diff --git a/docs/fingerprint/fingerprint-factory-requirements.md b/docs/fingerprint/fingerprint-factory-requirements.md
index 9849cdd393..4aaf564570 100644
--- a/docs/fingerprint/fingerprint-factory-requirements.md
+++ b/docs/fingerprint/fingerprint-factory-requirements.md
@@ -61,6 +61,12 @@ dartmonkey
 The corresponding firmware for the above command would be
 `/opt/google/biod/fw/dartmonkey_*.bin`.
 
+*** note
+**NOTE**: If you get an empty response when running the above commands, the
+Chrome OS Config settings may not have been updated for the Chrome OS board.
+See the instructions on [updating Chrome OS Config] for fingerprint.
+***
+
 Note that the fingerprint team continuously releases updates to the firmware, so
 SIEs should watch for version changes in ToT if they are maintaining a separate
 factory branch.
@@ -82,6 +88,13 @@ the rootfs. Note that this update process can take around 30 seconds; if that
 length of time is an issue then the factory or module house should pre-flash the
 latest firmware beforehand.
 
+*** note
+**NOTE**: If the FPMCU is not flashed in the factory as part of development
+builds (EVT, etc.), it's possible for developers (or Chromestop) to manually
+run [`flash_fp_mcu`], as long as they can disable [hardware write protect].
+Obviously this only applies during development, not mass production.
+***
+
 ## biod and timberslide
 
 Since `biod` communicates with the FPMCU, it’s best to disable it when running
@@ -463,6 +476,7 @@ Wrote /tmp/fp.1.png (14025 bytes)
 ```
 
 [Software Write Protect]: https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/master/docs/write_protection.md#Software-Write-Protect
+[hardware write protect]: https://chromium.googlesource.com/chromiumos/platform/ec/+/master/docs/write_protection.md#hw_wp
 [FPC1025: Module Test Specification]: http://go/cros-fingerprint-fpc1025-module-test-spec
 [FPC1145: Module Test Specification]: http://go/cros-fingerprint-fpc1145-module-test-spec
 [FPC In-Device Test Specification]: http://go/cros-fingerprint-fpc-indevice-test-spec
@@ -477,3 +491,4 @@ Wrote /tmp/fp.1.png (14025 bytes)
 [`flash_fp_mcu`]: https://chromium.googlesource.com/chromiumos/platform/ec/+/master/util/flash_fp_mcu
 [Fingerprint flashing documentation]: ./fingerprint.md#factory-rma-dev-updates
 [Chrome OS Config]: https://chromium.googlesource.com/chromiumos/platform2/+/master/chromeos-config/README.md
+[updating Chrome OS Config]: ./fingerprint.md#update-chromeos-config
diff --git a/docs/fingerprint/fingerprint.md b/docs/fingerprint/fingerprint.md
index 2c11992a7a..7264a70b6f 100644
--- a/docs/fingerprint/fingerprint.md
+++ b/docs/fingerprint/fingerprint.md
@@ -19,7 +19,7 @@ The main source code for fingerprint sensor functionality lives in the
 [`common/fpsensor`] directory. The driver code for specific sensors lives in the
 [`driver/fingerprint`] directory.
 
-## Hardware
+## Hardware {#hardware}
 
 The following "boards" (specified by the `BOARD` environment variable when
 building the EC code) are for fingerprint:
@@ -31,6 +31,8 @@ building the EC code) are for fingerprint:
     *   Support for the STM32F412 for the FPMCU is not yet fully complete,
         but it is functional enough for testing.
 
+### Determining Hardware {#chromeos-config-fingerprint}
+
 If you have access to a shell on your Chromebook, you can use [Chrome OS Config]
 to determine the FPMCU that it contains:
 
@@ -45,6 +47,12 @@ in the chroot to determine the FPMCU:
 (chroot) $  cros_config_host -c /build/<BOARD>/usr/share/chromeos-config/yaml/config.yaml -m <MODEL> get /fingerprint board
 ```
 
+*** note
+**NOTE**: If you get an empty response when running these commands, the
+[Chrome OS Config] properties for fingerprint may not have been set up yet. See
+the [section on updating Chrome OS Config](#update-chromeos-config).
+***
+
 ## Building FPMCU Firmware Locally
 
 ### See `Makefile` target options
@@ -303,6 +311,65 @@ Signature verification succeeded.
 about adding an EC command to show the Key ID (fingerprint) from the RO version.
 This would make it a lot easier during both development and testing.
 
+## Chrome OS Build (portage / ebuild)
+
+In order to use the fingerprint sensor with a given [Chrome OS board], a few
+things need to be configured for the [Chrome OS board].
+
+### Enable biod USE flag
+
+The biod [`USE` flag] needs to be enabled for the [Chrome OS board]. This `USE`
+flag
+[determines whether the `biod` daemon is built and installed][biod chromium-os].
+
+To enable the `USE` flag, update the `make.defaults` for the [Chrome OS board].
+See the [`make.defaults` for the Hatch board][hatch make.defaults] as an
+example.
+
+### Update FPMCU_FIRMWARE
+
+`FPMCU_FIRMWARE` should be set to the set of fingerprint firmware that should be
+built and installed for the [Chrome OS board].
+
+`FPMCU_FIRMWARE` is a [`USE_EXPAND` variable][`USE` flag],
+[defined in the base `make.defaults`][FPMCU_FIRMWARE make.defaults].
+
+The `biod` ebuild uses the resulting [`USE` flags] to
+[determine which FPMCU release firmware to build][biod release firmware] and the
+`chromeos-firmware-fpmcu` ebuild uses the resulting [`USE` flags] to
+[determine which firmware to install][firmware ebuild] to the rootfs in
+`/opt/google/biod/fw`.
+
+Possible values for `FPMCU_FIRMWARE` can be found by looking at the
+`FIRMWARE_EC_BOARD` values in the [`chromeos-fpmcu-release*` ebuilds], which
+correspond to the [FPMCU hardware](#hardware).
+
+See the [Hatch baseboard `make.defaults`] for an example.
+
+### Update Chrome OS Config {#update-chromeos-config}
+
+With "unibuild", the same OS image (build) for a given [Chrome OS board] is used
+across multiple devices. Often there will be some devices that have a
+fingerprint sensor, some that do not, and even different sensors for the same
+board.
+
+Determining what fingerprint hardware is on a given [Chrome OS board] is thus
+done at runtime, using [Chrome OS Config].
+
+The `fingerprint` config needs to be in the `model.yaml` for the given
+[Chrome OS board]. The [Chrome OS Config fingerprint] section describes the
+attributes for the `fingerprint` config in more detail.
+
+The [`ec_extras` attribute] needs to be set to the list of fingerprint firmware
+that should be built as part of the build.
+
+See the [`model.yaml` for the Hatch board][hatch model.yaml] as an example.
+
+You can test your changes by
+[running `cros_config`](#chromeos-config-fingerprint). The Chrome OS Config
+documentation has a [section on testing properties] that describes this in more
+detail.
+
 [`common/fpsensor`]: https://chromium.googlesource.com/chromiumos/platform/ec/+/master/common/fpsensor/
 [`driver/fingerprint`]: https://chromium.googlesource.com/chromiumos/platform/ec/+/master/driver/fingerprint
 [`nocturne_fp`]: https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/master/board/nocturne_fp/
@@ -329,3 +396,17 @@ This would make it a lot easier during both development and testing.
 [Fingerprint Factory Requirements]: ./fingerprint-factory-requirements.md
 [Chromium OS test image]: https://chromium.googlesource.com/chromiumos/platform/factory/+/master/README.md#building-test-image
 [Chrome OS Config]: https://chromium.googlesource.com/chromiumos/platform2/+/master/chromeos-config/README.md
+[Chrome OS Config fingerprint]: https://chromium.googlesource.com/chromiumos/platform2/+/refs/heads/master/chromeos-config/README.md#fingerprint
+[section on testing properties]: https://chromium.googlesource.com/chromiumos/platform2/+/refs/heads/master/chromeos-config/README.md#adding-and-testing-new-properties
+[Chrome OS board]: https://chromium.googlesource.com/chromiumos/docs/+/master/developer_guide.md#Select-a-board
+[biod chromium-os]: https://chromium.googlesource.com/chromiumos/overlays/chromiumos-overlay/+/4ea72b588af3394cb9fd1c330dcf726472183dfd/virtual/target-chromium-os/target-chromium-os-1.ebuild#154
+[hatch make.defaults]: https://chromium.googlesource.com/chromiumos/overlays/board-overlays/+/2f075f0e7ce09d3eb460f3c529da463a6201276c/overlay-hatch/profiles/base/make.defaults#22
+[Hatch baseboard `make.defaults`]: https://chrome-internal.googlesource.com/chromeos/overlays/baseboard-hatch-private/+/refs/heads/master/profiles/base/make.defaults#17
+[hatch model.yaml]: https://chrome-internal.googlesource.com/chromeos/overlays/overlay-hatch-private/+/master/chromeos-base/chromeos-config-bsp-hatch-private/files/model.yaml
+[`ec_extras` attribute]: https://chromium.googlesource.com/chromiumos/platform2/+/refs/heads/master/chromeos-config/README.md#build_targets
+[FPMCU_FIRMWARE make.defaults]: https://chromium.googlesource.com/chromiumos/overlays/chromiumos-overlay/+/4ea72b588af3394cb9fd1c330dcf726472183dfd/profiles/base/make.defaults#157
+[`USE` flag]: https://devmanual.gentoo.org/general-concepts/use-flags/index.html
+[`USE` flags]: https://devmanual.gentoo.org/general-concepts/use-flags/index.html
+[biod release firmware]: https://chromium.googlesource.com/chromiumos/overlays/chromiumos-overlay/+/4ea72b588af3394cb9fd1c330dcf726472183dfd/chromeos-base/biod/biod-9999.ebuild#49
+[firmware ebuild]: https://chrome-internal.googlesource.com/chromeos/overlays/chromeos-overlay/+/refs/heads/master/chromeos-base/chromeos-firmware-fpmcu/chromeos-firmware-fpmcu-9999.ebuild#40
+[`chromeos-fpmcu-release*` ebuilds]: https://chromium.googlesource.com/chromiumos/overlays/chromiumos-overlay/+/master/sys-firmware