Note about the importance of releases; clarify some docs

README.md

@@ -12,17 +12,17 @@ What makes the Tillitis Key 1 security token unique is that it doesn’t
 verify applications, it measures them (hashes a digest over the
 binary), before running them on its open hardware security processor.
 
-Each security token contains a Unique Device Secret (UDS),
-which together with an application measurement, and an optional
+Each security token contains a Unique Device Secret (UDS), which
+together with an application measurement, and an optional
 user-provided seed, is used to derive key material unique to each
 application. This allows users to build and load their own apps, while
 ensuring that each app loaded will have its own cryptographic
 identity. The design is similar to TCG DICE. The Tillitis Key 1
-platform allows for applications up to 64 KB.
-
-The first implementation is the Tillitis Key 1:
-![The Tillitis Key 1 PCB](doc/images/mta1-usb-v1.jpg)
+platform has 128 KB of RAM. The current firmware design allows for
+applications up to 64 KB with a 64 KB stack.
 
+![Tillitis Key 1 PCB, first implementation](doc/images/mta1-usb-v1.jpg)
+*Tillitis Key 1 PCB, first implementation*
 
 ## Documentation
 
@@ -35,6 +35,16 @@ The first implementation is the Tillitis Key 1:
 * [Quickstart](doc/quickstart.md) to program the Tillitis Key 1
 * [Release Notes](doc/release_notes.md)
 
+Note that development is ongoing. For example, changes might be made
+to the measuring and derivation of key material, causing the
+public/private keys of a signer app to change. To avoid unexpected
+changes, please use a tagged release. Read the [Release
+Notes](doc/release_notes.md) to keep up to date with changes and new
+releases.
+
+Applications and host programs that communicate with the apps are kept
+in this repository: https://github.com/tillitis/tillitis-key1-apps
+
 ## About this repository
 
 This repository contains hardware, software and utilities written as

doc/system_description/software.md

@@ -18,13 +18,16 @@ firmware and the loaded app. All types are little-endian.
 
 ## Constraints
 
-The application FPGA is a Lattice UP5K, with the following
+The application FPGA is a Lattice ICE40 UP5K, with the following
 specifications:
 
-  * 32KB x 4 SPRAM => 128KB for Application
-  * 4Kb x 30 EBR => 120Kb, PicoRV32 uses ~4 EBR internally => 13KB for
-    Firmware. We should probably aim for less; 8KB should be the
-    target.
+  * 30 EBR[^1] x 4 Kbit => 120 Kbit. PicoRV32 uses ~4 EBRs internally
+    => 13 KB for Firmware. We should probably aim for less; 8 KB
+    should be the target.
+  * 4 SPRAM x 32 KB => 128 KB RAM for application/software
+
+[^1]: Embedded Block RAM residing in the FPGA, can configured as RAM
+    or ROM.
 
 ## Introduction
 
@@ -41,8 +44,9 @@ which is outlined below. E.g. UDS isn't readable, and the `APP_{ADDR,
 SIZE}` are not writable for the application.
 
 The software on the Tillitis Key communicates to the host via the
-`{RX,TX}_FIFO` registers, using the framing protocol described in
-[Framing Protocol](../framing_protocol/framing_protocol.md).
+`UART_{RX,TX}_{STATUS,DATA}` registers, using the framing protocol
+described in [Framing
+Protocol](../framing_protocol/framing_protocol.md).
 
 The firmware defines a protocol (command/response interface) on top of
 the framing layer, which is used to bootstrap the application onto the
@@ -57,8 +61,8 @@ between the host and the device.
 
 ## Firmware
 
-The device has 128 kB RAM. The current firmware loads the app at the
-upper 64 kB. The lower 64 kB is currently set up as stack for the app.
+The device has 128 KB RAM. The current firmware loads the app at the
+upper 64 KB. The lower 64 KB is currently set up as stack for the app.
 
 The firmware is part of FPGA bitstream (ROM), and is loaded at
 `0x0000_0000`.
@@ -70,7 +74,7 @@ The PicoRV32 starts executing at `0x0000_0000`. Our firmware starts at
 `0x4000_0000` and upwards. A stack is also initialized, starting at
 0x4000_fff0 and downwards. When the initialization is finished, the
 firmware waits for incoming commands from the host, by busy-polling
-the `RX_FIFO_{AVAILABLE,DATA}`registers. When a complete command is
+the `UART_RX_{STATUS,DATA}` registers. When a complete command is
 read, the firmware executes the command.
 
 ### Loading an application
@@ -296,7 +300,7 @@ Examples:
 | `UDS_NAME0`        | r    | invisible  |        |         |           | ID of core                                             |
 | `UDS_NAME1`        | r    | invisible  |        |         |           | ID of core                                             |
 | `UDS_VERSION`      | r    | invisible  |        |         |           | Version of core                                        |
-| `UDS_START`        | r[^1]| invisible  | 4B     | u8[32]  |           | First word of Unique Device Secret key.                |
+| `UDS_START`        | r[^2]| invisible  | 4B     | u8[32]  |           | First word of Unique Device Secret key.                |
 | `UDS_LAST`         |      | invisible  |        |         |           | The last word of the UDS                               |
 | `UART_NAME0`       | r    | r          |        |         |           | ID of core                                             |
 | `UART_NAME1`       | r    | r          |        |         |           | ID of core                                             |
@@ -327,4 +331,4 @@ Examples:
 | `CDI_START`        | r/w  | r          | 32B    | u8[32]  |           | Compound Device Identifier (CDI). UDS+measurement...   |
 | `CDI_LAST`         |      | r          |        |         |           | Last word of CDI                                       |
 
-[^1]: The UDS can only be read *once* per power-cycle.
+[^2]: The UDS can only be read *once* per power-cycle.

doc/system_description/system_description.md

@@ -149,13 +149,13 @@ The Application FPGA hardware should provide the following:
 
 2. Communication
     - Rx-FIFO with status (data_available)
-      - 8 bit data in RX_FIFO_DATA address
-      - Byte received status bit in RX_FIFO_AVAILABLE address
+      - 8 bit data in UART_RX_DATA address
+      - Byte received status bit in UART_RX_STATUS address
       - Readable by FW and application
 
     - Tx-FIFO with capacity (fifo_ready)
-      - 8 bit data in TX_FIFO_DATA address
-      - Ready to store byte status bit in TX_FIFO_READY address
+      - 8 bit data in UART_RX_DATA address
+      - Ready to store byte status bit in UART_TX_STATUS address
       - Status readable by FW and application
       - Data writable by FW and application