Git-Mirrors/tillitis-key
1
0
Fork 0
mirror of https://github.com/tillitis/tillitis-key1.git synced 2024-12-25 15:39:27 -05:00
Code Issues Packages Projects Releases Wiki Activity

doc: Harmonize preformatted in tk1 core

Browse Source 
- No unnecessary indentation
- Mark API constants as preformatted
This commit is contained in:
Michael Cardell Widerkrantz 2024-10-07 17:19:48 +02:00 committed by Daniel Jobson
parent 7043521ba9
commit fe8f0b1aa9
No known key found for this signature in database
GPG Key ID: 3707A9DBF4BB8F1A
1 changed files with 56 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

109
hw/application_fpga/core/tk1/README.md
View File

@ -13,9 +13,9 @@ API.
### Access to device information ### Access to device information
``` ```
ADDR_NAME0: 0x00 ADDR_NAME0: 0x00
ADDR_NAME1: 0x01 ADDR_NAME1: 0x01
ADDR_VERSION: 0x02 ADDR_VERSION: 0x02
``` ```
These addresses provide read only information about the name (type) These addresses provide read only information about the name (type)
@ -26,7 +26,7 @@ applications.
### Control of execution mode ### Control of execution mode
``` ```
ADDR_SYSTEM_MODE_CTRL: 0x08 ADDR_SYSTEM_MODE_CTRL: 0x08
``` ```
This register controls if the device is executing in FW mode or in App This register controls if the device is executing in FW mode or in App
@ -37,10 +37,10 @@ by FW. If set the device is in app mode.
### Control of RGB LED ### Control of RGB LED
``` ```
ADDR_LED: 0x09 ADDR_LED: 0x09
LED_B_BIT: 0 LED_B_BIT: 0
LED_G_BIT: 1 LED_G_BIT: 1
LED_R_BIT: 2 LED_R_BIT: 2
``` ```
This register control the RGB LED on the TKey device. Setting a bit to This register control the RGB LED on the TKey device. Setting a bit to
@ -51,11 +51,11 @@ as well as by Apps.
### Control and status of GPIO ### Control and status of GPIO
``` ```
ADDR_GPIO: 0x0a ADDR_GPIO: 0x0a
GPIO1_BIT: 0 GPIO1_BIT: 0
GPIO2_BIT: 1 GPIO2_BIT: 1
GPIO3_BIT: 2 GPIO3_BIT: 2
GPIO4_BIT: 3 GPIO4_BIT: 3
``` ```
This register control and provide status access to the four GPIOs on This register control and provide status access to the four GPIOs on
@ -68,46 +68,48 @@ corresponding register is one or zero.
### Application introspection ### Application introspection
``` ```
ADDR_APP_START: 0x0c ADDR_APP_START: 0x0c
ADDR_APP_SIZE: 0x0d ADDR_APP_SIZE: 0x0d
``` ```
These registers provide read only information to the loaded app to These registers provide read only information to the loaded app to
itself - where it was loaded and its size. The values are written by itself - where it was loaded and its size. The values are written by
FW as part of the loading of the app. The registers can't be written FW as part of the loading of the app. The registers can't be written
when the ADDR_SYSTEM_MODE_CTRL has been set. when the `ADDR_SYSTEM_MODE_CTRL` has been set.
### Access to Blake2s ### Access to Blake2s
``` ```
ADDR_BLAKE2S: 0x10 ADDR_BLAKE2S: 0x10
``` ```
This register provides the 32-bit function pointer address to the This register provides the 32-bit function pointer address to the
Blake2s hash function in the FW. It is written by FW during boot. The Blake2s hash function in the FW. It is written by FW during boot. The
register can't be written to when the ADDR_SYSTEM_MODE_CTRL has been set. register can't be written to when the `ADDR_SYSTEM_MODE_CTRL` has been
set.
### Access to CDI ### Access to CDI
``` ```
ADDR_CDI_FIRST: 0x20 ADDR_CDI_FIRST: 0x20
ADDR_CDI_LAST: 0x27 ADDR_CDI_LAST: 0x27
``` ```
These registers provide access to the 256-bit compound device secret These registers provide access to the 256-bit compound device secret
calculated by the FW as part of loading an application. The registers calculated by the FW as part of loading an application. The registers
are written by the FW. The register can't be written to when the are written by the FW. The register can't be written to when the
ADDR_SYSTEM_MODE_CTRL has been set. Apps can read the CDI and is it as base `ADDR_SYSTEM_MODE_CTRL` has been set. The CDI is readable by apps,
secret for any secrets it needs to perform its intended use case. which can then use it as a base secret for any other secrets required
to carry out their intended use case.
### Access to UDI ### Access to UDI
``` ```
ADDR_UDI_FIRST: 0x30 ADDR_UDI_FIRST: 0x30
ADDR_UDI_LAST: 0x31 ADDR_UDI_LAST: 0x31
``` ```
These read-only registers provide access to the 64-bit Unique Device These read-only registers provide access to the 64-bit Unique Device
@ -119,12 +121,12 @@ instance for each bit in core read_data output bus.
Each SB\_LUT4 MUX is able to store 16 bits of data, in total 512 bits. Each SB\_LUT4 MUX is able to store 16 bits of data, in total 512 bits.
But since the UDI is 64 bits, we only use the two LSBs in each MUX. But since the UDI is 64 bits, we only use the two LSBs in each MUX.
Note that only the LSB address of the SB_LUT4 instances are connected Note that only the LSB address of the SB\_LUT4 instances are connected
to the CPU address. This means that only the two LSBs in each MUX can to the CPU address. This means that only the two LSBs in each MUX can
be addressed. be addressed.
During build of the FPGA design, the UDI is set to a known bit During build of the FPGA design, the UDI is set to a known bit
pattern, which means that the SB_LUT4 instantiations are initialized pattern, which means that the SB\_LUT4 instantiations are initialized
to a fixed bit pattern. to a fixed bit pattern.
The tool 'patch\_uds\_udi.py' is used to replace the fixed bit pattern The tool 'patch\_uds\_udi.py' is used to replace the fixed bit pattern
@ -136,8 +138,8 @@ bitstreams without having to do a full FPGA build.
### RAM memory protection ### RAM memory protection
``` ```
ADDR_RAM_ADDR_RAND: 0x40 ADDR_RAM_ADDR_RAND: 0x40
ADDR_RAM_DATA_RAND: 0x41 ADDR_RAM_DATA_RAND: 0x41
``` ```
These write only registers control how the data in the RAM is These write only registers control how the data in the RAM is
@ -145,8 +147,8 @@ randomized as a way of protecting the data. The randomization is
implemented using a pseudo random number generator with a state implemented using a pseudo random number generator with a state
initialized by a seed. initialized by a seed.
The ADDR_RAM_ADDR_RAND store the seed for how the addresses are The `ADDR_RAM_ADDR_RAND` store the seed for how the addresses are
randomized over the memory space. The ADDR_RAM_DATA_RAND store the randomized over the memory space. The `ADDR_RAM_DATA_RAND` store the
seed for how the data itself is randomized. FW writes random seed seed for how the data itself is randomized. FW writes random seed
values to these registers during boot. values to these registers during boot.
@ -154,28 +156,29 @@ values to these registers during boot.
### Security monitor ### Security monitor
``` ```
ADDR_CPU_MON_CTRL: 0x60 ADDR_CPU_MON_CTRL: 0x60
ADDR_CPU_MON_FIRST:0x61 ADDR_CPU_MON_FIRST:0x61
ADDR_CPU_MON_LAST: 0x62 ADDR_CPU_MON_LAST: 0x62
``` ```
Monitors events and state changes in the SoC and handles security Monitors events and state changes in the SoC and handles security
violations. Currently checks for: violations. Currently checks for:
1. Trying to execute instructions in FW_RAM. *Always enabled.* 1. Trying to execute instructions in FW\_RAM. *Always enabled.*
2. Trying to access RAM outside of the physical memory. *Always enabled* 2. Trying to access RAM outside of the physical memory. *Always enabled*
3. Trying to execute instructions from a memory area in RAM defined by 3. Trying to execute instructions from a memory area in RAM defined by
the application. the application.
Number 1 and 2 are always enabled. Number 3 is set and enabled by the Number 1 and 2 are always enabled. Number 3 is set and enabled by the
device application. Once enabled, by writing to ADDR_CPU_MON_CTRL, the device application. Once enabled, by writing to `ADDR_CPU_MON_CTRL`,
memory defined by ADDR_CPU_MON_FIRST and ADDR_CPU_MON_LAST will be the memory defined by `ADDR_CPU_MON_FIRST` and `ADDR_CPU_MON_LAST`
protected against execution. Typically the application developer will will be protected against execution. Typically the application
set this protection to cover the application stack and/or heap. developer will set this protection to cover the application stack
and/or heap.
An application can write to these registers to define the area and An application can write to these registers to define the area and
then enable the monitor. Once enabled the monitor can't be disabled, then enable the monitor. Once enabled the monitor can't be disabled,
and the ADDR_CPU_MON_FIRST and ADDR_CPU_MON_LAST registers can't be and the `ADDR_CPU_MON_FIRST` and `ADDR_CPU_MON_LAST` registers can't be
changed. This means that an application that wants to use the monitor changed. This means that an application that wants to use the monitor
must define the area first before enabling the monitor. must define the area first before enabling the monitor.
@ -209,37 +212,37 @@ The SPI-master is controlled using a few API
addresses: addresses:
``` ```
localparam ADDR_SPI_EN = 8'h80; ADDR_SPI_EN: 0x80
localparam ADDR_SPI_XFER = 8'h81; ADDR_SPI_XFER: 0x81
localparam ADDR_SPI_DATA = 8'h82; ADDR_SPI_DATA: 0x82
``` ```
**ADDR_SPI_EN** enables and disabled the SPI-master. Writing a 0x01 will `ADDR_SPI_EN` enables and disabled the SPI-master. Writing a 0x01 will
lower the SPI chip select to the memory. Writing a 0x00 will raise the lower the SPI chip select to the memory. Writing a 0x00 will raise the
chip select. chip select.
Writing to the **ADDR_SPI_XFER** starts a byte transfer. Reading from Writing to the `ADDR_SPI_XFER` starts a byte transfer. Reading from
the address returns the status for the SPI-master. If the return value the address returns the status for the SPI-master. If the return value
is not zero, the SPI-master is ready to send a byte. is not zero, the SPI-master is ready to send a byte.
**ADDR_SPI_DATA** is the address used to send and receive a byte. `ADDR_SPI_DATA` is the address used to send and receive a byte. data.
data. The least significant byte will be sent to the memory during a The least significant byte will be sent to the memory during a
transfer. The byte returned from the memory will be presented to SW if transfer. The byte returned from the memory will be presented to SW if
the address is read after a transfer has completed. the address is read after a transfer has completed.
The sequence of operations needed to perform is thus: The sequence of operations needed to perform is thus:
1. Activate the SPI-master by writing a 0x00000001 to ADDR_SPI_EN 1. Activate the SPI-master by writing a 0x00000001 to ADDR_SPI_EN
2. Write a byte to ADDR_SPI_DATA 2. Write a byte to `ADDR_SPI_DATA`
3. Read ADDR_SPI_XFER to check status. Repeat until the read 3. Read `ADDR_SPI_XFER` to check status. Repeat until the read
operation returns non-zero value operation returns non-zero value
4. Write to ADDR_SPI_XFER 4. Write to `ADDR_SPI_XFER`
5. Read ADDR_SPI_XFER to check status. Repeat until the read operation 5. Read `ADDR_SPI_XFER` to check status. Repeat until the read operation
returns a non-zero value returns a non-zero value
6. Read out the received byte from ADDR_SPI_DATA 6. Read out the received byte from `ADDR_SPI_DATA`
7. Repeat 2..6 as many times as needed to send a command and data to 7. Repeat 2..6 as many times as needed to send a command and data to
the memory and getting the expected status, data back. the memory and getting the expected status, data back.
8. Deactivate the SPI-master by writing 0x00000000 to ADDR_SPI_EN 8. Deactivate the SPI-master by writing 0x00000000 to `ADDR_SPI_EN`
The SPI connected memory on the board is the Winbond W25Q80. For The SPI connected memory on the board is the Winbond W25Q80. For
information about the memory including support commands and protocol, information about the memory including support commands and protocol,
@ -270,7 +273,7 @@ The reset is controlled by the following API address. Note that
any value written to the address will trigger the reset. any value written to the address will trigger the reset.
``` ```
localparam ADDR_SYSTEM_RESET = 8'h70; ADDR_SYSTEM_RESET: 0x70
``` ```