Document address structure, remove redundant symbols.

1 files changed, 81 insertions, 50 deletions

diff --git a/sw/cryptech.h b/sw/cryptech.h
index e36b71a..186f804 100644
--- a/sw/cryptech.h
+++ b/sw/cryptech.h
@@ -36,10 +36,46 @@
 //
 //======================================================================
 
+/*
 
-// Segments.
+Each Cryptech core has a set of 4-byte registers, which are accessed
+through a 16-bit address. The address space is divided as follows:
+  3 bits segment selector       | up to 8 segments
+  5 bits core selector          | up to 32 cores/segment (see note below)
+  8 bits register selector      | up to 256 registers/core (see modexp below)
+
+i.e, the address is structured as:
+sss ccccc rrrrrrrr
+
+The I2C and UART communication channels use this 16-bit address format
+directly in their read and write commands.
+
+The EIM communications channel translates this 16-bit address into a
+32-bit memory-mapped address in the range 0x08000000..807FFFF:
+00001000000000 sss 0 ccccc rrrrrrrr 00
+
+EIM, as implemented on the Novena, uses a 19-bit address space:
+  Bits 18..16 are the semgent selector.
+  Bits 15..10 are the core selector.
+  Bits 9..2 are the register selector.
+  Bits 1..0 are zero, because reads and writes are always word aligned.
+
+Note that EIM can support 64 cores per segment, but we sacrifice one bit
+in order to map it into a 16-bit address space.
+
+*/
+
+
+//------------------------------------------------------------------
+// Default sizes
+//------------------------------------------------------------------
 #define CORE_SIZE               0x100
 #define SEGMENT_SIZE            0x20 * CORE_SIZE
+
+
+//------------------------------------------------------------------
+// Segments
+//------------------------------------------------------------------
 #define SEGMENT_OFFSET_GLOBALS  0 * SEGMENT_SIZE
 #define SEGMENT_OFFSET_HASHES   1 * SEGMENT_SIZE
 #define SEGMENT_OFFSET_RNGS     2 * SEGMENT_SIZE
@@ -82,6 +118,7 @@
 #define COMM_ADDR_NAME1         COMM_ADDR_BASE + ADDR_NAME1
 #define COMM_ADDR_VERSION       COMM_ADDR_BASE + ADDR_VERSION
 
+// current name and version values
 #define NOVENA_BOARD_NAME0      "PVT1"
 #define NOVENA_BOARD_NAME1      "    "
 #define NOVENA_BOARD_VERSION    "0.10"
@@ -98,7 +135,7 @@
 //------------------------------------------------------------------
 // Hashes segment.
 //------------------------------------------------------------------
-// addresses and codes common to all hash cores
+// addresses common to all hash cores
 #define CTRL_INIT_CMD           1
 #define CTRL_NEXT_CMD           2
 #define ADDR_BLOCK              0x10
@@ -148,6 +185,7 @@
 #define MODE_SHA_384            2 << 2
 #define MODE_SHA_512            3 << 2
 
+// current name and version values
 #define SHA1_NAME0              "sha1"
 #define SHA1_NAME1              "    "
 #define SHA1_VERSION            "0.50"
@@ -226,6 +264,7 @@
 #define CSPRNG_ADDR_NBLOCKS_LO  CSPRNG_ADDR_BASE + 0x41
 #define CSPRNG_ADDR_NBLOCKS_HI  CSPRNG_ADDR_BASE + 0x42
 
+// current name and version values
 #define TRNG_NAME0              "trng"
 #define TRNG_NAME1              "    "
 #define TRNG_VERSION            "0.50"
@@ -247,45 +286,40 @@
 // CIPHERS segment.
 // -----------------------------------------------------------------
 // aes core.
-#define AES_ADDR_BASE          SEGMENT_OFFSET_CIPHERS + (0 * CORE_SIZE)
-#define AES_ADDR_NAME0         AES_ADDR_BASE + ADDR_NAME0
-#define AES_ADDR_NAME1         AES_ADDR_BASE + ADDR_NAME1
-#define AES_ADDR_VERSION       AES_ADDR_BASE + ADDR_VERSION
-
-#define AES_ADDR_CTRL          AES_ADDR_BASE + ADDR_CTRL
-#define AES_CTRL_INIT_BIT      CTRL_INIT_BIT
-#define AES_CTRL_NEXT_BIT      CTRL_NEXT_BIT
-
-#define AES_ADDR_STATUS        AES_ADDR_BASE + ADDR_STATUS
-#define AES_STATUS_READY_BIT   STATUS_READY_BIT
-#define AES_STATUS_VALID_BIT   STATUS_VALID_BIT
-
-#define AES_ADDR_CONFIG        AES_ADDR_BASE + 0x0a
-#define AES_CONFIG_ENCDEC_BIT  1
-#define AES_CONFIG_KEYLEN_BIT  2
-
-#define AES_ADDR_KEY0          0x10
-#define AES_ADDR_KEY1          0x11
-#define AES_ADDR_KEY2          0x12
-#define AES_ADDR_KEY3          0x13
-#define AES_ADDR_KEY4          0x14
-#define AES_ADDR_KEY5          0x15
-#define AES_ADDR_KEY6          0x16
-#define AES_ADDR_KEY7          0x17
-
-#define AES_ADDR_BLOCK0        0x20
-#define AES_ADDR_BLOCK1        0x21
-#define AES_ADDR_BLOCK2        0x22
-#define AES_ADDR_BLOCK3        0x23
-
-#define AES_ADDR_RESULT0       0x30
-#define AES_ADDR_RESULT1       0x31
-#define AES_ADDR_RESULT2       0x32
-#define AES_ADDR_RESULT3       0x33
-
-#define AES_CORE_NAME0         "aes "
-#define AES_CORE_NAME1         "    "
-#define AES_CORE_VERSION       "0.80"
+#define AES_ADDR_BASE           SEGMENT_OFFSET_CIPHERS + (0 * CORE_SIZE)
+#define AES_ADDR_NAME0          AES_ADDR_BASE + ADDR_NAME0
+#define AES_ADDR_NAME1          AES_ADDR_BASE + ADDR_NAME1
+#define AES_ADDR_VERSION        AES_ADDR_BASE + ADDR_VERSION
+#define AES_ADDR_CTRL           AES_ADDR_BASE + ADDR_CTRL
+#define AES_ADDR_STATUS         AES_ADDR_BASE + ADDR_STATUS
+
+#define AES_ADDR_CONFIG         AES_ADDR_BASE + 0x0a
+#define AES_CONFIG_ENCDEC_BIT   1
+#define AES_CONFIG_KEYLEN_BIT   2
+
+#define AES_ADDR_KEY0           0x10
+#define AES_ADDR_KEY1           0x11
+#define AES_ADDR_KEY2           0x12
+#define AES_ADDR_KEY3           0x13
+#define AES_ADDR_KEY4           0x14
+#define AES_ADDR_KEY5           0x15
+#define AES_ADDR_KEY6           0x16
+#define AES_ADDR_KEY7           0x17
+
+#define AES_ADDR_BLOCK0         0x20
+#define AES_ADDR_BLOCK1         0x21
+#define AES_ADDR_BLOCK2         0x22
+#define AES_ADDR_BLOCK3         0x23
+
+#define AES_ADDR_RESULT0        0x30
+#define AES_ADDR_RESULT1        0x31
+#define AES_ADDR_RESULT2        0x32
+#define AES_ADDR_RESULT3        0x33
+
+// current name and version values
+#define AES_CORE_NAME0          "aes "
+#define AES_CORE_NAME1          "    "
+#define AES_CORE_VERSION        "0.80"
 
 
 // Chacha core
@@ -293,17 +327,11 @@
 #define CHACHA_ADDR_NAME0       CHACHA_ADDR_BASE + ADDR_NAME0
 #define CHACHA_ADDR_NAME1       CHACHA_ADDR_BASE + ADDR_NAME1
 #define CHACHA_ADDR_VERSION     CHACHA_ADDR_BASE + ADDR_VERSION
-
 #define CHACHA_ADDR_CTRL        CHACHA_ADDR_BASE + ADDR_CTRL
-#define CHACHA_CTRL_INIT_BIT    CTRL_INIT_BIT
-#define CHACHA_CTRL_NEXT_BIT    CTRL_NEXT_BIT
-
 #define CHACHA_ADDR_STATUS      CHACHA_ADDR_BASE + ADDR_STATUS
-#define CHACHA_STATUS_READY_BIT STATUS_READY_BIT
-#define CHACHA_STATUS_VALID_BIT STATUS_VALID_BIT
 
 #define CHACHA_ADDR_KEYLEN      0x0a
-#define CHACHA_KEYLEN_BIT       1
+#define CHACHA_KEYLEN           1
 
 #define CHACHA_ADDR_ROUNDS      0x0b
 
@@ -353,6 +381,7 @@
 #define CHACHA_ADDR_DATA_OUT14  0x8e
 #define CHACHA_ADDR_DATA_OUT15  0x8f
 
+// current name and version values
 #define CHACHA_NAME0            "chac"
 #define CHACHA_NAME1            "ha  "
 #define CHACHA_VERSION          "0.80"
@@ -373,8 +402,6 @@
 #define MODEXP_ADDR_NAME1         MODEXP_ADDR_BASE + ADDR_NAME1
 #define MODEXP_ADDR_VERSION       MODEXP_ADDR_BASE + ADDR_VERSION
 #define MODEXP_ADDR_CTRL          MODEXP_ADDR_BASE + ADDR_CTRL
-#define MODEXP_CTRL_INIT_BIT      1
-#define MODEXP_CTRL_NEXT_BIT      2
 #define MODEXP_ADDR_STATUS        MODEXP_ADDR_BASE + ADDR_STATUS
 
 #define MODEXP_ADDR_DELAY         MODEXP_ADDR_BASE + 0x13
@@ -383,6 +410,10 @@
 #define MODEXP_MODULUS_LENGTH     MODEXP_ADDR_BASE + 0x20
 #define MODEXP_EXPONENT_LENGTH    MODEXP_ADDR_BASE + 0x21
 
+// Most cores need fewer than 256 registers, but Modexp needs many more.
+//#define NEXT_MATH_ADDR_BASE       SEGMENT_OFFSET_MATH + (0x05 * CORE_SIZE)
+
+// current name and version values
 #define MODEXP_NAME0              "mode"
 #define MODEXP_NAME1              "xp  "
 #define MODEXP_VERSION            "0.50"