[docs] SHA3 docs. Copypasta'd from old SHA3 content

docs/Generators/SHA3.rst

@@ -0,0 +1,70 @@
+SHA3 RoCC Accelerator
+===================================
+
+Introduction
+-----------------------------------
+Secure hashing algorithms represent a class of hashing functions that provide four attributes: ease
+of hash computation, inability to generate the message from the hash (one-way property), inability
+to change the message and not the hash (weakly collision free property), and inability to find
+two messages with the same hash (strongly collision free property). The National Institute of
+Standards and Technology (NIST) recently held a competition for a new algorithm to be added to
+its set of Secure Hashing Algorithms (SHA). In 2012 the winner was determined to be the Keccak
+hashing function and a rough specification for SHA3 was established. The algorithm operates on
+variable length messages with a sponge function, and thus alternates between absorbing chunks of
+the message into a set of state bits and permuting the state. The absorbing is a simple bitwise
+XOR while the permutation is a more complex function composed of several operations, χ, θ, ρ,
+π, ι, that all perform various bitwise operations, including rotations, parity calculations, XORs,
+etc. The Keccak hashing function is parameterized for different sizes of state and message chunks
+but for this lab we will only support the Keccak-256 variant with 1600 bits of state and 1088 bit
+message chunks. In addition, for this lab we will ignore the variable length portion to avoid one
+of the most complicated parts of Keccak the padding. Our interface, which is discussed further
+below, assume a single chunk of message is ready to be absorbed and hashed. A diagram of the SHA3
+accelerator is shown below.
+
+.. image:: ../_static/images/sha3.png
+
+Technical Details
+------------------------------------
+The accelerator is designed around three sub-systems, an
+interface with the processor, an interface with memory, and
+the actual hashing computation system. The interface
+with the processor is designed using the ROCC interface for
+coprocessors integrating with the RISC-V Rocket/BOOM
+processor. It includes the ability to transfer two 64 bit
+words to the co-processor, the request for a return value,
+and a small field for the function requested. The accelerator
+receives these requests using a ready/valid interface. The
+ROCC instruction is parsed and the needed information is
+stored into one of the T execution contexts, only if there is
+one available. These execution contexts contain the memory
+address of the message being hashed, the memory address
+to store the resulting hash in, the length of the message, and
+several other control fields.
+
+Once the execution context is valid the memory subsystem
+then begins to fetch chunks of the message. The memory
+subsystem is fully decoupled from the other subsystems
+and maintains either T or 4 memory buffers, whichever is
+smaller. The accelerators memory interface can provide a
+maximum of one 64 bit word per cycle which corresponds
+to 17 requests needed to fill a buffer (the size is dictated by
+the SHA3 algorithm). Memory requests to fill these buffers
+are sent out as rapidly as the memory interface can handle,
+with a tag field set to allow the different memory buffers
+requests to be distinguished, as they may be returned out of
+order. Once the memory subsystem has filled a buffer the
+control unit absorbs the buffer into the appropriate execution
+context, at which point the execution context is free to
+begin permutation, and the memory buffer is free to send
+more memory requests.
+
+After the buffer is absorbed, the hashing computation
+subsystem begins the permutation operations. Because the
+hashing subsystem has a parameterized number of execution
+units in parallel, D, as well as a parameterized number
+of round execution units, N, it requires a dynamic scheduler
+to determine which execution context are ready to run and
+on which available execution unit they should be run. Once
+the message is fully hashed, the hash is written to memory
+with a simple state machine.
+

docs/Generators/index.rst

@@ -15,3 +15,4 @@ The following pages introduce the generators integrated with the Chipyard framew
    BOOM
    Hwacha
    RocketChip
+   SHA3