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 Name	Type	Description
hmac_done	Event	HMAC-256 completes a message with key
fifo_empty	Event	Message FIFO empty condition
hmac_err	Event	HMAC error occurred. ERR_CODE register shows which error occurred

Security Alerts:

Alert Name	Description
fatal_fault	This fatal alert is triggered when a fatal TL-UL bus integrity fault is detected.

Security Countermeasures:

Countermeasure ID	Description
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

31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16

15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
													hmac_err	fifo_empty	hmac_done

Bits

Type

Reset

Name

Description

rw1c

0x0

hmac_done

HMAC-256 completes a message with key

rw1c

0x0

fifo_empty

Message FIFO empty condition

rw1c

0x0

hmac_err

HMAC error occurred. ERR_CODE register shows which error occurred

hmac.INTR_ENABLE @ 0x4

Interrupt Enable Register

Reset default = 0x0, mask 0x7

31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16

15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
													hmac_err	fifo_empty	hmac_done

Bits Type Reset Name Description

0x0

hmac_done

Enable interrupt when INTR_STATE.hmac_done is set.

0x0

fifo_empty

Enable interrupt when INTR_STATE.fifo_empty is set.

0x0

hmac_err

Enable interrupt when INTR_STATE.hmac_err is set.

hmac.INTR_TEST @ 0x8

Interrupt Test Register

Reset default = 0x0, mask 0x7

31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16

15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
													hmac_err	fifo_empty	hmac_done

Bits Type Reset Name Description

0x0

hmac_done

Write 1 to force INTR_STATE.hmac_done to 1.

0x0

fifo_empty

Write 1 to force INTR_STATE.fifo_empty to 1.

0x0

hmac_err

Write 1 to force INTR_STATE.hmac_err to 1.

hmac.ALERT_TEST @ 0xc

Alert Test Register

Reset default = 0x0, mask 0x1

31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16

15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
															fatal_fault

Bits

Type

Reset

Name

Description

0x0

fatal_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.

31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16

15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
												digest_swap	endian_swap	sha_en	hmac_en

Bits Type Reset Name Description

hmac_en

HMAC datapath enable.

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

sha_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.

0x0

endian_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.

0x0

digest_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

31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16

15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
														hash_process	hash_start

Bits

Type

Reset

Name

Description

r0w1c

hash_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.

r0w1c

hash_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

31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16

15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
							fifo_depth							fifo_full	fifo_empty

Bits

Type

Reset

Name

Description

0x1

fifo_empty

FIFO empty

fifo_full

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

3:2

Reserved

8:4

fifo_depth

FIFO entry count.

hmac.ERR_CODE @ 0x1c

HMAC Error Code

Reset default = 0x0, mask 0xffffffff

31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16
err_code...
15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
...err_code

Bits

Type

Reset

Name

Description

31:0

0x0

err_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.

31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16
secret...
15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
...secret

Bits

Type

Reset

Name

Description

31:0

secret

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.

31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16
key_0...
15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
...key_0

Bits

Type

Reset

Name

Description

31:0

key_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.

31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16
key_1...
15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
...key_1

Bits

Type

Reset

Name

Description

31:0

key_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.

31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16
key_2...
15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
...key_2

Bits

Type

Reset

Name

Description

31:0

key_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.

31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16
key_3...
15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
...key_3

Bits

Type

Reset

Name

Description

31:0

key_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.

31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16
key_4...
15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
...key_4

Bits

Type

Reset

Name

Description

31:0

key_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.

31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16
key_5...
15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
...key_5

Bits

Type

Reset

Name

Description

31:0

key_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.

31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16
key_6...
15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
...key_6

Bits

Type

Reset

Name

Description

31:0

key_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.

31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16
key_7...
15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
...key_7

Bits

Type

Reset

Name

Description

31:0

key_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};

31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16
digest_0...
15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
...digest_0

Bits

Type

Reset

Name

Description

31:0

digest_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};

31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16
digest_1...
15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
...digest_1

Bits

Type

Reset

Name

Description

31:0

digest_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};

31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16
digest_2...
15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
...digest_2

Bits

Type

Reset

Name

Description

31:0

digest_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};

31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16
digest_3...
15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
...digest_3

Bits

Type

Reset

Name

Description

31:0

digest_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};

31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16
digest_4...
15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
...digest_4

Bits

Type

Reset

Name

Description

31:0

digest_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};

31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16
digest_5...
15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
...digest_5

Bits

Type

Reset

Name

Description

31:0

digest_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};

31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16
digest_6...
15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
...digest_6

Bits

Type

Reset

Name

Description

31:0

digest_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};

31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16
digest_7...
15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
...digest_7

Bits

Type

Reset

Name

Description

31:0

digest_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.

31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16
v...
15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
...v

Bits

Type

Reset

Name

Description

31:0

0x0

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

31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16
v...
15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
...v

Bits

Type

Reset

Name

Description

31:0

0x0

Message Length [63:32]

hmac.MSG_FIFO @ + 0x800

512 item wo window

Byte writes are supported

	31	0
+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)

OpenTitan Documentation

Hardware Interfaces and Registers

Interfaces

Registers