usbdev_testplan.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"
  // TODO: remove the common testplans if not applicable
  import_testplans: ["hw/dv/tools/dvsim/testplans/csr_testplan.hjson",
                     "hw/dv/tools/dvsim/testplans/mem_testplan.hjson",
                     "hw/dv/tools/dvsim/testplans/intr_test_testplan.hjson",
                     "hw/dv/tools/dvsim/testplans/alert_test_testplan.hjson",
                     "hw/dv/tools/dvsim/testplans/tl_device_access_types_testplan.hjson",
                     "usbdev_sec_cm_testplan.hjson"]
  testpoints: [
    {
      name: smoke
      desc: '''
            Smoke test of data transfers in each direction, on both the CSR interface
            (buffer read/write) and the USB (packet transmission/reception).

            - DV environment programs CSRs for suitable pin configuration, leaving the device
              unconnected by not driving the DP pullup.
            - Program CSRs to enable SETUP packet reception, OUT traffic and IN traffic to a chosen
              endpoint.
            - Present a buffer description in the AvSetup Buffer FIFO, to receive the SETUP packet.
            - Enable the interface (assert DP pull up) to indicate device presence.
            - DV host-side detects device presence.
            - DV host-side transmits a SETUP packet to device address 0, chosen endpoint.
            - Check that the description of the SETUP packet appears in the RxFiFo, with the
              expected 'setup' indicator, buffer ID, and a packet length of 8 bytes.
            - Check that the SETUP packet has been received into the packet buffer memory and
              that the buffer holds the expected content.
            - DV host-side checks that ACK was received from usbdev in response to the SETUP packet.
            - Repeat the above for a regular OUT data packet using the AvOut Buffer FIFO, using the
              same endpoint.
            - Populate a buffer with known randomized packet data for collection from a
              randomly-chosen endpoint.
            - Program CSRs to present the packet for collection by the host.
            - DV host-side transmits an IN request to device address 0, chosen endpoint.
            - DV host-side collect IN DATA packet, and ACKnowledges receipt.
            - Check that the received packet matches against that data written into the buffer.
            - Check that CSRs indicate that the packet has been sent.
            '''
      stage: V1
      tests: ["usbdev_smoke"]
    }
    {
      name: in_trans
      desc: '''
            Verify read and write 1 to clear corresponding bits of the 'in_sent' register.

            - Configure the device for an IN transaction to a particular endpoint.
            - Read the 'in_sent' register value to get current status of sent packets and
              then write 1s to the bits which are already high.
            - Verify that reading the register shows only those bits high whose corresponding
              endpoints have sent a packet, and - for non-Isochronous transfers - received an ACK
              from the host.
            - Writing ones must clear the corresponding bits of the 'in_sent' register.
            '''
      stage: V2
      tests: ["usbdev_in_trans"]
    }
    {
      name: data_toggle_clear
      desc: '''
            Verify the ability to clear Data Toggle bits.

            - Set any random bit of the data toggle register from bit 0 to bit 11 then
              initiate an IN/OUT transaction on the corresponding endpoint whose bit is asserted.
            - Verify that writing 0 to a particular bit (bits 0-11) resets the data toggle bit for
              that particular IN/OUT endpoint to DATA0, to resynchronize with the USB host.
            - But it does not prevent toggling of the flags upon successful transmission/receipt of
              subsequent data packets.
            '''
      stage: V2
      tests: ["usbdev_data_toggle_clear"]
    }
    {
      name: phy_pins_sense
      desc: '''
            Verify that the 'phy_pins_sense' register reflects the current state of the DUT pins.

            - Read the 'phy_pins_sense' register via TL-UL interface and sample the input
              and output signals of the DUT at that particular instant.
            - Verify that the read value of the register reflects the sampled values of the
              inputs and outputs.
            '''
      stage: V2
      tests: ["usbdev_phy_pins_sense"]
    }
    {
      name: av_buffer
      desc: '''
            Verify the behavior of the Available OUT and Available SETUP Buffer FIFOs.

            - Choose at random whether to send a SETUP packet or an OUT packet.
            - Write a random 5-bit buffer ID into the 'avoutbuffer' or 'avsetupbuffer' as appropriate.
            - Send a SETUP/OUT token packet followed by a DATA packet to the DUT.
            - Verify that the packet arrives in the RX FIFO with the expected properties
              (buffer ID, packet length and setup/non-setup packet).
            - Verify that the specified buffer within the packet buffer memory contains the data that
              was transmitted.
            '''
      stage: V2
      tests: ["usbdev_av_buffer"]
    }
    {
      name: rx_fifo
      desc: '''
            Verify the functionality of rx fifo.

            - Send an OUT transaction to the DUT with appropriate data packet.
            - After successful reception read the buffer id, setup/out flag and size
              from the RX FIFO entry.
            - Then perform a read operation on the SRAM with address and control info
              provided by the rxfifo.
            - Verify that the data read from the SRAM matches the data sent to the
              device in the data packet of the OUT transaction.
            '''
      stage: V2
      tests: ["usbdev_pkt_buffer"]
    }
    {
      name: phy_config_tx_osc_test_mode
      desc: '''
            Verify the oscillator test mode when phy_config.tx_osc_test_mode is enabled.

            - Set the phy_config.tx_osc_test_mode.
            - Verify that the device starts transmitting the J/K pattern continuously.
            '''
      stage: V2
      tests: ["usbdev_phy_config_tx_osc_test_mode"]
    }
    {
      name: phy_config_eop_single_bit_handling
      desc: '''
            Verify the correct behavior of the phy_config.eop_single_bit configuration in the PHY module
            where a single SE0 bit is recognized as an end of packet, while two successive bits are
            required otherwise.

            - Set eop_single_bit field true in the 'phy_config' register and then send an OUT data packet with
              a single SE0 bit interval at the end followed by J state (bus Idle).
            - Verify that the device recognizes this EOP as valid, accepts the packet into the RX FIFO and
	      does not ignore the packet or raise any link_err interrupts.
            '''
      stage: V2
      tests: ["usbdev_phy_config_eop_single_bit_handling"]
    }
    {
      name: phy_config_pinflip
      desc: '''
            Verify that the 'phy_config.pinflip' bit swaps the use of the DP and DN signals on both
            the input and the output sides of the DUT.

            - Set up the DUT as normal but ensure that the 'pinflip' bit is instead set to true.
            - Ensure that the agent, including driver and monitor are aware of the pins being swapped.
            - Connect the device to the USB.
            - Verify that USB_DN is pulled high instead of USB_DP, and that USB_DP remains low.
            - Verify that OUT and and IN transactions complete normally and with the expected data
              being transferred.
            '''
      stage: V2
      tests: ["usbdev_phy_config_pinflip"]
    }
    {
      name: phy_config_rand_bus_type
      desc: '''
            Choose a random bus configuration and verify that the smoke sequence still passes.
            '''
      stage: V2
      tests: ["usbdev_phy_config_rand_bus_type"]
    }
    {
      name: phy_config_rx_dp_dn
      desc: '''
            Verify that the DP/DN input signals may be used to decode the USB traffic without an
            external differential receiver.
            The USBDEV normally relies upon an external differential receiver to ensure USB 2.0
            specification compliance but it can receive traffic directly using just DP and DN for
            reduced complexity and/or cost.

            - This just runs the smoke test with modified PHY configuration.
            '''
      stage: V2
      tests: ["usbdev_phy_config_rx_dp_dn"]
    }
    {
      name: phy_config_tx_use_d_se0
      desc: '''
            Verify that the D/SE0 outputs can be used to transmit data rather than the DP and DN
            signals.

            - This just runs the smoke test with modified PHY configuration.
            '''
      stage: V2
      tests: ["usbdev_phy_config_tx_use_d_se0"]
    }
    {
      name: phy_config_usb_ref_disable
      desc: '''
            Verify the reference signal generation for clock synchronization may be disabled.

            - Generate a number of SOF packets to the DUT.
            - Check that the 'usb_ref_val_o' rises indicating that valid packets are being detected.
            - Check that 'usb_ref_pulse_o' pulses periodically, in time with the transmission of
              SOF packets to the DUT.
            - Set the usb_ref_disable field true in the phy_config register, but continue to transmit
              the SOF packets.
            - Verify that the 'usb_ref_val_o' becomes deasserted and 'usb_ref_pulse_o' no longer
              pulses in response to the arrival of SOF packets.
            '''
      stage: V2
      tests: ["usbdev_phy_config_usb_ref_disable"]
    }
    {
      name: max_length_out_transaction
      desc: '''
            Verify the reception of maximum length OUT data packets.

            - Configure the endpoint with 'rxenable_out' bit set and 'ep_enable_out' set.
            - Host sends an OUT token followed by the data packet with maximum payload length of 64 bytes.
            - Verify that the DUT acknowledges through an ACK handshake packet.
            - Check that the received data packet within the DUT packet buffer memory matches the
              packet data that was transmitted.
            '''
      stage: V2
      tests: ["usbdev_max_length_out_transaction", "usbdev_stream_len_max"]
    }
    {
      name: max_length_in_transaction
      desc: '''
            Verify the transmission of maximum length IN data packets.

            - Configure the DUT to present a known packet of maximum length (64 bytes) for collection
              by the host.
            - Host sends an IN token, then device sends the data packet with maximum payload length of 64 bytes.
            - Verify that the usbdev responds appropriately to the ACK by recording that the IN DATA packet
              was successfully transmitted.
            - DV host-side shall check that the IN data packet contains the expected data with no
              bit stuffing errors and with a correct CRC16.
            '''
      stage: V2
      tests: ["usbdev_max_length_in_transaction"]
    }
    {
      name: min_length_out_transaction
      desc: '''
            Verify the reception of minimum length OUT data packets.

            - Configure the endpoint with 'rxenable_out' bit set and 'ep_enable_out' set.
            - Host sends an OUT token followed by the data packet with minimum payload length of 0 bytes.
            - Verify that the DUT acknowledges through an ACK handshake packet.
            - Check that the received data packet within the DUT packet buffer memory matches the
              packet data that was transmitted.
            '''
      stage: V2
      tests: ["usbdev_min_length_out_transaction"]
    }
    {
      name: min_length_in_transaction
      desc: '''
            Verify the transmission of minimum length IN data packets.

            - Configure the DUT to present the known packet of minimum length (0 bytes) for collection
              by the host.
            - Host sends an IN token, then device sends the data packet with minimum payload length of 0 bytes.
            - Verify that the usbdev responds appropriately to the ACK by recording that the IN DATA packet
              was successfully transmitted.
            - DV host-side shall check that the IN data packet contains the expected data with no
              bit stuffing errors and with a correct CRC16.
            '''
      stage: V2
      tests: ["usbdev_min_length_in_transaction"]
    }
    {
      name: random_length_out_transaction
      desc: '''
            Verify the reception of random length OUT data packets.

            - Configure the endpoint with 'rxenable_out' bit set and 'ep_enable_out' set.
            - Host sends an OUT token followed by the data packet with random payload length
              between 0 and 64 bytes.
            - Length from 0 inclusive to 64 inclusive should be supported.
            - Verify that the DUT acknowledges receipt with an ACK handshake packet.
            '''
      stage: V2
      tests: ["usbdev_random_length_out_transaction"]
    }
    {
      name: random_length_in_transaction
      desc: '''
            Verify the transmission of random length IN data packets.

            - Configure the DUT to present a packet of known random length (0-64 bytes, inclusive) and
              content for collection by the host.
            - Host sends an IN token, then device sends the data packet.
            - Verify that the DUT records successful transmission of the data packet by setting the
              corresponding bit of the 'in_sent' register.
            '''
      stage: V2
      tests: ["usbdev_random_length_in_transaction"]
    }
    {
      name: out_stall
      desc: '''
            Verify the functionality of OUT endpoint stall.

            - Set the 'out_stall' register's bit to 1 for a particular endpoint, then host issues an OUT token packet
              followed by data packet for that endpoint.
            - Verify that the device responds with the PID STALL Handshake.
            '''
      stage: V2
      tests: ["usbdev_out_stall"]
    }
    {
      name: in_stall
      desc: '''
            Verify the functionality of IN endpoint stall.

            - Set the 'in_stall' register's bit to 1 for a particular endpoint, then host issues an IN token packet
              for a particular endpoint.
            - Verify that the device responds with the PID STALL Handshake.
            '''
      stage: V2
      tests: ["usbdev_in_stall"]
    }
    {
      name: out_iso
      desc: '''
            Verify the functionality of isochronous transfer for OUT transaction.

            - Set the 'out_iso' register's bit to 1 for a paricular endpoint, then host issues an OUT token to that
              endpoint followed by the OUT data packet.
            - Verify that the device does not send any handshake packet in response.
            '''
      stage: V2
      tests: ["usbdev_out_iso"]
    }
    {
      name: in_iso
      desc: '''
            Verify the functionality of isochronous transfer for IN transaction.

            - Set the 'in_iso' register's bit to 1 for an endpoint, then host issues an IN token to that endpoint.
            - Configure the DUT with a data packet availabile for collection from that endpoint.
            - Host sends an IN request and collects the IN data packet, but does not send a handshake response.
            - Verify that the device signals successful transmission of the packet via the 'in_sent' register
              without awaiting a handshake packet from the host.
            '''
      stage: V2
      tests: ["usbdev_in_iso"]
    }
    {
      name: pkt_received
      desc: '''
            Verify the interrupt functionality of packet reception.

            - Send an OUT/SETUP token packet to an enabled endpoint while enabling the INTR_ENABLE[0] followed by the data.
            - Verify that the corresponding interrupt pin goes high after the successful OUT/SETUP packet reception.
            '''
      stage: V2
      tests: ["usbdev_pkt_received"]
    }
    {
      name: pkt_sent
      desc: '''
            Verify the interrupt functionality of packet transmission.

            - Send an IN transaction token packet to an enabled endpoint while INTR_ENABLE[1] is 1.
            - Verify that the corresponding interrupt pin goes high after sending the successful IN packet.
            '''
      stage: V2
      tests: ["usbdev_pkt_sent"]
    }
    {
      name: disconnected
      desc: '''
            Verify that if VBUS is lost then link is disconnected.

            - VBUS(sense) is set to 0 while INTR_ENABLE[2] is 0.
            - Verify that the corresponding Interrupt pin goes high after the link disconnected.
            '''
      stage: V2
      tests: ["usbdev_disconnected"]
    }
    {
      name: host_lost
      desc: '''
            Verify that if link is active (ie. not completely idle) but SOF was not received from
            host for 4.096 ms, the 'host lost' interrupt becomes asserted.

            - Note that there must be _some_ non-idle signaling on the USB during this time because
              otherwise the link state will become suspended, and 'host lost' will not be signaled.
            - Send SOF from host after 4.096 ms while INTR_ENABLE [3] is set.
            - Verify that the corresponding interrupt pin goes high once the host is lost.
            - SOF should normally be received every 1 ms.
            '''
      stage: V2
      tests: ["usbdev_host_lost"]
    }
    {
      name: link_reset
      desc: '''
            Verify that if the link is at SE0 longer than 10 us indicating a link reset
            (host asserts for min 10 ms, device can react after 2.5 us) then link reset
            will raise.

            - Send an SE0 Signal for close to the 10 ms. while INTR_ENABLE [4] is set.
            - Verify that the interrupt pin link_reset goes high once the link reset.
            '''
      stage: V2
      tests: ["usbdev_link_reset"]
    }
    {
      name: link_suspend
      desc: '''
            Verify that if the line has signaled J (Idle) for longer than 3 ms and is therefore in
            suspend state the 'link suspend' will be raised.

            - Leave the link in idle state for more than 3 ms while enable the INTR_ENABLE [5] is set and
              also set the wake_control.suspend_req afterwards.
            - Verify that the interrupt pin goes high once the link suspended.
            '''
      stage: V2
      tests: ["usbdev_link_suspend"]
    }
    {
      name: link_resume
      desc: '''
            Verify that when the link becomes active again after being suspended link resume will rise.

            - First suspend the link by keeping J signal for 3.1ms and then resume it by changing the
              polarity for 20ms. While the INTR_ENABLE[6] bit is set, also set the wake_control.wake_ack signal.
            - Verify that the interrupt pin link_resume goes high once the link resume.
            '''
      stage: V2
      tests: ["usbdev_link_resume"]
    }
    {
      name: av_empty
      desc: '''
            Verify the functionality of 'av_out_empty' and 'av_setup_empty' interrupts when the
      	    Av OUT/SETUP Buffer FIFO is empty.

            - Choose at random whether to test the AV OUT Buffer FIFO or the AV SETUP Buffer FIFO.
            - Enable the interrupt for AV OUT/SETUP empty by setting INTR_ENABLE[7/17] and then send back to back
              packets to the device.
            - Receive and discard any buffers that appear in the RX FIFO.
            - Verify that this interrupt pin goes high once the Av OUT/SETUP Buffer FIFO is empty.
            '''
      stage: V2
      tests: ["usbdev_av_empty"]
    }
    {
      name: rx_full
      desc: '''
            Verify the functionality of rx_full signal when RX FIFO is full.

            - Enable the interrupt for RX full by setting INTR_ENABLE[8] and then send back to back packets
              to the device.
            - Don't service the packets received by popping out from rx_fifo; leave it to become full.
            - Verify that this interrupt pin goes high once the received fifo is full.
            '''
      stage: V2
      tests: ["usbdev_rx_full"]
    }
    {
      name: av_overflow
      desc: '''
            Verify that if a write was done to either the Available OUT Buffer FIFO or the Available
            SETUP Buffer FIFO when the FIFO was full the 'av_overflow' signal becomes high.

            - Fill both of the Available buffer FIFOs.
            - Choose at random whether to supply an additional OUT buffer or a SETUP buffer.
            - Attempt to write a buffer ID to the chosen FIFO.
            - Verify that this interrupt pin goes high indicating that the available fifo has
              reached the overflowing condition.
            '''
      stage: V2
      tests: ["usbdev_av_overflow"]
    }
    {
      name: link_in_err
      desc: '''
            Verify that if a packet to an IN endpoint started to be received but was then dropped due to an error
            then link_in_err will raise.

            - Send an IN token to the device for initiating an IN transaction.
            - The device should respond with an IN data packet.
            - DV environment returns an invalid crc16 or unexpected PID in the handshake packet.
            - Verify that the link_in_err interrupt goes high following the handshake packet sent by the host.
            '''
      stage: V2
      tests: ["usbdev_link_in_err"]
    }
    {
      name: rx_crc_err
      desc: '''
            Verify that if a CRC error occurred then rx_crc_err will raise.

            - Send a token/data packet to the device while intentionally corrupting any of the CRC bits.
            - Verify that the rx_crc_err goes high following the reception of the invalid packet.
            '''
      stage: V2
      tests: ["usbdev_rx_crc_err"]
    }
    {
      name: rx_pid_err
      desc: '''
            Verify that if an invalid packed identifier (PID) was received then rx_pid_err will raise.

            - Send an invalid PID to the device with the higher bits not complementing the lower bits.
            - Verify that the interrupt pin goes high indicating PID error.
            '''
      stage: V2
      tests: ["usbdev_rx_pid_err"]
    }
    {
      name: rx_bitstuff_err
      desc: '''
            Verify that if an invalid bit stuffing was received then rx_bitstuffing_err will raise.

            - generate a packet with 7 consecutive ones (bypassing bitstufffing) on data line.
            - Verify that the interrupt pin goes high indicating bitstuff error.
            '''
      stage: V2
      tests: ["usbdev_bitstuff_err"]
    }
    {
      name: link_out_err
      desc: '''
            Verify that if a packet to an OUT endpoint started to be received but was then dropped due to an error
            then link_out_err will raise.

            - send an out packet to the device with invalid crc, token, avbuffer_empty, rx_fifo full conditions.
            - Verify that the interrupt pin goes high indicating an error in the link in OUT transaction.
            '''
      stage: V2
      tests: ["usbdev_link_out_err"]
    }
    {
      name: enable
      desc: '''
            Verify that DUT connects to the USB when enable is set.

            - set USB_CTRL_enable pin high.
            - Make sure 'phy_config.pinflip' isn't set.
            - Verify that the 'usb_dp_pullup_o' pin goes high.
            '''
      stage: V2
      tests: ["usbdev_enable"]
    }
    {
      name: resume_link_active
      desc: '''
            Verify that the DUT moves from the LinkPowered state to the LinkResuming state in response to
            the 'resume_link_active' bit being set.

            - Disconnect VBUS.
            - Read the link state from `usbstat` register to see if it is in Disconnected state and
              restore VBUS and the pull up.
            - The DUT should move to the Powered state.
            - Send resume signaling (K state) for 20 ms and set the usbctrl.resume_link_active.
            - Verify that the DUT moves into the Resuming state and subsequently ActiveNoSOF.
            '''
      stage: V2
      tests: ["usbdev_resume_link_active"]
    }
    {
      name: device_address
      desc: '''
            Verify that the device ignores all packets with addresses that do not match the
            assigned device address.

            - Assign device address to (usbctrl[22:16]) and send packets to this address.
            - Send packets to other addresses.
            - Verify that the device responds to all packets sent by the DV environment (USB side)
              to the assigned address.
            - Verify that the device ignores all packets that are sent to other addresses.
            '''
      stage: V2
      tests: ["usbdev_device_address"]
    }
    {
      name: invalid_data1_data0_toggle_test
      desc: '''
            Verify the detection and reporting of unexpected Data Toggle bits.

            - Send a sequence of OUT data packets to the device without toggling between DATA0 and
              DATA1 PIDs in consecutive data packets.
            - Verify that the interrupt pin goes high indicating a link error during OUT
              transactions.
            '''
      stage: V2
      tests: ["usbdev_invalid_data1_data0_toggle_test"]
    }
    {
      name: setup_stage
      desc: '''
            Verify the SETUP stage of enumeration.

            - Send a setup token with a valid setup packet followed by a DATA0 packet requesting
              information about device i.e. descriptors.
            - Verify that the device ACKs the setup packet.
            '''
      stage: V2
      tests: ["usbdev_setup_stage"]
    }
    {
      name: endpoint_access
      desc: '''
            Verify the accessibility of all endpoints when endpoints are enabled.

            - Access all the endpoints of the device in IN and OUT direction by enabling ep_out_enable and
              ep_in_enable along with rxenable_out for OUT transaction.
            - Verify that the device allows access to all endpoints by responding with ACK for OUT
              accesses and data_packet for IN Accesses.
            '''
      stage: V2
      tests: ["usbdev_endpoint_access"]
    }
    {
      name: disable_endpoint
      desc: '''
            Verify that packet transmission (IN and SETUP) and reception requests (IN) are ignored when
            endpoints are disabled.

            - Disable an endpoint by clearing bit of ep_out_enable and ep_in_enable.
            - Then initiate an IN/OUT transaction to that endpoint.
            - Verify that the Out transactions as well as IN transactions sent to the device on the
              particular endpoint will be ignored.
            '''
      stage: V2
      tests: ["usbdev_disable_endpoint"]
    }
    {
      name: out_trans_nak
      desc: '''
            Verify the functionality of OUT transaction when rxenable_out is not set.

            - clear a particular endpoint bit for rx_enable_out register.
            - Then send an out transaction to that endpoint.
            - Verify that the OUT transactions shall be NAKED by OUT endpoints.
            '''
      stage: V2
      tests: ["usbdev_out_trans_nak"]
    }
    {
      name: setup_trans_ignored
      desc: '''
            Verify the functionality of SETUP transaction when rxenable_setup is not set.

            - clear a particular endpoint bit for rxenable_setup register.
            - Then send a setup transaction to that endpoint.
            - Verify that the SETUP transactions shall not be received by enabled OUT endpoints
              if rxenable_setup is not set.
            '''
      stage: V2
      tests: ["usbdev_setup_trans_ignored"]
    }
    {
      name: nak_trans
      desc: '''
            Verify the functionality of OUT transaction when set_nak_out is set.

            - Set_nak_out and rxenable_out are both set
            - Issue OUT transaction and observe it complete.
            - Observe rxenable_out cleared.
            - Issue OUT transaction and observe it get NAK'd.
            - Verify that the OUT transactions shall be NAKED for disabled endpoint and
              the corresponding bit in rxenable_out register will be cleared.
            '''
      stage: V2
      tests: ["usbdev_nak_trans"]
    }
    {
      name: stall_trans
      desc: '''
            Verify that enabling out_stall shall cause STALL response to
            attempted OUT transactions.

            - Set out_stall register bits for a particular transaction.
            - Verify that we will get STALL response when we try to attempt OUT transactions.
            '''
      stage: V2
      tests: ["usbdev_stall_trans"]
    }
    {
      name: setup_priority_over_stall_response
      desc: '''
            Verify that enabling STALL response does not prevent the reception of a SETUP
            transaction/packet. Receipt of the SETUP packet shall clear both the `in_stall` and
            the `out_stall` bits for that endpoint.

            - Configure an endpoint for stall response to OUT transactions and then send a SETUP
              transaction to the device on the stalled endpoint.
            - Verify that the SETUP transaction, being higher in priority, clears both in_stall and
              out_stall bits for that endpoint.
            '''
      stage: V2
      tests: ["usbdev_setup_priority_over_stall_response"]
    }
    {
      name: stall_priority_over_nak
      desc: '''
            Verify that if the configuration has both STALL and NAK enabled the STALL
            handshake will take priority.

            - Configure an endpoint with STALL as well as NAK responses then issue an OUT
              transaction to that endpoint.
            - Verify that the STALL being higher in priority will take precedence over NAK responses.
            '''
      stage: V2
      tests: ["usbdev_stall_priority_over_nak"]
    }
    {
      name: pending_in_trans
      desc: '''
            Verify that the a Link Reset or SETUP transaction cancels any waiting IN transactions
            by clearing the rdy bit in the configin register of all endpoints.

            - Configure an endpoint for transmission by setting fields in 'configin[ep]' register and
              then setting the 'rdy' bit to 1.
            - Send a SETUP transaction to that endpoint or issue a link reset.
            - Verify that the 'rdy' bit in 'configin[ep]' is cleared and the 'pend' bit is set to 1.
            '''
      stage: V2
      tests: ["usbdev_pending_in_trans"]
    }
    {
      name: streaming_test
      desc: '''
            Verify the streaming capability of an endpoint in OUT transaction mode.

            - Issue back to back data packets to a particular enabled endpoint.
            - Read the information from RX FIFO as soon as a packet is received
              along with the buffer in the SRAM.
            - Send the buffer ID back to Available buffer FIFO after successful buffer read.
            - Verify that the device is capable of handling the streaming traffic for a
              large number of iterations without Available OUT Buffer FIFO becoming empty or the
              RX FIFO becoming full.
            '''
      stage: V2
      tests: ["usbdev_streaming_out"]
    }
    {
      name: max_clock_error_untracked
      desc: '''
            Verify the functionality of DUT at maximum clock frequency deltas.
            This test does not attempt to model the adjustment of the usb_clk oscillator,
            in response to SOF packets received from the USB host, and therefore cannot
            support the full frequency mismatch required by the USB 2.0 protocol specification.

            - Clock the device and the agent with opposite extremes of allowable frequency
              ranges and initiate a transaction with maximum data length.
            - Verify that the transactions occur successfully between the device and host agent
              in both directions, and that all transmitted bytes are decoded correctly.
            - Verify that there are no reports of bit stuffing errors or CRC errors.
            '''
      stage: V2
      tests: ["usbdev_freq_loclk",
              "usbdev_freq_hiclk"]
    }
    {
      name: max_clock_error_tracking
      desc: '''
            Verify the functionality of DUT at maximum clock frequency difference, adjusting the
            frequency of 'usb_clk' in response to the arrival times of the SOF packets sent
            from the USB host agent.

            - Implement tracking of the SOF packets from the host, using the 'usb_ref_pulse_o'
              signal from the DUT to adjust the USB device clock.
            - With the USB host agent operating at the maximum frequency permissible within the
              USB 2.0 protocol specification, start the USB device operating at the minimum
              permissible frequency and check that SOF packets are still received and decoded
              correctly.
            - Check that the 'usb_ref_pulse_o' signal is produced as expected, and that the
              'usb_clk' signal increases in frequency to match that of the USB host agent.
            - Verify that full length packet transmission to and from the host occurs successfully
              without reports of bit stuffing errors or CRC errors.
            - Repeat the above with the USB host agent at the minimum permissible frequency and
              the USB device starting at the maximum frequecy.
            '''
      stage: V2
      tests: ["usbdev_freq_loclk_max",
              "usbdev_freq_hiclk_max"]
    }
    {
      name: max_phase_error
      desc: '''
            Verify that the device and host can work in different phase corners of the 48 MHz clock.

            - Clock the device and the agent with opposite corners of phases and initiate a
              transaction with maximum data length.
            - Verify that the transaction between the host agent and device must be successful by
              raising interrupts for succesful packet reception or transmission after the end
              of the transaction.
            '''
      stage: V2
      tests: ["usbdev_freq_phase"]
    }
    {
      name: min_inter_pkt_delay
      desc: '''
            Verify the minimum 2 bit times from the SE0-to-J transition (from EOP) to the
            J-to-K transition.

            - Send at random either a SETUP token packet or an OUT token packet to the DUT.
            - After just 2 bit intervals of Idle state, transmit a DATA packet to the DUT.
            - Verify that the packet is received, decoded correctly and ACKnowledged by the DUT.
            '''
      stage: V2
      tests: ["usbdev_min_inter_pkt_delay"]
    }
    {
      name: max_inter_pkt_delay
      desc: '''
            Verify the maximum 7.5 bit times from the SE0-to-J transition (from EOP) to
            the J-to-K transition.

            - Send at random either a SETUP token packet or an OUT token packet to the DUT.
            - After 7.5 bit intervals of Idle state, transmit a DATA packet to the DUT.
            - Verify that the packet is received, decoded correctly and ACKnowledged by the DUT.
            '''
      stage: V2
      tests: ["usbdev_max_inter_pkt_delay"]
    }
    {
      name: device_timeout_missing_host_handshake
      desc: '''
            Verify that the device times out an IN transaction if it does not receive a
            handshake response from the host.

            - Configure the DUT to present a single packet for IN collection.
            - Collect a non-Isochronous IN packet from the DUT but do not send a handshake packet.
            - Host sends a random choice of SETUP, OUT or IN token packet to the DUT.
            - Check that the packet is still marked as 'rdy' and that 'in_sent' is not set.
            - Retry the IN packet collection and this time send the ACK handshake within the normal
              response period.
            - Check that that packet is collected, that 'rdy' is cleared and that the
              'in_sent' register bit indicates successful transmission of the packet.
            '''
      stage: V2
      tests: ["usbdev_timeout_missing_host_handshake"]
    }
    {
      name: device_timeout
      desc: '''
            Verify that the device times out transactions when a host response is 18 bit times
            after the packet transmitted by the DUT.

            - Configure the DUT to present a single packet for IN collection.
            - Collect a non-Isochronous IN packet from the DUT but do not send a handshake packet
              in response within 18 bit intervals.
            - Check that the packet is still marked as 'rdy' and that 'in_sent' is not set.
            - Send a delayed ACKnowledge handshake packet to the DUT.
            - Check that the packet is still marked as 'rdy' and that 'in_sent' is not set.
            - Retry the IN packet collection and this time send the ACK handshake within the normal
              response period.
            - Check that that packet is collected, that 'rdy' is cleared and that the
              'in_sent' register bit indicates successful transmission of the packet.
            '''
      stage: V2
      tests: ["usbdev_device_timeout"]
    }
    {
      name: packet_buffer
      desc: '''
            Exercise all buffers within the packet buffer memory, performing reads and writes of
            packet buffer data from both sides (CSR and USB) simultaneously.

            - Randomly choose between IN and OUT packet transfer on the USB side.
            - Randomly choose between buffer read and buffer write on the CSR side.
            - Ensure, however, that the CSR side and the USB side never access the same buffer
              simultaneously; this is guaranteed by the contract that exists between hardware and
              software.
            - Check all transferred data on both sides.
            - Ensure that it is possible for individual read and write accesses to occur at the
              packet buffer memory from both sides within the same cycle.
              Since the packet buffer memory is now a Single Port RAM implementation, this requires
              the CSR-side access to be delayed until the USB side is idle.
            '''
      stage: V2
      tests: ["usbdev_pkt_buffer"]
    }
    {
      name: nak_to_out_trans_when_avbuffer_empty_rxfifo_full
      desc: '''
            Verify that the device sends out NAK responses to OUT transactions when
            available buffer is empty and RX FIFO is full.

            - send out packets to the device at such a rate that avbuffer gets empty and
              RX Fifo becomes full.
            - Verify that the device unable to consume packets at such a rate will set NAK
              responses even though endpoint is enabled.
            '''
      stage: V2
      tests: ["usbdev_nak_to_out_trans_when_avbuffer_empty_rxfifo_full"]
    }
    {
      name: aon_wake_resume
      desc: '''
            Verify that the AON/Wake module is able to detect Resume Signaling and indicate that
            via the USB device register interface.

            - Connect the USB device to the USB host model.
            - Send Suspend Signaling to the USB device.
            - Verify that the 'link_suspend' interrupt is raised indicating that the USB has been
              Idle (J) for at least 3ms.
            - Enable the AON/Wake module, leaving it to maintain the pull up state.
            - Initiate Resume Signaling, driving the USB into the 'K' state.
            - Check that the 'wake_req_aon_o' signal from the 'usbdev_aon_wake' module becomes
              asserted.
            - Read from the 'wake_events' CSR of the USB device and check that the 'bus_not_idle'
              bit is asserted.
            - Disable the AON/Wake module and verify that the USB device is still connected,
              ie. the DP pullup is enabled and DP is high.
            '''
      stage: V2
      tests: ["usbdev_aon_wake_resume"]
    }
    {
      name: aon_wake_reset
      desc: '''
            Verify that the AON/Wake module is able to detect Reset Signaling and indicate that
            via the USB device register interface.

            - Connect the USB device to the USB host model.
            - Enable the AON/Wake module, leaving it to maintain the pull up state.
            - Perform a Bus Reset, driving SE0 state onto the USB for at least 10us; the
              specification requires at least 10ms of Reset Signaling for a full reset, but the
              AON/Wake module should respond a lot faster, to allow time for chip start up and
              software reinitialization.
            - Check that the 'wake_req_aon_o' signal from the 'usbdev_aon_wake' module becomes
              asserted.
            - Read from the 'wake_events' CSR of the USB device and check that the 'bus_reset'
              bit is asserted.
            - Disable the AON/Wake module and verify that the USB device is still connected,
              ie. the DP pullup is enabled and DP is high.
            '''
      stage: V2
      tests: ["usbdev_aon_wake_reset"]
    }
    {
      name: aon_wake_disconnect
      desc: '''
            Verify that the AON/Wake module is able to detect Bus Disconnection and indicate that
            via the USB device register interface.

            - Connect the USB device to the USB host model.
            - Enable the AON/Wake module, leaving it to maintain the pull up state.
            - Verify that the DP pull up remains asserted, indicating the presence of the device
              on the USB.
            - Lower the VBUS/SENSE signal.
            - Check that the 'wake_req_aon_o' signal from the 'usbdev_aon_wake' module becomes
              asserted.
            - Read from the 'wake_events' CSR of the USB device and check that the 'disconnected'
              bit is asserted.
            - Check that the DP pull up is no longer asserted; it shall be dropped by the
              usbdev_aon_wake module to protect against spurious reconnection.
            - Disable the AON/Wake module and verify that the USB device remains disconnected.
            '''
      stage: V2
      tests: ["usbdev_aon_wake_disconnect"]
    }
    {
      name: invalid_sync
      desc: '''
            Randomized interspersing of valid and invalid USB traffic. Generate bit-level changes
            on the USB that do not constitute valid SYNC signaling, interspersed with valid USB
            traffic to/from the device.

            - Set up the device with a single IN and a single OUT endpoint.
            - Fully populate the Available OUT Buffer FIFO.
            - Stream and check known traffic to (OUT) and from (IN) the device, with the CSR
              side simply returning unmodified every OUT packet that is received.
            - Randomly select whether to send an OUT packet, request an IN packet or generate
              invalid noise (never including a valid SYNC signal) on the USB.
            - Verify that all data has been streamed successfully, and that the USB device continued
              to operate correctly, ignoring all of the invalid signaling.
            '''
      stage: V2
      tests: ["usbdev_invalid_sync"]
    }
    {
      name: spurious_pids_ignored
      desc: '''
            Check that the device ignores packets with unexpected tokens such as NYET, PRE...
            Also test ACK and NAK when not in response to a transmitted IN packet.

            - Randomly transmit valid token packets that use unexpected/unsupported PIDs and,
              in the case of ACK/NAK handshake packet that are out of sequence.
            - This is important in ensuring that the USB device/communications does not fail in
              the event of host handshake responses (to IN packets) being delayed.
            - Test all possible PIDs other than SETUP, OUT and IN, including invalid PIDs where
              the lower and upper nibbles are not complementary, and DATA0 and DATA1 PIDs without
              a preceding SETUP, OUT or IN token packet.
            '''
      stage: V2
      tests: ["usbdev_spurious_pids_ignored"]
    }
    {
      name: low_speed_traffic
      desc: '''
            Test that Low Speed traffic on the bus in the downstream direction is appropriately
            ignored and does not cause the USB device to enter an invalid state.
            Background: Hubs are permitted to propagate downstream Low Speed signaling to Full
            Speed devices on other ports.

            - Connect the USB device, with a SETUP- and OUT-capable endpoint.
            - Repeatedly generate and check valid SETUP and OUT packets at Full Speed signaling
              speeds, whilst interspersing Full Speed traffic that consists of PRE tokens followed
              by randomized packet contents at Low Speed signaling.
            - Check that the USB device receives correctly all of the SETUP and OUT packets and is
              unaffected by the Low Speed signaling.
            - In particular, check that it does not generate unexpected interrupts because these
              could devalue the diagnostic use of those interrupts in detecting and reporting
              unreliable connections.
            '''
      stage: V2
      tests: ["usbdev_low_speed_traffic"]
    }
    {
      name: rand_bus_resets
      desc: '''
            Ensure that all of SETUP, OUT and IN traffic are robust against randomized
            bus resets from the USB and that communications may successfully be resumed after
            subsequent reconfiguration.

            - Configure the USB device to receive SETUP, OUT and IN traffic (the regular
              Default Pipe, ie. just Endpoint Zero, should suffice).
            - During the process of normal device configuration, issue a Bus Reset to the device at
              a random time (ensuring that it may occur during all transaction types), and then
              restart the configuration, checking that it completes successfully this time when no
              reset occurs.
            - The intention is to ensure that the internal state machines and logic do not get
              stuck or hold persistent inappropriate state.
            '''
      stage: V2
      tests: ["usbdev_rand_bus_resets"]
    }
    {
      name: rand_disconnects
      desc: '''
            Ensure that all of SETUP, OUT and IN traffic are robust against randomized
            disconnection of the USB and that communications may successfully be resumed after a
            bus reset and reconfiguration. (The bus reset should occur have a disconnection that
            was host-initiated, and before configuration traffic commences.)

            - Configure the USB device to receive SETUP, OUT and IN traffic (the regular
              Default Pipe, ie. just Endpoint Zero should suffice).
            - During the process of normal device configuration, disconnect the USB at a random
              time (ensuring that it may occur during all transaction types), and then restart
              the configuration after a Bus Reset and check that
              configuration completes successfully this time when no disconnection occurs.
            '''
      stage: V2
      tests: ["usbdev_rand_bus_disconnects"]
    }
    {
      name: rand_suspends
      desc: '''
            Deriving from the sequence 'usbdev_max_usb_traffic' ensure that traffic can be streamed
            back and forth successfully with the device being randomly suspended and resumed.
            '''
      stage: V2
      tests: ["usbdev_rand_suspends"]
    }
    {
      name: max_usb_traffic
      desc: '''
            Verify operation under maximal traffic to maximal endpoints, exercising all transfer
            types and all packet lengths, with randomized delays on the CSR side when receiving
            packets, supplying packets, making buffers available for use, and responding to
            interrupts.
            '''
      stage: V2
      tests: ["usbdev_max_usb_traffic"]
    }
    {
      name: stress_usb_traffic
      desc: '''
            Derived from 'max_usb_traffic' this also randomly introduces unexpected token packets,
            low speed traffic, invalid traffic, bus resets and disconnects, to ensure that these do
            not interfere with the transmission and reception of valid traffic.
            '''
      stage: V2
      tests: ["usbdev_stress_usb_traffic"]
    }
    {
      name: in_packet_retraction
      desc: '''
            Exercise retraction of IN packets for Isochronous streams, prioritizing the delivery of
            the most recent data over the reliable delivery of all data presented.

            - Configure a single IN endpoint for Isochronous support.
            - Repeatedly poll for and collect IN packets from the USB host model, randomizing the
              delays between collection attempts.
            - Present a stream of Isochronous packets on the IN endpoint, with each packet containing
              a serial number. Randomize the times between packet presentations, and keep on the CSR
              side a record of which packets were retracted/overwritten rather than being transmitted
              successfully to the host.
            - Check that the CSR side and the USB host model agree on which packets were successfully
              transmitted from the device to the host.
            '''
      stage: V2
      tests: ["usbdev_iso_retraction"]
    }
    {
      name: data_toggle_restore
      desc: '''
            Verify that each of the IN and OUT Data Toggle bits may be both set and cleared by
            software to ensure that resuming communications after returning from Deep Sleep
            is possible.

            - Ensure that the USB device disconnected (pull up not enabled) such that no
              communications shall occur with the device.
            - Set all of the even-numbered OUT Data Toggle bits to 1 and all of the odd-numbered
              OUT Data Toggle bits to 0.
            - Check that the OUT Data Toggle bits read as 0x555.
            - Set all of the even-numbered IN Data Toggle bits to 0 and all of the odd-numbered
              IN Data Toggle bits to 1.
            - Check that the IN Data Toggle bits read as 0xAAA.
            - Check that the OUT Data Toggle bits read as 0x555.
            - Invert all of the OUT Data Toggle bits.
            - Invert all of the IN Data Toggle bits.
            - Check that the OUT Data Toggle bits read as 0xAAA.
            - Check that the IN Data Toggle bits read as 0x555.
            - Set all of the OUT Data Toggle bits to random values.
            - Set all of the IN Data Toggle bits to random values.
            - Check that all of the OUT and IN Data Toggle bits read back as expected.
            - Test the interaction of USB traffic with the IN and OUT Data Toggle bits, but note
              that data toggle bits may only be toggled safely between packets.
            '''
      stage: V2
      tests: ["usbdev_data_toggle_restore"]
    }
    {
      name: setup_priority
      desc: '''
            Verify that the final slot of the Rx FIFO is reserved for use by SETUP packets only.
            The final slot of the Rx FIFO buffer shall never be assigned to an OUT DATA packet
            because it could force the USB device to be unresponsive to a SETUP DATA packet.

            - Configure the USB device to receive SETUP packets on Endpoint Zero.
            - Configure endpoint 1 to receive OUT DATA packets.
            - Place 1 buffer in the Available SETUP Buffer FIFO.
            - Place 8 buffers in the Available OUT Buffer FIFO.
            - Transmit 7 OUT DATA packets to endpoint 1, checking that each packet is
              ACKed, but do not read from Rx FIFO.
            - Check that the Rx FIFO contains 7 buffers.
            - Transmit 1 OUT DATA packet to endpoint 1.
            - Verify that the OUT DATA packet is NAKed as expected.
            - Check that the Rx FIFO depth is still 7.
            - Transmit a SETUP DATA packet to Endpoint Zero, checking that the packet is ACKed.
            - Check that the Rx FIFO depth is now 8.
            - Read the packets from the Rx FIFO, checking the properties of each of the 7 OUT
              DATA packets and the final 1 SETUP DATA packet in turn.
            '''
      stage: V2
      tests: ["usbdev_setup_priority"]
    }
    {
      name: fifo_resets
      desc: '''
            Test the software-controlled FIFO reset functionality, introduced as a contingency
            for error recovery and to permit reconfiguration of the USB device hardware without
            resorting to use of the block-level asynchronous reset.

            - Populate the USBDEV FIFOs with packets randomly.
            - Choose a random set of FIFOs to reset.
            - Check the FIFO levels match expectations.
            - Note: the handling of the Received Buffer FIFO requires configuration of,
              and transmission of packets to, the USB device since there is no direct means
              to inject packets from the CSR side.
            '''
      stage: V2
      tests: ["usbdev_fifo_rst"]
    }
    {
      name: dpi_config_host
      desc: '''
            Using the DPI model run the DUT through a typical configuration sequence consisting of
            Control Transfers that mimic the behavior of a physical USB host controller.

            - Connect the DUT to the USB and perform a Bus Reset.
            - Set up endpoint zero and read the Device Descriptor.
            - Set the device address.
            - Read the configuration descriptor.
            - Set the configuration.
            '''
      stage: V3
      tests: ["usbdev_dpi_config_host"]
    }
  ]

  covergroups: [
    {
      name: pids_cg
      desc: '''
        Observe all PIDs about which we care; a number of the available PIDs are ignored by the USB
        device because they related only to High Speed operation and/or hubs.
      '''
    }
    {
      name: framenum_rx_cg
      desc: '''
        Observe all significant/extreme frame numbers being reported via CSRs; this just ensures
        that all bits have been decoded and presented; the frame number has no significance to
        USBDEV but it's important to software.
      '''
    }
    {
      name: crc16_cg
      desc: '''
        CRC16 values on packets in each direction, because CRC16 is subject to bit stuffing.
      '''
    }
    {
      name: crc5_cg
      desc: '''
        Check some potentially problematic cases for bit stuffing with CRC5 in Token packets.
      '''
    }
    {
      name: address_cg
      desc: '''
        Check that all Device Address bits are decoded and usable and that those problematic
        combinations with endpoint values that demand bit stuffing within the token packet have
        been observed.
      '''
    }
    {
      name: ep_out_cfg_cg
      desc: '''
        Receipt of SETUP, OUT and PRE packets with different OUT endpoint configurations
      '''
    }
    {
      name: ep_in_cfg_cg
      desc: '''
        Receipt of IN and PRE packets with different IN endpoint configurations
      '''
    }
    {
      name: fifo_lvl_cg
      desc: '''
        Received SETUP/OUT packets with FIFO levels of interest
      '''
    }
    {
      name: data_pkt_cg
      desc: '''
        Length of DATA packets in each direction
      '''
    }
    {
      name: data_tog_endp_cg
      desc: '''
        Both DATA0 and DATA1 for each endpoint, and in each direction (Data Toggles), as well as
        both ACK and NAK (rollback and retry transaction in Packet Engines).
      '''
    }
    {
      name: pid_type_endp_cg
      desc: '''
        All of SETUP, IN, and OUT for each endpoint
      '''
    }


  ]

}