// Copyright lowRISC contributors.
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
{ name: "edn",
  clock_primary: "clk_i",
  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: "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: "hro",
      fields: [
        { bits: "0",
          desc: '''
                When true, the BOOT_REQ_DIS and BCAST_MODE_DIS fields within the CTRL registers
                can be modified. 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",
      tags: [ // Exclude from writes to these bits since hardware actions will start.
              "excl:CsrAllTests:CsrExclWrite"]
      fields: [
        { bits: "0",
          name: "EDN_ENABLE",
          desc: '''
                 Setting this bit enables the EDN module.
                 '''
        },
        { bits: "1",
          name: "CMD_FIFO_RST",
          desc: '''
                Setting this bit clears the three command FIFOs: the SW_CMD_REQ FIFO, the
                RESEED_CMD FIFO, and the GENERATE_CMD FIFO. This bit must be cleared by
                software before any further commands can be issued to these FIFOs.
                '''
        }
        { bits: "3:2",
          name: "HW_REQ_MODE",
          resval: 0
          desc: This field determines what hardware-based operational modes the EDN block will operate in.
          enum: [
            { value: 0,
              name: "DISABLED",
              desc: Disables BOOT_REQ_MODE and AUTO_REQ_MODE.
            },
            { value: 1,
              name: "AUTO_REQ_MODE",
              desc: '''
                Setting this bit 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.
                '''
            },
            { value: 2,
              name: "BOOT_REQ_MODE",
              desc: '''
                This decode 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.
                '''
            },
          ]
        },
      ]
    },
    { 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",
      regwen: "REGWEN",
      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",
      regwen: "REGWEN",
      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",
      regwen: "REGWEN",
      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: "ERR_CODE",
      desc: "Hardware detection of 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).
                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",
      regwen: "REGWEN",
      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.
                  '''
        },
      ]
    },
  ]
}