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

{ name: "kmac"
  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:    "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:    "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: "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."
    }
  ]
  regwidth: "32"
  registers: [
    { name: "CFG_REGWEN"
      desc: '''Controls the configurability of !!CFG register.

            This register ensures the contents of !!CFG 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

          Software selects the entropy source with this field. In EdnMode,
          the entropy generator sends requests to EDN to get the entropy. The
          received entropy is fed into internal LFSR.

          In SwMode, the software should update the internal LFSR seed
          through !!ENTROPY_SEED_0 etc.

          Out of the reset, the entropy module inside KMAC IP generates LFSR to
          support the ROM_CTRL operation. The logic does not go back to the
          reset state to prevent KMAC from using LFSR with seeds. SW must
          configure correct entropy_mode prior to setting the entropy_ready.
          '''

          enum: [
            { value: "0"
              name: "idle_mode"
              desc: '''At reset state, the entropy mode is Idle mode. It does
              not operate in this mode.
              '''
            }
            { value: "1"
              name: "edn_mode"
              desc: "Entropy generator module fetches entropy from EDN"
            }
            { value: "2"
              name: "sw_mode"
              desc: '''Software update the internal entropy via register
              interface'''
            }
          ]
          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.
          '''
          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: "3:0"
          name: "cmd"
          desc: '''Issue a command to the KMAC/SHA3 IP. To prevent sw from
                writing multiple bits at once, the field is defined as enum.
                '''
          enum: [
            { value: "1"
              name: "start"
              desc: '''If writes 1 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: "2"
              name: "process"
              desc: '''If writes 1 into this field when KMAC/SHA3 began its
                    operation and received the entire message, it computes the
                    digest or signing.
                    '''
            } // e: process
            { value: "4"
              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: "8"
              name: "done"
              desc: '''If writes 1 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: "Message FIFO entry count"
        }
        { bits: "14"
          name: "fifo_empty"
          desc: "Message FIFO Empty indicator"
          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 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"
        regwen: "CFG_REGWEN"
        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
  ]
}