Git-Mirrors/tillitis-key
1
0
Fork 0
mirror of https://github.com/tillitis/tillitis-key1.git synced 2025-12-15 00:28:50 -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
Firmware loads the application at the start of RAM (`0x4000_0000`). It
use a part of the special FW\_RAM for its own stack.
Firmware loads the application at the start of RAM (`0x4000_0000`)
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
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).
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
loss.
data about why a reset has been made. All zeroes(?) meaning default
behaviour.
2. If it was reset intentende to start a device app from client, see
App loaded from client below.
2. If it was reset with intention to start a device app from client,
see App loaded from client below.
3. If it was reset to start a device app from the flash it first
checks which app it should start from the resetinfo (out of two
available). If no data is available, start with the first.
3. Default is to start the first device app from flash. If resetinfo
says otherwise it starts the other one.
4. Load flash app into RAM without USS.
5. Compute digest of loaded 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,
compare the digests. Halt CPU if differences.
8. Start the app. See details in description below.
7. Proceed to [Start the device app](#start-the-device-app) below.
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
@ -275,31 +272,32 @@ Firmware waits for data coming in through the UART.
firmware send back the `FW_RSP_LOAD_APP_DATA_READY` response
containing the digest.
5. If there was a digest left in resetinfo from earlier app in the
chain, compare the computed digest with the left digest. If it's
not the same, halt CPU.
#### Start the device app
6. 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.
1. If there is an app digest in the resetinfo left from previous app,
compare the digests. Halt CPU if differences.
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
let the device application know where it is loaded and how large
it is, if it wants to relocate in RAM.
let the device application know where it is loaded and how large it
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.
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
application mode. In this mode some memory access is restricted,
e.g. some addresses are inaccessible (`UDS`), and some are
switched from read/write to read-only (see [the memory
e.g. some addresses are inaccessible (`UDS`), and some are switched
from read/write to read-only (see [the memory
map](https://dev.tillitis.se/memory/)).
If during this whole time any commands are received which are not