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
SYSCALL0xe1
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 AddressFWSyscallAppDescription
TK1_FW_RAM_BASE0xd0000000r/wr/wiStart of firmware RAM (4 kiB).
TK1_MMIO_TRNG_STATUS0xc0000024rrrIf bit 1 set TRNG_ENTROPY is ready to be read.
TK1_MMIO_TRNG_ENTROPY0xc0000080rrrA word of entropy.
TK1_MMIO_TIMER_CTRL0xc1000020r/wr/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_STATUS0xc1000024rrrBit 0 is 1 when the timer is running.
TK1_MMIO_TIMER_PRESCALER0xc1000028r/wr/wr/wPrescaler init value. Write blocked when running.
TK1_MMIO_TIMER_TIMER0xc100002cr/wr/wr/wTimer init or current value while running. Write blocked when running.
TK1_MMIO_UDS_FIRST0xc2000040riiFirst word of Unique Device Secret key. 8 words. Word access only. Note: Only readable once per power up.
TK1_MMIO_UDS_LAST0xc200005criiLast word of the UDS. Note: Only readable once per power up.
TK1_MMIO_UART_RX_STATUS0xc3000080rrrNon-zero when there is data to read.
TK1_MMIO_UART_RX_DATA0xc3000084rrrData to read. Only the LSB of the word contains data.
TK1_MMIO_UART_RX_BYTES0xc3000088rrrNumber of unread bytes received from client.
TK1_MMIO_UART_TX_STATUS0xc3000100rrrNon-zero when it’s OK to write data to send.
TK1_MMIO_UART_TX_DATA0xc3000104wwwData to send. Only the LSB of the word will be sent.
TK1_MMIO_TOUCH_STATUS0xc4000024rrrBit 0 is 1 when touched. After detecting a touch event (reading a 1), write anything here to acknowledge the event.
TK1_MMIO_SYSCALL0xe1000000wwwWrite 1 to trigger a syscall.
TK1_MMIO_QEMU_DEBUG0xfe001000wwwDebug console (only in QEMU). Only the LSB of the word will be sent.
TK1_MMIO_TK1_NAME00xff000000rrrTKey FPGA design name, first part, default “tk1”.
TK1_MMIO_TK1_NAME10xff000004rrrTKey FPGA design name, second part, default “mkdf”.
TK1_MMIO_TK1_VERSION0xff000008rrrVersion of FPGA design (See UDI for product version or serial)
TK1_MMIO_TK1_LED0xff000024r/wr/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/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/wr/wrApp load address, stored by firmware so app can find itself in memory.
TK1_MMIO_TK1_APP_SIZE0xff000034r/wr/wrApp size, stored by firmware so app can read its own size.
TK1_MMIO_TK1_CDI_FIRST0xff000080r/wr/wrThe computed Compound Device Identifier (CDI). 8 words.
TK1_MMIO_TK1_CDI_LAST0xff00009cr/wr/wrLast word of CDI.
TK1_MMIO_TK1_UDI_FIRST0xff0000c0rriFirst word of Unique Device ID (UDI). 2 words. Set during provisioning.
TK1_MMIO_TK1_UDI_LAST0xff0000c4rriLast word of UDI
TK1_MMIO_TK1_RAM_ADDR_RAND0xff000100wwiSeed word for the RAM address randomization.
TK1_MMIO_TK1_RAM_DATA_RAND0xff000104wwiSeed word for the RAM data randomization.
TK1_MMIO_TK1_CPU_MON_CTRL0xff000180wwwBit 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_FIRST0xff000184wwwStart address (32-bit) of the RAM area monitored for execution attempts.
TK1_MMIO_TK1_CPU_MON_LAST0xff000188wwwLast address (32-bit) of the RAM area monitored for execution attempts.
TK1_MMIO_TK1_SYSTEM_RESET0xff0001C0wwiWrite 1 to reset the FPGA.
TK1_MMIO_TK1_SPI_EN0xff000200wwiWrite 1 to enable the SPI-master, 0 to disable. The chip select pin will go low when the SPI-master is enabled and high when disabled.
TK1_MMIO_TK1_SPI_XFER0xff000204r/wr/wiWrite to start an SPI byte transfer. Read to get the SPI transfer status. If the value read is not 0 a new transfer can be started.
TK1_MMIO_TK1_SPI_DATA0xff000208r/wr/wiWrite to load byte to send. Read to get received byte.