// 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", primary: true},
    {clock: "clk_edn_i", reset: "rst_edn_ni"}
  ]
  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: "fatal_fault",
      desc: '''
      This fatal alert is triggered when a fatal TL-UL bus integrity fault is detected.
      '''
    }
  ],
  param_list: [
    { name:    "EnMasking"
      type:    "bit"
      default: "1"
      desc:    '''
        Disable(0) or enable(1) first-order masking of Keccak round.

        If masking is enabled, ReuseShare parameter will impact the design.
        '''
      local:   "false"
      expose:  "true"
    }
    { name:    "ReuseShare"
      type:    "int"
      default: "0"
      desc:    '''
        If enabled (1), the internal Keccak round logic will re-use the
        adjacent shares as entropy in Domain-Oriented Masking AND logic.
        It improves the throughput of Keccak, as it only requires small
        amount of entropy rather than 1600 bit per round.

        This feature is not implemented yet.
        '''
      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"
    }
  ]
  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: "",
      struct:  "logic",
      width:   "1"
    }
  ]
  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"
      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"
      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"]
        } // 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"
            }
          ]
        } // 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"
            }
          ]
        } // 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"
        } // 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.
                '''
        } // 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).
                '''
        } // 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_LOWER and !!ENTROPY_SEED_UPPER.
          '''

          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'''
            }
          ]
        } // 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.
          '''
        } // f: entropy_fast_process
        { 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.
          '''
          hwaccess: "hrw"
          tags: [// Randomly write mem will cause this reg updated by design
                 "excl:CsrAllTests:CsrExclWrite"]
        } // 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
                '''
          hwaccess: "hrw"
          tags: [// Randomly write mem will cause this reg updated by design
                 "excl:CsrNonInitTests:CsrExclCheck"]
        } // f: err_processed
      ]
    } // 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"
        }
      ]
    } // 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"
      desc: '''Entropy Refresh Threshold and Counter

      KMAC entropy can be refreshed after the given threshold KMAC operations
      run. If the KMAC hash counter hits (GTE) the configured threshold, 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"
      fields: [
        { bits: "HashCntW-1:0"
          name: "threshold"
          desc: "Hash Threshold"
        }
        { bits: "HashCntW+15:16"
          name: "hash_cnt"
          desc: "Hash (KMAC) counter"
          swaccess: "ro"
          hwaccess: "hwo"
        }
      ]
    } // R: ENTROPY_REFRESH
    { name: "ENTROPY_SEED_LOWER"
      desc: '''Entropy Seed [31:0].

      Everytime when the software writes into this register, LFSR is reseeded
      with the value of {ENTROPY_SEED_UPPER, ENTROPY_SEED_LOWER}.
      '''
      swaccess: "rw"
      hwaccess: "hro"
      hwqe: "true"
      regwen: "CFG_REGWEN"
      fields: [
        { bits: "31:0"
          name: "seed"
          desc: "Seed [31:0]"
        }
      ]
    } // R: ENTROPY_SEED_LOWER
    { name: "ENTROPY_SEED_UPPER"
      desc: '''Entropy Seed [63:32].

      Everytime when the software writes into !!ENTROPY_SEED_LOWER register,
      LFSR is reseeded with the value of {ENTROPY_SEED_UPPER,
      ENTROPY_SEED_LOWER}.
      '''
      swaccess: "rw"
      hwaccess: "hro"
      hwqe: "true"
      regwen: "CFG_REGWEN"
      fields: [
        { bits: "31:0"
          name: "seed"
          desc: "Seed [63:32]"
        }
      ]
    } // R: ENTROPY_SEED_UPPER
    { 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"
        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"
        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"
        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:CsrExclCheck"]
        }
      ]
    } // 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
  ]
}