Hardware Interfaces and Registers

Interfaces

Referring to the Comportable guideline for peripheral device functionality, the module hmac has the following hardware interfaces defined.

Primary Clock: clk_i

Other Clocks: none

Bus Device Interfaces (TL-UL): tl

Bus Host Interfaces (TL-UL): none

Peripheral Pins for Chip IO: none

Inter-Module Signals: Reference

Inter-Module Signals
Port Name Package::Struct Type Act Width Description
idle prim_mubi_pkg::mubi4 uni req 1
tl tlul_pkg::tl req_rsp rsp 1

Interrupts:

Interrupt NameTypeDescription
hmac_doneEvent

HMAC-256 completes a message with key

fifo_emptyEvent

Message FIFO empty condition

hmac_errEvent

HMAC error occurred. ERR_CODE register shows which error occurred

Security Alerts:

Alert NameDescription
fatal_fault

This fatal alert is triggered when a fatal TL-UL bus integrity fault is detected.

Security Countermeasures:

Countermeasure IDDescription
HMAC.BUS.INTEGRITY

End-to-end bus integrity scheme.

Registers

Summary
Name Offset Length Description
hmac.INTR_STATE 0x0 4

Interrupt State Register

hmac.INTR_ENABLE 0x4 4

Interrupt Enable Register

hmac.INTR_TEST 0x8 4

Interrupt Test Register

hmac.ALERT_TEST 0xc 4

Alert Test Register

hmac.CFG 0x10 4

HMAC Configuration register.

hmac.CMD 0x14 4

HMAC command register

hmac.STATUS 0x18 4

HMAC Status register

hmac.ERR_CODE 0x1c 4

HMAC Error Code

hmac.WIPE_SECRET 0x20 4

Randomize internal secret registers.

hmac.KEY_0 0x24 4

HMAC Secret Key

hmac.KEY_1 0x28 4

HMAC Secret Key

hmac.KEY_2 0x2c 4

HMAC Secret Key

hmac.KEY_3 0x30 4

HMAC Secret Key

hmac.KEY_4 0x34 4

HMAC Secret Key

hmac.KEY_5 0x38 4

HMAC Secret Key

hmac.KEY_6 0x3c 4

HMAC Secret Key

hmac.KEY_7 0x40 4

HMAC Secret Key

hmac.DIGEST_0 0x44 4

Digest output. If HMAC is disabled, the register shows result of SHA256

hmac.DIGEST_1 0x48 4

Digest output. If HMAC is disabled, the register shows result of SHA256

hmac.DIGEST_2 0x4c 4

Digest output. If HMAC is disabled, the register shows result of SHA256

hmac.DIGEST_3 0x50 4

Digest output. If HMAC is disabled, the register shows result of SHA256

hmac.DIGEST_4 0x54 4

Digest output. If HMAC is disabled, the register shows result of SHA256

hmac.DIGEST_5 0x58 4

Digest output. If HMAC is disabled, the register shows result of SHA256

hmac.DIGEST_6 0x5c 4

Digest output. If HMAC is disabled, the register shows result of SHA256

hmac.DIGEST_7 0x60 4

Digest output. If HMAC is disabled, the register shows result of SHA256

hmac.MSG_LENGTH_LOWER 0x64 4

Received Message Length calculated by the HMAC in bits [31:0]

hmac.MSG_LENGTH_UPPER 0x68 4

Received Message Length calculated by the HMAC in bits [63:32]

hmac.MSG_FIFO 0x800 2048

Message FIFO. Any write to this window will be appended to the FIFO. Only the lower [1:0] bits of the address matter to writes within the window (for correctly dealing with non 32-bit writes)

hmac.INTR_STATE @ 0x0

Interrupt State Register

Reset default = 0x0, mask 0x7
31302928272625242322212019181716
 
1514131211109876543210
  hmac_err fifo_empty hmac_done
BitsTypeResetNameDescription
0rw1c0x0hmac_done

HMAC-256 completes a message with key

1rw1c0x0fifo_empty

Message FIFO empty condition

2rw1c0x0hmac_err

HMAC error occurred. ERR_CODE register shows which error occurred


hmac.INTR_ENABLE @ 0x4

Interrupt Enable Register

Reset default = 0x0, mask 0x7
31302928272625242322212019181716
 
1514131211109876543210
  hmac_err fifo_empty hmac_done
BitsTypeResetNameDescription
0rw0x0hmac_done

Enable interrupt when INTR_STATE.hmac_done is set.

1rw0x0fifo_empty

Enable interrupt when INTR_STATE.fifo_empty is set.

2rw0x0hmac_err

Enable interrupt when INTR_STATE.hmac_err is set.


hmac.INTR_TEST @ 0x8

Interrupt Test Register

Reset default = 0x0, mask 0x7
31302928272625242322212019181716
 
1514131211109876543210
  hmac_err fifo_empty hmac_done
BitsTypeResetNameDescription
0wo0x0hmac_done

Write 1 to force INTR_STATE.hmac_done to 1.

1wo0x0fifo_empty

Write 1 to force INTR_STATE.fifo_empty to 1.

2wo0x0hmac_err

Write 1 to force INTR_STATE.hmac_err to 1.


hmac.ALERT_TEST @ 0xc

Alert Test Register

Reset default = 0x0, mask 0x1
31302928272625242322212019181716
 
1514131211109876543210
  fatal_fault
BitsTypeResetNameDescription
0wo0x0fatal_fault

Write 1 to trigger one alert event of this kind.


hmac.CFG @ 0x10

HMAC Configuration register.

Reset default = 0x0, mask 0xf

The register is updated when the engine is in Idle. If the software updates the register while the engine computes the hash, the updated value is discarded.

31302928272625242322212019181716
 
1514131211109876543210
  digest_swap endian_swap sha_en hmac_en
BitsTypeResetNameDescription
0rwxhmac_en

HMAC datapath enable.

If this bit is 1, HMAC operates when hash_start toggles.

1rwxsha_en

SHA256 enable. If 0, SHA engine won't initiate compression, this is used to stop operation of the SHA engine until configuration has been done. When the SHA engine is disabled the digest is cleared.

2rw0x0endian_swap

Endian swap.

If 0, each value will be added to the message in little-endian byte order. The value is written to MSG_FIFO same to the SW writes.

If 1, then each individual multi-byte value, regardless of its alignment, written to MSG_FIFO will be added to the message in big-endian byte order.

A message written to MSG_FIFO one byte at a time will not be affected by this setting.

From a hardware perspective byte swaps are performed on a TL-UL word granularity.

3rw0x0digest_swap

Digest register byte swap.

If 1 the value contained in each digest output register is converted to big-endian byte order. This setting does not affect the order of the digest output registers, DIGEST_0 still contains the first 4 bytes of the digest.


hmac.CMD @ 0x14

HMAC command register

Reset default = 0x0, mask 0x3
31302928272625242322212019181716
 
1514131211109876543210
  hash_process hash_start
BitsTypeResetNameDescription
0r0w1cxhash_start

If writes 1 into this field, SHA256 or HMAC begins its operation.

CPU should configure relative information first, such as message_length, secret_key.

1r0w1cxhash_process

If writes 1 into this field, SHA256 or HMAC calculates the digest or signing based on currently received message.


hmac.STATUS @ 0x18

HMAC Status register

Reset default = 0x1, mask 0x1f3
31302928272625242322212019181716
 
1514131211109876543210
  fifo_depth   fifo_full fifo_empty
BitsTypeResetNameDescription
0ro0x1fifo_empty

FIFO empty

1roxfifo_full

FIFO full. Data written to the FIFO whilst it is full will cause back-pressure on the interconnect

3:2Reserved
8:4roxfifo_depth

FIFO entry count.


hmac.ERR_CODE @ 0x1c

HMAC Error Code

Reset default = 0x0, mask 0xffffffff
31302928272625242322212019181716
err_code...
1514131211109876543210
...err_code
BitsTypeResetNameDescription
31:0ro0x0err_code

If error interrupt occurs, this register has information of error cause. Please take a look at `hw/ip/hmac/rtl/hmac_pkg.sv:err_code_e enum type.


hmac.WIPE_SECRET @ 0x20

Randomize internal secret registers.

Reset default = 0x0, mask 0xffffffff

If CPU writes value into the register, the value is used to randomize internal variables such as secret key, internal state machine, or hash value.

31302928272625242322212019181716
secret...
1514131211109876543210
...secret
BitsTypeResetNameDescription
31:0woxsecret

Secret value


hmac.KEY_0 @ 0x24

HMAC Secret Key

Reset default = 0x0, mask 0xffffffff

SHA256 assumes secret key is hashed 256bit key. Order of the secret key is: key[255:0] = {KEY0, KEY1, KEY2, ... , KEY7};

The registers are allowed to be updated when the engine is in Idle state. If the engine computes the hash, it discards any attempts to update the secret keys and report an error.

31302928272625242322212019181716
key_0...
1514131211109876543210
...key_0
BitsTypeResetNameDescription
31:0woxkey_0

32-bit chunk of 256-bit Secret Key


hmac.KEY_1 @ 0x28

HMAC Secret Key

Reset default = 0x0, mask 0xffffffff

SHA256 assumes secret key is hashed 256bit key. Order of the secret key is: key[255:0] = {KEY0, KEY1, KEY2, ... , KEY7};

The registers are allowed to be updated when the engine is in Idle state. If the engine computes the hash, it discards any attempts to update the secret keys and report an error.

31302928272625242322212019181716
key_1...
1514131211109876543210
...key_1
BitsTypeResetNameDescription
31:0woxkey_1

For HMAC1


hmac.KEY_2 @ 0x2c

HMAC Secret Key

Reset default = 0x0, mask 0xffffffff

SHA256 assumes secret key is hashed 256bit key. Order of the secret key is: key[255:0] = {KEY0, KEY1, KEY2, ... , KEY7};

The registers are allowed to be updated when the engine is in Idle state. If the engine computes the hash, it discards any attempts to update the secret keys and report an error.

31302928272625242322212019181716
key_2...
1514131211109876543210
...key_2
BitsTypeResetNameDescription
31:0woxkey_2

For HMAC2


hmac.KEY_3 @ 0x30

HMAC Secret Key

Reset default = 0x0, mask 0xffffffff

SHA256 assumes secret key is hashed 256bit key. Order of the secret key is: key[255:0] = {KEY0, KEY1, KEY2, ... , KEY7};

The registers are allowed to be updated when the engine is in Idle state. If the engine computes the hash, it discards any attempts to update the secret keys and report an error.

31302928272625242322212019181716
key_3...
1514131211109876543210
...key_3
BitsTypeResetNameDescription
31:0woxkey_3

For HMAC3


hmac.KEY_4 @ 0x34

HMAC Secret Key

Reset default = 0x0, mask 0xffffffff

SHA256 assumes secret key is hashed 256bit key. Order of the secret key is: key[255:0] = {KEY0, KEY1, KEY2, ... , KEY7};

The registers are allowed to be updated when the engine is in Idle state. If the engine computes the hash, it discards any attempts to update the secret keys and report an error.

31302928272625242322212019181716
key_4...
1514131211109876543210
...key_4
BitsTypeResetNameDescription
31:0woxkey_4

For HMAC4


hmac.KEY_5 @ 0x38

HMAC Secret Key

Reset default = 0x0, mask 0xffffffff

SHA256 assumes secret key is hashed 256bit key. Order of the secret key is: key[255:0] = {KEY0, KEY1, KEY2, ... , KEY7};

The registers are allowed to be updated when the engine is in Idle state. If the engine computes the hash, it discards any attempts to update the secret keys and report an error.

31302928272625242322212019181716
key_5...
1514131211109876543210
...key_5
BitsTypeResetNameDescription
31:0woxkey_5

For HMAC5


hmac.KEY_6 @ 0x3c

HMAC Secret Key

Reset default = 0x0, mask 0xffffffff

SHA256 assumes secret key is hashed 256bit key. Order of the secret key is: key[255:0] = {KEY0, KEY1, KEY2, ... , KEY7};

The registers are allowed to be updated when the engine is in Idle state. If the engine computes the hash, it discards any attempts to update the secret keys and report an error.

31302928272625242322212019181716
key_6...
1514131211109876543210
...key_6
BitsTypeResetNameDescription
31:0woxkey_6

For HMAC6


hmac.KEY_7 @ 0x40

HMAC Secret Key

Reset default = 0x0, mask 0xffffffff

SHA256 assumes secret key is hashed 256bit key. Order of the secret key is: key[255:0] = {KEY0, KEY1, KEY2, ... , KEY7};

The registers are allowed to be updated when the engine is in Idle state. If the engine computes the hash, it discards any attempts to update the secret keys and report an error.

31302928272625242322212019181716
key_7...
1514131211109876543210
...key_7
BitsTypeResetNameDescription
31:0woxkey_7

For HMAC7


hmac.DIGEST_0 @ 0x44

Digest output. If HMAC is disabled, the register shows result of SHA256

Reset default = 0x0, mask 0xffffffff

Order of the digest is: digest[255:0] = {DIGEST0, DIGEST1, DIGEST2, ... , DIGEST7};

31302928272625242322212019181716
digest_0...
1514131211109876543210
...digest_0
BitsTypeResetNameDescription
31:0roxdigest_0

32-bit chunk of 256-bit Digest


hmac.DIGEST_1 @ 0x48

Digest output. If HMAC is disabled, the register shows result of SHA256

Reset default = 0x0, mask 0xffffffff

Order of the digest is: digest[255:0] = {DIGEST0, DIGEST1, DIGEST2, ... , DIGEST7};

31302928272625242322212019181716
digest_1...
1514131211109876543210
...digest_1
BitsTypeResetNameDescription
31:0roxdigest_1

For HMAC1


hmac.DIGEST_2 @ 0x4c

Digest output. If HMAC is disabled, the register shows result of SHA256

Reset default = 0x0, mask 0xffffffff

Order of the digest is: digest[255:0] = {DIGEST0, DIGEST1, DIGEST2, ... , DIGEST7};

31302928272625242322212019181716
digest_2...
1514131211109876543210
...digest_2
BitsTypeResetNameDescription
31:0roxdigest_2

For HMAC2


hmac.DIGEST_3 @ 0x50

Digest output. If HMAC is disabled, the register shows result of SHA256

Reset default = 0x0, mask 0xffffffff

Order of the digest is: digest[255:0] = {DIGEST0, DIGEST1, DIGEST2, ... , DIGEST7};

31302928272625242322212019181716
digest_3...
1514131211109876543210
...digest_3
BitsTypeResetNameDescription
31:0roxdigest_3

For HMAC3


hmac.DIGEST_4 @ 0x54

Digest output. If HMAC is disabled, the register shows result of SHA256

Reset default = 0x0, mask 0xffffffff

Order of the digest is: digest[255:0] = {DIGEST0, DIGEST1, DIGEST2, ... , DIGEST7};

31302928272625242322212019181716
digest_4...
1514131211109876543210
...digest_4
BitsTypeResetNameDescription
31:0roxdigest_4

For HMAC4


hmac.DIGEST_5 @ 0x58

Digest output. If HMAC is disabled, the register shows result of SHA256

Reset default = 0x0, mask 0xffffffff

Order of the digest is: digest[255:0] = {DIGEST0, DIGEST1, DIGEST2, ... , DIGEST7};

31302928272625242322212019181716
digest_5...
1514131211109876543210
...digest_5
BitsTypeResetNameDescription
31:0roxdigest_5

For HMAC5


hmac.DIGEST_6 @ 0x5c

Digest output. If HMAC is disabled, the register shows result of SHA256

Reset default = 0x0, mask 0xffffffff

Order of the digest is: digest[255:0] = {DIGEST0, DIGEST1, DIGEST2, ... , DIGEST7};

31302928272625242322212019181716
digest_6...
1514131211109876543210
...digest_6
BitsTypeResetNameDescription
31:0roxdigest_6

For HMAC6


hmac.DIGEST_7 @ 0x60

Digest output. If HMAC is disabled, the register shows result of SHA256

Reset default = 0x0, mask 0xffffffff

Order of the digest is: digest[255:0] = {DIGEST0, DIGEST1, DIGEST2, ... , DIGEST7};

31302928272625242322212019181716
digest_7...
1514131211109876543210
...digest_7
BitsTypeResetNameDescription
31:0roxdigest_7

For HMAC7


hmac.MSG_LENGTH_LOWER @ 0x64

Received Message Length calculated by the HMAC in bits [31:0]

Reset default = 0x0, mask 0xffffffff

Message is byte granularity. lower 3bits [2:0] are ignored.

31302928272625242322212019181716
v...
1514131211109876543210
...v
BitsTypeResetNameDescription
31:0ro0x0v

Message Length [31:0]


hmac.MSG_LENGTH_UPPER @ 0x68

Received Message Length calculated by the HMAC in bits [63:32]

Reset default = 0x0, mask 0xffffffff
31302928272625242322212019181716
v...
1514131211109876543210
...v
BitsTypeResetNameDescription
31:0ro0x0v

Message Length [63:32]


hmac.MSG_FIFO @ + 0x800
512 item wo window
Byte writes are supported
310
+0x800 
+0x804 
 ...
+0xff8 
+0xffc 

Message FIFO. Any write to this window will be appended to the FIFO. Only the lower [1:0] bits of the address matter to writes within the window (for correctly dealing with non 32-bit writes)