// Copyright lowRISC contributors.
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
{ name: "edn",
  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."}
// TODO: add intrp
//    { name: "edn_ebus_check_failed"
//      desc: "Asserted when the entropy bus integrity check has failed."}
    { 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:   "7",
      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",
    }
  ],

  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 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: "EDN control register",
      swaccess: "rw",
      hwaccess: "hro",
      regwen: "REGWEN",
      fields: [
        { bits: "3:0",
          name: "EDN_ENABLE",
          desc: '''
                Setting this field to 0xA enables the EDN module.
                 '''
          resval: "0x5"
        },
        { bits: "7:4",
          name: "BOOT_REQ_MODE",
          desc: '''
                Setting this field to 0xA 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: "0x5"
        },
        { bits: "11:8",
          name: "AUTO_REQ_MODE",
          desc: '''
                Setting this field to 0xA will enable the EDN block to automatically send another
                request to CSRNG application interface. It is assumed that the command has been
                set up ahead of time, such that when the previous command has returned ack, then
                a new 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.
                 '''
          resval: "0x5"
        },
        { bits: "15:12",
          name: "CMD_FIFO_RST",
          desc: '''
                Setting this field to 0xA  clears the three command FIFOs: the SW_CMD_REQ FIFO, 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: "0x5"
        },
      ]
    },
    { name: "SUM_STS",
      desc: "EDN summary status register",
      swaccess: "rw",
      hwaccess: "hwo",
      tags: [ // EDN internal HW can modify status register
              "excl:CsrAllTests:CsrExclCheck"]
      fields: [
        { bits: "0",
          name: "REQ_MODE_SM_STS",
          desc: '''
                This bit reflects the status of the EDN command state machine. This bit is asserted
                whenever the the state machine is actively managing commands in either auto
                request mode, or boot-time request mode.  After the state machine has
                been suspended, this status bit should be polled to know when the last remaining
                state machine command has been completed, at which point is safe to issue custom
                commands via the software command forwarding interface. A value of zero indicates
                that all commands have completed, and the state machine is idle.
                '''
        }
        { bits: "1",
          name: "BOOT_INST_ACK",
          desc: '''
                This bit indicates that the EDN state machine has started the instantiation
                process. If this bit is asserted it means the state machine has started in
                boot-time request mode and that the CSRNG has confirmed that this
                EDN will be the next application to receive a seed from the entropy_src IP.
                '''
        }
      ]
    },
    { 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 AUTO_REQ_MODE is set, this
                register will have no effect on operation.
                '''
        }
      ]
    },
    { name: "SW_CMD_STS",
      desc: "EDN 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 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 AUTO_REQ_MODE. This command will be sent only after
                the MAX_NUM_REQS_BETWEEN_RESEEDS counter value has reached zero. On overflow this
                FIFO pops the oldest word from the previous command. Updated commands can be inserted
                by pushing 13 command words into the FIFO, pushing the previous command out.
                '''
        }
      ]
    },
    { 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 AUTO_REQ_MODE. This command will be sent only after
                receiving a command ack from the previous command. On overflow this
                FIFO pops the oldest word from the previous command. Updated commands can be inserted
                by pushing 13 command words into the FIFO, pushing the previous command out.
                '''
        }
      ]
    },
    { 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
                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",
      fields: [
        { 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 to this register resets the status bits.
                '''
        }
      ]
    },
    {
      name: "ERR_CODE",
      desc: "Hardware detection of error conditions status register",
      swaccess: "ro",
      hwaccess: "hwo",
      tags: [ // The internal HW can modify the error code registers
              "excl:CsrAllTests:CsrExclCheck"],
      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).
                This bit will stay set until firmware clears it.
                '''
        }
        { 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).
                This bit will stay set until firmware clears it.
                '''
        }
        { 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, and also
                an interrupt if enabled.
                This bit will stay set until firmware clears it.
                '''
        }
        { 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, and also
                an interrupt if enabled.
                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 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 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 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 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 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 firmware clears it.
                '''
        }
      ]
    },
    { name: "ERR_CODE_TEST",
      desc: "Test error conditions register",
      swaccess: "rw",
      hwaccess: "hro",
      hwqe: "true",
      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.
                  '''
        },
      ]
    },
  ]
}