Skip to content

Commit

Permalink
[hmac,doc] S&R reg changes when IDLE
Browse files Browse the repository at this point in the history 
- a bug has been found via PR lowRISC#25554, but this has been considered as
a specification bug. This PR fixes this issue. Now the specification
says that DIGEST and MSG_LENGTH registers may be updated only when HMAC
is in IDLE state. And writting out of this IDLE window may lead to
unpredictable results.

Signed-off-by: Martin Velay <[email protected]>
  • Loading branch information
@martin-velay @vogelpi
martin-velay authored and vogelpi committed Dec 13, 2024
1 parent 2f3c379 commit 89a83ed
Show file tree
Hide file tree
Showing 2 changed files with 25 additions and 17 deletions.
15 changes: 10 additions & 5 deletions hw/ip/hmac/data/hmac.hjson
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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, and the digest can be written to from SW which enables restoring context (to support context switching).'''
When the SHA-2 engine is disabled the digest is cleared.'''
tags: [// don't enable hmac and sha data paths - we will do that in functional tests
"excl:CsrNonInitTests:CsrExclWrite"]
}
Expand Down Expand Up @@ -382,7 +382,9 @@
fields: [
{ bits: "0",
name: "hmac_idle",
desc: "HMAC idle status."
desc: '''HMAC idle status.
When IDLE, the `DIGEST` and the `MSG_LENGTH_LOWER`/`MSG_LENGTH_UPPER` can be written to from SW which enables restoring context (to support context switching).
'''
resval: "1"
}
{ bits: "1",
Expand Down Expand Up @@ -468,7 +470,8 @@
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 to by software.
When `STATUS.hmac_idle` is 1, these registers may be written to by software.
Outside of this window, writes can cause unpredictable behavior.
''',
count: "NumDigestWords",
cname: "HMAC",
Expand All @@ -491,7 +494,8 @@
Message is byte granularity.
Lower 3 bits [2:0] are ignored.

When `CFG.sha_en` is 0, this register can be written by software.
When `STATUS.hmac_idle` is 1, this register may be written by software.
Outside of this window, writes can cause unpredictable behavior.
''',
swaccess: "rw",
hwaccess: "hrw",
Expand All @@ -504,7 +508,8 @@
{ name: "MSG_LENGTH_UPPER",
desc: '''Received Message Length calculated by the HMAC in bits [63:32]

When `CFG.sha_en` is 0, this register can be written by software.
When `STATUS.hmac_idle` is 1, this register may be written by software.
Outside of this window, writes can cause unpredictable behavior.
For SHA-2-2 256 computations, message length is 64-bit {MSG_LENGTH_UPPER, MSG_LENGTH_LOWER}.f
For SHA-2 384/512 message length is extended to 128-bit in line with [nist-fips-180-4] where the upper 64 bits get zero-padded: {32'b0, 32'b0, MSG_LENGTH_UPPER, MSG_LENGTH_LOWER}.
''',
Expand Down
27 changes: 15 additions & 12 deletions hw/ip/hmac/doc/registers.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -244,7 +244,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, and the digest can be written to from SW which enables restoring context (to support context switching).
When the SHA-2 engine is disabled the digest is cleared.

### CFG . hmac_en
HMAC datapath enable.
Expand Down Expand Up @@ -298,14 +298,14 @@ HMAC Status register
{"reg": [{"name": "hmac_idle", "bits": 1, "attr": ["ro"], "rotate": -90}, {"name": "fifo_empty", "bits": 1, "attr": ["ro"], "rotate": -90}, {"name": "fifo_full", "bits": 1, "attr": ["ro"], "rotate": -90}, {"bits": 1}, {"name": "fifo_depth", "bits": 6, "attr": ["ro"], "rotate": 0}, {"bits": 22}], "config": {"lanes": 1, "fontsize": 10, "vspace": 120}}
```

| Bits | Type | Reset | Name | Description |
|:------:|:------:|:-------:|:-----------|:---------------------------------------------------------------------------------------------------|
| 31:10 | | | | Reserved |
| 9:4 | ro | x | fifo_depth | FIFO entry count. |
| 3 | | | | Reserved |
| 2 | ro | x | fifo_full | FIFO full. Data written to the FIFO whilst it is full will cause back-pressure on the interconnect |
| 1 | ro | 0x1 | fifo_empty | FIFO empty |
| 0 | ro | 0x1 | hmac_idle | HMAC idle status. |
| Bits | Type | Reset | Name | Description |
|:------:|:------:|:-------:|:-----------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 31:10 | | | | Reserved |
| 9:4 | ro | x | fifo_depth | FIFO entry count. |
| 3 | | | | Reserved |
| 2 | ro | x | fifo_full | FIFO full. Data written to the FIFO whilst it is full will cause back-pressure on the interconnect |
| 1 | ro | 0x1 | fifo_empty | FIFO empty |
| 0 | ro | 0x1 | hmac_idle | HMAC idle status. When IDLE, the `DIGEST` and the `MSG_LENGTH_LOWER`/`MSG_LENGTH_UPPER` can be written to from SW which enables restoring context (to support context switching). |

## ERR_CODE
HMAC Error Code
Expand Down Expand Up @@ -413,7 +413,8 @@ For SHA-2 256 order of the 256-bit digest[255:0] = {DIGEST0, DIGEST1, DIGEST2, D
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 to by software.
When `STATUS.hmac_idle` is 1, these registers may be written to by software.
Outside of this window, writes can cause unpredictable behavior.
- Reset default: `0x0`
- Reset mask: `0xffffffff`

Expand Down Expand Up @@ -455,7 +456,8 @@ Received Message Length calculated by the HMAC in bits [31:0]
Message is byte granularity.
Lower 3 bits [2:0] are ignored.

When `CFG.sha_en` is 0, this register can be written by software.
When `STATUS.hmac_idle` is 1, this register may be written by software.
Outside of this window, writes can cause unpredictable behavior.
- Offset: `0xe4`
- Reset default: `0x0`
- Reset mask: `0xffffffff`
Expand All @@ -473,7 +475,8 @@ When `CFG.sha_en` is 0, this register can be written by software.
## MSG_LENGTH_UPPER
Received Message Length calculated by the HMAC in bits [63:32]

When `CFG.sha_en` is 0, this register can be written by software.
When `STATUS.hmac_idle` is 1, this register may be written by software.
Outside of this window, writes can cause unpredictable behavior.
For SHA-2-2 256 computations, message length is 64-bit {MSG_LENGTH_UPPER, MSG_LENGTH_LOWER}.f
For SHA-2 384/512 message length is extended to 128-bit in line with [nist-fips-180-4] where the upper 64 bits get zero-padded: {32'b0, 32'b0, MSG_LENGTH_UPPER, MSG_LENGTH_LOWER}.
- Offset: `0xe8`
Expand Down

0 comments on commit 89a83ed

Please sign in to comment.