// Copyright lowRISC contributors.
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
{ name: "csrng",
  clock_primary: "clk_i",
  bus_device: "tlul",
  bus_host: "none",
  param_list: [
    { name: "SBoxImpl",
      type: "aes_pkg::sbox_impl_e",
      default: "aes_pkg::SBoxImplLut",
      desc: "Selection of the S-Box implementation. See aes_pkg.sv.",
      local: "false",
      expose: "true"
    },
    { name: "NHwApps",
      type: "int",
      default: "2",
      desc: "Number of CSRNG hardware applications",
      local: "true"
    }
  ],
  interrupt_list: [
    { name: "cs_cmd_req_done"
      desc: "Asserted when a command request is completed."}
    { name: "cs_entropy_req"
      desc: "Asserted when a request for entropy has been made."}
    { name: "cs_hw_inst_exc"
      desc: "Asserted when a hardware-attached CSRNG instance encounters a command exception"}
    { name: "cs_fifo_err"
      desc: "Asserted when a FIFO error occurs."}
  ],
  inter_signal_list: [
    { struct:  "csrng"
      type:    "req_rsp"
      name:    "csrng_cmd"
      act:     "rsp"
      package: "csrng_pkg"
      width:   "2",
    }
    { struct:  "entropy_src_hw_if"
      type:    "req_rsp",
      name:    "entropy_src_hw_if"
      act:     "req"
      package: "entropy_src_pkg"
    }
    { struct:  "logic"
      type:    "uni"
      name:    "efuse_sw_app_enable"
      act:     "rcv"
      width:   1
      package: ""
    }
    { struct:  "lc_tx"
      type:    "uni"
      name:    "lc_dft_en"
      act:     "rcv"
      default: "lc_ctrl_pkg::Off"
      package: "lc_ctrl_pkg"
    }
  ],
  regwidth: "32",
  registers: [
    { name: "REGEN",
      desc: "Register write enable for all control registers",
      swaccess: "rw1c",
      hwaccess: "hro",
      fields: [
        {
            bits:   "0",
            desc: '''
                  When true, the writeable registers can be modified.
                  When false, they become read-only. Defaults true, write one to clear. Note that this needs to be
                  cleared after initial configuration at boot in order to lock in the listed register settings.
                  '''
            resval: 1
        },
      ]
    },
    { name: "CTRL",
      desc: "Control register",
      swaccess: "rw",
      hwaccess: "hro",
      regwen: "REGEN",
      fields: [
        {
            bits: "0",
            name: "ENABLE",
            desc: '''
                  Setting this bit will enable the CSRNG module. The application interface for software
                  (register based) will be enabled only if the respective efuse input is enabled.
                  '''
            tags: [// Exclude from writes to these bits.
                   "excl:CsrAllTests:CsrExclWrite"]
        },
        {
            bits: "1",
            name: "AES_CIPHER_DISABLE",
            desc: '''
                  Setting this bit will disable the AES cipher core module. If set, then commands will
                  bypass the AES cipher core, but still move through the logical flow of CSRNG.
                  This mode is primarily for debug purposes.
                  '''
        },
        {
            bits: "19:16",
            name: "FIFO_DEPTH_STS_SEL",
            desc: "This field will select which FIFO depth will be read out for diagnostic purposes."
        },
      ]
    },
    {
      name: "SUM_STS",
      desc: "Summary status register",
      swaccess: "ro",
      hwaccess: "hwo",
      fields: [
        { bits: "23:0",
          name: "FIFO_DEPTH_STS",
          desc: "These bits show the current status of the CRSNG FIFO depths."
        }
        { bits: "31",
          name: "DIAG",
          desc: "This this an internal generic diagnostic bit."
        }
      ]
    },
    {
      name: "CMD_REQ",
      desc: "Command request register",
      swaccess: "wo",
      hwaccess: "hro",
      hwqe: "true",
      regwen: "REGEN",
      fields: [
        { bits: "31:0",
          name: "CMD_REQ",
          desc: '''
                Writing this request with defined CSRNG commands will initiate all
                possible CSRNG actions. The application interface must wait for the
                "ack" to return before issuing new commands.
                '''
        }
      ]
    },
    {
      name: "SW_CMD_STS",
      desc: "Application interface command status register",
      swaccess: "ro",
      hwaccess: "hwo",
      fields: [
        { bits: "0",
          name: "CMD_RDY",
          desc: '''This bit indicates when the command interface is ready to accept commands.
                '''
          resval: "1"
        }
        { bits: "1",
          name: "CMD_STS",
          desc: '''
                This one bit field is the status code returned with the application command ack.
                It is updated each time a command ack is asserted on the internal application
                interface for software use.
                0b0: Request completed successfully
                0b1: Request completed with an error
                '''
          resval: "0"
        }
      ]
    },
    {
      name: "GENBITS_VLD",
      desc: "Generate bits returned valid register",
      swaccess: "ro",
      hwaccess: "hwo",
      hwext: "true",
      fields: [
        { bits: "0",
          name: "GENBITS_VLD",
          desc: "This bit is set when genbits are available on this application interface."
        }
        { bits: "1",
          name: "GENBITS_FIPS",
          desc: "This bit is set when genbits are FIPS/CC compliant."
        }
      ]
    },
    {
      name: "GENBITS",
      desc: "Generate bits returned register",
      swaccess: "ro",
      hwaccess: "hrw",
      hwext: "true",
      hwre: "true",
      fields: [
        { bits: "31:0",
          name: "GENBITS",
          desc: '''
                Reading this register will get the generated bits that were requested with
                the generate request. This register must be four times for each request
                number made. For example, a application command generate request with
                a `creq` value of 4 requires this register to be read 16 times to get all
                of the data out of the FIFO path.
                '''
        }
      ]
    },
    {
      name: "HW_EXC_STS",
      desc: "Hardware instance exception status register",
      swaccess: "rw",
      hwaccess: "hwo",
      fields: [
        { bits: "14:0",
          name: "HW_EXC_STS",
          desc: '''
                Reading this register indicates whether one of the CSRNG HW instances has
                encountered an exception.  Each bit corresponds to a particular hardware
                instance, with bit 0 corresponding to instance HW0, bit 1 corresponding
                to instance HW1, and so forth. (To monitor the status of requests made
                to the SW instance, check the CMD_STS register). Writing a zero to this register
                resets the status bits.
                '''
        }
      ]
    },
    {
      name: "ERR_CODE",
      desc: "Hardware detection of error conditions status register",
      swaccess: "rw",
      hwaccess: "hwo",
      fields: [
        { bits: "0",
          name: "SFIFO_CMD_ERR",
          desc: '''
                This bit will be set to one when an error has been detected for the
                command stage command FIFO. The type of error is reflected in the type status
                bits (bits 28 through 30 of this register).
                This bit will stay set until firmware clears it.
                '''
        }
        { bits: "1",
          name: "SFIFO_GENBITS_ERR",
          desc: '''
                This bit will be set to one when an error has been detected for the
                command stage genbits FIFO. The type of error is reflected in the type status
                bits (bits 28 through 30 of this register).
                This bit will stay set until firmware clears it.
                '''
        }
        { bits: "2",
          name: "SFIFO_CMDREQ_ERR",
          desc: '''
                This bit will be set to one when an error has been detected for the
                cmdreq FIFO. The type of error is reflected in the type status
                bits (bits 28 through 30 of this register).
                This bit will stay set until firmware clears it.
                '''
        }
        { bits: "3",
          name: "SFIFO_RCSTAGE_ERR",
          desc: '''
                This bit will be set to one when an error has been detected for the
                rcstage FIFO. The type of error is reflected in the type status
                bits (bits 28 through 30 of this register).
                This bit will stay set until firmware clears it.
                '''
        }
        { bits: "4",
          name: "SFIFO_KEYVRC_ERR",
          desc: '''
                This bit will be set to one when an error has been detected for the
                keyvrc FIFO. The type of error is reflected in the type status
                bits (bits 28 through 30 of this register).
                This bit will stay set until firmware clears it.
                '''
        }
        { bits: "5",
          name: "SFIFO_UPDREQ_ERR",
          desc: '''
                This bit will be set to one when an error has been detected for the
                updreq FIFO. The type of error is reflected in the type status
                bits (bits 28 through 30 of this register).
                This bit will stay set until firmware clears it.
                '''
        }
        { bits: "6",
          name: "SFIFO_BENCREQ_ERR",
          desc: '''
                This bit will be set to one when an error has been detected for the
                bencreq FIFO. The type of error is reflected in the type status
                bits (bits 28 through 30 of this register).
                This bit will stay set until firmware clears it.
                '''
        }
        { bits: "7",
          name: "SFIFO_BENCACK_ERR",
          desc: '''
                This bit will be set to one when an error has been detected for the
                bencack FIFO. The type of error is reflected in the type status
                bits (bits 28 through 30 of this register).
                This bit will stay set until firmware clears it.
                '''
        }
        { bits: "8",
          name: "SFIFO_PDATA_ERR",
          desc: '''
                This bit will be set to one when an error has been detected for the
                pdata FIFO. The type of error is reflected in the type status
                bits (bits 28 through 30 of this register).
                This bit will stay set until firmware clears it.
                '''
        }
        { bits: "9",
          name: "SFIFO_FINAL_ERR",
          desc: '''
                This bit will be set to one when an error has been detected for the
                final FIFO. The type of error is reflected in the type status
                bits (bits 28 through 30 of this register).
                This bit will stay set until firmware clears it.
                '''
        }
        { bits: "10",
          name: "SFIFO_GBENCACK_ERR",
          desc: '''
                This bit will be set to one when an error has been detected for the
                gbencack FIFO. The type of error is reflected in the type status
                bits (bits 28 through 30 of this register).
                This bit will stay set until firmware clears it.
                '''
        }
        { bits: "11",
          name: "SFIFO_GRCSTAGE_ERR",
          desc: '''
                This bit will be set to one when an error has been detected for the
                grcstage FIFO. The type of error is reflected in the type status
                bits (bits 28 through 30 of this register).
                This bit will stay set until firmware clears it.
                '''
        }
        { bits: "12",
          name: "SFIFO_GGENREQ_ERR",
          desc: '''
                This bit will be set to one when an error has been detected for the
                ggenreq FIFO. The type of error is reflected in the type status
                bits (bits 28 through 30 of this register).
                This bit will stay set until firmware clears it.
                '''
        }
        { bits: "13",
          name: "SFIFO_GADSTAGE_ERR",
          desc: '''
                This bit will be set to one when an error has been detected for the
                gadstage FIFO. The type of error is reflected in the type status
                bits (bits 28 through 30 of this register).
                This bit will stay set until firmware clears it.
                '''
        }
        { bits: "14",
          name: "SFIFO_GGENBITS_ERR",
          desc: '''
                This bit will be set to one when an error has been detected for the
                ggenbits FIFO. The type of error is reflected in the type status
                bits (bits 28 through 30 of this register).
                This bit will stay set until firmware clears it.
                '''
        }
        { bits: "15",
          name: "SFIFO_BLKENC_ERR",
          desc: '''
                This bit will be set to one when an error has been detected for the
                blkenc FIFO. The type of error is reflected in the type status
                bits (bits 28 through 30 of this register).
                This bit will stay set until firmware clears it.
                '''
        }
        { bits: "28",
          name: "FIFO_WRITE_ERR",
          desc: '''
                This bit will be set to one when any of the source bits (bits 0 through 15 of this
                this register) are asserted as a result of an error pulse generated from
                any full FIFO that has been recieved a write pulse.
                This bit will stay set until firmware clears it.
                '''
        }
        { bits: "29",
          name: "FIFO_READ_ERR",
          desc: '''
                This bit will be set to one when any of the source bits (bits 0 through 15 of this
                this register) are asserted as a result of an error pulse generated from
                any empty FIFO that has recieved a read pulse.
                This bit will stay set until firmware clears it.
                '''
        }
        { bits: "30",
          name: "FIFO_STATE_ERR",
          desc: '''
                This bit will be set to one when any of the source bits (bits 0 through 15 of this
                this register) are asserted as a result of an error pulse generated from
                any FIFO where both the empty and full status bits are set.
                This bit will stay set until firmware clears it.
                '''
        }
      ]
    },
  ]
}