Memory Map

Memory Map #

Addressing #

Layout of a 32-bit address:

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
MMIO0b116 bits for core select, 24 bits rest

Address Prefixes #

The first 8 bits in a 32-bit address.

nameprefix
ROM0x00
RAM0x40
MMIO0xc0
MMIO TRNG0xc0
MMIO TIMER0xc1
MMIO UDS0xc2
MMIO UART0xc3
MMIO TOUCH0xc4
MMIO FW_RAM0xd0
MMIO TK10xff

MMIO #

MMIO begins at 0xc000_0000 but please use the constants in tk1_mem.h in the tkey-libs repository.

Note: MMIO accesses should be 32 bits wide. Use for example lw and sw to load and store 32-bit words. Exceptions are FW_RAM and QEMU_DEBUG.

In the following table, r equals read and r/w equals read and write access.

NameFWAppSizeTypeContentDescription
TRNG_STATUSrrTRNG_STATUS_READY_BIT is 1 when an entropy word is available.
TRNG_ENTROPYrr4Bu32Entropy word. Reading a word will clear TRNG_STATUS.
TIMER_CTRLr/wr/wIf TIMER_STATUS_RUNNING_BIT in TIMER_STATUS is 0, setting TIMER_CTRL_START_BIT here starts the timer. If TIMER_STATUS_RUNNING_BIT in TIMER_STATUS is 1, setting TIMER_CTRL_STOP_BIT here stops the timer.
TIMER_STATUSrrTIMER_STATUS_RUNNING_BIT is 1 when the timer is running.
TIMER_PRESCALERr/wr/w4BPrescaler init value. Write blocked when running.
TIMER_TIMERr/wr/w4BTimer init or current value while running. Write blocked when running.
UDS_FIRSTr1invisible32Bu32[8]First word of Unique Device Secret key. Word access only. Note: Only readable once per power up.
UDS_LASTinvisibleThe last word of the UDS. Note: Only readable once per power up.
UART_BITRATEr/wr/w2Bu16Default 288 (62 500 bps). The bitrate is set by writing the divisor, calculated by: divisor = 18E6 / bps.
UART_DATABITSr/wr/w4 bitsu8Default 8.
UART_STOPBITSr/wr/w2 bitsu8Default 1.
UART_RX_STATUSrr1Bu8Non-zero when there is data to read.
UART_RX_DATArr1Bu8Data to read. Only the LSB contains data.
UART_RX_BYTESrr4Bu32Number of bytes received from the host and not yet read by the SW or FW.
UART_TX_STATUSrr1Bu8Non-zero when it’s OK to write data to send.
UART_TX_DATAww1Bu8Data to send. Only the LSB contains data.
TOUCH_STATUSr/wr/wTOUCH_STATUS_EVENT_BIT is 1 when touched. After detecting a touch event (reading a 1), write anything here to acknowledge the event.
FW_RAMr/winvisible2 kiBu8[2048]Firmware-only RAM.
UDIrinvisible8Bu64Unique Device ID (UDI).
QEMU_DEBUGwwu8Debug console (only in QEMU)
NAME0rr4Bchar[4]“tk1 "ID of core/stick, first part.
NAME1rr4Bchar[4]“mkdf”ID of core/stick, second part.
VERSIONrr4Bu321Version of core/stick.
SWITCH_APPr/wr1Bu8Write anything here to trigger the switch to application mode. Reading returns 0 if TKey is in firmware mode, 0xffffffff if in app mode.
LEDr/wr/w1Bu8Controls the RGB color of the status indicator LED on TKey. Bit 0 is Blue, bit 1 is Green, and bit 2 is Red LED.
GPIOr/wr/w1Bu8Bits 0 and 1 contain the input level of GPIO 1 and 2. Bits 3 and 4 store the output level of GPIO 3 and 4.
APP_ADDRr/wr4Bu32App load address, stored by firmware so app can find itself in memory.
APP_SIZEr/wr4Bu32App size, stored by firmware so app can read its own size.
BLAKE2Sr/wr4Bu32Function pointer to a BLAKE2S function in the firmware.
CDI_FIRSTr/wr32Bu8[32]The computed Compound Device Identifier (CDI).
CDI_LASTrLast word of CDI.
RAM_ASLRwinvisible4Bu32Seed value for the RAM randomization.
RAM_SCRAMBLEwinvisible4Bu32Data scrambling seed value for the RAM.
CPU_MON_CTRLww4Bu32Bit 0 enables CPU execution monitor. Can’t be unset. Lock addresses.
CPU_MON_FIRSTww4Bu32First address of the area monitored for execution attempts.
CPU_MON_LASTww4Bu32Last address of the area monitored for execution attempts.

  1. Each word of the UDS can only be read once after TKey has started. ↩︎