Update README with info about the core functions

Signed-off-by: Joachim Strömbergson <joachim@assured.se>

hw/application_fpga/core/tk1/README.md

@@ -1,6 +1,178 @@
 # tk1
 
 ## Introduction
-The tk1 core provides design informantion as well as control of TKey specific
-functionlity such as execution mode, SW controlled stack protection, memory
-scrambling, handling of illegal instructions.
+
+The tk1 core is where information, control and monitoring
+functionality unique to the TKey1 can be found. This means that it
+provides more than one distinct functionality accessible via the core
+API.
+
+
+## API
+
+### Access to device information
+
+```
+	ADDR_NAME0:   0x00
+	ADDR_NAME1:   0x01
+	ADDR_VERSION: 0x02
+```
+
+These addresses provide read only information about the name (type)
+and version of the device. They can be read by FW as well as
+applications.
+
+
+### Control of execution mode
+
+```
+	ADDR_SWITCH_APP: 0x08
+```
+
+This register controls if the device is executing in FW mode or in App
+mode. The register can be written once between power cycles, and only
+by FW. If set the device is in app mode.
+
+
+### Control of RGB LED
+
+```
+	ADDR_LED:  0x09
+	LED_B_BIT: 0
+	LED_G_BIT: 1
+	LED_R_BIT: 2
+```
+
+This register control the RGB LED on the TKey device. Setting a bit to
+one turns the corresponding color on. It can be read and written by FW
+as well as by Apps.
+
+
+### Control and status of GPIO
+
+```
+	ADDR_GPIO: 0x0a
+	GPIO1_BIT: 0
+	GPIO2_BIT: 1
+	GPIO3_BIT: 2
+	GPIO4_BIT: 3
+```
+
+This register control and provide status access to the four GPIOs on
+the TKey. GPIO one and two are inputs. They will sample the input
+level and present it to SW. GPIO three and four are outputs. They will
+emit either high or low voltage level depending on if the
+corresponding register is one or zero.
+
+
+### Application introspection
+
+```
+	ADDR_APP_START: 0x0c
+	ADDR_APP_SIZE:  0x0d
+```
+
+These registers provide read only information to the loaded app to
+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
+when the ADDR_SWITCH_APP has been set.
+
+
+### Access to Blake2s
+
+```
+	ADDR_BLAKE2S: 0x10
+```
+
+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
+register can't be written to when the ADDR_SWITCH_APP has been set.
+
+
+### Access to CDI
+
+```
+  ADDR_CDI_FIRST: 0x20
+  ADDR_CDI_LAST:  0x27
+```
+
+These registers provide access to the 256-bit compound device secret
+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
+ADDR_SWITCH_APP has been set. Apps can read the CDI and is it as base
+secret for any secrets it needs to perform its intended use case.
+
+
+### Access to UDI
+
+```
+  ADDR_UDI_FIRST: 0x30
+  ADDR_UDI_LAST:  0x31
+```
+
+These registers provide read access to the 64-bit unique device
+identity. The UDI is stored as ROM within the FPGA configuration. The
+registers can't be written to.
+
+
+### RAM memory protecion
+
+```
+  ADDR_RAM_ASLR:     0x40
+  ADDR_RAM_SCRAMBLE: 0x41
+```
+
+These write only registers control how the data in the RAM is
+scrambled as a way of protecting the data. The ADDR_RAM_ASLR control
+how the addresses are scrambled. The ADDR_RAM_SCRAMBLE control how the
+data itself is scrambled. FW writes random values to these registers
+during boot.
+
+
+### Execution monitor
+
+```
+  ADDR_CPU_MON_CTRL: 0x60
+  ADDR_CPU_MON_FIRST:0x61
+  ADDR_CPU_MON_LAST: 0x62
+```
+
+These registers control the execution monitor related to the RAM. Once
+enabled, by writing to ADDR_CPU_MON_CTRL, the memory are defined by
+ADDR_CPU_MON_FIRST and ADDR_CPU_MON_LAST inclusive will be protected
+against execution. Typically this will be the application stack and,
+or heap.
+
+Applications can write to these registers to define the area and then
+enable the monitor. One enabled, the monitor can't be disabled, and
+the ADDR_CPU_MON_FIRST and ADDR_CPU_MON_LAST registers can't be
+changes. This means that an application that wants to use the monitor
+must define the area first before enabling the monitor.
+
+Once enabled, if the CPU tries to read an instruction from the defined
+area, the core will force the CPU to instead read an all zero, illegal
+instruction. This illegal instruction will trigger the CPU to enter
+its TRAP state, from which it can't returned unless the TKey is power
+cycled.
+
+The FW will not write to these registers as part of loading an
+app. The app developer must define the area and enable the monitor to
+get the protection.
+
+Note that there is a second memory area that is under the protection
+of the execution monitor - the FW_RAM. The execution protection of
+this memory is always anabled and the definition of the area is hard
+coded into the FPGA design.
+
+One feature not obvious from the API is that when the CPU traps, the
+core will detect that and start flashing the RGB LED with a red
+light - indicating that the CPU is its trap state and no further
+execution is possible.
+
+
+## Implementation
+
+The core is implemented as a single module. Future versions will
+probably be separated into separate modules.
+
+---