tillitis-key/hw/application_fpga
Daniel Jobson 66888a3756
tb: Make uart selftesting
- Exit with the right exit code
2024-12-09 13:55:43 +01:00
..
core tb: Make uart selftesting 2024-12-09 13:55:43 +01:00
data A construction of a minimal SPI master. 2024-06-11 15:28:29 +02:00
fw Add needed changes to firmware for simulation. 2024-11-28 16:10:00 +01:00
rtl Change "rosc" references to "trng" 2024-11-14 16:35:51 +01:00
tb Updated application_fpga_verilator.cc to match module application_fpga_sim. 2024-11-28 16:10:01 +01:00
tools Add script to split app into simulation ram 2024-11-28 16:10:00 +01:00
application_fpga.bin.sha256 Add APP_SIZE parameter to tk1 block to set size of application when simulating. 2024-11-28 16:09:59 +01:00
config.vlt Config verilator lint to ignore known 3rd-party warnings; let warnings be fatal 2023-03-01 13:37:31 +01:00
firmware.bin.sha512 FPGA: Move RAM address and data scrambling into the RAM module. 2024-08-30 10:53:13 +02:00
Makefile Add make target for testbench simulation and simulation firmware. 2024-11-28 16:10:01 +01:00
README.md fpga: remove the API for configuring the UART core 2024-11-26 15:24:12 +01:00

TKey hardware design

The Application FPGA block diagram

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:

  1. Get a random 32-bit value from the TRNG to use as data state for Xorwow.
  2. Get a random 32-bit value from the TRNG to use as accumulator for Xorwow.
  3. 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.
  4. Write a random 32-bit value from the TRNG into the ADDR_RAM_ADDR_RAND register.
  5. Write a random 32-bit value from the TRNG into the ADDR_RAM_DATA_RAND register.
  6. 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 contain a 512-byte 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.