Added documentation.

1 files changed, 54 insertions, 3 deletions

diff --git a/README.md b/README.md
index 27bf6c1..36e5995 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,54 @@
-# sha3 #
-Hardware implementation of the SHA-3 (Keccak) cryptographic hash
-function as specified in NIST FIPS-202.
+# SHA-3
+
+## Core Description
+
+This core implements the sponge construction defined in the SHA-3 hash standard.
+ 
+## API Specification
+
+The interface of the core is similar to other CrypTech cores. FMC memory map is split into two parts, the first part contains registers and looks like the following:
+
+| Offset | Register      |
+|--------|---------------|
+| 0x0000 | NAME0         |
+| 0x0004 | NAME1         |
+| 0x0008 | VERSION       |
+| 0x0020 | CONTROL       |
+| 0x0024 | STATUS        |
+
+The core has the following registers:
+
+ * **NAME0**, **NAME1**  
+Read-only core name ("sha3", "    " [four whitespaces]).
+
+ * **VERSION**  
+Read-only core version, currently "0.10".
+
+ * **CONTROL**  
+Register bits:  
+[31:2] Don't care, always read as 0  
+[1] "next" control bit  
+[0] "init" control bit  
+The "init" control bit replaces the core's state with the contents of the input block and starts hashing, it should be used to absorb the very first block of data into the sponge. The "next" control bit xor's the core's state with the contents of the input block and continues hashing, it should be used to absorb subsequent blocks into the sponge. The core starts operation when a control bit changes from 0 to 1. This way when a bit is set, the core will only perform one operation and then stop. To start another operation, the bit must be cleared at first and then set to 1 again. Note, that "init" has priority over "next", if both bits are set simultaneously, "init" takes precedence.
+
+ * **STATUS**
+Read-only register bits:  
+[31:2] Don't care, always read as 0  
+[1] "valid" control bit  
+[0] "ready" control bit (always read as 1)  
+The "valid" status bit is cleared as soon as the core starts absorbing input data block, and gets set after the operation is complete. The "ready" status bit is hardwired to always read 1.
+
+
+The second part of the address space is split into two banks:
+
+| Offset | Bank  |
+|--------|-------|
+|  0x200 | BLOCK |
+|  0x300 | STATE |
+
+
+Length of each bank is 200 bytes, the first bank has read-write access and contains input data block, the second bank is read-only and contains the core's internal state.
+
+## Vendor-specific Primitives
+
+This core doesn't use vendor-specific primitives.