KMAC DV document

Goals

  • DV
    • Verify all KMAC IP features by running dynamic simulations with a SV/UVM based testbench
    • Develop and run all tests based on the testplan below towards closing code and functional coverage on the IP and all of its sub-modules
  • FPV
    • Verify TileLink device protocol compliance with an SVA based testbench

Current status

Design features

For detailed information on KMAC design features, please see the KMAC HWIP technical specification.

Testbench architecture

KMAC testbench has been constructed based on the CIP testbench architecture.

Block diagram

Block diagram

Top level testbench

Top level testbench is located at hw/ip/kmac/dv/tb/tb.sv. It instantiates the KMAC DUT module hw/ip/kmac/rtl/kmac.sv. In addition, it instantiates the following interfaces, connects them to the DUT and sets their handle into uvm_config_db:

Common DV utility components

The following utilities provide generic helper tasks and functions to perform activities that are common across the project:

Compile-time configurations

Two compile-time configurations are tested:

  • kmac_masked - this configuration enables internal secure data masking features
  • kmac_unmasked - this configuration disables all internal security features

A macro define EN_MASKING is defined as a build option in hw/ip/kmac/dv/kmac_base_sim_cfg.hjson, which is used to set the correct compile-time settings.

Global types & methods

All common types and methods defined at the package level can be found in kmac_env_pkg. Some of them in use are:

parameter int KMAC_NUM_SHARES = 2;

parameter int KMAC_NUM_KEYS_PER_SHARE = 16;

parameter bit [TL_AW-1:0] KMAC_FIFO_BASE = 32'h800;
parameter bit [TL_AW-1:0] KMAC_FIFO_END = 32'FFC;

// interrupt types
typedef enum int {
  KmacDone = 0,
  KmacFifoEmpty = 1,
  KmacErr = 2;
  KmacNumIntrs = 3
} kmac_intr_e;

// types of application interfaces
typedef enum int {
  AppKeymgr,
  AppLc,
  AppRom
} kmac_app_e;

typedef virtual pins_if#(1)      idle_vif;
typedef virtual kmac_sideload_if sideload_vif

// Helper function that returns the KMAC key size in bytes
function automatic int get_key_size_bytes(kmac_pkg::key_len_e len);
  case (len)
    Key128: return 16;
    Key192: return 24;
    Key256: return 32;
    Key384: return 48;
    Key512: return 64;
    default: `uvm_fatal("kmac_env_pkg", $sformatf("%0s is an invalid key length", len.name()))
  endcase
endfunction

TL_agent

KMAC testbench instantiates (already handled in CIP base env) tl_agent which provides the ability to drive and independently monitor random traffic via TL host interface into KMAC device.

EDN Agent

The KMAC testbench instantiates a push_pull_agent in Pull mode as the agent modelling the EDN interface (this is already handled in the CIP base classes). This agent will return random data as entropy after a random delay any time the KMAC sends a request.

KMAC_APP Agent

The KMAC testbench instantiates an array of kmac_app_agent to model the application interfaces used by other IP blocks to request a KMAC hash operation on some data. These interfaces are used to send in message data to the KMAC, and to receive an output digest.

UVM RAL Model

The KMAC RAL model is created with the ralgen FuseSoC generator script automatically when the simulation is at the build stage.

It can be created manually by invoking regtool:

Reference models

The KMAC testbench utilizes a C++ reference model for various hashing operations (SHA3, SHAKE, CSHAKE, KMAC) to check the DUT’s digest output for correctness.

Stimulus strategy

Test sequences

All test sequences reside in hw/ip/kmac/dv/env/seq_lib. The kmac_base_vseq virtual sequence is extended from cip_base_vseq and serves as a starting point. All test sequences are extended from kmac_base_vseq. It provides commonly used handles, variables, functions and tasks that the test sequences can simple use / call. Some of the most commonly used tasks / functions are as follows:

  • set_prefix() - This task encodes 2 input strings (function name and customization string) into a bytestream as per NIST standard specifications and writes the data to the PREFIX CSRs
  • write_msg() - This task breaks down the input messages into chunks less than or equal to the TLUL bus size, and writes each chunk to the message FIFO window of the KMAC
  • read_digest_shares() - This task reads the output digest data from the STATE_SHARE windows, manually squeezing (polling for more output data) as necessary

Functional coverage

To ensure high quality constrained random stimulus, it is necessary to develop a functional coverage model. Please refer to the covergroups section under testplan for coverpoints that are implemented.

Self-checking strategy

Scoreboard

The kmac_scoreboard is primarily used for end to end checking. It creates the following analysis ports to retrieve the data monitored by corresponding interface agents:

  • tl_a_chan_fifo: TL address channel
  • tl_d_chan_fifo: TL data channel
  • kmac_app_req_fifo[kmac_pkg::NumAppIntf]: An array of analysis FIFOs to hold request transactions coming from the various application interfaces
  • kmac_app_rsp_fifo[kmac_pkg::NumAppIntf]: An array of analysis FIFOs to hold response transactions coming from the various application interfaces
  • edn_fifo: FIFO used to hold transactions coming from the EDN interface

The KMAC scoreboard implements a cycle-accurate model of the DUT that is used to thoroughly check the operation of the KMAC IP. Though complex to implement, this is extremely useful for CSR prediction as many of the status fields rely on exact timing of the design (e.g. CSR fields that reflect the internal message FIFO pointers need to be predicted in the scoreboard on the exact cycle that they are updated in the design otherwise it will result in prediction mismatches).

The cycle-accurate model is also designed to check the operation of the various application interfaces as well as the EDN interface to provide full confidence in the design’s correctness.

In addition to the cycle-accurate model, the scoreboard tracks the input message as it is written to the message FIFO in chunks, assembles it into a full bytestream, and uses this complete message as input for the DPI-C++ reference model to produce the expected digest value. As the test sequence reads the output STATE_SHARE windows after a hash operation, the scoreboard will assemble the read digest data into the actual digest value, which can easily be compared against the output of the C++ reference model.

Assertions

  • TLUL assertions: The tb/kmac_bind.sv binds the tlul_assert assertions to the IP to ensure TileLink interface protocol compliance.
  • Unknown checks on DUT outputs: The RTL has assertions to ensure all outputs are initialized to known values after coming out of reset.

Building and running tests

We are using our in-house developed regression tool for building and running our tests and regressions. Please take a look at the link for detailed information on the usage, capabilities, features and known issues. Here’s how to run a smoke test:

$ $REPO_TOP/util/dvsim/dvsim.py $REPO_TOP/hw/ip/kmac/dv/kmac_sim_cfg.hjson -i kmac_smoke

Testplan

Testpoints

Stage Name Tests Description
V1 smoke _smoke

KMAC smoke test will contain a number of rounds, and acts as a base for many other tests. In each round, we run a full KMAC hashing operation:

  • Randomly enable interrupts, operation mode (SHA3/SHAKE/CSHAKE/KMAC), key length (if applicable), constraining all settings to be legal.
  • Set function name to "KMAC" and set customization string as empty if applicable.
  • Randomly set endianness of input msg and internal keccak state.
  • Randomly provide a sideloaded key, do not set cfg.sideload.
  • Set output length between 1-keccak_rate bytes if applicable.
  • Randomly select either SW or EDN as the source of entropy
  • Trigger KMAC to start absorbing input message.
    • During absorption stage randomly read from STATE window, expect 0.
  • Write message to MSG_FIFO window, maximum length of 32 bytes.
  • Check SHA3 engine status.
  • Trigger KMAC to finish absorbing stage, check kmac_done is set and status.squeeze is set.
  • Read output digest, and compare against output from reference C++ model.
    • In masked configuration: both shares are XORed to get unmasked result digest.
    • In unmasked configuration: Share1 is the result digest, Share2 should be 0.
  • Signal cmd.done to tell KMAC to clear internal state.
  • Try reading output digest again, confirm that it is 0.

This test, and all other tests in the testplan, will be checked for correctness in two different ways:

  • first, a DPI-C model is used to check that the correct digest value is produced
  • a cycle-accurate model is implemented in the scoreboard to provide constant checks during each hash operation and ensure that internal state is being updated correctly
V1 csr_hw_reset kmac_csr_hw_reset

Verify the reset values as indicated in the RAL specification.

  • Write all CSRs with a random value.
  • Apply reset to the DUT as well as the RAL model.
  • Read each CSR and compare it against the reset value. it is mandatory to replicate this test for each reset that affects all or a subset of the CSRs.
  • It is mandatory to run this test for all available interfaces the CSRs are accessible from.
  • Shuffle the list of CSRs first to remove the effect of ordering.
V1 csr_rw kmac_csr_rw

Verify accessibility of CSRs as indicated in the RAL specification.

  • Loop through each CSR to write it with a random value.
  • Read the CSR back and check for correctness while adhering to its access policies.
  • It is mandatory to run this test for all available interfaces the CSRs are accessible from.
  • Shuffle the list of CSRs first to remove the effect of ordering.
V1 csr_bit_bash kmac_csr_bit_bash

Verify no aliasing within individual bits of a CSR.

  • Walk a 1 through each CSR by flipping 1 bit at a time.
  • Read the CSR back and check for correctness while adhering to its access policies.
  • This verify that writing a specific bit within the CSR did not affect any of the other bits.
  • It is mandatory to run this test for all available interfaces the CSRs are accessible from.
  • Shuffle the list of CSRs first to remove the effect of ordering.
V1 csr_aliasing kmac_csr_aliasing

Verify no aliasing within the CSR address space.

  • Loop through each CSR to write it with a random value
  • Shuffle and read ALL CSRs back.
  • All CSRs except for the one that was written in this iteration should read back the previous value.
  • The CSR that was written in this iteration is checked for correctness while adhering to its access policies.
  • It is mandatory to run this test for all available interfaces the CSRs are accessible from.
  • Shuffle the list of CSRs first to remove the effect of ordering.
V1 csr_mem_rw_with_rand_reset kmac_csr_mem_rw_with_rand_reset

Verify random reset during CSR/memory access.

  • Run csr_rw sequence to randomly access CSRs
  • If memory exists, run mem_partial_access in parallel with csr_rw
  • Randomly issue reset and then use hw_reset sequence to check all CSRs are reset to default value
  • It is mandatory to run this test for all available interfaces the CSRs are accessible from.
V1 regwen_csr_and_corresponding_lockable_csrkmac_csr_rw
kmac_csr_aliasing

Verify regwen CSR and its corresponding lockable CSRs.

  • Randomly access all CSRs
  • Test when regwen CSR is set, its corresponding lockable CSRs become read-only registers

Note:

  • If regwen CSR is HW read-only, this feature can be fully tested by common CSR tests - csr_rw and csr_aliasing.
  • If regwen CSR is HW updated, a separate test should be created to test it.

This is only applicable if the block contains regwen and locakable CSRs.

V1 mem_walk kmac_mem_walk

Verify accessibility of all memories in the design.

  • Run the standard UVM mem walk sequence on all memories in the RAL model.
  • It is mandatory to run this test from all available interfaces the memories are accessible from.
V1 mem_partial_access kmac_mem_partial_access

Verify partial-accessibility of all memories in the design.

  • Do partial reads and writes into the memories and verify the outcome for correctness.
  • Also test outstanding access on memories
V2 long_msg_and_output _long_msg_and_output

Same as the smoke test, except with a message of up to 100KB. Max firmware input size for KMAX is around 392KB, but this is too large for a DV simulation. Average input size from firmware would be around 60-100KB, so we use 100KB as a max input size for DV, but will enable easy extensibility for emulation testing where we can enable much larger messages. Allow output length to vary up to 1KB (for XOF functions). If output length is greater than keccak_rate bytes, keccak rounds will be run manually to squeeze extra output data. Set function name as "KMAC" and enable full randomization of customization string (if applicable).

V2 burst_write _burst_write

This is the same as the long_message test, except we burst-write chunks of the message into the msg_fifo, and disable intermediate status/CSR checks.

V2 test_vectors _test_vectors_sha3_224
_test_vectors_sha3_256
_test_vectors_sha3_384
_test_vectors_sha3_512
_test_vectors_shake_128
_test_vectors_shake_256
_test_vectors_kmac
_test_vectors_kmac_xof

These tests drive NIST test vectors for SHA3/SHAKE/KMAC into the design and check the output against the expected digest values.

V2 sideload _sideload

Same as the smoke test, except we set cfg.sideload and provide a valid sideloaded key as well as a valid SW-provided key. KMAC should operate on the sideloaded key regardless of the cfg_shadowed.sideload field value.

V2 app _app

Test that the Keymgr/ROM/LC can all initiate a KMAC operation through the application interface - Keymgr uses KMAC hash, while ROM/LC use CShake. Use an array of kmac_app_agents to send message data to the KMAC and to control the hashing logic, and set cfg.sideload if the Keymgr is enabled. The result digest sent to the kmac_app_agent will be compared against the result from the DPI reference model. In addition, read from the STATE window afterwards and confirm that this access is blocked and will return 0.

V2 app_with_partial_data _app_with_partial_data

Basd on the kmac_app test, this test will send partial data from application interface by sending strb with values other than 8'hFF. Because the scoreboard is cycle accurate and does not support this feature, this test will not check status and intr_state registers, but will check other registers and all interface data including digest.

V2 entropy_refresh _entropy_refresh

Test entropy interface for KMAC.

This test randomly chooses to execute either a SW-controlled hash or a hash from the App interface. All configuration fields are left as is, but now we will request EDN entropy by setting the following registers with random value:

  • "cmd.entropy_req": Request an EDN entropy
  • "cmd.hash_cnt_clear": Clear the entropy_refresh_hash_cnt
  • "entropy_refresh_threshold_shadowed": The threshold when KMAC should request an EDN entropy

In masked mode, scoreboard will check:

  • Register entropy_refresh_hash_cnt value
  • KMAC requests EDN at the correct time

In unmasked mode, scoreboard will check:

  • Register entropy_refresh_hash_cnt always returns 0
V2 error _error

Try several error sequences:

  • Update key/prefix/config during absorption/process/squeeze stage.
  • Write msg to msg_fifo during process/squeeze stage
  • When in KMAC mode, set the function name to not "KMAC"
  • Incorrect SHA3 control flow:
    • Issue Process/Run/Done cmds before issuing Start
    • Issue Run/Done before issuing Process
    • Issue Start after issuing Process
    • If squeezing data, issue Start/Process after issuing Run
  • Incorrect KMAC configurations (e.g. set KMAC strength as 512).
  • Provide software inputs during operation of the application interface

// TODO: Not all of these errors have been supported yet, and more errors might be // added later. // So this might be split into several error tests later on.

V2 key_error _key_error

Test kmac responses correctly when keymgr app sends request but key is not valid. Stimulus:

  • Configure kmac and send keymgr request, but did not set valid bit for keymgr key input.
  • Wait randomly clock cycles.
  • Issue err_processed, then wait for the keymgr interface handshake to finish.
  • Repeat the above sequence a few times.
  • Issue correct kmac request from app or sw interface.

Check:

  • Check error related registers including err_code, status, and interrupt.
  • Check keymgr interface responses with all zero digests and error bit is set.
  • Check kmac can resume normal functionalities after processing this error case.
V2 edn_timeout_error _edn_timeout_error

Test kmac responses correctly when EDN response timeout. Based on kmac app sequence, this sequence configures kmac to ensure an EDN timeout error by writing entropy_period.wait_timer and entropy_period.prescaler registers. Check:

  • Check error related registers including err_code, status, and interrupt.
  • Check keymgr interface responses with error bit sets to 1.
  • Check kmac can resume normal functionalities after processing this error case.
  • Check timeout error will not trigger if the entropy_mode is set to SW, or masking is disabled.
V2 entropy_mode_error _entropy_mode_error

Test kmac responses correctly when entropy mode is configured incorrectly. Based on kmac edn_timeout sequence, this sequence write incorrect ral.cfg_shadowed.entropy_mode before entropy is fetched. Check:

  • Check error related registers including err_code, status, and interrupt.
  • Check keymgr interface responses with error bit sets to 1.
  • Check kmac can resume normal functionalities after processing this error case.
  • Check timeout error will not trigger if masking is disabled.
V2 entropy_ready_error _entropy_ready_error

Test kmac responses correctly when entropy_ready field is not set. Based on kmac app sequence, this sequence does not write 1 to ral.cfg_shadowed.entropy_ready field before a kmac operation. Check:

  • If masking is enabled and the kmac operation is EDN mode:
    • If it is a SW operation, check error related registers including err_code, status, and interrupt.
    • If it is an APP operation, check keymgr interface responses with error bit sets to 1.
  • If masking is not enabled or the operation does not require entropy:
    • Check no error triggered.
V2 lc_escalation _lc_escalation

Randomly set lc_escalate_en to value that is not Off during Kmac operations.

Checks:

  • Fatal alert fires continuously until reset is issued.
  • Status fields: alert_fatal_fault is set to 1 and sha3_idle is reset to 0.
  • Kmac does not accept any SW or APP requests.
  • Digest window always output all 0s.
V2 stress_all kmac_stress_all
  • Combine above sequences in one test to run sequentially, except csr sequence and some error tests that disabled scoreboard.
  • Randomly add reset between each sequence
V2 intr_test kmac_intr_test

Verify common intr_test CSRs that allows SW to mock-inject interrupts.

  • Enable a random set of interrupts by writing random value(s) to intr_enable CSR(s).
  • Randomly "turn on" interrupts by writing random value(s) to intr_test CSR(s).
  • Read all intr_state CSR(s) back to verify that it reflects the same value as what was written to the corresponding intr_test CSR.
  • Check the cfg.intr_vif pins to verify that only the interrupts that were enabled and turned on are set.
  • Clear a random set of interrupts by writing a randomly value to intr_state CSR(s).
  • Repeat the above steps a bunch of times.
V2 alert_test kmac_alert_test

Verify common alert_test CSR that allows SW to mock-inject alert requests.

  • Enable a random set of alert requests by writing random value to alert_test CSR.
  • Check each alert_tx.alert_p pin to verify that only the requested alerts are triggered.
  • During alert_handshakes, write alert_test CSR again to verify that: If alert_test writes to current ongoing alert handshake, the alert_test request will be ignored. If alert_test writes to current idle alert handshake, a new alert_handshake should be triggered.
  • Wait for the alert handshakes to finish and verify alert_tx.alert_p pins all sets back to 0.
  • Repeat the above steps a bunch of times.
V2 tl_d_oob_addr_access kmac_tl_errors

Access out of bounds address and verify correctness of response / behavior

V2 tl_d_illegal_access kmac_tl_errors

Drive unsupported requests via TL interface and verify correctness of response / behavior. Below error cases are tested bases on the [TLUL spec]({{< relref "hw/ip/tlul/doc/_index.md#explicit-error-cases" >}})

  • TL-UL protocol error cases
    • invalid opcode
    • some mask bits not set when opcode is PutFullData
    • mask does not match the transfer size, e.g. a_address = 0x00, a_size = 0, a_mask = 'b0010
    • mask and address misaligned, e.g. a_address = 0x01, a_mask = 'b0001
    • address and size aren't aligned, e.g. a_address = 0x01, a_size != 0
    • size is greater than 2
  • OpenTitan defined error cases
    • access unmapped address, expect d_error = 1 when devmode_i == 1
    • write a CSR with unaligned address, e.g. a_address[1:0] != 0
    • write a CSR less than its width, e.g. when CSR is 2 bytes wide, only write 1 byte
    • write a memory with a_mask != '1 when it doesn't support partial accesses
    • read a WO (write-only) memory
    • write a RO (read-only) memory
    • write with instr_type = True
V2 tl_d_outstanding_access kmac_csr_hw_reset
kmac_csr_rw
kmac_csr_aliasing
kmac_same_csr_outstanding

Drive back-to-back requests without waiting for response to ensure there is one transaction outstanding within the TL device. Also, verify one outstanding when back- to-back accesses are made to the same address.

V2 tl_d_partial_access kmac_csr_hw_reset
kmac_csr_rw
kmac_csr_aliasing
kmac_same_csr_outstanding

Access CSR with one or more bytes of data. For read, expect to return all word value of the CSR. For write, enabling bytes should cover all CSR valid fields.

V2S shadow_reg_update_error kmac_shadow_reg_errors

Verify shadowed registers' update error.

  • Randomly pick a shadowed register in the DUT.
  • Write it twice with different values.
  • Verify that the update error alert is triggered and the register value remains unchanged.
  • Verify the update_error status register field is set to 1.
  • Repeat the above steps a bunch of times.
V2S shadow_reg_read_clear_staged_value kmac_shadow_reg_errors

Verify reading a shadowed register will clear its staged value.

  • Randomly pick a shadowed register in the DUT.
  • Write it once and read it back to clear the staged value.
  • Then write it twice with the same new value (but different from the previous step).
  • Read it back to verify the new value and ensure that the update error alert did not trigger.
  • Verify the update_error status register field remains the same value.
  • Repeat the above steps a bunch of times.
V2S shadow_reg_storage_error kmac_shadow_reg_errors

Verify shadowed registers' storage error.

  • Randomly pick a shadowed register in the DUT.
  • Backdoor write to shadowed or committed flops to create a storage fatal alert.
  • Check if fatal alert continuously fires until reset.
  • Verify that all other frontdoor write attempts are blocked during the storage error.
  • Verify that storage_error status register field is set to 1.
  • Reset the DUT.
  • Read all CSRs to ensure the DUT is properly reset.
  • Repeat the above steps a bunch of times.
V2S shadowed_reset_glitch kmac_shadow_reg_errors

Verify toggle shadowed_rst_n pin can trigger storage error.

  • Randomly drive shadowed_rst_n pin to low or rst_n pin to low.
  • check if any registers have been written before the reset. If so check if storage error fatal alert is triggered.
  • Check status register.
  • Drive shadowed_rst_n pin or rst_n pin back to high.
  • If fatal alert is triggered, reset the DUT.
  • Read all CSRs to ensure the DUT is properly reset.
  • Repeat the above steps a bunch of times.
V2S shadow_reg_update_error_with_csr_rw kmac_shadow_reg_errors_with_csr_rw

Run shadow_reg_update_error sequence in parallel with csr_rw sequence.

  • Randomly select one of the above sequences.
  • Apply csr_rw sequence in parallel but disable the csr_access_abort to ensure all shadowed registers' write/read to be executed without aborting.
  • Repeat the above steps a bunch of times.
V2S tl_intg_err kmac_tl_intg_err
kmac_sec_cm

Verify that the data integrity check violation generates an alert.

  • Randomly inject errors on the control, data, or the ECC bits during CSR accesses. Verify that triggers the correct fatal alert.
  • Inject a fault at the onehot check in u_reg.u_prim_reg_we_check and verify the corresponding fatal alert occurs
V2S sec_cm_bus_integrity kmac_tl_intg_err

Verify the countermeasure(s) BUS.INTEGRITY.

V2S sec_cm_lc_escalate_en_intersig_mubi _lc_escalation

Verify global LC_ESCALATE_EN mubi

V2S sec_cm_sw_key_key_masking _smoke

Verify the countermeasure(s) SW_KEY.KEY.MASKING.

V2S sec_cm_key_sideload _sideload

Verify the key from KeyMgr is sideloaded.

V2S sec_cm_cfg_shadowed_config_shadow kmac_shadow_reg_errors

Verify the countermeasure(s) CFG_SHADOWED.CONFIG.SHADOW.

V2S sec_cm_fsm_sparse kmac_sec_cm

Verify the countermeasure(s) FSM.SPARSE.

V2S sec_cm_ctr_redun kmac_sec_cm

Verify the countermeasure(s) CTR.REDUN.

V2S sec_cm_packer_ctr_redun kmac_sec_cm

Verify the countermeasure(s) PACKER.CTR.REDUN.

V2S sec_cm_cfg_shadowed_config_regwen _smoke

Verify the countermeasure(s) CFG_SHADOWED.CONFIG.REGWEN.

V2S sec_cm_fsm_global_esc _lc_escalation

Verify the countermeasure(s) FSM.GLOBAL_ESC.

V2S sec_cm_fsm_local_esc kmac_sec_cm

Verify the countermeasure(s) FSM.LOCAL_ESC.

V2S sec_cm_logic_integrity N/A

Verify the countermeasure(s) LOGIC.INTEGRITY.

V2S sec_cm_absorbed_ctrl_mubi _mubi

Verify the countermeasure(s) ABSORBED.CTRL.INTEGRITY

V2S sec_cm_sw_cmd_ctrl_sparse _smoke

Verify the countermeasure(s) SW_CMD.CTRL.INTEGRITY

V3 throughput _throughput

Measure the throughput of the various hashing calculations and make sure they correspond to the expected throughput range for the design.

V3 stress_all_with_rand_reset kmac_stress_all_with_rand_reset

This test runs 3 parallel threads - stress_all, tl_errors and random reset. After reset is asserted, the test will read and check all valid CSR registers.

Covergroups

Name Description
app_cg

Covers several scenarios related to the app interface:

  • A single data beat is sent
  • All partial data lengths have been seen (only applies to the last data beat)
  • Errors are reported through this interface
  • Done signal is sent while keccak rounds are currently active/inactive

Note that this covergroup will be duplicated once per app interface.

app_sw_cfg_cg

Covers several scenarios related to the app interface and cfg_shadowed register value:

  • Hash_mode field value.
  • Kmac_en field value.
  • Kstrength field value.

These sw register settings should not affect kmac app interface calculation. Note that this covergroup will be duplicated once per app interface.

cmd_process_cg

Covers that the KMAC can handle seeing a CmdProcess command during the following sets of scenarios:

  • various msgfifo status (full/empty/in between)
  • while keccak rounds are currently active/inactive
config_cg

Covers that all valid configuration settings for the KMAC have been tested. Individual config settings that will be covered include:

  • hashing mode (sha3/shake/kmac)
  • security strength (128/224/256/384/512)
  • key length (128/192/256/384/512)
  • message endianness enable/disable
  • digest endianness enable/disable
  • XOF mode when using KMAC hashing All valid combinations of the above will also be crossed.
edn_cg

Covers that EDN entropy can be received by KMAC while keccak rounds are active/inactive, crossed with a few entropy configuration values (fast entropy, etc...).

entropy_timer_cg

Cover the values for the entropy_period register's prescaler and wait_timer fields. Cross these field ranges with whether the entropy EDN mode is on or off.

error_cg

Covers all error scenarios:

  • ErrKeyNotValid: covers that secret key is invalid when KeyMgr initiates App operation
  • ErrSwPushedMsgFifo: covers that SW writes the msgfifo while App interface is active
  • ErrSwIssuedCmdInAppActive: covers that SW writes all possible commands to the KMAC while App interface is active
  • ErrWaitTimerExpired: covers that the KMAC timed out while waiting for EDN entropy
  • ErrIncorrectEntropyMode: covers that incorrect entropy modes are detected by the KMAC
  • ErrUnexpectedModeStrength: covers that 128-bit strength is seen for SHA3, and all but 128/256 bit strengths are seen for XOF functions
  • ErrIncorrectFunctionName: covers that the function name is configured incorrectly when KMAC mode is enabled
  • ErrSwCmdSequence: covers that SW issues commands to the KMAC out of order
msg_len_cg

Covers various input message length ranges, to ensure that KMAC can operate successfully on different sized messages. The minimum tested msg length is 0 bytes, and the maximum length is 10_000 bytes, we will cover that an acceptable distribution of lengths has been seen, and specifically cover some corner cases (like length 0).

msgfifo_level_cg

Covers that all possible fifo statuses have been seen when running different hash operations (like sha3/shake/cshake/kmac), such as various fifo depths, fifo full, and fifo empty.

msgfifo_write_mask_cg

Covers that the msgfifo has been written using all possible TLUL masks.

output_digest_len_cg

Similar to the msg_len_cg, we also want to cover various output digest lengths to ensure that KMAC can successfully produce outputs of varying sizes. Note that this only applies to XOF functions, as SHA3 functions have a fixed output length.

prefix_range_cg

The prefix used for CSHAKE and KMAC (function_name + customization_string) are only allowed to be valid alphabet letters, or a space character. This covergroup covers that all of these characters have appeared in a prefix value.

regwen_val_when_new_value_written_cg

Cover each lockable reg field with these 2 cases:

  • When regwen = 1, a different value is written to the lockable CSR field, and a read occurs after that.
  • When regwen = 0, a different value is written to the lockable CSR field, and a read occurs after that.

This is only applicable if the block contains regwen and locakable CSRs.

sha3_status_cg

Covers that all sha3-related status fields have eventually been seen.

shadow_field_errs_cg

Cover all shadow register errors for each register field.

For all register fields within the shadowed register, this coverpoint covers the following errors:

  • Update error
  • Storage error
sideload_cg

Covers that the KMAC sees scenarios where the sideloaded key is provided and should be used (en_sideload==1, app_mode==AppKeymgr), and scenarios where the sideloaded key is provided but should not be used.

state_read_mask_cg

Covers that the state windows have been read using all possible TLUL masks.

tl_errors_cg

Cover the following error cases on TL-UL bus:

  • TL-UL protocol error cases.
  • OpenTitan defined error cases, refer to testpoint tl_d_illegal_access.
tl_intg_err_cg

Cover all kinds of integrity errors (command, data or both) and cover number of error bits on each integrity check.

Cover the kinds of integrity errors with byte enabled write on memory if applicable: Some memories store the integrity values. When there is a subword write, design re-calculate the integrity with full word data and update integrity in the memory. This coverage ensures that memory byte write has been issued and the related design logic has been verfied.