// Copyright lowRISC contributors.
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
{ name:               "csrng",
  human_name:         "Cryptographically Secure Random Number Generator",
  one_line_desc:      "Takes entropy bits to produce cryptographically secure random numbers for consumption by hardware blocks and by software",
  one_paragraph_desc: '''
  Cryptographically Secure Random Number Generator (CSRNG) consumes random seeds from Entropy Source and generates random numbers for separate application interface contexts, such as multiple entropy distribution networks and software.
  When used in fully deterministic mode, the random numbers are generated just based on seeds provided by the application input.
  CSRNG targets compliance with [BSI's AIS31 recommendations for Common Criteria (CC)][bsi-ais31] as well as NIST's [SP 800-90A][nist-sp-800-90a] and [SP 800-90C][nist-sp-800-90c].
  Internally, it uses the CTR_DRBG construction with a security strength of 256 bits as specified by [SP 800-90A][nist-sp-800-90a].

  [bsi-ais31]: https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Zertifizierung/Interpretationen/AIS_31_Functionality_classes_for_random_number_generators_e.pdf
  [nist-sp-800-90a]: https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-90Ar1.pdf
  [nist-sp-800-90c]: https://csrc.nist.gov/CSRC/media/Publications/sp/800-90c/draft/documents/sp800_90c_second_draft.pdf
  '''
  design_spec:        "../doc",
  dv_doc:             "../doc/dv",
  hw_checklist:       "../doc/checklist",
  sw_checklist:       "/sw/device/lib/dif/dif_csrng",
  version:            "1.0",
  life_stage:         "L1",
  design_stage:       "D2S",
  verification_stage: "V2S",
  dif_stage:          "S2",
  clocking: [{clock: "clk_i", reset: "rst_ni"}],
  bus_interfaces: [
    { protocol: "tlul", direction: "device" }
  ],
  param_list: [
    // Random netlist constants
    { name:      "RndCnstCsKeymgrDivNonProduction",
      desc:      "Compile-time random bits for csrng state group diversification value",
      type:      "csrng_pkg::cs_keymgr_div_t",
      randcount: "384",
      randtype:  "data",
    }
    { name:      "RndCnstCsKeymgrDivProduction",
      desc:      "Compile-time random bits for csrng state group diversification value",
      type:      "csrng_pkg::cs_keymgr_div_t",
      randcount: "384",
      randtype:  "data",
    }
    // Regular parameters
    { name: "SBoxImpl",
      type: "aes_pkg::sbox_impl_e",
      default: "aes_pkg::SBoxImplCanright",
      desc: "Selection of the S-Box implementation. See aes_pkg.sv.",
      local: "false",
      expose: "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_fatal_err"
      desc: "Asserted when a FIFO error or a fatal alert occurs. Check the !!ERR_CODE register to get more information."}
  ],
  alert_list: [
    { name: "recov_alert",
      desc: "This alert is triggered when a recoverable alert occurs.  Check the !!RECOV_ALERT_STS register to get more information."
    }
    { name: "fatal_alert",
      desc: '''
            This alert triggers (i) if an illegal state machine state is reached, or
            (ii) if an AES fatal alert condition occurs, or (iii) if a fatal integrity
            failure is detected on the TL-UL bus.
            '''
    }
  ],
  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:  "cs_aes_halt"
      type:    "req_rsp",
      name:    "cs_aes_halt"
      act:     "rsp"
      package: "entropy_src_pkg"
    }
    { struct:  "mubi8"
      type:    "uni"
      name:    "otp_en_csrng_sw_app_read"
      act:     "rcv"
      package: "prim_mubi_pkg"
    }
    { struct:  "lc_tx"
      type:    "uni"
      name:    "lc_hw_debug_en"
      act:     "rcv"
      default: "lc_ctrl_pkg::Off"
      package: "lc_ctrl_pkg"
    }
  ],
  countermeasures: [
    { name: "CONFIG.REGWEN"
      desc: "Registers are protected from writes."
    }
    { name: "CONFIG.MUBI"
      desc: "Registers have multi-bit encoded fields."
    }
    { name: "INTERSIG.MUBI"
      desc: "OTP signal used to enable software access to registers."
    }
    { name: "MAIN_SM.FSM.SPARSE"
      desc: "The CSRNG main state machine uses a sparse state encoding."
    }
    { name: "UPDATE.FSM.SPARSE"
      desc: "The CSRNG update state machine uses a sparse state encoding."
    }
    { name: "BLK_ENC.FSM.SPARSE"
      desc: "The CSRNG block encrypt state machine uses a sparse state encoding."
    }
    { name: "OUTBLK.FSM.SPARSE"
      desc: "The CSRNG block output state machine uses a sparse state encoding."
    }
    { name: "GEN_CMD.CTR.REDUN"
     desc: "The generate command uses a counter that is protected by a second counter that counts in the opposite direction."
    }
    { name: "DRBG_UPD.CTR.REDUN"
     desc: "The ctr_drbg update algorthm uses a counter that is protected by a second counter that counts in the opposite direction."
    }
    { name: "DRBG_GEN.CTR.REDUN"
     desc: "The ctr_drbg generate algorthm uses a counter that is protected by a second counter that counts in the opposite direction."
    }
    { name: "CTRL.MUBI"
      desc: "Multi-bit field used for selection control."
    }
    { name: "MAIN_SM.CTR.LOCAL_ESC"
      desc: "A mismatch detected inside any CSRNG counter moves the  main state machine into a terminal error state."
    }
    { name: "CONSTANTS.LC_GATED"
      desc: "Seed diversification based on the lifecycle state."
    }
    { name: "SW_GENBITS.BUS.CONSISTENCY"
      desc: "Comparison on successive bus values for genbits returned on the software channel."
    }
    { name: "TILE_LINK.BUS.INTEGRITY"
      desc: "Tilelink end-to-end bus integrity scheme."
    }
    { name: "AES_CIPHER.FSM.SPARSE",
      desc: '''
        The AES cipher core FSM uses a sparse state encoding.
        See the AES module documentation for AES-specific countermeasures.
      '''
    }
    { name: "AES_CIPHER.FSM.REDUN",
      desc: '''
        The AES cipher core FSM uses multiple, independent logic rails.
        See the AES module documentation for AES-specific countermeasures.
      '''
    }
    { name: "AES_CIPHER.CTRL.SPARSE",
      desc: '''
        Critical control signals for the AES cipher core such as handshake and MUX control signals use sparse encodings.
        See the AES module documentation for AES-specific countermeasures.
      '''
    }
    { name: "AES_CIPHER.FSM.LOCAL_ESC",
      desc: '''
        The AES cipher core FSM moves to a terminal error state upon local escalation.
        Can be triggered by AES_CIPHER.FSM.SPARSE, AES_CIPHER.FSM.REDUN, AES_CIPHER.CTR.REDUN and AES_CIPHER.CTRL.SPARSE.
        See the AES module documentation for AES-specific countermeasures.
      '''
    }
    { name: "AES_CIPHER.CTR.REDUN",
      desc: '''
        The AES round counter inside the AES cipher core FSM is protected with multiple, independent logic rails.
        See the AES module documentation for AES-specific countermeasures.
      '''
    }
    { name: "AES_CIPHER.DATA_REG.LOCAL_ESC",
      desc: '''
        Upon local escalation, the AES cipher core doesn't output intermediate state.
        See the AES module documentation for AES-specific countermeasures.
      '''
    }
  ],
  regwidth: "32",
  registers: [
    { name: "REGWEN",
      desc: "Register write enable for all control registers",
      swaccess: "rw0c",
      hwaccess: "none",
      fields: [
        {
            bits: "0",
            desc: ''' When true, all writeable registers can be modified.
            When false, they become read-only.
            '''
            resval: 1
        }
      ]
    },
    { name: "CTRL",
      desc: "Control register",
      swaccess: "rw",
      hwaccess: "hro",
      regwen: "REGWEN",
      tags: [// Keep HW from affecting other registers.
                 "excl:CsrAllTests:CsrExclWrite"]
      fields: [
        {
            bits: "3:0",
            name: "ENABLE",
            mubi: true
            desc: '''
                  Setting this field to kMultiBitBool4True will enable the CSRNG module. The modules
                  of the entropy complex may only be enabled and disabled in a specific order, see
                  Programmers Guide for details.
                  '''
          resval: false
        },
        {
            bits: "7:4",
            name: "SW_APP_ENABLE",
            mubi: true
            desc: '''
                  Setting this field to kMultiBitBool4True will enable reading from the !!GENBITS register.
                  This application interface for software (register based) will be enabled
                  only if the otp_en_csrng_sw_app_read input vector is set to the enable encoding.
                  '''
          resval: false
        },
        {
            bits: "11:8",
            name: "READ_INT_STATE",
            mubi: true
            desc: '''
                  Setting this field to kMultiBitBool4True will enable reading from the !!INT_STATE_VAL register.
                  Reading the internal state of the enable instances will be enabled
                  only if the otp_en_csrng_sw_app_read input vector is set to the enable encoding.
                  '''
          resval: false
        },
      ]
    },
    {
      name: "CMD_REQ",
      desc: "Command request register",
      swaccess: "wo",
      hwaccess: "hro",
      hwqe: "true",
      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",
      tags: [// Internal HW can modify status register
                 "excl:CsrNonInitTests:CsrExclCheck"]
      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: "INT_STATE_NUM",
      desc: "Internal state number register",
      swaccess: "rw",
      hwaccess: "hro",
      hwqe: "true",
      fields: [
        {
            bits: "3:0",
            name: "INT_STATE_NUM",
            desc: '''
                  Setting this field will set the number for which internal state can be
                  selected for a read access. Up to 16 internal state values can be chosen
                  from this register. The actual number of valid internal state fields
                  is set by parameter NHwApps plus 1 software app. For those selections that point
                  to reserved locations (greater than NHwApps plus 1), the returned value
                  will be zero. Writing this register will also reset the internal read
                  pointer for the !!INT_STATE_VAL register.
                  Note: This register should be read back after being written to ensure
                  that the !!INT_STATE_VAL read back is accurate.
                  '''
        },
      ]
    },
    {
      name: "INT_STATE_VAL",
      desc: "Internal state read access register",
      swaccess: "ro",
      hwaccess: "hrw",
      hwext: "true",
      hwre: "true",
      fields: [
        { bits: "31:0",
          name: "INT_STATE_VAL",
          desc: '''
                Reading this register will dump out the contents of the selected internal state field.
                Since the internal state field is 448 bits wide, it will require 14 reads from this
                register to gather the entire field. Once 14 reads have been done, the internal read
                pointer (selects 32 bits of the 448 bit field) will reset to zero. The !!INT_STATE_NUM
                can be re-written at this time (internal read pointer is also reset), and then
                another internal state field can be read.
                '''
        }
      ]
    },
    {
      name: "HW_EXC_STS",
      desc: "Hardware instance exception status register",
      swaccess: "rw0c",
      hwaccess: "hwo",
      fields: [
        { bits: "15: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 !!SW_CMD_STS register). Writing a zero to this register
                resets the status bits.
                '''
        }
      ]
    },
    {
      name: "RECOV_ALERT_STS",
      desc: "Recoverable alert status register",
      swaccess: "rw0c",
      hwaccess: "hwo",
      fields: [
        { bits: "0",
          name: "ENABLE_FIELD_ALERT",
          desc: '''
                This bit is set when the ENABLE field in the !!CTRL register is set to
                a value other than kMultiBitBool4True or kMultiBitBool4False.
                Writing a zero resets this status bit.
                '''
        }
        { bits: "1",
          name: "SW_APP_ENABLE_FIELD_ALERT",
          desc: '''
                This bit is set when the SW_APP_ENABLE field in the !!CTRL register is set to
                a value other than kMultiBitBool4True or kMultiBitBool4False.
                Writing a zero resets this status bit.
                '''
        }
        { bits: "2",
          name: "READ_INT_STATE_FIELD_ALERT",
          desc: '''
                This bit is set when the READ_INT_STATE field in the !!CTRL register is set to
                a value other than kMultiBitBool4True or kMultiBitBool4False.
                Writing a zero resets this status bit.
                '''
        }
        { bits: "3",
          name: "ACMD_FLAG0_FIELD_ALERT",
          desc: '''
                This bit is set when the FLAG0 field in the Application Command is set to
                a value other than kMultiBitBool4True or kMultiBitBool4False.
                Writing a zero resets this status bit.
                '''
        }
        { bits: "12",
          name: "CS_BUS_CMP_ALERT",
          desc: '''
                This bit is set when the software application port genbits bus value is equal
                to the prior valid value on the bus, indicating a possible attack.
                Writing a zero resets this status bit.
                '''
        }
        { bits: "13",
          name: "CS_MAIN_SM_ALERT",
          desc: '''
                This bit is set when an unsupported/illegal CSRNG command is being processed.
                The main FSM will hang unless the module enable field is set to the disabled state.
                '''
        }
      ]
    },
    {
      name: "ERR_CODE",
      desc: "Hardware detection of error conditions status register",
      swaccess: "ro",
      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 the next reset.
                '''
        }
        { 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 the next reset.
                '''
        }
        { 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 the next reset.
                '''
        }
        { 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 the next reset.
                '''
        }
        { 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 the next reset.
                '''
        }
        { 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 the next reset.
                '''
        }
        { 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 the next reset.
                '''
        }
        { 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 the next reset.
                '''
        }
        { 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 the next reset.
                '''
        }
        { 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 the next reset.
                '''
        }
        { 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 the next reset.
                '''
        }
        { 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 the next reset.
                '''
        }
        { 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 the next reset.
                '''
        }
        { 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 the next reset.
                '''
        }
        { 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 the next reset.
                '''
        }
        { 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 the next reset.
                '''
        }
        { bits: "20",
          name: "CMD_STAGE_SM_ERR",
          desc: '''
                This bit will be set to one when an illegal state has been detected for the
                command stage state machine. This error will signal a fatal alert, and also
                an interrupt if enabled.
                This bit will stay set until the next reset.
                '''
        }
        { bits: "21",
          name: "MAIN_SM_ERR",
          desc: '''
                This bit will be set to one when an illegal state has been detected for the
                main state machine. This error will signal a fatal alert, and also
                an interrupt if enabled.
                This bit will stay set until the next reset.
                '''
        }
        { bits: "22",
          name: "DRBG_GEN_SM_ERR",
          desc: '''
                This bit will be set to one when an illegal state has been detected for the
                ctr_drbg gen state machine. This error will signal a fatal alert, and also
                an interrupt if enabled.
                This bit will stay set until the next reset.
                '''
        }
        { bits: "23",
          name: "DRBG_UPDBE_SM_ERR",
          desc: '''
                This bit will be set to one when an illegal state has been detected for the
                ctr_drbg update block encode state machine. This error will signal a fatal alert, and also
                an interrupt if enabled.
                This bit will stay set until the next reset.
                '''
        }
        { bits: "24",
          name: "DRBG_UPDOB_SM_ERR",
          desc: '''
                This bit will be set to one when an illegal state has been detected for the
                ctr_drbg update out block state machine. This error will signal a fatal alert, and also
                an interrupt if enabled.
                This bit will stay set until the next reset.
                '''
        }
        { bits: "25",
          name: "AES_CIPHER_SM_ERR",
          desc: '''
                This bit will be set to one when an AES fatal error has been detected.
                This error will signal a fatal alert, and also
                an interrupt if enabled.
                This bit will stay set until the next reset.
                '''
        }
        { bits: "26",
          name: "CMD_GEN_CNT_ERR",
          desc: '''
                This bit will be set to one when a mismatch in any of the hardened counters
                has been detected.
                This error will signal a fatal alert, and also
                an interrupt if enabled.
                This bit will stay set until the next reset.
                '''
        }
        { 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 the next reset.
                '''
        }
        { 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 the next reset.
                '''
        }
        { 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 the next reset.
                '''
        }
      ]
    },
    { name: "ERR_CODE_TEST",
      desc: "Test error conditions register",
      swaccess: "rw",
      hwaccess: "hro",
      hwqe: "true",
      regwen: "REGWEN",
      tags: [// Keep HW from affecting other registers.
                "excl:CsrAllTests:CsrExclWrite"]
      fields: [
        {
            bits: "4:0",
            name: "ERR_CODE_TEST",
            desc: '''
                  Setting this field will set the bit number for which an error
                  will be forced in the hardware. This bit number is that same one
                  found in the !!ERR_CODE register. The action of writing this
                  register will force an error pulse. The sole purpose of this
                  register is to test that any error properly propagates to either
                  an interrupt or an alert.
                  '''
        },
      ]
    },
    { name: "MAIN_SM_STATE",
      desc: "Main state machine state debug register",
      swaccess: "ro",
      hwaccess: "hwo",
      fields: [
        { bits: "7:0",
          name: "MAIN_SM_STATE",
          desc: '''This is the state of the CSRNG main state machine.
                See the RTL file `csrng_main_sm` for the meaning of the values.
                '''
          resval: 0x4e
        }
      ]
    },
  ]
}