mirror of
https://github.com/tillitis/tillitis-key1.git
synced 2024-12-29 17:36:26 -05:00
187 lines
6.1 KiB
Markdown
187 lines
6.1 KiB
Markdown
# The TKey FPGA
|
|
|
|
## Introduction
|
|
The TKey application FPGA (application_fpga design) contain
|
|
the application platform CPU system onto which secure applications
|
|
are loaded, measured and executed. The platform is a compact
|
|
System on Chip (SoC) with the following cores.
|
|
|
|
|
|
|
|
The application FPGA is currently implemented using a Lattice
|
|
[iCE40 UltraPlus UP5K device](https://www.latticesemi.com/en/Products/FPGAandCPLD/iCE40UltraPlus).
|
|
Only open tools are used in the toolchain.
|
|
|
|
|
|
### Top level
|
|
|
|
The top level application_fpga design contain 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 exection mode. There are two
|
|
execution modes - firmware and application. Basically, in application mode
|
|
the access is more restrictive.
|
|
|
|
The API for all cores is described in the Memory mapped hardware
|
|
functions in the [System
|
|
Description](system_description.md#memory-mapped-hardware-functions).
|
|
|
|
|
|
### Cores
|
|
|
|
#### CPU
|
|
The CPU core is an instance of the [PicoRV32 core](https://github.com/YosysHQ/picorv32).
|
|
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.
|
|
|
|
|
|
#### Clock and 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 18 MHz.
|
|
|
|
The device also generates its own reset.
|
|
|
|
|
|
#### FW ROM
|
|
|
|
The ROM memory containing the firmware. After reset the CPU will
|
|
read from the ROM to load, measure and start applications.
|
|
|
|
The RAM memort is only accessible by the firmware.
|
|
|
|
|
|
#### FW RAM
|
|
|
|
A 512w32 small RAM only accessible by the firmware. The firmware
|
|
use the RAM during loading and measurement of the application.
|
|
|
|
|
|
#### UDS
|
|
|
|
Unique Device Secret memory.
|
|
|
|
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 FW mode. Reading from the UDS in APP mode
|
|
will return all zeros.
|
|
|
|
|
|
#### Application 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.
|
|
|
|
|
|
#### 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.
|
|
|
|
|
|
#### UART
|
|
|
|
A standard UART interface for receiving bytes from and send bytes
|
|
to the host via the interface MCU on the TKey.
|
|
|
|
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 timer is available to use by firmware and applications.
|
|
|
|
|
|
#### ROSC
|
|
|
|
The ROSC is a ring oscillator based internal entropy source, or
|
|
True Random Number Generator (TRNG). By default the TRNG use 32
|
|
free running digital oscillators. By default, the oscillators are
|
|
sampled after 4096 cycles. The states are XOR combined to create
|
|
a single bit. After another 4096 cycles a second bit is created,
|
|
and the two bits are XOR combined to a single entropy bit. The
|
|
entropy bit is added to a 32 bit entropy word.
|
|
|
|
After 32 bits has been collected, the data ready flag is set,
|
|
indicating that an entropy word is ready for consumption. Note
|
|
that entropy bit generation and collections is running continuously,
|
|
bits will be added, and the discarded after 32 more bits have
|
|
been added.
|
|
|
|
If a data word has been read from the TRNG, by default at least
|
|
32 bits will collected before new data will be available.
|
|
|
|
The ROSC TRNG is available to use by firmware and applications.
|
|
|
|
Note: The ROSC generates entropy with a fairly good quality.
|
|
However for security related use cases, for example keys, the ROSC
|
|
should not be used directly. Instead use it to create a seed
|
|
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, HKDF.
|
|
|
|
|
|
#### Touch sensor
|
|
|
|
The core provides a stable interface to the touch sensor on the
|
|
TKey device. Using the core, the firmware and applications can
|
|
get information about touch events and manage detection of
|
|
events.
|
|
|
|
It is recommended that SW start by acknowledge any stray events prior
|
|
to signal 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.
|
|
|
|
|
|
#### TKey
|
|
|
|
The TKey core contains several functions, and acts as
|
|
main HW interface between firmware and applications. The core
|
|
includes:
|
|
|
|
- Read access to the 64 bit FPGA design name, expressed as ASCII chars.
|
|
- Read access to the 32 bit FPGA design version, expressed as an integer
|
|
|
|
- Control and status access for the RGB LED on TKey board
|
|
- Setting bit 0 high turns on the Blue LED.
|
|
- Setting bit 1 high turns on the Green LED.
|
|
- Setting bit 2 high turns on the Red LED.
|
|
|
|
- Control and status access for the 4 GPIOs on the TKey board
|
|
- GPIO 1 and 2 are inputs and provide read access to the
|
|
current sampled value digital values on the pins.
|
|
|
|
- GPIO 3 and 4 are outputs. The digital value written to
|
|
the bits will be presented on the pins.
|
|
|
|
- Application read access to information about the loaded
|
|
application. The information is written by the firmware.
|
|
- Start address
|
|
- Size of address
|
|
|
|
- Application read access to the CDI generated and written
|
|
by the firmware when the application is loaded.
|
|
|
|
- Application-Firmware execution mode control. Can be read
|
|
by the application and written by firmware. When written
|
|
to by the firmware, the hardware will switch to application
|
|
mode and start executing the application.
|