kmac.hjson

// Copyright lowRISC contributors.
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0

{
  name:               "kmac",
  human_name:         "KMAC Accelerator",
  one_line_desc:      "Accelerator for Keccak-based keyed hash message authentication code and SHA-3 hash functions; with SCA and FI countermeasures",
  one_paragraph_desc: '''
  OpenTitan protocols use [Keccak/SHA-3][nist-fips-202]-based cryptographic primitives for data authentication, integrity checking, and key derivation.
  KMAC Accelerator supports Keccak-based Message Authentication Code (KMAC) and the SHA3-derived functions SHAKE and cSHAKE as defined in [NIST SP 800-185][nist-sp-800-185].
  The Keccak core uses first-order domain-oriented masking (DOM) to deter side-channel analysis (SCA).
  To save area, the masking can optionally be disabled using a compile-time Verilog parameter.
  In addition, KMAC Accelerator features several countermeasures to deter fault injection (FI) attacks.

  [nist-fips-202]: https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf
  [nist-sp-800-185]: https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-185.pdf
  '''
  design_spec:        "../doc",
  dv_doc:             "../doc/dv",
  hw_checklist:       "../doc/checklist",
  sw_checklist:       "/sw/device/lib/dif/dif_kmac",
  revisions: [
    {
      version:            "1.0",
      life_stage:         "L1",
      design_stage:       "D2S",
      verification_stage: "V2S",
      dif_stage:          "S2",
      commit_id:          "c2a8c64ccbca39707be7883dfd2f8c1100813730",
    }
  ]
  clocking: [
    {clock: "clk_i", reset: "rst_ni", idle: "idle_o", primary: true},
    {clock: "clk_edn_i", reset: "rst_edn_ni", idle: "idle_o"}
  ]
  bus_interfaces: [
    { protocol: "tlul", direction: "device" }
  ],

  interrupt_list: [
    { name: "kmac_done"
      desc: "KMAC/SHA3 absorbing has been completed"
    }
    { name: "fifo_empty"
      desc: "Message FIFO empty condition"
    }
    { name: "kmac_err"
      desc: "KMAC/SHA3 error occurred. ERR_CODE register shows the details"
    }
  ]
  alert_list: [
    { name: "recov_operation_err"
      desc: '''
        Alert for KMAC operation error. It occurs when the shadow registers have update errors.
        '''
    }
    { name: "fatal_fault_err",
      desc: '''
      This fatal alert is triggered when a fatal error is detected inside the KMAC unit.
      Examples for such faults include:
      i) TL-UL bus integrity fault.
      ii) Storage errors in the shadow registers.
      iii) Errors in the message, round, or key counter.
      iv) Any internal FSM entering an invalid state.
      v) An error in the redundant lfsr.
      The KMAC unit cannot recover from such an error and needs to be reset.
      '''
    }
  ],
  param_list: [
    { name:    "EnMasking"
      type:    "bit"
      default: "1"
      desc:    '''
        Disable(0) or enable(1) first-order masking of Keccak round.
        '''
      local:   "false"
      expose:  "true"
    }
    { name:    "SwKeyMasked"
      type:    "bit"
      default: "0"
      desc:    '''
        Disable(0) or enable(1) software key masking in case masking is disabled (EnMasking == 0).
        If masking is enabled, this parameter has no effect.
        Mainly useful for software interface compatibility between the masked and unmasked design.
        Mostly relevant for SCA measurements.
        '''
      local:   "false"
      expose:  "true"
    }
    { name:    "SecCmdDelay"
      type:    "int"
      default: "0"
      desc: '''
        Command delay, useful for SCA measurements only.
        A value of e.g. 40 allows the processor to go into sleep before KMAC starts operation.
        If a value greater than 0 is chosen, software can pass two commands in series.
        The second command is buffered internally and will be presented to the hardware SecCmdDelay number of cycles after the first one.
        '''
      local:   "false"
      expose:  "true"
    }
    { name:    "SecIdleAcceptSwMsg"
      type:    "bit"
      default: "0"
      desc: '''
        If enabled (1), software writes to the message FIFO before having received a START command are not ignored.
        Disabled (0) by default.
        Useful for SCA measurements only.
        '''
      local:   "false"
      expose:  "true"
    }
    { name:    "NumWordsKey"
      type:    "int"
      default: "16"
      desc:    "Number of words for the secret key"
      local:   "true"
    }
    { name:    "NumWordsPrefix"
      type:    "int"
      default: "11"
      desc:    "Number of words for Encoded NsPrefix."
      local:   "true"
    }
    { name:    "NumEntriesMsgFifo"
      type:    "int"
      default: "10"
      desc:    "Number of entries in the message FIFO. Must match kmac_pkg::MsgFifoDepth."
      local:   "true"
    }
    { name:    "NumBytesMsgFifoEntry"
      type:    "int"
      default: "8"
      desc:    "Number of bytes in a single entry of the message FIFO. Must match kmac_pkg::MsgWidth."
      local:   "true"
    }
    { name:    "HashCntW"
      type:    "int unsigned"
      default: "10"
      desc:    "Width of the hash counter in the entropy"
      local:   "true"
    }
    { name:    "NumSeedsEntropyLfsr",
      type:    "int",
      default: "5",
      desc:    "Number of words for the LFSR seed used for entropy generation",
      local:   "true"
    }
    { name:      "RndCnstLfsrSeed"
      desc:      "Compile-time random data for LFSR default seed"
      type:      "kmac_pkg::lfsr_seed_t"
      randcount: "800"
      randtype:  "data"
    }
    { name:      "RndCnstLfsrPerm",
      desc:      "Compile-time random permutation for LFSR output",
      type:      "kmac_pkg::lfsr_perm_t"
      randcount: "800",
      randtype:  "perm",
    }
    { name:      "RndCnstLfsrFwdPerm",
      desc:      "Compile-time random permutation for forwarding LFSR state",
      type:      "kmac_pkg::lfsr_fwd_perm_t"
      randcount: "32",
      randtype:  "perm",
    }
    { name:      "RndCnstMsgPerm"
      desc:      "Compile-time random permutation for LFSR Message output"
      type:      "kmac_pkg::msg_perm_t"
      randcount: "64"
      randtype:  "perm"
    }
  ]
  inter_signal_list: [
    { struct:  "hw_key_req"
      type:    "uni"
      name:    "keymgr_key"
      act:     "rcv"
      package: "keymgr_pkg"
    }
    { struct:  "app"
      type:    "req_rsp"
      name:    "app"
      act:     "rsp"
      package: "kmac_pkg"
      width:   "3"
    }
    { struct:  "edn"
      type:    "req_rsp"
      name:    "entropy"
      act:     "req"
      width:   "1"
      package: "edn_pkg"
    }
    { name:    "idle",
      type:    "uni",
      act:     "req",
      package: "prim_mubi_pkg",
      struct:  "mubi4",
      width:   "1"
    }
    { struct:  "logic"
      type:    "uni"
      name:    "en_masking"
      act:     "req"
    }
    { struct:  "lc_tx"
      type:    "uni"
      name:    "lc_escalate_en"
      act:     "rcv"
      default: "lc_ctrl_pkg::Off"
      package: "lc_ctrl_pkg"
    }
  ]
  countermeasures: [
    { name: "BUS.INTEGRITY",
      desc: "End-to-end bus integrity scheme."
    }
    { name: "LC_ESCALATE_EN.INTERSIG.MUBI"
      desc: "The global escalation input signal from the life cycle is multibit encoded"
    }
    { name: "SW_KEY.KEY.MASKING"
      desc: '''Data storage and secret key are two share to guard against 1st
        order attack.'''
    }
    { name: "KEY.SIDELOAD"
      desc: "Key from KeyMgr is sideloaded."
    }
    { name: "CFG_SHADOWED.CONFIG.SHADOW"
      desc: "Shadowed CFG register."
    }
    { name: "FSM.SPARSE"
      desc: "FSMs in KMAC are sparsely encoded."
    }
    { name: "CTR.REDUN"
      desc: '''Round counter, key index counter, sentmsg counter and hash counter
        use prim_count for redundancy'''
    }
    { name: "PACKER.CTR.REDUN"
      desc: "Packer Position counter uses prim_count for redundancy"
    }
    { name: "CFG_SHADOWED.CONFIG.REGWEN"
      desc: "CFG_SHADOWED is protected by REGWEN"
    }
    { name: "FSM.GLOBAL_ESC"
      desc: "Escalation moves all sparse FSMs into an invalid state."
    }
    { name: "FSM.LOCAL_ESC"
      desc: "Local fatal faults move all sparse FSMs into an invalid state."
    }
    { name: "LOGIC.INTEGRITY"
      desc: "The reset net for the internal state register and critical nets around the output register are buried."
    }
    { name: "ABSORBED.CTRL.MUBI"
      desc: "`absorbed` signal is mubi4_t type to protect against FI attacks."
    }
    { name: "SW_CMD.CTRL.SPARSE"
      desc: "`sw_cmd` and related signals are sparse encoded to protect against FI attacks."
    }
  ]
  regwidth: "32"
  registers: [
    { name: "CFG_REGWEN"
      desc: '''Controls the configurability of !!CFG_SHADOWED register.

            This register ensures the contents of !!CFG_SHADOWED register cannot be
            changed by the software while the KMAC/SHA3 is in operation mode.
            '''
      swaccess: "ro"
      hwaccess: "hwo"
      hwext: "true"
      fields: [
        { bits: "0"
          name: "en"
          desc: "Configuration enable."
          resval: "1"
        } // f : en
      ]
      tags: [// This regwen is completely under HW management and thus cannot be manipulated
             // by software.
             "excl:CsrNonInitTests:CsrExclCheck"]
    } // R : CFG_REGWEN
    { name: "CFG_SHADOWED"
      desc: '''KMAC Configuration register.

            This register is  updated when the hashing engine is in Idle.
            If the software updates the register while the engine computes, the
            updated value will be discarded.
            '''
      regwen:   "CFG_REGWEN"
      swaccess: "rw"
      hwaccess: "hro"
      shadowed: "true"
      hwqe:     "true"
      update_err_alert:  "recov_operation_err"
      storage_err_alert: "fatal_fault_err"
      fields: [
        { bits: "0"
          name: "kmac_en"
          desc: '''KMAC datapath enable.

                If this bit is 1, the incoming message is processed in KMAC
                with the secret key.
                '''
          tags: [// don't enable kmac and sha data paths - we will do that in functional tests
                 "excl:CsrNonInitTests:CsrExclWrite",
                 "shadowed_reg_path:u_cfg_reg_shadowed.u_cfg_reg_shadowed_kmac_en"
                 ]
        } // f: kmac_en
        { bits: "3:1"
          name: "kstrength"
          desc: '''Hashing Strength

                3 bit field to select the security strength of SHA3 hashing
                engine. If mode field is set to SHAKE or cSHAKE, only 128 and
                256 strength can be selected. Other value will result error
                when hashing starts.
                '''
          enum: [
            { value: "0"
              name:  "L128"
              desc: "128 bit strength. Keccak rate is 1344 bit"
            }
            { value: "1"
              name:  "L224"
              desc: "224 bit strength. Keccak rate is 1152 bit"
            }
            { value: "2"
              name:  "L256"
              desc: "256 bit strength. Keccak rate is 1088 bit"
            }
            { value: "3"
              name:  "L384"
              desc: "384 bit strength. Keccak rate is 832 bit"
            }
            { value: "4"
              name:  "L512"
              desc: "512 bit strength. Keccak rate is 576 bit"
            }
          ]
          tags: ["shadowed_reg_path:u_cfg_reg_shadowed.u_cfg_reg_shadowed_kstrength"]
        } // f: strength
        { bits: "5:4"
          name: "mode"
          desc: '''Keccak hashing mode.

                This module supports SHA3 main hashing algorithm and the part
                of its derived functions, SHAKE and cSHAKE with limitations.
                This field is to select the mode.
                '''
          enum: [
            { value: "0"
              name: "SHA3"
              desc: "SHA3 hashing mode. It appends `2'b 10` to the end of msg"
            }
            { value: "2"
              name: "SHAKE"
              desc: "SHAKE hashing mode. It appends `1111` to the end of msg"
            }
            { value: "3"
              name: "cSHAKE"
              desc: "cSHAKE hashing mode. It appends `00` to the end of msg"
            }
          ]
          tags: ["shadowed_reg_path:u_cfg_reg_shadowed.u_cfg_reg_shadowed_mode"]
        } // f: mode
        { bits: "8"
          name: "msg_endianness"
          desc: '''Message Endianness.

                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.
                If 0, each value will be added to the message in little-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.
                '''
          resval: "0"
          tags: ["shadowed_reg_path:u_cfg_reg_shadowed.u_cfg_reg_shadowed_msg_endianness"]
        } // f: msg_endianness
        { bits: "9"
          name: "state_endianness"
          desc: '''State Endianness.

                If 1 then each individual word in the !!STATE output register
                is converted to big-endian byte order.
                The order of the words in relation to one another is not
                changed.
                This setting does not affect how the state is interpreted
                during computation.
                '''
          tags: ["shadowed_reg_path:u_cfg_reg_shadowed.u_cfg_reg_shadowed_state_endianness"]
        } // f: state_endianness
        { bits: "12"
          name: "sideload"
          desc: '''Sideloaded Key.

                If 1, KMAC uses KeyMgr sideloaded key for SW initiated KMAC
                operation. KMAC uses the sideloaded key regardless of this
                configuration when KeyMgr initiates the KMAC operation for
                Key Derivation Function (KDF).
                '''
          tags: ["shadowed_reg_path:u_cfg_reg_shadowed.u_cfg_reg_shadowed_sideload"]
        } // f: sideload
        { bits: "17:16"
          name: entropy_mode
          desc: '''Entropy Mode

          Using this field, software can configure mode of operation of the internal pseudo-random number generator (PRNG).
          For the hardware to actually switch to an entropy mode other than the default idle_mode, software further needs to set the !!CFG_SHADOWED.entropy_ready bit.
          After that point, the hardware cannot be made to return to idle_mode unless the module is reset.
          '''

          enum: [
            { value: "0"
              name: "idle_mode"
              desc: '''Default mode after reset.

              The sole purpose of this mode is to enable ROM_CTRL operation right after coming out of reset.

              The internal PRNG is not reseeded with fresh entropy, nor updated while the core operates.
              It should therefore not be used after this very initial stage.
              Software should setup a different mode and set !!CFG_SHADOWED.entropy_ready as early as possible.

              The module cannot be made to return to idle_mode once any of the other modes have been used.
              '''
            }
            { value: "1"
              name: "edn_mode"
              desc: '''Receive fresh entropy from EDN for reseeding the internal PRNG.

              This entropy mode is to be used for regular operation.

              Once the !!CFG_SHADOWED.entropy_ready bit is set after reset, the module requests fresh entropy from EDN for reseeding the internal PRNG.
              Only after that, the module can start processing commands.
              Depending on !!CFG_SHADOWED, the internal PRNG is then used for (re-)masking inputs (prefix, key, message) and intermediate results of the Keccak core.

              Depending on !!ENTROPY_PERIOD, the module will periodically reseed the internal PRNG with fresh entropy from EDN.
              Using !!CMD.entropy_req software can manually initiate the reseeding.

              '''
            }
            { value: "2"
              name: "sw_mode"
              desc: '''Receive initial entropy from software for reseeding the internal PRNG.

              This entropy mode is a fall-back option to be used if the entropy complex is not available.

              Once the !!CFG_SHADOWED.entropy_ready bit is set after reset, the module will wait for software to write each of the !!ENTROPY_SEED_0 - !!ENTROPY_SEED_4 registers exactly once and in ascending order.
              Only after that, the module can start processing commands.
              Depending on !!CFG_SHADOWED, the internal PRNG is then used for (re-)masking inputs (prefix, key, message) and intermediate results of the Keccak core.

              After this point, the PRNG can no longer be reseeded by software - also after switching back into this mode from edn_mode.
              However, it is possible to switch to edn_mode.
              '''
            }
          ]
          tags: ["shadowed_reg_path:u_cfg_reg_shadowed.u_cfg_reg_shadowed_entropy_mode"]
        } // f: entropy_mode
        { bits: "19"
          name: entropy_fast_process
          desc: '''Entropy Fast process mode.

          If 1, entropy logic uses garbage data while not processing the KMAC
          key block. It will re-use previous entropy value and will not
          expand the entropy when it is consumed. Only it refreshes the
          entropy while processing the secret key block. This process should
          not be used if SCA resistance is required because it may cause side
          channel leakage.
          '''
          tags: ["shadowed_reg_path:u_cfg_reg_shadowed.u_cfg_reg_shadowed_entropy_fast_process"]
        } // f: entropy_fast_process
        { bits: "20"
          name: msg_mask
          desc: '''Message Masking with PRNG.

            If 1, KMAC applies PRNG to the input messages to the Keccak module
            when KMAC mode is on.
            '''
        } // f: msg_mask
        { bits: "24"
          name: entropy_ready
          desc: '''Entropy Ready status.

          Software sets this field to allow the entropy generator in KMAC to
          fetch the entropy and run.
          '''
          tags: [// Randomly write mem will cause this reg updated by design
                 "excl:CsrAllTests:CsrExclWrite",
                 "shadowed_reg_path:u_cfg_reg_shadowed.u_cfg_reg_shadowed_entropy_ready"]
        } // f: entropy_ready
        { bits: "25"
          name: err_processed
          desc: '''When error occurs and one of the state machine stays at
                 Error handling state, SW may process the error based on
                 ERR_CODE, then let FSM back to the reset state
                '''
          tags: ["shadowed_reg_path:u_cfg_reg_shadowed.u_cfg_reg_shadowed_err_processed"]
        } // f: err_processed
        { bits: "26"
          name: en_unsupported_modestrength
          desc: '''Enable Unsupported Mode and Strength configs.

            SW may set this field for KMAC to move forward with unsupported
            Keccak Mode and Strength configurations, such as cSHAKE512.

            If not set, KMAC won't propagate the SW command (CmdStart) to the
            rest of the blocks (AppIntf, KMAC Core, SHA3).
            '''
          tags: [// Randomly write mem will cause this reg updated by design
                 "excl:CsrAllTests:CsrExclWrite",
                 "shadowed_reg_path:u_cfg_reg_shadowed.u_cfg_reg_shadowed_en_unsupported_modestrength"]
        } // f: en_unsupported_modestrength
      ]
      tags: ["shadowed_reg_path:u_cfg_reg_shadowed"]
    } // R: CFG
    { name: "CMD"
      desc: '''KMAC/ SHA3 command register.

            This register is to control the KMAC to start accepting message,
            to process the message, and to manually run additional keccak
            rounds at the end. Only at certain stage, the CMD affects to the
            control logic. It follows the sequence of

            `start` --> `process` --> {`run` if needed --> } `done`
            '''
      swaccess: "r0w1c"
      hwaccess: "hro"
      hwext: "true"
      hwqe:  "true"
      tags: [// design assertion : after start sets, can only wr msg or set process
             // design assertion : process can be set only after start is set
             "excl:CsrAllTests:CsrExclWrite"]
      fields: [
        { bits: "5:0"
          name: "cmd"
          desc: '''Issue a command to the KMAC/SHA3 IP. The command is sparse
                encoded. To prevent sw from writing multiple commands at once,
                the field is defined as enum.
                '''
          enum: [
            { value: "29"
              name: "start"
              desc: '''Writing 6'b011101 or dec 29 into this field when KMAC/SHA3
                    is in idle, KMAC/SHA3 begins its operation.

                    If the mode is cSHAKE, before receiving the message, the
                    hashing logic processes Function name string N and
                    customization input string S first. If KMAC mode is enabled,
                    additionally it processes secret key block.
                    '''
            } // e: start
            { value: "46"
              name: "process"
              desc: '''Writing 6'b101110 or dec 46 into this field when KMAC/SHA3
                    began its operation and received the entire message, it
                    computes the digest or signing.
                    '''
            } // e: process
            { value: "49"
              name: "run"
              desc: '''The `run` field is used in the sponge squeezing stage.
                    It triggers the keccak round logic to run full 24 rounds.
                    This is optional and used when software needs more digest
                    bits than the keccak rate.

                    It only affects when the kmac/sha3 operation is completed.
                    '''
            } // e: run
            { value: "22"
              name: "done"
              desc: '''Writing 6'b010110 or dec 22 into this field when KMAC/SHA3
                    squeezing is completed, KMAC/SHA3 hashing engine clears internal
                    variables and goes back to Idle state for next command.
                    '''
            } // e: done
          ] // enum
        } // f: cmd
        { bits: "8"
          name: "entropy_req"
          desc: '''SW triggered Entropy Request

          If writes 1 to this field
          '''
        } // f: entropy_req
        { bits: "9"
          name: "hash_cnt_clr"
          desc: "If writes 1, it clears the hash (KMAC) counter in the entropy module"
        }
      ]
    } // R: CMD
    { name: "STATUS"
      desc: '''KMAC/SHA3 Status register.'''
      swaccess: "ro"
      hwaccess: "hwo"
      hwext: "true"
      fields: [
        { bits: "0"
          name: "sha3_idle"
          desc: "If 1, SHA3 hashing engine is in idle state."
          resval: "1"
        }
        { bits: "1"
          name: "sha3_absorb"
          desc: "If 1, SHA3 is receiving message stream and processing it"
        }
        { bits: "2"
          name: "sha3_squeeze"
          desc: '''If 1, SHA3 completes sponge absorbing stage.
                In this stage, SW can manually run the hashing engine.
                '''
        }
        { bits: "12:8"
          name: "fifo_depth"
          desc: "Count of occupied entries in the message FIFO."
        }
        { bits: "14"
          name: "fifo_empty"
          desc: '''Message FIFO Empty indicator.

            The FIFO's `Pass` parameter is set to `1'b 1`. So, by default, if
            the SHA engine is ready, the write data to FIFO just passes
            through.

            In this case, `fifo_depth` remains **0**. `fifo_empty`, however,
            lowers the value to **0** for a cycle, then goes back to the empty
            state, **1**.

            See the "Message FIFO" section in the spec for the reason.
            '''
          resval: "1"
        }
        { bits: "15"
          name: "fifo_full"
          desc: "Message FIFO Full indicator"
        }
        { bits: "16",
          name: "ALERT_FATAL_FAULT",
          resval: "0",
          desc: '''
            No fatal fault has occurred inside the KMAC unit (0).
            A fatal fault has occured and the KMAC unit needs to be reset (1),
            Examples for such faults include
            i) TL-UL bus integrity fault
            ii) storage errors in the shadow registers
            iii) errors in the message, round, or key counter
            iv) any internal FSM entering an invalid state
            v) an error in the redundant lfsr
          '''
        }
        { bits: "17",
          name: "ALERT_RECOV_CTRL_UPDATE_ERR",
          resval: "0",
          desc: '''
            An update error has not occurred (0) or has occured (1) in the shadowed Control Register.
            KMAC operation needs to be restarted by re-writing the Control Register.
          '''
        }
      ]
    } // R: STATUS
    { name: "ENTROPY_PERIOD"
      desc: '''Entropy Timer Periods.
      '''
      swaccess: "rw"
      hwaccess: "hro"
      regwen: "CFG_REGWEN"
      fields: [
        { bits: "9:0"
          name: "prescaler"
          desc: '''EDN Wait timer prescaler.

          EDN Wait timer has 16 bit value. The timer value is increased when the timer pulse is generated. Timer pulse is raises when the number of the clock cycles hit this prescaler value.

          The exact period of the timer pulse is unknown as the KMAC input clock may contain jitters.
          '''
        }
        { bits: "31:16"
          name: "wait_timer"
          desc: '''EDN request wait timer.

          The entropy module in KMAC waits up to this field in the timer pulse
          after it sends request to EDN module. If the timer expires, the
          entropy module moves to an error state and notifies to the system.

          If there is a pending EDN request during wait timer update, then this update is delayed until the EDN request is complete.

          If 0, the entropy module waits the EDN response always. If EDN does
          not respond in this configuration, the software shall reset the IP.
          '''
          tags: [// Writing this timer may cause EDN wait timeout, which triggers a SVA error
                 // We will do that in functional tests
                 "excl:CsrNonInitTests:CsrExclWrite"]
        }
      ]
    } // R: ENTROPY_PERIOD
    {
      name: "ENTROPY_REFRESH_HASH_CNT"
      desc: '''Entropy Refresh Counter

      KMAC entropy can be refreshed after the given threshold KMAC operations
      run. If the KMAC hash counter !!ENTROPY_REFRESH_HASH_CNT hits (GTE) the
      configured threshold !!ENTROPY_REFRESH_THRESHOLD_SHADOWED, the entropy
      module in the KMAC IP requests new seed to EDN and reset the KMAC
      hash counter.

      If the threshold is 0, the refresh by the counter does not work. And the
      counter is only reset by the CMD.hash_cnt_clr CSR bit.
      '''
      swaccess: "ro"
      hwaccess: "hwo"
      regwen: "CFG_REGWEN"
      fields: [
        { bits: "HashCntW-1:0"
          name: "hash_cnt"
          desc: "Hash (KMAC) counter"
        }
      ]
    } // R: ENTROPY_REFRESH_HASH_CNT
    {
      name: "ENTROPY_REFRESH_THRESHOLD_SHADOWED"
      desc: '''Entropy Refresh Threshold

      KMAC entropy can be refreshed after the given threshold KMAC operations
      run. If the KMAC hash counter !!ENTROPY_REFRESH_HASH_CNT hits (GTE) the
      configured threshold !!ENTROPY_REFRESH_THRESHOLD_SHADOWED, the entropy
      module in the KMAC IP requests new seed to EDN and reset the KMAC
      hash counter.

      If the threshold is 0, the refresh by the counter does not work. And the
      counter is only reset by the CMD.hash_cnt_clr CSR bit.
      '''
      swaccess: "rw"
      hwaccess: "hro"
      regwen: "CFG_REGWEN"
      shadowed: "true"
      update_err_alert:  "recov_operation_err"
      storage_err_alert: "fatal_fault_err"
      fields: [
        { bits: "HashCntW-1:0"
          name: "threshold"
          desc: "Hash Threshold"
        }
      ]
    } // R: ENTROPY_REFRESH_THRESHOLD_SHADOWED
    { multireg: {
        name: "ENTROPY_SEED"
        desc: '''Entropy Seed

              Entropy seed registers for the integrated entropy generator.

              If !!CFG_SHADOWED.entropy_mode is set to sw_mode, software first needs to set
              !!CFG_SHADOWED.entropy_ready and then write the !!ENTROPY_SEED_0 -
              !!ENTROPY_SEED_4 registers in ascending order. Software writes one 32-bit value
              to every register which is subsequently loaded into the corresponding 32-bit LFSR
              chunk of the entropy generator.

              After writing all !!ENTROPY_SEED_0 registers, the entropy generator will start
              its operation. After this point, writing these registers has no longer any
              effect.
              '''
        count: "NumSeedsEntropyLfsr"
        cname: "KMAC"
        hwext: "true"
        hwqe : "true"
        swaccess: "wo"
        hwaccess: "hro"
        fields: [
          { bits: "31:0"
            name: "seed"
            desc: "32-bit chunk of the entropy generator seed"
          }
        ]
      } // R: ENTROPY_SEED
    } // multireg: ENTROPY_SEED
    { multireg: {
        name: "KEY_SHARE0"
        desc: '''KMAC Secret Key

              KMAC secret key can be up to 512 bit.
              Order of the secret key is:
              key[512:0] = {KEY15, KEY14, ... , KEY0};

              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.

              Current KMAC supports up to 512 bit secret key. It is the sw
              responsibility to keep upper bits of the secret key to 0.
              '''
        count: "NumWordsKey"
        cname: "KMAC"
        hwext: "true"
        hwqe : "true"
        swaccess: "wo"
        hwaccess: "hro"
        regwen:   "CFG_REGWEN"
        fields: [
          { bits: "31:0"
            name: "key"
            desc: "32-bit chunk of up-to 512-bit Secret Key"
          }
        ]
      } // R: KEY_SHARE0
    } // multireg: KEY_SHARE0
    { multireg: {
        name: "KEY_SHARE1"
        desc: '''KMAC Secret Key, 2nd share.

              KMAC secret key can be up to 512 bit.
              Order of the secret key is:
              key[512:0] = {KEY15, KEY14, ... , KEY0};

              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.

              Current KMAC supports up to 512 bit secret key. It is the sw
              responsibility to keep upper bits of the secret key to 0.
              '''
        count: "NumWordsKey"
        cname: "KMAC"
        hwext: "true"
        hwqe : "true"
        swaccess: "wo"
        hwaccess: "hro"
        regwen:   "CFG_REGWEN"
        fields: [
          { bits: "31:0"
            name: "key"
            desc: "32-bit chunk of up-to 512-bit Secret Key"
          }
        ]
      } // R: KEY_SHARE1
    } // multireg: KEY_SHARE1
    { name: "KEY_LEN"
      desc: '''Secret Key length in bit.

            This value is used to make encoded secret key in KMAC.
            KMAC supports certain lengths of the secret key. Currently it
            supports 128b, 192b, 256b, 384b, and 512b secret keys.
            '''
      regwen: "CFG_REGWEN"
      swaccess: "wo"
      hwaccess: "hro"
      hwext: "false"
      fields: [
        { bits: "2:0"
          name: "len"
          desc: "Key length choice"
          enum: [
            { value: "0"
              name:  "Key128"
              desc: "Key length is 128 bit."
            }
            { value: "1"
              name:  "Key192"
              desc: "Key length is 192 bit."
            }
            { value: "2"
              name:  "Key256"
              desc: "Key length is 256 bit."
            }
            { value: "3"
              name:  "Key384"
              desc: "Key length is 384 bit."
            }
            { value: "4"
              name:  "Key512"
              desc: "Key length is 512 bit."
            }
          ]
        } // f : len
      ]
    } // R : KEY_LEN
    { multireg: {
        name: "PREFIX"
        desc: '''cSHAKE Prefix register.

              Prefix including Function Name N and Customization String S.
              The SHA3 assumes this register value is encoded as:
              `encode_string(N) || encode_string(S) || 0`. It means that the
              software can freely decide the length of N or S based on the
              given Prefix register size 320bit. 320bit is determined to have
              32-bit of N and up to 256-bit of S + encode of their length.

              It is SW responsibility to fill the register with encoded value
              that is described at Section 2.3.2 String Encoding in NIST SP
              800-185 specification.

              Order of Prefix is:
              prefix[end:0] := {PREFIX(N-1), ..., PREFIX(1), PREFIX(0) }

              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.
              '''
        count: "NumWordsPrefix"
        cname: "KMAC"
        hwext: "false"
        swaccess: "rw"
        hwaccess: "hro"
        regwen:   "CFG_REGWEN"
        fields: [
          { bits: "31:0"
            name: "prefix"
            desc: "32-bit chunk of Encoded NS Prefix"
          }
        ]
      } // R: PREFIX
    } // multireg: PREFIX
    { name: "ERR_CODE"
      desc: "KMAC/SHA3 Error Code",
      swaccess: "ro",
      hwaccess: "hwo",
      fields: [
        { bits: "31:0",
          name: "err_code",
          desc: '''If error interrupt occurs, this register has information of error cause.
                Please take a look at `hw/ip/kmac/rtl/kmac_pkg.sv:err_code_e enum type.
                '''
          tags: [// Randomly write mem will cause this reg updated by design
                 "excl:CsrNonInitTests:CsrExclWriteCheck"]
        }
      ]
    } // R: ERR_CODE
    { skipto: "0x400"}
    { window: {
        name: "STATE"
        items: "128"  // 512B address space
        swaccess: "ro"
        desc: '''Keccak State (1600 bit) memory.

              The software can get the processed digest by reading this memory
              region. Unlike MSG_FIFO, STATE memory space sees the addr[9:0].
              If Masking feature is enabled, the software reads two shares from
              this memory space.

              0x400 - 0x4C7: State share
              0x500 - 0x5C7: Mask share of the state, 0 if EnMasking = 0
              '''
      }
    } // W: STATE

    { skipto: "0x800"}

    { window: {
        name: "MSG_FIFO"
        items: "512"     // 2kB range
        swaccess: "wo"
        byte-write: "true"
        desc: '''Message FIFO.

              Any write to this window will be appended to the FIFO. Only lower
              2 bits `[1:0]` of the address matter to writes within the window
              in order to handle with sub-word writes.
              '''
      }
    } // W: MSG_FIFO
  ]
}