Adding README that describes the mkmif core.

1 files changed, 115 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..771cb6f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,115 @@
+# Master Key Memory Interface #
+This core provides a 32-bit interface to a master key memory (MKM)
+implemented using an external volatile memory. The memory targeted is
+[Microchip 23K640](https://www.microchip.com/wwwproducts/en/23K640), a
+serial SRAM with a SPI interface.
+
+
+## Purpose and Functionality ##
+The Master Key Memory is where a cryptographic master key is stored. the
+key is used (for example) to cryptographically wrap other keys and
+secrets. By wiping the MKM and thus the master key, the wrapped secrets
+are protected against leakage to a local attacker that physically breaks
+an actuve tamper detect shield.
+
+The core will in future versions provide functionality to autonomosly
+protect against memory remanence effects by rotating bits in stored data
+and moving data to different addresses in the external memory. The core
+will also be able to automously zeroise the memory when given an alarm
+signal.
+
+The current version however simply provides an interface to the slower,
+serial memory including initializing the memory in the correct mode. The
+core supports three commands: read word, write word and initalize
+memory.
+
+
+## Limitations ##
+The SPI clock is generated by the core clock (clk) divided by the
+SPI clock divisor * 2 (the divisor is the half period in cycles). The
+default divisor is set to generate an SPI clock of less than 1 MHz when
+the core clock is 50 MHz. For other speeds and other
+core frequencies the divisor will have to be adjusted.
+
+The core will only read and write complete 32-bit words.
+
+Commands given while the core is performing a read, write or
+initialization operation will silently be ignored.
+
+
+## Implementation ##
+The implementation is divided into three parts:
+
+- A SPI interface able to transmit a given number of bits at a given SPI
+  clock rate. Data received are simultaneously collected and provided as
+  read data. The SPI interface also generates the SPI clock and chip
+  enable.
+
+- A command handler core that tha read and write words as well as send
+  init commands to the memory using the SPI interface.
+
+- An API interface that provides the ability to configure the SPI clock
+  speed, setting the address to be read or written and data access.
+
+
+The current implementation will initiate the Microchip memory directly
+after reset and set the memory in sequential mode. This means that it
+would actually be possible to write a stream of data to the memory, but
+since the API only handles a single 32-bit word, the mode is only used
+to remove the need to update the address between bytes.
+
+
+### Implementation Results ###
+
+**Altera Cyclone IV E**
+
+- Registers: 212
+- Logic Elements: 289
+- Fmax: 250 MHz
+
+
+**Altera Cyclone V**
+
+- Registers: 221
+- ALMs: 113
+- Fmax: 194 MHz
+
+
+**Xilinx Spartan 6**
+
+- Slice Registers: 206
+- Slice LUTs: 185
+- Fmax: 200 MHz
+
+
+**Xilinx Artix 7**
+
+- Slice Registers: 205
+- Slice LUTs: 176
+- Fmax: 383 MHz
+
+
+## Status ##
+
+**(2016-05-10)**
+
+The core has now been verified in a Xilinx Spartan-6 FPGA and the target
+Microchip memory connected to the FPGA.memory. Read and write access has
+successfully been performed with SPI clock speeds from 300 Hz to 10 MHz.
+
+
+**(2016-05-02)**
+
+Functional development completed. Simulation based debugging
+completed. Built design for both Altera and Xilinx FPGAs.
+
+
+**(2016-04-25)**
+
+Refactored core into top_-, core- and spi-modules. Made the design much
+simpler. First implementation almost completed.
+
+
+**(2016-04-21)**
+
+Core implementation started.