[Cryptech-Commits] [core/hash/sha3] 03/05: Added documentation.

[git at cryptech.is]

This is an automated email from the git hooks/post-receive script.

meisterpaul1 at yandex.ru pushed a commit to branch master
in repository core/hash/sha3.

commit 19a93b332e5c0091498a1f7ce4481c44716e5b93
Author: Pavel V. Shatov (Meister) <meisterpaul1 at yandex.ru>
AuthorDate: Tue Dec 5 22:30:34 2017 +0300

    Added documentation.
---
 README.md | 57 ++++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file 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 [...]
+
+ * **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.