Git-Mirrors/tillitis-key
1
0
Fork 0
mirror of https://github.com/tillitis/tillitis-key1.git synced 2025-12-15 08:38:53 -05:00
Code Issues Projects Releases Packages Wiki Activity

Clarify golden path

Browse source 
- Clarify what the default behaviour is.
- Clarify when we should halt CPU.
- Move common things when booting from flash and UART to its own
  section.
This commit is contained in:
Michael Cardell Widerkrantz 2025-03-06 16:30:37 +01:00 • committed by Mikael Ågren
parent aa9335691f
commit 3ef1dade37
No known key found for this signature in database
GPG key ID: E02DA3D397792C46
1 changed files with 63 additions and 65 deletions
Download patch file Download diff file Expand all files Collapse all files

58
hw/application_fpga/fw/README.md
View file

@ -192,8 +192,9 @@ from execution, except through the system call mechanism.
### Golden path ### Golden path
Firmware loads the application at the start of RAM (`0x4000_0000`). It Firmware loads the application at the start of RAM (`0x4000_0000`)
use a part of the special FW\_RAM for its own stack. from either flash or the UART. It use a part of the special FW\_RAM
for its own stack.
When reset is released, the CPU starts executing the firmware. It When reset is released, the CPU starts executing the firmware. It
begins in `start.S` by clearing all CPU registers, clears all FW\_RAM, begins in `start.S` by clearing all CPU registers, clears all FW\_RAM,
@ -206,27 +207,23 @@ and setting up the RAM address and data hardware scrambling with
values from the True Random Number Generator (TRNG). values from the True Random Number Generator (TRNG).
1. Check the special resetinfo area in FW\_RAM to see if there is any 1. Check the special resetinfo area in FW\_RAM to see if there is any
data about why a reset has been made. Or all zeroes(?) meaning a power data about why a reset has been made. All zeroes(?) meaning default
loss. behaviour.
2. If it was reset intentende to start a device app from client, see 2. If it was reset with intention to start a device app from client,
App loaded from client below. see App loaded from client below.
3. If it was reset to start a device app from the flash it first 3. Default is to start the first device app from flash. If resetinfo
checks which app it should start from the resetinfo (out of two says otherwise it starts the other one.
available). If no data is available, start with the first.
4. Load flash app into RAM without USS. 4. Load flash app into RAM without USS.
5. Compute digest of loaded app. 5. Compute digest of loaded app.
6. Compare against stored app digest in partition table to note if app 6. Compare against stored app digest in partition table to note if app
has been corrupted on flash. has been corrupted on flash. If corrupted, halt CPU.
7. If there is an app digest in the resetinfo left from previous app, 7. Proceed to [Start the device app](#start-the-device-app) below.
compare the digests. Halt CPU if differences.
8. Start the app. See details in description below.
If the app is the first set in a chain, it's the job of the app itself If the app is the first set in a chain, it's the job of the app itself
to reset the TKey when it has done its job. For instance, a verified to reset the TKey when it has done its job. For instance, a verified
@ -275,31 +272,32 @@ Firmware waits for data coming in through the UART.
firmware send back the `FW_RSP_LOAD_APP_DATA_READY` response firmware send back the `FW_RSP_LOAD_APP_DATA_READY` response
containing the digest. containing the digest.
5. If there was a digest left in resetinfo from earlier app in the #### Start the device app
chain, compare the computed digest with the left digest. If it's
not the same, halt CPU.
6. The Compound Device Identifier 1. If there is an app digest in the resetinfo left from previous app,
([CDI]((#compound-device-identifier-computation))) is then compare the digests. Halt CPU if differences.
computed by doing a new BLAKE2s using the Unique Device Secret
(UDS), the application digest, and any User Supplied Secret
(USS) digest already received.
7. The start address of the device app, currently `0x4000_0000`, is 2. The Compound Device Identifier
([CDI]((#compound-device-identifier-computation))) is then computed
by doing a new BLAKE2s using the Unique Device Secret (UDS), the
application digest, and any User Supplied Secret (USS) digest
already received.
3. The start address of the device app, currently `0x4000_0000`, is
written to `APP_ADDR` and the size of the binary to `APP_SIZE` to written to `APP_ADDR` and the size of the binary to `APP_SIZE` to
let the device application know where it is loaded and how large let the device application know where it is loaded and how large it
it is, if it wants to relocate in RAM. is, if it wants to relocate in RAM.
8. The firmware now clears the part of the special `FW_RAM` where it 4. The firmware now clears the part of the special `FW_RAM` where it
keeps it stack. keeps it stack.
9. The interrupt handler for system calls is enabled. 5. The interrupt handler for system calls is enabled.
10. Firmware starts the application by jumping to the contents of 6. Firmware starts the application by jumping to the contents of
`APP_ADDR`. Hardware automatically switches from firmware mode to `APP_ADDR`. Hardware automatically switches from firmware mode to
application mode. In this mode some memory access is restricted, application mode. In this mode some memory access is restricted,
e.g. some addresses are inaccessible (`UDS`), and some are e.g. some addresses are inaccessible (`UDS`), and some are switched
switched from read/write to read-only (see [the memory from read/write to read-only (see [the memory
map](https://dev.tillitis.se/memory/)). map](https://dev.tillitis.se/memory/)).
If during this whole time any commands are received which are not If during this whole time any commands are received which are not