[hmac,doc] Documentation fixes

This updates the HMAC documentation to correspond
with the changes in the commits above as well as
commits minor fixes.

Signed-off-by: Ghada Dessouky <[email protected]>

hw/ip/hmac/README.md

@@ -36,7 +36,7 @@ The 1024-bit secret key is written in [`KEY_0`](doc/registers.md#key) to [`KEY_3
 For example, to use a 256-bit secret key, [`CFG.key_length`] should be configured to 0x02 and then only secret key registers [`KEY_0`](doc/registers.md#key) to [`KEY_7`] are read and relevant for the HMAC operation.
 The digest size required is configured in [`CFG.digest_size`].
 The message to authenticate is written to [`MSG_FIFO`](doc/registers.md#msg_fifo) and the HMAC generates a 256/384/512-bit digest value (depending on the digest size configuration provided) which can be read from [`DIGEST_0`](doc/registers.md#digest) to [`DIGEST_7`](doc/registers.md#digest) for SHA-2 256, or from [`DIGEST_0`] to [`DIGEST_12`] for SHA-2 384, or from [`DIGEST_0`] to [`DIGEST_15`] for SHA-2 512.
-The `hash_done` interrupt is raised to report to software that the final digest is available.
+The `hmac_done` interrupt is raised to report to software that the final digest is available.
 
 This module allows software to save and restore the hashing context so that different message streams can be interleaved; please check the [Programmer's Guide](doc/programmers_guide.md#saving-and-restoring-the-context) for more information.
 

hw/ip/hmac/data/hmac.hjson

@@ -195,7 +195,7 @@
           desc: '''SHA-2 enable.
 
                  If 0, the SHA engine will not initiate compression, this is used to stop operation of the SHA-2 engine until configuration has been done.
-                 When the SHA-2 engine is disabled the digest is cleared.'''
+                 When the SHA-2 engine is disabled the digest is cleared, and the digest can be written to from SW which enables restoring context (to support context switching).'''
           tags: [// don't enable hmac and sha data paths - we will do that in functional tests
                  "excl:CsrNonInitTests:CsrExclWrite"]
         }
@@ -440,11 +440,11 @@
 
               If HMAC is disabled, the register shows result of SHA-2 256/384/512.
               Order of the 512-bit digest[511:0] = {DIGEST0, DIGEST1, DIGEST2, ... , DIGEST15}.
-              For SHA-2 256 order of the 256-bit digest[255:0] = {DIGEST0, DIGEST1, DIGEST2, DIGEST3, DIGEST4, DIGEST5, DIGEST6, DIGEST7} and {DIGEST8 - DIGEST15} are all-zero.
-              For SHA-2 384, {DIGEST12-DIGEST15} are truncated and are all-zero.
+              For SHA-2 256 order of the 256-bit digest[255:0] = {DIGEST0, DIGEST1, DIGEST2, DIGEST3, DIGEST4, DIGEST5, DIGEST6, DIGEST7} and {DIGEST8 - DIGEST15} are irrelevant and should not be read out.
+              For SHA-2 384, {DIGEST12-DIGEST15} are truncated; they are irrelevant and should not be read out.
 
               The digest gets cleared when `CFG.sha_en` transitions from 1 to 0.
-              When `CFG.sha_en` is 0, these registers can be written by software.
+              When `CFG.sha_en` is 0, these registers can be written to by software.
               ''',
         count: "NumDigestWords",
         cname: "HMAC",

hw/ip/hmac/doc/programmers_guide.md

@@ -38,6 +38,9 @@ void hmac_init(unsigned int endianess, unsigned int digest_endian) {
 The following code shows how to send a message to the HMAC, the procedure is the same whether a full HMAC or just a SHA-2 computation is required (choose between them using [`CFG.hmac_en`](registers.md#cfg)).
 In both cases the SHA-2 engine must be enabled using [`CFG.sha_en`](registers.md#cfg) (once all other configuration has been properly set).
 If the message is larger than 512-bit, the software must wait until the FIFO is not full before writing further bits.
+For SHA-2 256, only `DIGEST_0`..`7` should be read out; the redundant digests are irrelevant and would hold irrelevant values.
+For SHA-2 384, only `DIGEST_0`..`11` should be read out, the rest should be truncated out by not being read via SW.
+For SHA-2 512, all `DIGEST_0`..`15` should be read out.
 
 ```c
 void run_hmac(uint32_t *msg, uint32_t msg_len, uint32_t *hash) {

hw/ip/hmac/doc/registers.md

@@ -232,7 +232,7 @@ From a hardware perspective byte swaps are performed on a TL-UL word granularity
 SHA-2 enable.
 
  If 0, the SHA engine will not initiate compression, this is used to stop operation of the SHA-2 engine until configuration has been done.
- When the SHA-2 engine is disabled the digest is cleared.
+ When the SHA-2 engine is disabled the digest is cleared, and the digest can be written to from SW which enables restoring context (to support context switching).
 
 ### CFG . hmac_en
 HMAC datapath enable.
@@ -396,11 +396,11 @@ Digest output.
 
 If HMAC is disabled, the register shows result of SHA-2 256/384/512.
 Order of the 512-bit digest[511:0] = {DIGEST0, DIGEST1, DIGEST2, ... , DIGEST15}.
-For SHA-2 256 order of the 256-bit digest[255:0] = {DIGEST0, DIGEST1, DIGEST2, DIGEST3, DIGEST4, DIGEST5, DIGEST6, DIGEST7} and {DIGEST8 - DIGEST15} are all-zero.
-For SHA-2 384, {DIGEST12-DIGEST15} are truncated and are all-zero.
+For SHA-2 256 order of the 256-bit digest[255:0] = {DIGEST0, DIGEST1, DIGEST2, DIGEST3, DIGEST4, DIGEST5, DIGEST6, DIGEST7} and {DIGEST8 - DIGEST15} are irrelevant and should not be read out.
+For SHA-2 384, {DIGEST12-DIGEST15} are truncated; they are irrelevant and should not be read out.
 
 The digest gets cleared when `CFG.sha_en` transitions from 1 to 0.
-When `CFG.sha_en` is 0, these registers can be written by software.
+When `CFG.sha_en` is 0, these registers can be written to by software.
 - Reset default: `0x0`
 - Reset mask: `0xffffffff`