// Copyright lowRISC contributors.
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
{ name: "usbdev",
  clock_primary: "clk_i",
  other_clock_list: [ "clk_usb_48mhz_i" ]
  reset_primary: "rst_ni",
  other_reset_list: [ "rst_usb_48mhz_ni" ]
  bus_device: "tlul",
  bus_host: "none",
  available_inout_list: [
    { name: "d", desc: "USB data differential" }
    { name: "dp", desc: "USB data D+" }
    { name: "dn", desc: "USB data D-" }
  ],
  available_input_list: [
    {  name: "sense", desc: "USB host VBUS sense" }
  ],
  available_output_list: [
    { name: "se0", desc: "USB single-ended zero link state" }
    { name: "pullup", desc: "USB pullup control" }
    { name: "tx_mode_se", desc: "USB single-ended transmit mode control" }
    { name: "suspend", desc: "USB link suspend state" }
  ],
  param_list: [
    { name:    "NEndpoints",
      type:    "int",
      default: "12",
      desc:    "Number of endpoints",
      local:   "true"
    }
  ],
  interrupt_list: [
    { name: "pkt_received"
      desc: "raised if a packet was received using an OUT or SETUP transaction."}
    { name: "pkt_sent"
      desc: "raised if a packet was sent as part of an IN transaction."}
    { name: "disconnected",
      desc: "Raised if VBUS is lost thus the link is disconnected"}
    { name: "host_lost",
      desc: '''
            Raised if link is active but start of frame not received from
            host for 4.096ms. The SOF should be every 1ms.
            '''
    }
    { name: "link_reset",
      desc: '''
            Raised if the link is at SE0 longer than 3us indicating a link
            reset (host asserts for min 10ms, device can react after 2.5us).
            '''
    }
    { name: "link_suspend",
      desc: '''
            Raised if the line has signalled J for longer than 3ms and is
            therefore in suspend state.
            '''
    }
    { name: "link_resume",
      desc: '''
            Raised when the link becomes active again after being suspended.
            '''
    }
    { name: "av_empty",
      desc: '''
            Raised when a transaction is NACKed because the AVBuffer FIFO
            for OUT or SETUP transactions is empty.
            '''
    }
    { name: "rx_full",
      desc: '''
            Raised when a transaction is NACKed because the Receive FIFO
            for OUT or SETUP transactions is full.
            '''
    }
    { name: "av_overflow",
      desc: '''
            Raised if a write was done to the AVBuffer fifo when the
            FIFO was full.
            '''
    }
    { name: "link_in_err",
      desc: '''
            Raised if a packet to an IN endpoint started to be received but was
            then dropped due to an error. After transmitting the IN payload,
            the USB device expects a valid ACK handshake packet. This error is
            raised if either the packet or CRC is invalid or a different token
            was received.
            '''
    }
    { name: "rx_crc_err",
      desc: '''
            Raised if a CRC error occured.
            '''
    }
    { name: "rx_pid_err",
      desc: '''
            Raised if an invalid PID was received.
            '''
    }
    { name: "rx_bitstuff_err",
      desc: '''
            Raised if an invalid bitstuffing was received.
            '''
    }
    { name: "frame",
      desc: '''
            Raised when the USB frame number is updated with a valid SOF frame.
            '''
    }
    { name: "connected",
      desc: "Raised if VBUS is applied."
    }
  ]
  regwidth: "32",
  registers: [
    { name: "usbctrl",
      desc: "USB Control",
      swaccess: "rw",
      hwaccess: "hro",
      fields: [
        {
          bits: "0",
          name: "enable",
          desc: '''
               Set to enable the USB interface and assert the FS pullup.
          '''
          tags: [// Prevent usb from being enabled to avoid other unforeseen side effects.
                 "excl:CsrNonInitTests:CsrExclWrite"]
        }
        {
          bits: "22:16",
          name: "device_address",
          hwaccess: "hrw",
          desc: '''
                Device address set by host (this should be copied from
                the Set Device ID SETUP packet).

                This will be zeroed by the hardware when the link resets.
          '''
          tags: [// This field is reset to 0 if usb is not enabled.
                 "excl:CsrNonInitTests:CsrExclWriteCheck"]
        }
      ]
    }
    { name: "usbstat",
      desc: "USB Status",
      swaccess: "ro",
      hwaccess: "hwo",
      hwext: "true",
      fields: [
        {
          bits: "10:0",
          name: "frame",
          desc: '''
                Frame index received from host. On an active link this
                will increment every milisecond.
                '''
        }
        {
          bits: "11",
          name: "host_lost",
          desc: '''
                Start of frame not received from host for 4.096ms
                and the line is active.
                '''
        }
        {
          bits: "14:12",
          name: "link_state",
          desc: '''
                State of USB link, decoded from line.
                '''
          enum: [
            { value: "0",
              name: "disconnect",
              desc: "Link disconnected (no VBUS)"
            },
            { value: "1",
              name: "powered",
              desc: "Link powered, but not reset yet"
            },
            { value: "2",
              name: "powered_suspend",
              desc: "Link suspended (constant idle for > 3ms), but not reset yet"
            },
            { value: "3",
              name: "active",
              desc: "Link active"
            },
            { value: "4",
              name: "suspend",
              desc: "Link suspended (constant idle for > 3ms)"
            },

          ]
        }
        {
          bits: "15",
          name: "sense",
          desc: '''
                Refelects the state of the sense pin. 1 indicates that
                the host is providing VBUS.
                '''
        }
        {
          bits: "18:16",
          name: "av_depth",
          desc: '''
                Number of buffers in the Available-Buffer FIFO.

                These buffers are available for receiving packets.
                '''
        }
        {
          bits: "23",
          name: "av_full",
          desc: "Available buffers FIFO is full"
        }
        {
          bits: "26:24",
          name: "rx_depth",
          desc: '''
                Number of buffers in the Receive FIFO.

                These buffers have packets that have been received and
                should be popped from the FIFO and processed.
                '''
        }
        {
          bits: "31",
          name: "rx_empty",
          resval: "1",
          desc: "Receive FIFO is empty"
        }
      ]
    }
    { name: "avbuffer",
      desc: "Available Buffer FIFO",
      swaccess: "wo",
      hwaccess: "hro",
      hwqe: "true",
      fields: [
        {
          bits: "4:0",
          name: "buffer",
          desc: '''
                This field contains the buffer number being passed to the
                USB receive engine.

                If the FIFO is full then the write is discarded.
                '''
        }
      ]
      tags: [// Writing this CSR affects the ral.usbstat.av_depth field.
             "excl:CsrNonInitTests:CsrExclWrite"]
    }
    { name: "rxfifo",
      desc: "Received packet FIFO",
      swaccess: "ro",
      hwaccess: "hrw",
      hwext: "true",
      hwre: "true",
      fields: [
        {
          bits: "4:0",
          name: "buffer",
          desc: '''
                This field contains the buffer number that data was received
                into. On read the buffer is popped from the FIFO and returned
                to software.
                '''
        }
        {
          bits: "14:8",
          name: "size",
          desc: '''
                This field contains the size in bytes of the packet written
                to the buffer.
                '''
        }
        {
          bits: "19",
          name: "setup",
          desc: '''
                This field indicates the type of transaction received. It is
                set for a SETUP transaction and clear for an OUT transaction.
                '''
        }
        {
          bits: "23:20",
          name: "ep",
          desc: '''
                This field contains the Endpoint to which the packet was
                directed.
                '''
        }
      ]
    }
    { multireg: {
        name: "rxenable_setup",
        count: "NEndpoints"
        cname: "Endpoint"
        desc: "Receive SETUP transaction enable",
        swaccess: "rw",
        hwaccess: "hro",
        fields: [
          {
            bits: "0",
            name: "setup",
            desc: '''
                  This bit must be set to enable SETUP transactions to be
                  received on the endpoint. If the bit is clear then a
                  SETUP request will be responded to with a NACK.
                  '''
          }
        ]
      }
    }
    { multireg: {
        name: "rxenable_out",
        count: "NEndpoints"
        cname: "Endpoint"
        desc: "Receive OUT transaction enable",
        swaccess: "rw",
        hwaccess: "hro",
        fields: [
          {
            bits: "0",
            name: "out",
            desc: '''
                  This bit must be set to enable OUT transactions to be
                  received on the endpoint. If the bit is clear then an
                  OUT request will be responded to with a NACK.
                  '''
          }
        ]
      }
    }
    { multireg: {
        name: "in_sent",
        count: "NEndpoints"
        cname: "Endpoint"
        desc: "IN Transaction Sent",
        swaccess: "rw1c",
        hwaccess: "hwo",
        fields: [
          {
            bits: "0",
            name: "sent",
            desc: '''
                  This bit will be set when the ACK is received from
                  the host to indicate successful packet delivery
                  as part of an IN transaction.
                  '''
          }
        ]
      }
    }
    { multireg: {
        name: "stall",
        count: "NEndpoints"
        cname: "Endpoint"
        desc: "Endpoint STALL control",
        swaccess: "rw",
        hwaccess: "hrw",
        fields: [
          {
                bits: "0",
                name: "stall",
                desc: '''
                      If this bit is set then an IN or OUT
                      transaction to this endpoint will be responded to
                      with a STALL return. This is used when the endpoint
                      is disabled (functional stall) or when a control transfer
                      is not supported (protocol stall). SETUP transactions
                      are always accepted and a SETUP will clear the stall
                      flag (this is necessary for protocol stalls, to avoid
                      sending stalls on subsequent IN/OUT transfers).
                      '''
          }
        ]
      }
    }
    { multireg: {
        name: "configin",
        count: "NEndpoints"
        cname: "Endpoint"
        desc: "Configure IN Transaction",
        swaccess: "rw",
        hwaccess: "hro",
        fields: [
          {
            bits: "4:0",
            name: "buffer",
            desc: '''
                  The buffer number containing the data to send when
                  an IN transaction is received on the Endpoint.
                  '''
          }
          {
            bits: "14:8",
            name: "size",
            desc: '''
                  The number of bytes to send from the buffer.

                  If this is 0 then a CRC only packet is sent.

                  If this is greater than 64 then 64 bytes are sent.
                  '''
          }
          {
            bits: "30",
            name: "pend",
            swaccess: "rw1c"
            hwaccess: "hrw"
            desc: '''
                  This bit indicates a pending transaction was canceled by the hardware.

                  The bit is set when the rdy bit is cleared by hardware because of a
                  SETUP packet being received or a link reset being detected.

                  The bit remains set until cleared by being written with a 1.
                  '''
          }
          {
            bits: "31",
            name: "rdy",
            hwaccess: "hrw"
            desc: '''
                  This bit should be set to indicate the buffer is ready
                  for sending. It will be cleared when the ACK is received
                  indicating the host has accepted the data.

                  This bit will also be cleared if an enabled SETUP
                  transaction is received on the Endpoint. This allows
                  use of the IN channel for transfer of SETUP information.
                  The original buffer must be resubmitted after the SETUP
                  sequence is complete. A link reset also clears the bit.
                  In either of the cases where the hardware cancels the
                  transaction it will also set the pend bit.
                  '''
          }
        ]
      }
    }
    { multireg: {
        name: "iso",
        count: "NEndpoints"
        cname: "Endpoint"
        desc: "Endpoint ISO setting",
        swaccess: "rw",
        hwaccess: "hro",
        fields: [
          {
                bits: "0",
                name: "iso",
                desc: '''
                      If this bit is set then the endpoint will be treated
                      as an ISO endpoint. No handshake packet will be sent
                      for an OUT transaction and no handshake packet will be
                      expected for an IN transaction.
                      '''
          }
        ]
      }
    }
    { multireg: {
        name: "data_toggle_clear",
        count: "NEndpoints"
        cname: "Endpoint"
        desc: "Clear the data toggle flag",
        swaccess: "wo",
        hwaccess: "hro",
        hwqe: "true",
        fields: [
          {
                bits: "0",
                name: "clear",
                desc: '''
                      Writing 1 to this bit will clear the data toggle bit for
                      this endpoint to Data0 in both IN and OUT directions.
                      The register must no be written again within 200 ns.
                      '''
          }
        ]
      }
    }
    { name: "phy_config",
      desc: "USB PHY Configuration",
      swaccess: "rw",
      hwaccess: "hro",
      fields: [
        {
          bits: "0",
          resval: "0",
          name: "rx_differential_mode",
          desc: '''
               Use the differential RX signal instead of the single ended signals.
               Currently only 0 (single-ended operation) is supported.
          '''
        }
        {
          bits: "1",
          resval: "0",
          name: "tx_differential_mode",
          desc: '''
               Use the differential TX signal instead of the single ended signals.
               Currently only 0 (single-ended operation) is supported.
          '''
        }
        {
          bits: "2",
          name: "eop_single_bit",
          resval: "1",
          desc: '''
               Recognize a single SE0 bit as an end of packet, otherwise two
               successive bits are required.
          '''
        }
        {
          bits: "3",
          name: "override_pwr_sense_en",
          desc: "Override the USB Power sense value with override_pwr_sense_val."
          tags: [// Overriding pwr sense will cause the usbdev to think the link is powered up.
                 "excl:CsrNonInitTests:CsrExclWrite"]
        }
        {
          bits: "4",
          name: "override_pwr_sense_val",
          desc: "0: USB power not present, 1: present."
        }
      ]
    }

    { window: {
        name: "buffer",
        items: "512",
        validbits: "32",
        byte-write: "false",
        unusual: "false"
        swaccess: "rw",
        desc: '''
              2kB packet buffer. Divided into 32 64-byte packets.

              The packet buffer is used for sending and receiveing packets.
              '''
      },
    },
  ]
}