usbdev.hjson

// Copyright lowRISC contributors (OpenTitan project).
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
{
  name:               "usbdev",
  human_name:         "USB Device",
  one_line_desc:      "USB 2.0 Full Speed device interface (12 Mbit/s)",
  one_paragraph_desc: '''
  USB Device provides compatibility with the industry standard Universal Serial Bus by implementing a Full Speed device (12 Mbit/s) according to the USB 2.0 Specification.
  USB Device supports up to 12 bidirectional endpoints which may be used to support all of the USB 2.0 transfer types, including Isochronous transfers.
  Support for packet transmission and reception is provided in hardware, with the generation of interrupts for software to mediate the different stages of Control and Data Transfers.
  The maximum packet size for transfers is configurable up to the specification limit of 64 bytes per packet, reducing the protocol overhead for Bulk transfers, and the inbuilt 2 KiB memory can accommodate 32 packets.
  USB Device may be configured to use either a single-ended interface to an external differential transceiver or a differential input/output for more direct interfacing and reduced hardware complexity when prototyping.
  '''
  // Unique comportable IP identifier defined under KNOWN_CIP_IDS in the regtool.
  cip_id:             "31",
  design_spec:        "../doc",
  dv_doc:             "../doc/dv",
  hw_checklist:       "../doc/checklist",
  sw_checklist:       "/sw/device/lib/dif/dif_usbdev",
  version:            "2.0.0",
  life_stage:         "L1",
  design_stage:       "D2S",
  verification_stage: "V2S",
  dif_stage:          "S2",
  clocking: [
    // clk_i must be 48 MHz
    {clock: "clk_i", reset: "rst_ni", primary: true},
    {clock: "clk_aon_i", reset: "rst_aon_ni"},
  ]
  bus_interfaces: [
    { protocol: "tlul", direction: "device" }
  ],
  available_inout_list: [
    { name: "usb_dp", desc: "USB data D+" }
    { name: "usb_dn", desc: "USB data D-" }
  ],
  available_input_list: [
    {  name: "sense", desc: "USB host VBUS sense" }
  ],
  available_output_list: [],
  inter_signal_list: [
    { name:    "usb_rx_d",
      desc:    "USB RX data from an external differential receiver, if available"
      type:    "uni",
      act:     "rcv",
      package: "",
      struct:  "logic",
      width:   "1"
    }
    { name:    "usb_tx_d",
      desc:    "USB transmit data value (not used if usb_tx_se0 is set)"
      type:    "uni",
      act:     "req",
      package: "",
      struct:  "logic",
      width:   "1"
    }
    { name:    "usb_tx_se0",
      desc:    "Force transmission of a USB single-ended zero (i.e. both D+ and D- are low) regardless of usb_tx_d"
      type:    "uni",
      act:     "req",
      package: "",
      struct:  "logic",
      width:   "1"
    }
    { name:    "usb_tx_use_d_se0",
      desc:    "Use the usb_tx_d and usb_tx_se0 TX interface, instead of usb_dp_o and usb_dn_o"
      type:    "uni",
      act:     "req",
      package: "",
      struct:  "logic",
      width:   "1"
    }
    { name:    "usb_dp_pullup",
      desc:    "USB D+ pullup control"
      type:    "uni",
      act:     "req",
      package: "",
      struct:  "logic",
      width:   "1"
    }
    { name:    "usb_dn_pullup",
      desc:    "USB D- pullup control"
      type:    "uni",
      act:     "req",
      package: "",
      struct:  "logic",
      width:   "1"
    }
    { name:    "usb_rx_enable",
      desc:    "USB differential receiver enable"
      type:    "uni",
      act:     "req",
      package: "",
      struct:  "logic",
      width:   "1"
    }
    { name:    "usb_ref_val",
      desc:    "This indicates that USB timing reference signal 'usb_ref_pulse' is valid"
      type:    "uni",
      act:     "req",
      package: "",
      struct:  "logic",
      width:   "1"
    }
    { name:    "usb_ref_pulse",
      desc:    "USB timing reference signal. This signal pulses for a single 48MHz clock every 1ms USB frame"
      type:    "uni",
      act:     "req",
      package: "",
      struct:  "logic",
      width:   "1"
    },
    { name:    "usb_aon_suspend_req",
      desc:    "Request to activate the AON/Wake module and take control of the USB pullups"
      type:    "uni",
      act:     "req",
      package: "",
      struct:  "logic",
      width:   "1"
    },
    { name:    "usb_aon_wake_ack",
      desc:    "Acknowledge a wake signal from the AON/Wake and relinquish control of the USB pullups"
      type:    "uni",
      act:     "req",
      package: "",
      struct:  "logic",
      width:   "1"
    },
    { name:    "usb_aon_bus_reset",
      desc:    "Indicates that the reason for waking was that a USB Bus Reset occurred"
      type:    "uni",
      act:     "rcv",
      package: "",
      struct:  "logic",
      width:   "1"
    },
    { name:    "usb_aon_sense_lost",
      desc:    "Indicates that the reason for waking was that the VBUS/SENSE signal became deasserted"
      type:    "uni",
      act:     "rcv",
      package: "",
      struct:  "logic",
      width:   "1"
    },
    { name:    "usb_aon_bus_not_idle",
      desc:    "Indicates that the reason for waking was that the USB is in a non-idle state"
      type:    "uni",
      act:     "rcv",
      package: "",
      struct:  "logic",
      width:   "1"
    },
    { name:    "usb_aon_wake_detect_active",
      desc:    "Indicates that the external AON/Wake module is active and controlling the USB pullups",
      type:    "uni",
      act:     "rcv",
      package: "",
      struct:  "logic",
      width:   "1"
    },
    { struct:  "ram_1p_cfg",
      package: "prim_ram_1p_pkg",
      type:    "uni",
      name:    "ram_cfg",
      act:     "rcv"
    }
  ]
  param_list: [
    { name:    "Stub",
      type:    "bit",
      default: "0",
      desc:    "Stub out the core of entropy_src logic"
      local:   "false",
      expose:  "true"
    },
    { name:    "NEndpoints",
      type:    "int",
      default: "12",
      desc:    "Number of endpoints",
      local:   "true"
    },
    { name:    "RcvrWakeTimeUs",
      type:    "int",
      default: "1",
      desc:    "Maximum number of microseconds for the differential receiver to become operational",
      local:   "false",
      expose:  "true"
    }
  ],
  interrupt_list: [
    { name: "pkt_received"
      desc: '''
            Raised if a packet was received using an OUT or SETUP transaction.
            This interrupt is directly tied to whether the RX FIFO is empty, so it should be cleared only after handling the FIFO entry.
            '''
      type: "status"
    }
    { name: "pkt_sent"
      desc: '''
            Raised if a packet was sent as part of an IN transaction.
            This interrupt is directly tied to whether a sent packet has not been acknowledged in the !!in_sent register.
            It should be cleared only after clearing all bits in the !!in_sent register.
            '''
      type: "status"
    }
    { name: "disconnected",
      desc: '''
            Raised if VBUS is lost, thus the link is disconnected.
            '''
    }
    { name: "host_lost",
      desc: '''
            Raised if link is active but SOF was not received from host for 4.096 ms. The SOF should be every 1 ms.
            '''
    }
    { name: "link_reset",
      desc: '''
            Raised if the link is at SE0 longer than 3 us indicating a link reset (host asserts for min 10 ms, device can react after 2.5 us).
            '''
    }
    { name: "link_suspend",
      desc: '''
            Raised if the line has signaled 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_out_empty",
      desc: '''
            Raised when the Available OUT Buffer FIFO is empty and the device interface is enabled.
            This interrupt is directly tied to the FIFO status, so the Available OUT Buffer FIFO must be provided with a free buffer before the interrupt can be cleared.
            '''
      type: "status"
    }
    { name: "rx_full",
      desc: '''
            Raised when the RX FIFO is full and the device interface is enabled.
            This interrupt is directly tied to the FIFO status, so the RX FIFO must have an entry removed before the interrupt is cleared.
            If the condition is not cleared, the interrupt can re-assert.
            '''
      type: "status"
    }
    { name: "av_overflow",
      desc: '''
            Raised if a write was done to either the Available OUT Buffer FIFO or the Available SETUP Buffer 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, leading to a NAK instead,
            or if a different token was received.
            '''
    }
    { name: "rx_crc_err",
      desc: '''
            Raised if a CRC error occurred on a received packet.
            '''
    }
    { name: "rx_pid_err",
      desc: '''
            Raised if an invalid Packet IDentifier (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.
            '''
    }
    { name: "powered",
      desc: "Raised if VBUS is applied."
    }
    { name: "link_out_err",
      desc: '''
            Raised if a packet to an OUT endpoint started to be received but was then dropped due to an error.
            This error is raised if the data toggle, token, packet and/or CRC are invalid, or if the appropriate Available OUT Buffer FIFO is empty and/or the Received Buffer FIFO is full when a packet should have been received.
            '''
    }
    {
      name: "av_setup_empty",
      desc: '''
            Raised when the Available SETUP Buffer FIFO is empty and the device interface is enabled.
            This interrupt is directly tied to the FIFO status, so the Available SETUP Buffer FIFO must be provided with a free buffer before the interrupt can be cleared.
            '''
      type: "status"
    }
  ]
  alert_list: [
    { name: "fatal_fault",
      desc: '''
      This fatal alert is triggered when a fatal TL-UL bus integrity fault is detected.
      '''
    }
  ],
  features: [
    {
      name: "USBDEV.CONN.VBUS"
      desc: '''Detection of VBUS/SENSE signal from the host controller, indicating a
            connection and/or supplying power.
            '''
    }
    {
      name: "USBDEV.CONN.PULLUP"
      desc: '''Assertion and removal of pull up resistor indicating Full Speed device
            presence on the USB.
            '''
    }
    {
      name: "USBDEV.CONN.REF_PULSE"
      desc: '''Generation of a reference pulse in response to Start Of Frame packet
            reception, to synchronize the device clock with that of the host controller.
            '''
    }
    {
      name: "USBDEV.CONN.PIN_CONFIG"
      desc: '''Support for different pin configurations; pin flipping, transmission and
            reception modes.
            '''
    }
    {
      name: "USBDEV.CONN.RESET"
      desc: '''usbdev reset and the ability to empty the Av and Rx FIFOs. Required for
            adapting to polarity of SBU connections on USB-C cables.
            '''
    }
    {
      name: "USBDEV.BUFFER.MEMORY"
      desc: '''usbdev presents a conventional 512-entry 32-bit RAM on the memory bus
            that supports read/write operations for receiving and sending packets over
            the USB. Writing and reading of partial words is not supported.
            '''
    }
    {
      name: "USBDEV.TRANSFER.CONTROL_RX"
      desc: "Reception of packets in Control Transfers from the host controller."
    }
    {
      name: "USBDEV.TRANSFER.CONTROL_TX"
      desc: "Transmission of response packets in Control Transfers from the host."
    }
    {
      name: "USBDEV.TRANSFER.ENDPOINTS"
      desc: "Use of multiple endpoints in communication with the host controller."
    }
    {
      name: "USBDEV.TRANSFER.BULK"
      desc: "Bulk Transfer streams."
    }
    {
      name: "USBDEV.TRANSFER.ISOCHRONOUS"
      desc: "Support for Isochronous Transfers and Endpoints."
    }
    {
      name: "USBDEV.TRANSFER.CONTROL"
      desc: '''Support for Control Transfers/Endpoints other than the Default Control Pipe
            at Endpoint Zero.
            '''
    }
    {
      name: "USBDEV.TRANSFER.INTERRUPT"
      desc: "Support for Interrupt Transfers and Endpoints."
    }
    {
      name: "USBDEV.POWER.SUSPEND"
      desc: "Detection of Suspend request from the host."
    }
    {
      name: "USBDEV.POWER.RESUME"
      desc: "Detection of Resume Signaling from the host controller."
    }
    {
      name: "USBDEV.POWER.AON"
      desc: "Handover of the USB to the AON module that handles Wake signaling."
    }
    {
      name: "USBDEV.POWER.WAKE_DISCONNECT",
      desc: "Wake from Sleep in response to Disconnection."
    }
    {
      name: "USBDEV.POWER.WAKE_RESUME",
      desc: "Wake from Sleep in response to Resume Signaling."
    }
    {
      name: "USBDEV.POWER.WAKE_BUS_RESET",
      desc: "Wake from Sleep in response to Bus Reset from host."
    }
    {
      name: "USBDEV.POWER.TOGGLE_RESTORE",
      desc: '''Save and restore Data Toggles for all IN and OUT endpoints.
            Resuming from Deep Sleep requires the ability to restore the Data Toggles
            to an arbitrary state. (Requires prod-only RTL changes.)
            '''
    }
  ],
  countermeasures: [
    { name: "BUS.INTEGRITY",
      desc: "End-to-end bus integrity scheme."
    }
  ]
  regwidth: "32",
  registers: [
    { name: "usbctrl",
      desc: "USB Control",
      swaccess: "rw",
      hwaccess: "hro",
      fields: [
        {
          bits: "0",
          name: "enable",
          desc: '''
                Set to connect the USB interface (i.e. assert the pullup).
                '''
          tags: [// Prevent usb from being enabled to avoid other unforeseen side effects.
                 "excl:CsrNonInitTests:CsrExclWrite"]
        }
        {
          bits: "1",
          name: "resume_link_active",
          swaccess: "wo"
          hwqe: "true",
          desc: '''
                Write a 1 to this bit to instruct usbdev to jump to the LinkResuming state.
                The write will only have an effect when the device is in the LinkPowered state.
                Its intention is to handle a resume-from-suspend event after the IP has been powered down.
                '''
        }
        {
          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"]
        }
      ]
    }
    { multireg: {
        name: "ep_out_enable",
        count: "NEndpoints"
        cname: "Endpoint"
        desc: '''
              Enable an endpoint to respond to transactions in the downstream direction.
              Note that as the default endpoint, endpoint 0 must be enabled in both the IN and OUT directions before enabling the USB interface to connect.
              '''
        swaccess: "rw",
        hwaccess: "hro",
        fields: [
          {
            bits: "0",
            name: "enable",
            desc: '''
                  This bit must be set to enable downstream transactions to be received on the endpoint and elicit responses.
                  If the bit is clear, any SETUP or OUT packets sent to the endpoint will be ignored.
                  '''
          }
        ]
      }
    }
    { multireg: {
        name: "ep_in_enable",
        count: "NEndpoints"
        cname: "Endpoint"
        desc: '''
              Enable an endpoint to respond to transactions in the upstream direction.
              Note that as the default endpoint, endpoint 0 must be enabled in both the IN and OUT directions before enabling the USB interface to connect.
              '''
        swaccess: "rw",
        hwaccess: "hro",
        fields: [
           {
            bits: "0",
            name: "enable",
            desc: '''
                  This bit must be set to enable upstream transactions to be received on the endpoint and elicit responses.
                  If the bit is clear then any IN packets sent to the endpoint will be ignored.
                  '''
          }
        ]
      }
    }
    { 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.096 ms and the line is active.
                '''
        }
        {
          bits: "14:12",
          name: "link_state",
          desc: '''
                State of USB link, decoded from line.
                '''
          enum: [
            { value: "0",
              name: "disconnected",
              desc: "Link disconnected (no VBUS or no pull-up connected)"
            },
            { value: "1",
              name: "powered",
              desc: "Link powered and connected, but not reset yet"
            },
            { value: "2",
              name: "powered_suspended",
              desc: "Link suspended (constant idle/J for > 3 ms), but not reset yet"
            },
            { value: "3",
              name: "active",
              desc: "Link active"
            },
            { value: "4",
              name: "suspended",
              desc: "Link suspended (constant idle for > 3 ms), was active before becoming suspended"
            },
            { value: "5",
              name: "active_nosof",
              desc: "Link active but no SOF has been received since the last reset."
            },
            { value: "6",
              name: "resuming",
              desc: "Link resuming to an active state, pending the end of resume signaling"
            },
          ]
        }
        {
          bits: "15",
          name: "sense",
          desc: '''
                Reflects the state of the sense pin.
                1 indicates that the host is providing VBUS.
                Note that this bit always shows the state of the actual pin and does not take account of the override control.
                '''
        }
        {
          bits: "19:16",
          name: "av_out_depth",
          desc: '''
                Number of buffers in the Available OUT Buffer FIFO.

                These buffers are available for receiving OUT DATA packets.
                '''
        }
        {
          bits: "22:20",
          name: "av_setup_depth",
          desc: '''
                Number of buffers in the Available SETUP Buffer FIFO.

                These buffers are available for receiving SETUP DATA packets.
                '''
        }
        {
          bits: "23",
          name: "av_out_full",
          desc: '''
                Available OUT Buffer FIFO is full.
                '''
        }
        {
          bits: "27:24",
          name: "rx_depth",
          desc: '''
                Number of buffers in the Received Buffer FIFO.

                These buffers have packets that have been received and
                should be popped from the FIFO and processed.
                '''
        }
        {
          bits: "30",
          name: "av_setup_full",
          desc: '''
                Available SETUP Buffer FIFO is full.
                '''
        }
        {
          bits: "31",
          name: "rx_empty",
          resval: "1",
          desc: '''
                Received Buffer FIFO is empty.
                '''
        }
      ]
      tags: [// Updated by HW based on observed USB signals, comprises also readbacks.
             // Pinmux configuration can affect at least the sense and link_state bits.
             // Exclude all read checks in all tests including reset tests.
             "excl:CsrAllTests:CsrExclCheck"]
    }
    { name: "avoutbuffer",
      desc: "Available OUT Buffer FIFO",
      swaccess: "wo",
      hwaccess: "hro",
      hwext: "true",
      hwqe: "true",
      fields: [
        {
          bits: "4:0",
          name: "buffer",
          desc: '''
                This field contains the buffer ID being passed to the USB receive engine.

                If the Available OUT Buffer FIFO is full, any write operations are discarded.
                '''
        }
      ]
      tags: [// Writing this CSR affects the ral.usbstat.av_depth field.
             "excl:CsrNonInitTests:CsrExclWrite"]
    }
    { name: "avsetupbuffer",
      desc: "Available SETUP Buffer FIFO",
      swaccess: "wo",
      hwaccess: "hro",
      hwext: "true",
      hwqe: "true",
      fields: [
        {
          bits: "4:0",
          name: "buffer",
          desc: '''
                This field contains the buffer ID being passed to the USB receive engine.

                If the Available SETUP Buffer FIFO is full, any write operations are discarded.
                '''
        }
      ]
      tags: [// Writing this CSR affects the ral.usbstat.av_depth field.
             "excl:CsrNonInitTests:CsrExclWrite"]
    }
    { name: "rxfifo",
      desc: "Received Buffer FIFO",
      swaccess: "ro",
      hwaccess: "hrw",
      hwext: "true",
      hwre: "true",
      fields: [
        {
          bits: "4:0",
          name: "buffer",
          desc: '''
                This field contains the buffer ID that data was received into.
                On read the buffer ID is popped from the Received Buffer FIFO and returned to software.
                '''
        }
        {
          bits: "14:8",
          name: "size",
          desc: '''
                This field contains the data length in bytes of the packet written to the buffer.
                '''
        }
        {
          bits: "19",
          name: "setup",
          desc: '''
                This bit indicates if the received transaction is of type SETUP (1) or OUT (0).
                '''
        }
        {
          bits: "23:20",
          name: "ep",
          desc: '''
                This field contains the endpoint ID 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 packet will be ignored. The bit should be set for
                  control endpoints (and only control endpoints).
                  '''
          }
        ]
      }
    }
    { multireg: {
        name: "rxenable_out",
        count: "NEndpoints"
        cname: "Endpoint"
        desc: "Receive OUT transaction enable",
        swaccess: "rw",
        hwaccess: "hrw",
        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 NAK, if the endpoint is enabled.
                  If set_nak_out for this endpoint is set, hardware will clear this bit whenever an OUT transaction is received on this endpoint.
                  Software must set this bit again to receive the next OUT transaction.
                  Until that happens, hardware will continue to NAK any OUT transaction to this endpoint.
                  '''
          }
        ]
      }
    }
    { multireg: {
        name: "set_nak_out",
        count: "NEndpoints"
        cname: "Endpoint"
        desc: "Set NAK after OUT transactions",
        swaccess: "rw",
        hwaccess: "hro",
        fields: [
          {
            bits: "0",
            name: "enable",
            desc: '''
                  When this bit is set, hardware will clear this endpoint's rxenable_out bit whenever an OUT transaction is received on this endpoint.
                  This bit should not be changed while the endpoint is active.
                  '''
          }
        ]
      }
    }
    { multireg: {
        name: "in_sent",
        count: "NEndpoints"
        cname: "Endpoint"
        desc: "IN Transaction Sent",
        swaccess: "rw1c",
        hwaccess: "hrw",
        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: "out_stall",
        count: "NEndpoints"
        cname: "Endpoint"
        desc: "OUT Endpoint STALL control",
        swaccess: "rw",
        hwaccess: "hrw",
        fields: [
          {
            bits: "0",
            name: "endpoint",
            desc: '''
                  If this bit is set then an OUT transaction to this endpoint will elicit a STALL handshake, when a non-isochronous endpoint is enabled.
                  If the configuration has both STALL and NAK enabled, the STALL handshake will take priority.

                  Note that SETUP transactions are always either accepted or ignored.
                  For endpoints that accept SETUP transactions, a SETUP packet will clear the STALL flag on endpoints for both the IN and OUT directions.
                  '''
          }
        ]
      }
    }
    { multireg: {
        name: "in_stall",
        count: "NEndpoints"
        cname: "Endpoint"
        desc: "IN Endpoint STALL control",
        swaccess: "rw",
        hwaccess: "hrw",
        fields: [
          {
            bits: "0",
            name: "endpoint",
            desc: '''
                  If this bit is set then an IN transaction to this endpoint will elicit a STALL handshake, when a non-isochronous endpoint is enabled.
                  If the configuration has both STALL and NAK enabled, the STALL handshake will take priority.

                  Note that SETUP transactions are always either accepted or ignored.
                  For endpoints that accept SETUP transactions, a SETUP packet will clear the STALL flag on endpoints for both the IN and OUT directions.
                  '''
          }
        ]
      }
    }
    { multireg: {
        name: "configin",
        count: "NEndpoints"
        cname: "Endpoint"
        desc: "Configure IN Transaction",
        swaccess: "rw",
        hwaccess: "hro",
        fields: [
          {
            bits: "4:0",
            name: "buffer",
            desc: '''
                  The buffer ID 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: "29",
            name: "sending",
            swaccess: "rw1c",
            hwaccess: "hwo",
            desc: '''
                  This bit indicates that the buffer is in the process of being collected by the
                  host. It becomes set upon the first attempt by the host to collect a buffer from
                  this endpoint when the rdy bit was set.

                  It is cleared when the packet has been collected successfully or the pending
                  transaction has been canceled by the hardware through detection of a
                  link reset or receipt of a SETUP packet.
                  '''
          }
          {
            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.
                  '''
          }
        ]
        tags: [// 'rdy', 'pend' and 'sending' bits interact with each other.
               "excl:CsrNonInitTests:CsrExclWrite"]
      }
    }
    { multireg: {
        name: "out_iso",
        count: "NEndpoints"
        cname: "Endpoint"
        desc: "OUT Endpoint isochronous setting",
        swaccess: "rw",
        hwaccess: "hro",
        fields: [
          {
            bits: "0",
            name: "iso",
            desc: '''
                  If this bit is set then the endpoint will be treated as an isochronous endpoint.
                  No handshake packet will be sent for an OUT transaction.
                  Note that if a rxenable_setup is set for this endpoint's number, this bit will not take effect.
                  Control endpoint configuration trumps isochronous endpoint configuration.
                  '''
          }
        ]
      }
    }
    { multireg: {
        name: "in_iso",
        count: "NEndpoints"
        cname: "Endpoint"
        desc: "IN Endpoint isochronous setting",
        swaccess: "rw",
        hwaccess: "hro",
        fields: [
          {
            bits: "0",
            name: "iso",
            desc: '''
                  If this bit is set then the endpoint will be treated as an isochronous endpoint.
                  No handshake packet will be expected for an IN transaction.
                  Note that if a rxenable_setup is set for this endpoint's number, this bit will not take effect.
                  Control endpoint configuration trumps isochronous endpoint configuration.
                  '''
          }
        ]
      }
    }
    {
      name: "out_data_toggle",
      desc: "OUT Endpoints Data Toggles",
      swaccess: "rw",
      hwaccess: "hrw",
      hwext: "true",
      hwqe: "true",
      fields: [
        {
          bits: "11:0",
          name: "status",
          desc: '''
                Reading returns the current state of the OUT endpoint Data Toggle flags.
                Writing sets the Data Toggle flag for each endpoint if the corresponding mask bit
                in the upper half of this register is set.
                '''
        }
        {
          bits: "27:16",
          name: "mask",
          desc: '''
                Reads as zero.
                When writing, a set bit will cause the Data Toggle flag of the corresponding
                OUT endpoint to be updated. A clear bit will leave the flag for the corresponding
                endpoint unchanged.
                '''
        }
      ],
      tags: [// This CSR has mask bits that gate writes.
             "excl:CsrNonInitTests:CsrExclWrite"]
    }
    {
      name: "in_data_toggle",
      desc: "IN Endpoints Data Toggles",
      swaccess: "rw",
      hwaccess: "hrw",
      hwext: "true",
      hwqe: "true",
      fields: [
        {
          bits: "11:0",
          name: "status",
          desc: '''
                Reading returns the current state of the IN endpoint Data Toggle flags.
                Writing sets the Data Toggle flag for each endpoint if the corresponding mask bit
                in the upper half of this register is set.
                '''
        }
        {
          bits: "27:16",
          name: "mask",
          desc: '''
                Reads as zero.
                When writing, a set bit will cause the Data Toggle flag of the corresponding
                IN endpoint to be updated. A clear bit will leave the flag for the corresponding
                endpoint unchanged.
                '''
        }
      ],
      tags: [// This CSR has mask bits that gate writes.
             "excl:CsrNonInitTests:CsrExclWrite"]
    }
    { name: "phy_pins_sense",
      desc: '''
            USB PHY pins sense.
            This register can be used to read out the state of the USB device inputs and outputs from software.
            This is designed to be used for debugging purposes or during chip testing.
            '''
      swaccess: "ro",
      hwaccess: "hwo",
      hwext: "true",
      fields: [
        {
          bits: "0",
          name: "rx_dp_i",
          desc: "USB D+ input."
        }
        {
          bits: "1",
          name: "rx_dn_i",
          desc: "USB D- input."
        }
        {
          bits: "2",
          name: "rx_d_i",
          desc: "USB data input from an external differential receiver, if available."
        }
        {
          bits: "8",
          name: "tx_dp_o",
          desc: "USB transmit D+ output (readback)."
        }
        {
          bits: "9",
          name: "tx_dn_o",
          desc: "USB transmit D- output (readback)."
        }
        {
          bits: "10",
          name: "tx_d_o",
          desc: "USB transmit data value (readback)."
        }
        {
          bits: "11",
          name: "tx_se0_o",
          desc: "USB single-ended zero output (readback)."
        }
        {
          bits: "12",
          name: "tx_oe_o",
          desc: "USB OE output (readback)."
        }
        {
          bits: "16",
          name: "pwr_sense",
          desc: "USB power sense signal."
        }
      ]
      tags: [// Updated by HW based on observed USB PHY signals, comprises also readbacks.
             // Exclude all read checks in all tests including reset tests.
             "excl:CsrAllTests:CsrExclCheck"]
    }
    { name: "phy_pins_drive",
      desc: '''
            USB PHY pins drive.
            This register can be used to control the USB device inputs and outputs from software.
            This is designed to be used for debugging purposes or during chip testing.
            '''
      swaccess: "rw",
      hwaccess: "hro",
      fields: [
        {
          bits: "0",
          name: "dp_o",
          desc: "USB transmit D+ output, used with dn_o."
        }
        {
          bits: "1",
          name: "dn_o",
          desc: "USB transmit D- output, used with dp_o."
        }
        {
          bits: "2",
          name: "d_o",
          desc: "USB transmit data output, encoding K and J when se0_o is 0."
        }
        {
          bits: "3",
          name: "se0_o",
          desc: "USB single-ended zero output."
        }
        {
          bits: "4",
          name: "oe_o",
          desc: "USB OE output."
        }
        {
          bits: "5",
          name: "rx_enable_o",
          desc: "Enable differential receiver."
        }
        {
          bits: "6",
          name: "dp_pullup_en_o",
          desc: "USB D+ pullup enable output."
        }
        {
          bits: "7",
          name: "dn_pullup_en_o",
          desc: "USB D- pullup enable output."
        }
        {
          bits: "16",
          name: "en",
          desc: '''
                0: Outputs are controlled by the hardware block.
                1: Outputs are controlled with this register.
                '''
          tags: [// Prevent random csr tests from driving conflicting values into the chip
                 "excl:CsrNonInitTests:CsrExclWrite"]
        }
      ]
    }
    { name: "phy_config",
      desc: "USB PHY Configuration",
      swaccess: "rw",
      hwaccess: "hro",
      fields: [
        {
          bits: "0",
          resval: "0",
          name: "use_diff_rcvr",
          desc: '''
                Detect received K and J symbols from the usb_rx_d signal, which must be driven from an external differential receiver.
                If 1, make use of the usb_rx_d input.
                If 0, the usb_rx_d input is ignored and the usb_rx_dp and usb_rx_dn pair are used to detect K and J (useful for some environments, but will be unlikely to pass full USB compliance).
                Regardless of the state of this field usb_rx_dp and usb_rx_dn are always used to detect SE0.
                This bit also feeds the rx_enable pin, activating the receiver when the device is not suspended.
                '''
          tags: [// Writing can provoke state changes in the receiver logic and thus raise errors.
                 "excl:CsrNonInitTests:CsrExclWrite"]
        }
        {
          bits: "1",
          resval: "0",
          name: "tx_use_d_se0",
          desc: '''
                If 1, select the d and se0 TX interface.
                If 0, select the dp and dn TX interface.
                This directly controls the output pin of the same name.
                It is intended to be used to enable the use of a variety of external transceivers, to select an encoding that matches the transceiver.
                '''
        }
        {
          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.
                '''
          tags: [// Writing can provoke state changes in the receiver logic and thus raise errors.
                 "excl:CsrNonInitTests:CsrExclWrite"]
        }
        {
          bits: "5",
          resval: "0",
          name: "pinflip",
          desc: '''
                Flip the D+/D- pins.
                Particularly useful if D+/D- are mapped to SBU1/SBU2 pins of USB-C.

                '''
          tags: [// Writing can provoke state changes in the receiver logic and thus raise errors.
                 "excl:CsrNonInitTests:CsrExclWrite"]
        }
        {
          bits: "6",
          resval: "0",
          name: "usb_ref_disable",
          desc: '''
                0: Enable reference signal generation for clock synchronization, 1: disable it by forcing the associated signals to zero.

                '''
        }
        {
          bits: "7",
          resval: "0",
          name: "tx_osc_test_mode",
          desc: '''
                Disable (0) or enable (1) oscillator test mode.
                If enabled, the device constantly transmits a J/K pattern, which is useful for testing the USB clock.
                Note that while in oscillator test mode, the device no longer receives SOFs and consequently does not generate the reference signal for clock synchronization.
                The clock might drift off.

                '''
          tags: [// Writing can provoke state changes in the receiver logic and thus raise errors.
                 "excl:CsrNonInitTests:CsrExclWrite"]
        }
      ]
    }
    { name: "wake_control",
      desc: "USB wake module control for suspend / resume",
      swaccess: "wo",
      hwaccess: "hro",
      hwext: "true",
      hwqe: "true",
      async: "clk_aon_i",
      fields: [
        {
          bits: "0",
          resval: "0",
          name: "suspend_req",
          desc: '''
                Suspend request to the wake detection module.

                Trigger the wake detection module to begin monitoring for wake-from-suspend events.
                When written with a 1, the wake detection module will activate.
                Activation may not happen immediately, and its status can be verified by checking wake_events.module_active.
                '''
          tags: [// Prevent usb wake functions from being turned on outside of directed tests
                 "excl:CsrNonInitTests:CsrExclWrite"]
        }
        {
          bits: "1",
          resval: "0",
          name: "wake_ack",
          desc: '''
                Wake acknowledgement.

                Signal to the wake detection module that it may release control of the pull-ups back to the main block and return to an inactive state.
                The release back to normal state may not happen immediately.
                The status can be confirmed via wake_events.module_active.

                Note that this bit can also be used without powering down, such as when usbdev detects resume signaling before transitions to low power states have begun.
                '''
        },
      ]
    }
    { name: "wake_events",
      desc: "USB wake module events and debug",
      swaccess: "ro",
      hwaccess: "hwo",
      async: "clk_aon_i",
      fields: [
        {
          bits: "0",
          resval: "0",
          name: "module_active",
          desc: '''
                USB aon wake module is active, monitoring events and controlling the pull-ups.
                '''
        }
        {
          bits: "8",
          resval: "0",
          name: "disconnected",
          desc: '''
                USB aon wake module detected VBUS was interrupted while monitoring events.
                '''
        }
        {
          bits: "9",
          resval: "0",
          name: "bus_reset",
          desc: '''
                USB aon wake module detected a bus reset while monitoring events.
                '''
        }
        {
          bits: "10",
          resval: "0",
          name: "bus_not_idle",
          desc: '''
                USB aon wake module detected a non-idle bus while monitoring events.
                '''
        }
      ]
    }
    { name: "fifo_ctrl",
      desc: "FIFO control register",
      swaccess: "wo",
      hwaccess: "hro",
      fields: [
        {
          bits: "0",
          resval: "0",
          name: "avout_rst",
          desc: '''
                Software reset of the Available OUT Buffer FIFO. This must be used only when the USB device
                is not connected to the USB.
                '''
          hwqe: "true"
          tags: [// Prevent interaction with the Av OUT FIFO state indicators.
                 "excl:CsrNonInitTests:CsrExclWrite"]
        }
        {
          bits: "1",
          resval: "0",
          name: "avsetup_rst",
          desc: '''
                Software reset of the Available SETUP Buffer FIFO. This must be used only when the USB device
                is not connected to the USB.
                '''
          hwqe: "true"
          tags: [// Prevent interaction with the Av SETUP FIFO state indicators.
                 "excl:CsrNonInitTests:CsrExclWrite"]
        }
        {
          bits: "2",
          resval: "0",
          name: "rx_rst",
          desc: '''
                Software reset the of Rx Buffer FIFO. This must be used only when the USB device is not
                connected to the USB.
                '''
          hwqe: "true"
          tags: [// Prevent interaction with the Rx FIFO state indicators.
                 "excl:CsrNonInitTests:CsrExclWrite"]
        }
      ]
    }
    { name: "count_out",
      desc: "Counter for OUT side USB events.",
      resval: "0",
      hwext: "true",
      fields: [
        {
          bits: "7:0",
          name: "count",
          desc: "Number of events counted.",
          swaccess: "ro",
          hwaccess: "hwo"
        }
        {
          bits: "12",
          name: "datatog_out",
          desc: '''
                Count the OUT transactions for which the USB device acknowledged the OUT packet
                and dropped it internally, which is the correct response to a packet transmitted
                with an incorrect Data Toggle.

                The expectation is that this packet is a retry of the previous packet transmission
                and that the handshake response was not received intact by the USB host, indicating
                unreliable communications.

                Other causes of Data Toggle synchronization failure may result in data loss.
                '''
          swaccess: "rw",
          hwaccess: "hrw",
          hwqe: "true"
        }
        {
          bits: "13",
          name: "drop_rx",
          desc: '''
                Count the SETUP/OUT packets ignored, dropped or NAKed because the RX FIFO was full.
                SETUP packets have been ignored, Isochronous OUT packets have been dropped, and
                non-Isochronous OUT packets have been NAKed.
                '''
          swaccess: "rw",
          hwaccess: "hrw",
          hwqe: "true"
        }
        {
          bits: "14",
          name: "drop_avout",
          desc: '''
                Count the OUT packets that could not be accepted because there was no buffer in the
                Av OUT FIFO. Non-Isochronous OUT packets have been NAKed.
                Isochronous OUT packets were ignored.
                '''
          swaccess: "rw",
          hwaccess: "hrw",
          hwqe: "true"
        }
        {
          bits: "15",
          name: "ign_avsetup",
          desc: '''
                Count the SETUP packets that were ignored because there was no buffer in the
                Av SETUP FIFO.
                '''
          swaccess: "rw",
          hwaccess: "hrw",
          hwqe: "true"
        }
        {
          bits: "27:16"
          name: "endpoints",
          desc: "Set of OUT endpoints for which this counter is enabled.",
          swaccess: "rw",
          hwaccess: "hrw",
          hwqe: "true"
        }
        {
          bits: "31",
          name: "rst",
          desc: "Write 1 to reset the counter.",
          swaccess: "wo",
          hwaccess: "hro",
          hwqe: "true",
          tags: [// Prevent interaction with the count field.
                 "excl:CsrNonInitTests:CsrExclWrite"]
        }
      ]
    }
    { name: "count_in",
      desc: "Counter for IN side USB events.",
      resval: "0",
      hwext: "true",
      fields: [
        {
          bits: "7:0",
          name: "count",
          desc: "Number of events counted.",
          swaccess: "ro",
          hwaccess: "hwo",
        }
        {
          bits: "13",
          name: "nodata",
          desc: '''
                Count the IN transactions that were attempted when there was no packet available
                in the corresponding 'configin' register(s). This is not necessarily an error
                condition, and the counter primarily offers some visibility into when the IN
                traffic is underusing the available bus bandwidth.
                It is of particular utility to Isochronous IN endpoints.
                '''
          swaccess: "rw",
          hwaccess: "hrw",
          hwqe: "true"
        }
        {
          bits: "14",
          name: "nak",
          desc: '''
                Count the IN transactions rejected by the host responding with a NAK handshake.
                '''
          swaccess: "rw",
          hwaccess: "hrw",
          hwqe: "true"
        }
        {
          bits: "15",
          name: "timeout",
          desc: '''
                Count the IN transactions for which the USB host did not respond with a handshake,
                and the transactions timed out. This indicates that the host did not receive it
                and decode it as a valid packet, suggesting that communication is unreliable.

                Isochronous IN transactions are excluded from this count because there is no
                handshake response to Isochronous packet transfers.
                '''
          swaccess: "rw",
          hwaccess: "hrw",
          hwqe: "true"
        }
        {
          bits: "27:16"
          name: "endpoints",
          desc: "Set of endpoints for which this counter is enabled.",
          swaccess: "rw",
          hwaccess: "hrw",
          hwqe: "true"
        }
        {
          bits: "31",
          name: "rst",
          desc: "Write 1 to reset the counter.",
          swaccess: "wo",
          hwaccess: "hro",
          hwqe: "true",
          tags: [// Prevent interaction with the count field.
                 "excl:CsrNonInitTests:CsrExclWrite"]
        }
      ]
    }
    { name: "count_nodata_in",
      desc: '''
            Count of IN transactions for which no packet data was available.

            This secondary register allows some partitioning of endpoints among the two
            counters, for more targeted measurement, eg. endpoints may be grouped according to
            the expected bandwidth usage, or Isochronous vs. non-Isochronous transfers.
            '''
      resval: "0",
      hwext: "true",
      fields: [
        {
          bits: "7:0",
          name: "count",
          desc: '''
                Number of IN transactions that were attempted when there was no packet available
                in the corresponding 'configin' register(s).
                '''
          swaccess: "ro",
          hwaccess: "hwo"
        }
        {
          bits: "27:16"
          name: "endpoints",
          desc: "Set of endpoints for which this counter is enabled.",
          swaccess: "rw",
          hwaccess: "hrw",
          hwqe: "true"
        }
        {
          bits: "31",
          name: "rst",
          desc: "Write 1 to reset the counter.",
          swaccess: "wo",
          hwaccess: "hro",
          hwqe: "true",
          tags: [// Prevent interaction with the count field.
                 "excl:CsrNonInitTests:CsrExclWrite"]
        }
      ]
    }
    { name: "count_errors",
      desc: "Count of error conditions detected on token packets from the host.",
      resval: "0",
      hwext: "true",
      fields: [
        {
          bits: "7:0",
          name: "count",
          desc: "Number of events counted.",
          swaccess: "ro",
          hwaccess: "hwo"
        }
        {
          bits: "27",
          name: "pid_invalid",
          desc: '''
                Number of Invalid PIDs detected on packets from the host. Invalid PIDs may
                indicate very unreliable communication and/or a substantial frequency mismatch
                between the host and the device.
                '''
          swaccess: "rw",
          hwaccess: "hrw",
          hwqe: "true"
        }
        {
          bits: "28",
          name: "bitstuff",
          desc: '''
                Number of SETUP/OUT packets that were ignored, dropped or NAKed because a
                Bit Stuffing error was detected.
                '''
          swaccess: "rw",
          hwaccess: "hrw",
          hwqe: "true"
        }
        {
          bits: "29",
          name: "crc16",
          desc: '''
                Count SETUP/OUT DATA packets that were ignored, dropped or NAKed because a
                CRC16 error was detected.
                '''
          swaccess: "rw",
          hwaccess: "hrw",
          hwqe: "true"
        }
        {
          bits: "30",
          name: "crc5",
          desc: '''
                Count CRC5 errors detected on token packets sent by the host. CRC5 errors on
                token packets received from the host indicate very unreliable communication and
                possibly a substantial frequency mismatch between the host and the device.
                '''
          swaccess: "rw",
          hwaccess: "hrw",
          hwqe: "true"
        }
        {
          bits: "31",
          name: "rst",
          desc: "Write 1 to reset the counter.",
          swaccess: "wo",
          hwaccess: "hro",
          hwqe: "true",
          tags: [// Prevent interaction with the count field.
                 "excl:CsrNonInitTests:CsrExclWrite"]
        }
      ]
    }
    { window: {
        name: "buffer",
        items: "512",
        validbits: "32",
        byte-write: "false",
        unusual: "false"
        swaccess: "rw",
        desc: '''
              2 KiB packet buffer. Divided into thirty two 64-byte buffers.

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