1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
|
# Fingerprint Firmware (FPMCU)
[TOC]
*** note
NOTE: The build commands assume you are in the `~/trunk/src/platform/ec`
directory inside the chroot.
***
*** note
WARNING: When switching branches in the EC codebase, you probably want to nuke
the `build` directory or at least the board you're working on: `rm -rf
build/<board>` or `make clobber` to prevent compilation errors.
***
## Software
The main source code for fingerprint sensor functionality lives in the
[`common/fpsensor`] directory.
## Hardware
The following "boards" (specified by the `BOARD` environment variable when
building the EC code) are for fingerprint:
* [`nocturne_fp`] aka [`nami_fp`] aka [`dartmonkey`]
* Based on [STM32H743] (Cortex-M7).
* [`hatch_fp`] aka [`bloonchipper`]
* Based on [STM32F412] (Cortex-M4).
* Support for the STM32F412 for the FPMCU is not yet fully complete,
but it is functional enough for testing.
## Building FPMCU Firmware Locally
### See `Makefile` target options
```bash
(chroot) ~/trunk/src/platform/ec $ make help
```
### Build
Replace `<BOARD_NAME>` in the command below with the fingerprint MCU that you
are targeting (e.g., `nocturne_fp`, `dartmonkey`, `bloonchipper`).
```bash
(chroot) ~/trunk/src/platform/ec $ make BOARD=<BOARD_NAME> -j
```
### Verbose Build output
Use `V=1` to see the complete compiler output (all flags).
```bash
(chroot) ~/trunk/src/platform/ec $ make V=1 BOARD=nocturne_fp -j
```
## Building all EC firmware (before "repo upload")
Before uploading a change to Gerrit via `repo upload`, you'll need to build
*all* the boards in the EC codebase to make sure your changes do not break any
others.
*** note
NOTE: If you forget to do this, do not worry. `repo upload` will warn you and
prevent you from uploading.
***
```bash
(chroot) ~/trunk/src/platform/ec $ make buildall -j
```
## Build tests
```bash
(chroot) ~/trunk/src/platform/ec $ make BOARD=nocturne_fp tests-nocturne_fp -j
```
## Build ectool
```bash
(chroot) ~/trunk/src/platform/ec $ make BOARD=nocturne_fp utils-host -j
```
## Build and run the `host_command` fuzz test
```bash
(chroot) ~/trunk/src/platform/ec $ make BOARD=nocturne_fp run-host_command_fuzz
```
## Production Updates
### `fp_updater.sh` and `bio_fw_updater`
[`fp_updater.sh`] and [`bio_fw_updater`] are wrappers around [`flashrom`] and
require already-functioning RO firmware running on the FPMCU. It’s meant to be
used in production to update the RW firmware. `fp_updater.sh` was used prior to
M77; `bio_fw_updater` replaces it.
It's also possible to use the updater to update the RO firmware if you disable
*both* HW and SW write protect, which we use for updating development devices
that do not have write protect enabled (dogfood devices, EVT, etc.)
In production, only the RW portion of the firmware can be updated (unless the
user disables [hardware write protection]).
## Factory / RMA / Development Updates
### `flash_fp_mcu`
*** note
NOTE: This tool is really just for us to use during development or during the
RMA flow (must go through finalization again in that case). We never update RO
in the field (can’t by design).
***
[`flash_fp_mcu`] enables spidev and toggles some GPIOs to put the FPMCU (STM32)
into bootloader mode. At that point it uses `stm32mon` to rewrite the entire
flash (both RO and RW). This will only work if [hardware write protection] is
disabled.
### `stm32mon`
[`stm32mon`] is a tool used to send commands to the STM32 bootloader. We use it
for development (through `flash_fp_mcu`) to erase and flash the entire chip.
## Keys
The `RO` section of the fingerprint firmware contains the public portion of the
key used to sign the RW firmware. It uses the public key to validate the
signature of the RW firmware before jumping to it. It is not possible to
update the public key stored in the RO firmware once a device has been shipped
(i.e., once the hardware write protect is enabled).
*** promo
TODO(tomhughes): Add details about different types of keys (`dev`, `premp`,
`mp`, etc).
***
### Resources
* https://sites.google.com/a/google.com/chromeos/resources/engineering/releng/signer-documentation
* https://sites.google.com/a/google.com/chromeos/paygen---payload
* https://b.corp.google.com/issues/77882970
## Signing
[`futility`] is used to sign EC firmware. There’s a wrapper script around it
for signing called [`sign_official_build.sh`].
### Key ID
The output of `futility show` will show a `Public Key File` and `Signature`
section, each of which have an `ID` field. This ID lets you match the key to the
signature in case there is more than one.
[It’s just a sha1sum of the public key,][vboot_key_id] so it lets you
[uniquely identify the key being used][vb2_public_key].
If you have the key (e.g., in PEM format), you can compute the `ID` with the
`futility show` command:
```bash
(chroot) $ futility show ./path/to/key.pem
```
#### Example
If you are building the `hatch_fp` "board" on your local machine (which signs
the resulting `ec.bin` with the `dev` key, you can check the `ID` with:
```bash
(chroot)$ futility show board/hatch_fp/dev_key.pem
```
```
Private Key file: board/hatch_fp/dev_key.pem
Key length: 3072
Key sha1sum: 61382804da86b4156d666cc9a976088f8b647d44
```
```bash
(chroot)$ futility show build/hatch_fp/ec.bin
```
```
Public Key file: build/hatch_fp/ec.bin
Vboot API: 2.1
Desc: ""
Signature Algorithm: 7 RSA3072EXP3
Hash Algorithm: 2 SHA256
Version: 0x00000001
ID: 61382804da86b4156d666cc9a976088f8b647d44
Signature: build/hatch_fp/ec.bin
Vboot API: 2.1
Desc: ""
Signature Algorithm: 7 RSA3072EXP3
Hash Algorithm: 2 SHA256
Total size: 0x1b8 (440)
ID: 61382804da86b4156d666cc9a976088f8b647d44
Data size: 0x2864c (165452)
Signature verification succeeded.
```
### Showing Key ID (fingerprint) for running FW
[Asked on chromeos-chatty-firmware][chatty-firmware-q]
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.
[`common/fpsensor`]: https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/master/common/fpsensor/
[`nocturne_fp`]: https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/master/board/nocturne_fp/
[`nami_fp`]: https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/master/board/nami_fp/
[`hatch_fp`]: https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/master/board/hatch_fp/
[`bloonchipper`]: https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/master/board/bloonchipper/
[`dartmonkey`]: https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/master/board/dartmonkey/
[hardware write protection]: ../write_protection.md
[`flash_fp_mcu`]: https://chromium.googlesource.com/chromiumos/platform/ec/+/master/board/nocturne_fp/flash_fp_mcu
[`stm32mon`]: https://chromium.googlesource.com/chromiumos/platform/ec/+/e1f3f89e7ea7945adddd0c2e6838f5e59856cff2/util/stm32mon.c#14
[`futility`]: https://chromium.googlesource.com/chromiumos/platform/vboot_reference/+/master/futility/
[`sign_official_build.sh`]: https://chromium.googlesource.com/chromiumos/platform/vboot_reference/+/master/scripts/image_signing/sign_official_build.sh
[vboot_key_id]: https://chromium.googlesource.com/chromiumos/platform/vboot_reference/+/e7db36856ce418552637d1981c173d22dfe5bf39/firmware/2lib/include/2id.h#5
[vb2_public_key]: https://chromium.googlesource.com/chromiumos/platform/vboot_reference/+/e7db36856ce418552637d1981c173d22dfe5bf39/firmware/2lib/include/2rsa.h#14
[chatty-firmware-q]: https://groups.google.com/a/google.com/d/msg/chromeos-chatty-firmware/ZSg423wsFPg/26UbdGwjFQAJ
[`fp_updater.sh`]: http://go/cros-fp-updater-nocturne-source
[`bio_fw_updater`]: https://chromium.googlesource.com/chromiumos/platform2/+/refs/heads/master/biod/tools
[`flashrom`]: https://chromium.googlesource.com/chromiumos/third_party/flashrom/
[STM32F412]: https://www.st.com/resource/en/reference_manual/dm00180369.pdf
[STM32H743]: https://www.st.com/resource/en/reference_manual/dm00314099.pdf
|
