| .. | ||
| core | ||
| data | ||
| fw | ||
| rtl | ||
| tb | ||
| tools | ||
| application_fpga.bin.sha256 | ||
| config.vlt | ||
| firmware.bin.sha512 | ||
| Makefile | ||
| README.md | ||
TKey hardware design
The application FPGA is implemented using a Lattice iCE40 UltraPlus UP5K device. Only open tools are used in the toolchain.
The design top level is in rtl/application_fpga.v. It contains
instances of all cores as well as the memory system.
The memory system allows the CPU to access cores in different ways given the current execution mode. There are two execution modes - firmware and application. Basically, in application mode the access is more restrictive.
The rest of the components are under cores. They typically have
their own README.md file documenting them and their API in detail.
Hardware functions with APIs, assets, and input/output are memory
mapped starting at base address 0xc000_0000. For specific offsets
and bitmasks, see the file fw/tk1_mem.h.
Rough memory map:
| name | prefix |
|---|---|
| ROM | 0x00 |
| RAM | 0x40 |
| TRNG | 0xc0 |
| Timer | 0xc1 |
| UDS | 0xc2 |
| UART | 0xc3 |
| Touch | 0xc4 |
| FW_RAM | 0xd0 |
| TK1 | 0xff |
clk_reset_gen
Generator for system clock and system reset.
The device does not rely on external clock or reset. Instead the internal HFOSC oscillator combined with an internal PLL is used to generate the main clock. Currently the clock frequency driving the SoC is 21 MHz.
The device also generates its own reset.
fw_ram
Special firmware-only RAM. Unreachable from app mode.
picorv32
A softcore 32 bit RISC-V CPU from upstreams PicoRV32.
Configuration of optional CPU features like ENABLE_FAST_MUL et
cetera are in rtl/application_fpga.v.
The instance enables the following features
- Compressed ISA (C extension)
- Fast multiplication. Two cycles for 32x32 multiplication
- Barrel shifter
No other modification to the core has been done. No interrupts are used.
ram
The 128 KByte main RAM. The RAM is only used by applications. The memory is cleared by firmware before an application is loaded.
The application RAM is available to use by firmware and applications.
The RAM core also implements (from the view of the CPU) transparent RAM address and data scrambling. This scrambling is applied to make it harder to extract application and application data from a memory dump directly from the memory cores.
rom
ROM for the firmware. The firmware.elf minus the ELF header is embedded here in the bitstream.
After reset the CPU will initialize the program counter to start of ROM.
timer
A general purpose 32 bit timer. The timer will count down from the initial value to one. In order to handle long time sequences (minutes, hours, days) there is also a 32 bit prescaler.
The timer is available to use by firmware and applications.
tk1
See tk1 README for details.
Contains:
- FPGA name and version.
- Execution mode control: firmware mode/application mode.
- RGB LED control.
- General purpose input/output (GPIO) pin control.
- Application introspection: start address and size of binary.
- BLAKE2s function access.
- Compound Device Identity (CDI).
- Unique Device Identity (UDI).
- RAM memory protection.
- Security monitor.
- SPI main.
- System reset.
Illegal instruction monitor
Execution of illegal instructions will cause the CPU to enter its trap state from which it can't exit. The hardware in the TKey will monitor the CPU state. If the CPU enters the trap state, the hardware will start flashing the RED led, signalling that the TKey is stuck in an error state.
RAM memory protection
The TKey hardware includes a simple form of RAM memory protection. The purpose of the RAM memory protection is to make it somewhat harder and more time consuming to extract application assets by dumping the RAM contents from a TKey device. The memory protection is not based on encryption and should not be confused with real encryption. The protection is randomised between power cycles. The randomisation should make it infeasible to improve asset extraction by observing multiple memory dumps from the same TKey device. The attack should also not directly scale to multiple TKey devices.
The RAM address and data scrambling is done in de RAM core.
The memory protection is setup by the firmware. Access to the memory protection controls is disabled for applications. Before the memory protecetion is enabled, the RAM is filled with randomised data using Xorwow. So during boot the firmware perform the following steps to setup the memory protection:
- Get a random 32-bit value from the TRNG to use as data state for Xorwow.
- Get a random 32-bit value from the TRNG to use as accumulator for Xorwow.
- Fill RAM with a random sequence of values by writing to all RAM addresses. For each address use Xorwow to generate a new state, using the accumulator.
- Write a random 32-bit value from the TRNG into the ADDR_RAM_ADDR_RAND register.
- Write a random 32-bit value from the TRNG into the ADDR_RAM_DATA_RAND register.
- Receive the application sent from the client and write it in sequence into RAM.
touch_sense
Provide touch sensor events to software.
It is recommended that software start by acknowledge any stray events prior to signalling to the user that a touch event is expected and then start waiting for an event.
The touch sensor is available to use by firmware and applications.
trng
Provide a True Random Number Generator to software.
The TRNG generates entropy with a fairly good quality. However for security related use cases, for example key generation, the TRNG should not be used directly. Instead use it to create a seed, and reseed as necessary, for a Digital Random Bit Generator (DRBG), also known as a Cryptographically Safe Pseudo Random Number Generator (CSPRNG). Examples of such generators are Hash_DRGG, CTR_DRBG, and HKDF.
uart
A simple universal asynchronous receiver/transmitter (UART) used for communication with the client through the USB controller.
The UART default speed is 62500 bps, but can be adjusted by the application. (Note that the host must set the same bitrate too.)
The UART contain a 512 but Rx-FIFO with status (data available).
The UART is available to use by firmware and applications.
uds
The Unique Device Secret. During build initial value is taken from
data/uds.hex.
However, with the finished bitstream you can patch in another UDS and
UDI by using tools/patch_uds_udi.py with nextpnr.
It's a 256 bit memory implemented using eight 32-bit registers. The registers can only be accessed once between power cycling. This means that the UDS must be read as u32. If read as u8, only the first byte from a given address will be correct, subsequent bytes will be zero.
The UDS can only be read in firmware mode. Reading from the UDS in application mode will return all zeros.
References
More detailed information about the firmware running on the device can be found in the hw/application_fpga/fw/README.md.