Memory Map

Memory Map #

An overview of the memory of the TKey. See Hardware for how to use the hardware functions.

Addressing #

31st bit                              0th bit
v                                     v
0000 0000 0000 0000 0000 0000 0000 0000
  • Bits [31 .. 30] (2 bits): Top level prefix (described below)
  • Bits [29 .. 24] (6 bits): Core select. There is space for 64 cores.
  • Bits [23 .. 0] (24 bits): Actual memory or in-core address.

Assigned Top Level Prefixes #

The first 2 bits in a 32-bit address.

nameprefixaddress length
ROM0b0030 bit address
RAM0b0130 bit address
reserved0b10
Hardware functions0b116 bits for core select, 24 bits rest

Address Prefixes #

The first 8 bits in a 32-bit address.

nameprefix
ROM0x00
RAM0x40
TRNG0xc0
TIMER0xc1
UDS0xc2
UART0xc3
TOUCH0xc4
FW_RAM0xd0
QEMU0xfe Not used in real hardware!
TK10xff

Hardware functions #

The hardware functions begins at 0xc000_0000 but please use the constants in tk1_mem.h in the tkey-libs repository if you can.

Note: The address in the table below is the word address. The data might be available only in the first bits or maybe the LSB of the word. Also note that some data is readable only by word, not byte addressing. Note the description.

In the following table r mean read, r/w means read and write access, i means invisible.

NameWord AddressFWApp*Description *
TK1_FW_RAM_BASE0xd0000000r/wiStart of firmware RAM (2 kiB).
TK1_MMIO_TRNG_STATUS0xc0000024rrIf bit 1 set TRNG_ENTROPY is ready to be read.
TK1_MMIO_TRNG_ENTROPY0xc0000080rrA word of entropy.
TK1_MMIO_TIMER_CTRL0xc1000020r/wr/wIf bit 0 in TK1_MMIO_TIMER_STATUS is 0, setting bit 0 starts the timer. If bit 0 in TK1_MMIO_TIMER_STATUS is 1, setting bit 1 stops the timer.
TK1_MMIO_TIMER_STATUS0xc1000024rrBit 0 is 1 when the timer is running.
TK1_MMIO_TIMER_PRESCALER0xc1000028r/wr/wPrescaler init value. Write blocked when running.
TK1_MMIO_TIMER_TIMER0xc100002cr/wr/wTimer init or current value while running. Write blocked when running.
TK1_MMIO_UDS_FIRST0xc2000040riFirst word of Unique Device Secret key. 8 words. Word access only. Note: Only readable once per power up.
TK1_MMIO_UDS_LAST0xc200005criLast word of the UDS. Note: Only readable once per power up.
TK1_MMIO_UART_BIT_RATE0xc3000040r/wr/wDefault 288 (62 500 bps). The bitrate is set by writing the divisor, calculated by: divisor = 18E6 / bps.
TK1_MMIO_UART_DATA_BITS0xc3000044r/wr/wDefault 8.
TK1_MMIO_UART_STOP_BITS0xc3000048r/wr/wDefault 1.
TK1_MMIO_UART_RX_STATUS0xc3000080rrNon-zero when there is data to read.
TK1_MMIO_UART_RX_DATA0xc3000084rrData to read. Only the LSB of the word contains data.
TK1_MMIO_UART_RX_BYTES0xc3000088rrNumber of unread bytes received from client.
TK1_MMIO_UART_TX_STATUS0xc3000100rrNon-zero when it’s OK to write data to send.
TK1_MMIO_UART_TX_DATA0xc3000104wwData to send. Only the LSB of the word will be sent.
TK1_MMIO_TOUCH_STATUS0xc4000024rrBit 0 is 1 when touched. After detecting a touch event (reading a 1), write anything here to acknowledge the event.
TK1_MMIO_QEMU_DEBUG0xfe001000wwDebug console (only in QEMU). Only the LSB of the word will be sent.
TK1_MMIO_TK1_NAME00xff000000rrTKey FPGA design name, first part, default “tk1”.
TK1_MMIO_TK1_NAME10xff000004rrTKey FPGA design name, second part, default “mkdf”.
TK1_MMIO_TK1_VERSION0xff000008rrVersion of FPGA design (See UDI for product version or serial)
TK1_MMIO_TK1_SWITCH_APP0xff000020r/wrWrite anything here to trigger the switch to application mode. Reading returns 0 in firmware mode, 0xffffffff in app mode.
TK1_MMIO_TK1_LED0xff000024r/wr/wControls the RGB color of the status indicator LED on TKey. Bit 0 is Blue, bit 1 is Green, and bit 2 is Red LED.
TK1_MMIO_TK1_GPIO0xff000028r/wr/wBits 0 and 1 contain the input level of GPIO 1 and 2. Bits 2 and 3 store the output level of GPIO 3 and 4.
TK1_MMIO_TK1_APP_ADDR0xff000030r/wrApp load address, stored by firmware so app can find itself in memory.
TK1_MMIO_TK1_APP_SIZE0xff000034r/wrApp size, stored by firmware so app can read its own size.
TK1_MMIO_TK1_BLAKE2S0xff000040r/wrFunction pointer to a BLAKE2S function in the firmware.
TK1_MMIO_TK1_CDI_FIRST0xff000080r/wrThe computed Compound Device Identifier (CDI). 8 words.
TK1_MMIO_TK1_CDI_LAST0xff00009cr/wrLast word of CDI.
TK1_MMIO_TK1_UDI_FIRST0xff0000c0riFirst word of Unique Device ID (UDI). 2 words. Set during provisioning.
TK1_MMIO_TK1_UDI_LAST0xff0000c4riLast word of UDI
TK1_MMIO_TK1_RAM_ADDR_RAND0xff000100wiSeed word for the RAM address randomization.
TK1_MMIO_TK1_RAM_DATA_RAND0xff000104wiSeed word for the RAM data randomization.
TK1_MMIO_TK1_CPU_MON_CTRL0xff000180wwBit 0 enables Security Monitor. Can’t be unset. Locks the area between the addresses set in TK1_CPU_MON_FIRST and TK1_CPU_MON_LAST.
TK1_MMIO_TK1_CPU_MON_FIRST0xff000184wwStart address (32-bit) of the RAM area monitored for execution attempts.
TK1_MMIO_TK1_CPU_MON_LAST0xff000188wwLast address (32-bit) of the RAM area monitored for execution attempts.