Git-Mirrors/tillitis-key
1
0
Fork 0
mirror of https://github.com/tillitis/tillitis-key1.git synced 2025-03-12 10:06:47 -04:00
Code Issues Packages Projects Releases Wiki Activity

doc: Update firmware README to include USB Mode Protocol

Browse Source 
+ minor link and typo fixes.
This commit is contained in:
Michael Cardell Widerkrantz 2025-02-11 15:05:38 +01:00
parent 179c13e9bf
commit d2c7fb0ba9
No known key found for this signature in database
GPG Key ID: D3DB3DDF57E704E5
1 changed files with 33 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
hw/application_fpga/fw/README.md
View File

@ -37,15 +37,38 @@ memory access control.
## Communication ## Communication
The firmware communicates to the host via the The firmware communicates with the client using the
`UART_{RX,TX}_{STATUS,DATA}` registers, using the framing protocol `UART_{RX,TX}_{STATUS,DATA}` registers. On top of that is uses three
described in the [Framing protocols: The USB Mode protocol, the TKey framing protocol, and the
Protocol](https://dev.tillitis.se/protocol/). firmware's own protocol.
To communicate between the CPU and the CH552 USB controller it uses an
internal protocol, used only within the TKey, which we call the USB
Mode Protocol. It is used in both directions.
| *Name* | *Size* | *Comment* |
|----------|-----------|------------------------------------|
| Endpoint | 1B | Origin or destination USB endpoint |
| Length | 1B | Number of bytes following |
| Payload | See above | Actual data from or to firmware |
The different endpoints:
| *Name* | *Value* | *Comment* |
|--------|---------|---------------------------------------------------------------------|
| CTRL | 0x20 | A USB HID special debug pipe. Useful for debug prints. |
| CDC | 0x40 | USB CDC-ACM, a serial port on the client. |
| HID | 0x80 | A USB HID security token device, useful for FIDO-type applications. |
On top of the USB Mode Protocol is [the TKey Framing
Protocol](https://dev.tillitis.se/protocol/) which is described in the
Developer Handbook.
The firmware uses a protocol on top of this framing layer which is The firmware uses a protocol on top of this framing layer which is
used to bootstrap the application. All commands are initiated by the used to bootstrap an application. All commands are initiated by the
client. All commands receive a reply. See [Firmware client. All commands receive a reply. See [Firmware
protocol](#firmware-protocol) for specific details. protocol](http://dev.tillitis.se/protocol/#firmware-protocol) in the
Dev Handbook for specific details.
## Memory constraints ## Memory constraints
@ -137,12 +160,9 @@ application mode, but with no privileged access.
Firmware loads the application at the start of RAM (`0x4000_0000`). It Firmware loads the application at the start of RAM (`0x4000_0000`). It
uses the special FW\_RAM for its own stack. uses the special FW\_RAM for its own stack.
When the firmware starts it clears all FW\_RAM, then sets up a stack
there before jumping to `main()`.
When reset is released, the CPU starts executing the firmware. It When reset is released, the CPU starts executing the firmware. It
begins by clearing all CPU registers, and then sets up a stack for begins by clearing all CPU registers, clears all FW\_RAM, sets up a
itself and then jumps to main(). stack for itself there, and then jumps to `main()`.
Beginning at `main()` it sets up the "system calls", then fills the Beginning at `main()` it sets up the "system calls", then fills the
entire RAM with pseudo random data and setting up the RAM address and entire RAM with pseudo random data and setting up the RAM address and
@ -187,8 +207,8 @@ Typical expected use scenario:
stack. After this it performs no more function calls and uses no stack. After this it performs no more function calls and uses no
more automatic variables. more automatic variables.
8. Firmware starts the application by first switching to from 8. Firmware starts the application by first switching from firmware
firmware mode to application mode by writing to the `SYSTEM_MODE_CTRL` mode to application mode by writing to the `SYSTEM_MODE_CTRL`
register. In this mode the MMIO region is restricted, e.g. some register. In this mode the MMIO region is restricted, e.g. some
registers are removed (`UDS`), and some are switched from registers are removed (`UDS`), and some are switched from
read/write to read-only (see [the memory read/write to read-only (see [the memory