// Copyright lowRISC contributors.
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
{
  name:               "edn",
  human_name:         "Entropy Distribution Network",
  one_line_desc:      "Distributes random numbers produced by CSRNG to hardware blocks",
  one_paragraph_desc: '''
  Entropy Distribution Network (EDN) interfaces various hardware blocks consuming random numbers to CSRNG.
  Besides adapting bus widths, it provides a set of registers for firmware to manage the corresponding CSRNG application interface.
  This allows configuring EDN to automatically send reseed and generate commands to the connected CSRNG context in order to continuously supply consumers with entropy of defined quality.
  Additionally, EDN supports a boot-time request mode, in which it supplies a limited amount of potentially lower-quality entropy with less firmware interaction immediately at boot-time or after reset.
  '''
  design_spec:        "../doc",
  dv_doc:             "../doc/dv",
  hw_checklist:       "../doc/checklist",
  sw_checklist:       "/sw/device/lib/dif/dif_edn",
  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" }
  ],
  interrupt_list: [
    { name: "edn_cmd_req_done"
      desc: "Asserted when a software CSRNG request has completed."}
    { name: "edn_fatal_err"
      desc: "Asserted when a FIFO error occurs."}
  ],
  alert_list: [
    { name: "recov_alert",
      desc: "This alert is triggered when entropy bus data matches on consecutive clock cycles."
    }
    { name: "fatal_alert",
      desc: '''
            This alert triggers (i) if an illegal state machine state is reached, or
            (ii) if a fatal integrity failure is detected on the TL-UL bus.
            ''',
    }
  ],
  inter_signal_list: [
    { struct:  "csrng",  // csrng_req_t, csrng_rsp_t
      type:    "req_rsp",
      name:    "csrng_cmd",
      act:     "req",
      width:   "1",
      package: "csrng_pkg",
      desc:    '''
               EDN supports a signal CSRNG application interface.
               ''',
    }
    { struct:  "edn",  // edn_req_t, edn_rsp_t
      type:    "req_rsp",
      name:    "edn",
      act:     "rsp",
      width:   "8",
      default: "'0",
      desc:    '''
               The collection of peripheral ports supported by edn. The width (4)
               indicates the number of peripheral ports on a single instance.
               Due to limitations in the parametrization of top-level interconnects
               this value is not currently parameterizable.  However, the number
               of peripheral ports may change in a future revision.
               ''',
      package: "edn_pkg",
    }
  ],
  countermeasures: [
    { name: "CONFIG.REGWEN"
      desc: "Registers are protected from writes."
    }
    { name: "CONFIG.MUBI"
      desc: "Registers have multi-bit encoded fields."
    }
    { name: "MAIN_SM.FSM.SPARSE"
      desc: "The EDN main state machine uses a sparse state encoding."
    }
    { name: "ACK_SM.FSM.SPARSE"
      desc: "The EDN ACK state machine uses a sparse state encoding."
    }
    { name: "CTR.REDUN"
      desc: "Counter hardening on the generate command maximum requests counter."
    }
    { name: "MAIN_SM.CTR.LOCAL_ESC"
      desc: "A mismatch detected inside any EDN counter moves the main state machine into a terminal error state."
    }
    { name: "CS_RDATA.BUS.CONSISTENCY"
      desc: "Comparison on successive bus values for genbits returned from csrng that will distribute over the endpoint buses."
    }
    { name: "TILE_LINK.BUS.INTEGRITY"
      desc: "Tilelink end-to-end bus integrity scheme."
    }
  ],

  regwidth: "32",
  registers: [
    { name: "REGWEN",
      desc: "Register write enable for all control registers",
      swaccess: "rw0c",
      hwaccess: "none",
      fields: [
        { bits: "0",
          desc: '''
                When true, the CTRL can be written by software.
                When false, this field read-only. Defaults true, write zero 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: "EDN control register",
      swaccess: "rw",
      hwaccess: "hro",
      regwen: "REGWEN",
      tags: [// Keep HW from affecting other registers.
                "excl:CsrAllTests:CsrExclWrite"]
     fields: [
        { bits: "3:0",
          name: "EDN_ENABLE",
          mubi: true,
          desc: '''
                Setting this field to kMultiBitBool4True enables the EDN 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: "BOOT_REQ_MODE",
          mubi: true,
          desc: '''
                Setting this field to kMultiBitBool4True will enable the feature where the EDN block
                will automatically send a boot-time request to the CSRNG application interface.
                The purpose of this feature is to request entropy as fast as possible after reset,
                and during chip boot-time.
                 '''
          resval: false
        },
        { bits: "11:8",
          name: "AUTO_REQ_MODE",
          mubi: true,
          desc: '''
                Setting this field to kMultiBitBool4True will enable the EDN block to automatically
                send another request to CSRNG application interface. It is assumed that a CSRNG
                instantiate command will be issued using the !!SW_CMD_REQ register interface.
                When this command has an command ack returned from CSRNG, a
                new generate command will be send out again without software intervention. It is
                expected that the generate command will be sent repeatedly so that a continuous
                supply of entropy can be delivered to the endpoints. Reseed commands will be sent
                on a programmable basic between generate commands.
                The !!GENERATE_CMD, !!RESEED_CMD, and !!MAX_NUM_REQS_BETWEEN_RESEEDS registers must
                set up before the !!SW_CMD_REQ register command is issued.
                 '''
          resval: false
        },
        { bits: "15:12",
          name: "CMD_FIFO_RST",
          mubi: true,
          desc: '''
                Setting this field to kMultiBitBool4True clears the two command FIFOs: the
                RESEED_CMD FIFO and the GENERATE_CMD FIFO. This field must be
                set to the reset state by software before any further commands can be issued to
                these FIFOs.
                '''
          resval: false
        },
      ]
    },
    { name: "BOOT_INS_CMD",
      desc: "EDN boot instantiate command register",
      swaccess: "rw",
      hwaccess: "hro",
      tags: [// Keep HW from affecting other registers.
                "excl:CsrAllTests:CsrExclWrite"]
      fields: [
        { bits: "31:0",
          name: "BOOT_INS_CMD",
          desc: '''
                This field is used as the value for Instantiate command at boot time.
                '''
         resval: 0x0000_0901
        }
      ]
    },
    { name: "BOOT_GEN_CMD",
      desc: "EDN boot generate command register",
      swaccess: "rw",
      hwaccess: "hro",
      tags: [// Keep HW from affecting other registers.
                "excl:CsrAllTests:CsrExclWrite"]
      fields: [
        { bits: "31:0",
          name: "BOOT_GEN_CMD",
          desc: '''
                This field is used as the value for generate command at boot time.
                '''
         resval: 0x00ff_f003
       }
      ]
    },
    { name: "SW_CMD_REQ",
      desc: "EDN csrng app command request register",
      swaccess: "wo",
      hwaccess: "hro",
      hwext: "true",
      hwqe: "true",
      fields: [
        { bits: "31:0",
          name: "SW_CMD_REQ",
          desc: '''
                Any CSRNG action can be initiated by writing a CSRNG command to this
                register. The application interface must wait for the "ack" to
                return before issuing new commands. This interface is intended
                to be controlled solely by software.

                If !!CTRL.AUTO_REQ_MODE is set, only the first instantiate command has any
                effect.  After that command has been processed, writes to this register
                register will have no effect on operation.
                Note that CSRNG command format details can be found
                in the CSRNG documentation.
                '''
        }
      ]
    },
    { name: "SW_CMD_STS",
      desc: "EDN 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: "0"
        }
        { 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 CSRNG interface.
                0b0: Request completed successfully
                0b1: Request completed with an error
                '''
          resval: "0"
        }
      ]
    },
    { name: "RESEED_CMD",
      desc: "EDN csrng reseed command register",
      swaccess: "wo",
      hwaccess: "hro",
      hwext: "true",
      hwqe: "true",
      fields: [
        { bits: "31:0",
          name: "RESEED_CMD",
          desc: '''
                Writing this register will fill a FIFO with up to 13 command words (32b words).
                This FIFO will be used to automatically send out a reseed command to the CSRNG
                application interface when in !!CTRL.AUTO_REQ_MODE. This command will be sent only after
                the MAX_NUM_REQS_BETWEEN_RESEEDS counter value has reached zero.

                If more than 13 entires are written to the FIFO, the design will automatically generate
                a fatal alert.

                Note that CSRNG command format details can be found
                in the CSRNG documentation.
                '''
        }
      ]
    },
    { name: "GENERATE_CMD",
      desc: "EDN csrng generate command register",
      swaccess: "wo",
      hwaccess: "hro",
      hwext: "true",
      hwqe: "true",
      fields: [
        { bits: "31:0",
          name: "GENERATE_CMD",
          desc: '''
                Writing this register will fill a FIFO with up to 13 command words (32b words).
                This FIFO will be used to automatically send out a generate command to the CSRNG
                appl interface when in !!CTRL.AUTO_REQ_MODE. This command will be sent only after
                receiving a command ack from the previous command.

                If more than 13 entires are written to the FIFO, the design will automatically generate
                a fatal alert.

                Note that CSRNG command format details can be found
                in the CSRNG documentation.
                '''
        }
      ]
    },
    { name: "MAX_NUM_REQS_BETWEEN_RESEEDS",
      desc: "EDN maximum number of requests between reseeds register",
      swaccess: "rw",
      hwaccess: "hro",
      hwqe: "true",
      fields: [
        { bits: "31:0",
          name: "MAX_NUM_REQS_BETWEEN_RESEEDS",
          desc: '''
                Setting this field will set the number of generate requests that can be made
                to CSRNG before a reseed request is made. This value only has meaning when in
                !!CTRL.AUTO_REQ_MODE. This register supports a maximum of 2^32 requests between reseeds.
                This register will be used by a counter that counts down, triggering an
                automatic reseed when it reaches zero.
                '''
        }
      ]
    },
    {
      name: "RECOV_ALERT_STS",
      desc: "Recoverable alert status register",
      swaccess: "rw0c",
      hwaccess: "hwo",
          tags: [ // The internal HW can modify the error code registers
                 "excl:CsrAllTests:CsrExclCheck"]
      fields: [
        { bits: "0",
          name: "EDN_ENABLE_FIELD_ALERT",
          desc: '''
                This bit is set when the EDN_ENABLE field is set to an illegal value,
                something other than kMultiBitBool4True or kMultiBitBool4False.
                Writing a zero resets this status bit.
                '''
        }
        { bits: "1",
          name: "BOOT_REQ_MODE_FIELD_ALERT",
          desc: '''
                This bit is set when the BOOT_REQ_MODE field is set to an illegal value,
                something other than kMultiBitBool4True or kMultiBitBool4False.
                Writing a zero resets this status bit.
                '''
        }
        { bits: "2",
          name: "AUTO_REQ_MODE_FIELD_ALERT",
          desc: '''
                This bit is set when the !!CTRL.AUTO_REQ_MODE field is set to an illegal value,
                something other than kMultiBitBool4True or kMultiBitBool4False.
                Writing a zero resets this status bit.
                '''
        }
        { bits: "3",
          name: "CMD_FIFO_RST_FIELD_ALERT",
          desc: '''
                This bit is set when the CMD_FIFO_RST field is set to an illegal value,
                something other than kMultiBitBool4True or kMultiBitBool4False.
                Writing a zero resets this status bit.
                '''
        }
        { bits: "12",
          name: "EDN_BUS_CMP_ALERT",
          desc: '''
                This bit is set when the interal entropy bus value is equal to the prior
                valid value on the bus, indicating a possible attack.
                Writing a zero resets this status bit.
                '''
        }
      ]
    },
    {
      name: "ERR_CODE",
      desc: "Hardware detection of fatal error conditions status register",
      swaccess: "ro",
      hwaccess: "hwo",
      fields: [
        { bits: "0",
          name: "SFIFO_RESCMD_ERR",
          desc: '''
                This bit will be set to one when an error has been detected for the
                reseed command FIFO. The type of error is reflected in the type status
                bits (bits 28 through 30 of this register).
                When this bit is set, a fatal error condition will result.
                '''
        }
        { bits: "1",
          name: "SFIFO_GENCMD_ERR",
          desc: '''
                This bit will be set to one when an error has been detected for the
                generate command FIFO. The type of error is reflected in the type status
                bits (bits 28 through 30 of this register).
                When this bit is set, a fatal error condition will result.
                This bit will stay set until the next reset.
                '''
        }
        { bits: "2",
          name: "SFIFO_OUTPUT_ERR",
          desc: '''
                This bit will be set to one when an error has been detected for the
                output FIFO. The type of error is reflected in the type status
                bits (bits 28 through 30 of this register).
                When this bit is set, a fatal error condition will result.
                '''
        }
        { bits: "20",
          name: "EDN_ACK_SM_ERR",
          desc: '''
                This bit will be set to one when an illegal state has been detected for the
                EDN ack stage state machine. This error will signal a fatal alert.
                This bit will stay set until the next reset.
                '''
        }
        { bits: "21",
          name: "EDN_MAIN_SM_ERR",
          desc: '''
                This bit will be set to one when an illegal state has been detected for the
                EDN main stage state machine. This error will signal a fatal alert.
                This bit will stay set until the next reset.
                '''
        }
        { bits: "22",
          name: "EDN_CNTR_ERR",
          desc: '''
                This bit will be set to one when a hardened counter has detected an error
                condition. This error will signal a fatal alert.
                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 1 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 1 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 1 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",
      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: "8:0",
          name: "MAIN_SM_STATE",
          desc: '''This is the state of the EDN main state machine.
                See the RTL file `edn_main_sm` for the meaning of the values.
                '''
          resval: 0x185
        }
      ]
    },
  ]
}