cocotb_usb module reference

Descriptors

This module provides classes for standard USB descriptors and requests.

class cocotb_usb.descriptors.Descriptor

Base class for storing common descriptor elements.

get()

Return descriptor contents as a list of bytes.

class cocotb_usb.descriptors.DeviceDescriptor(bLength, bcdUSB, bDeviceClass, bDeviceSubClass, bDeviceProtocol, bMaxPacketSize0, idVendor, idProduct, bcdDevice, iManufacturer, iProduct, iSerialNumber, bNumConfigurations, bDescriptorType=1)

Class representing USB device descriptor.

class cocotb_usb.descriptors.EndpointDescriptor(bLength, bEndpointAddress, bmAttributes, wMaxPacketSize, bInterval, bDescriptorType=5)

Class representing standard USB endpoint descriptor.

class cocotb_usb.descriptors.InterfaceDescriptor(bLength, bInterfaceNumber, bAlternateSetting, bNumEndpoints, bInterfaceClass, bInterfaceSubclass, bInterfaceProtocol, iInterface, bDescriptorType=4, subdescriptors=[])

Class representing standard USB interface descriptor.

class cocotb_usb.descriptors.ConfigDescriptor(bLength, wTotalLength, bNumInterfaces, bConfigurationValue, iConfiguration, bmAttributes, bMaxPower, bDescriptorType=2, interfaces=[])

Class representing standard USB configuration descriptor.

Can also represent OTHER_SPEED_CONFIGURATION descriptor, as they have identical contents.

class cocotb_usb.descriptors.StringDescriptorZero(wLangIdList, bLength=None, bDescriptorType=3)

Class representing USB string descriptor with index 0.

This one is different than other string descriptors in that it contains an array of supported LanguageIds instead of an actual string.

class cocotb_usb.descriptors.StringDescriptor(bString, bLength=None, bDescriptorType=3)

Class representing standard USB string descriptor.

class cocotb_usb.descriptors.DeviceQualifierDescriptor(bcdUSB, bDeviceClass, bDeviceSubClass, bDeviceProtocol, bMaxPacketSize0, bNumConfigurations, bLength=10, bDescriptorType=6)

Class representing standard USB device qualifier descriptor.

class cocotb_usb.descriptors.USBDeviceRequest(bmRequestType, bRequest, wValue, wIndex, wLength, data=None)

Class grouping common USB request definitions.

build(bRequest, wValue, wIndex, wLength)

Create a USB request with provided values.

>>> USBDeviceRequest.build(
... bmRequestType=0x00,
... bRequest=0x05,
... wValue=0x02,
... wIndex=0x00,
... wLength=0x00)
[0, 5, 2, 0, 0, 0, 0, 0]
cocotb_usb.descriptors.setAddressRequest(address)

Create a standard SET_ADDRESS USB request.

Parameters:address (int) – Address to be set. Should be below 128. 
>>> setAddressRequest(0x30)
[0, 5, 48, 0, 0, 0, 0, 0]
cocotb_usb.descriptors.getDescriptorRequest(descriptor_type, descriptor_index, lang_id, length)

Create a standard GET_DESCRIPTOR USB request.

Parameters:
  • descriptor_type (int) – Type of the descriptor as per USB specification.
  • descriptor_index (int) – Index of descriptor to be read.
  • lang_id (int) – LangId of descriptor to be read or 0 if unspecified.
  • length (int) – Number of bytes requested.
 
>>> getDescriptorRequest(
... descriptor_type=2,
... descriptor_index=1,
... lang_id=0,
... length=9
... )
[128, 6, 1, 2, 0, 0, 9, 0]
cocotb_usb.descriptors.setConfigurationRequest(configuration)

Create a standard SET_CONFIGURATION USB request.

Parameters:configuration (int) – Configuration value to be set. Should be below 256. 
>>> setConfigurationRequest(3)
[0, 9, 3, 0, 0, 0, 0, 0]
cocotb_usb.descriptors.setFeatureRequest(feature_selector, recipient, target=0, test_selector=0)

Create a standard SET_FEATURE USB request.

Parameters:
  • feature_selector (int) – Feature selector as defined in USB specification.
  • recipient (int) – One of Device (0), Interface (1) or Endpoint (2).
  • target (int) – Number of interface or endpoint.
  • test_selector (int) – Test mode selector, valid only for TEST_MODE feature selector.
 
>>> setFeatureRequest(
... feature_selector=0,
... recipient=0)
[0, 3, 0, 0, 0, 0, 0, 0]

Supported USB device classes

DFU

class cocotb_usb.descriptors.dfu.DfuAttributes

Class for storing common DFU descriptor attributes.

class cocotb_usb.descriptors.dfu.DfuFunctionalDescriptor(bmAttributes, wDetachTimeout, wTransferSize, bcdDFUVersion, bLength=9, bDescriptorType=33)

Class for storing functional descriptor of DFU.

class cocotb_usb.descriptors.dfu.DfuRequest(bmRequestType, bRequest, wValue, wIndex, wLength, data=None)

Base class for DFU requests.

cocotb_usb.descriptors.dfu.parseDfuFunctional(f)

Parser function to read values of supported DFU descriptors for the device from config file.

Parameters:field – JSON structure for this class to be parsed.

CDC

class cocotb_usb.descriptors.cdc.CDC

Base class for storing common CDC definitions.

class cocotb_usb.descriptors.cdc.Header(bcdCDC, bLength=5, bDescriptorType=36, bDescriptorSubtype=0)

Descriptor representing start of CDC class-specific section.

class cocotb_usb.descriptors.cdc.CallManagement(bmCapabilities, bDataInterface, bLength=5, bDescriptorType=36, bDescriptorSubtype=1)

Describes call processing for the Communication interface. See section 5.2.3.2 of CDC specification for details.

class cocotb_usb.descriptors.cdc.AbstractControlManagement(bmCapabilities, bLength=4, bDescriptorType=36, bDescriptorSubtype=2)

Describes commands supported by the ACM subclass. See section 5.2.3.3 of CDC specification for details.

class cocotb_usb.descriptors.cdc.DirectLineManagement(bmCapabilities, bLength=4, bDescriptorType=36, bDescriptorSubtype=3)

Describes commands supported by the DLCM subclass. See section 5.2.3.4 of CDC specification for details.

class cocotb_usb.descriptors.cdc.Union(bMasterInterface, bSlaveInterface_list, bDescriptorType=36, bDescriptorSubtype=6)

This descriptor enables grouping interfaces that can be treated as a functional unit. See section 5.2.3.8 of CDC specification for details.

cocotb_usb.descriptors.cdc.parseCDC(field)

Parser function to read values of supported CDC descriptors for the device from config file.

Parameters:field – JSON structure for this class to be parsed.
class cocotb_usb.descriptors.cdc.CDCRequest

Class grouping selected CDC request definitions.

cocotb_usb.descriptors.cdc.sendEncapsulatedCommand(interface, data_len)

Return a byte list corresponding to a SET_CONTROL_LINE_STATE request.

Parameters:
  • interface (int) – Target interface number.
  • data_len (int) – Length of data to be transferred.
 
>>> sendEncapsulatedCommand(
... interface=1,
... data_len=16
... )
[33, 0, 0, 0, 1, 0, 16, 0]
cocotb_usb.descriptors.cdc.getEncapsulatedResponse(interface, data_len)

Return a byte list corresponding to a SET_CONTROL_LINE_STATE request.

Parameters:
  • interface (int) – Target interface number.
  • data_len (int) – Length of data to be received.
 
>>> getEncapsulatedResponse(
... interface=3,
... data_len=32
... )
[161, 1, 0, 0, 3, 0, 32, 0]
class cocotb_usb.descriptors.cdc.LineCodingStructure(dwDTERate, bCharFormat, bParityType, bDataBits)

Structure for storing line coding setting for use with SET_LINE_CODING and GET_LINE_CODING requests.

Parameters:
  • dwDTERate (int) – Data terminal rate, in bits per second.
  • bCharFormat (int) – How many stop bits to use.
  • bParityType (int) – Parity type.
  • bDataBits (int) – How many data bits are used.
classmethod size()
>>> LineCodingStructure.size()
7
get()

Return structure contents as a list of bytes.

>>> l = LineCodingStructure(
... dwDTERate=115200,
... bCharFormat=LineCodingStructure.STOP_BITS_1,
... bParityType=LineCodingStructure.PARITY_ODD,
... bDataBits=LineCodingStructure.DATA_BITS_8
... )
>>> l.get()
[0, 194, 1, 0, 0, 1, 8]
cocotb_usb.descriptors.cdc.setLineCoding(interface)

Return a byte list corresponding to a SET_CONTROL_LINE_STATE request. See LineCodingStructure for defined parameters.

Parameters:
  • interface (int) – Target interface number.
  • data_len (int) – Length of data structure to be transferred.
 
>>> setLineCoding(interface=5)
[33, 32, 0, 0, 5, 0, 7, 0]
cocotb_usb.descriptors.cdc.getLineCoding(interface)

Return a byte list corresponding to a GET_CONTROL_LINE_STATE request. See LineCodingStructure for defined parameters.

Parameters:interface (int) – Target interface number. 
>>> getLineCoding(interface=2)
[161, 33, 0, 0, 2, 0, 7, 0]
cocotb_usb.descriptors.cdc.setControlLineState(interface, rts, dtr)

Return a byte list corresponding to a SET_CONTROL_LINE_STATE request.

Parameters:
  • interface (int) – Target interface number.
  • rts (bool) – Whether to set RTS line to 1 (True) or 0 (False).
  • dtr (bool) – Whether to set DTR line to 1 (True) or 0 (False).
 
>>> setControlLineState(0, 1, 1)
[33, 34, 3, 0, 0, 0, 0, 0]

>>> setControlLineState(3, 1, 0)
[33, 34, 2, 0, 3, 0, 0, 0]

>>> setControlLineState(5, 0, 1)
[33, 34, 1, 0, 5, 0, 0, 0]

Clocks and triggers

This module provides extended cocotb classes for unprecise and drifting clocks.

class cocotb_usb.clocks.UnstableTrigger(time_ps, delta_neg, delta_pos, units=None)

A trigger with uncertainty within defined range.

prime(callback)

Register for a timed callback.

class cocotb_usb.clocks.UnstableClock(signal, period, jitter_neg, jitter_pos, units=None)

A 50:50 duty cycle clock driver with added jitter.

Parameters:
  • signal – The clock pin/signal to be driven.
  • period (int) – The clock period. Must convert to an even number of timesteps.
  • jitter_neg (int) – Maximum negative jitter.
  • jitter_pos (int) – Maximum positive jitter.
  • units (str, optional) – One of None, 'fs', 'ps', 'ns', 'us', 'ms', 'sec'. When no units is given (None) the timestep is determined by the simulator.
start(cycles=None, start_high=True)

Clocking coroutine. Start driving your clock by forking a call to this.

Parameters:
  • cycles (int, optional) – Cycle the clock cycles number of times, or if None then cycle the clock forever. Note: 0 is not the same as None, as 0 will cycle no times.
  • start_high (bool, optional) – Whether to start the clock with a 1 for the first half of the period. Default is True.

Device

This module provides a class for containing the set of USB descriptors for a given device.

The descriptors are read from a JSON file. See here for its structure.

class cocotb_usb.device.UsbDevice(config_file)

Object for storing USB descriptors information in a structured manner

Parameters:config_file (path) – JSON file containing descriptor values.

Host

This module provides classes that imitate USB host for tests, abstract lower levels of USB communication and verify the device responses.

class cocotb_usb.host.UsbTest(dut, **kwargs)

Base class for communicating with a USB test bench.

Parameters:
  • dut – Object under test as passed by cocotb.
  • decouple_clocks (bool, optional) – Indicates whether host and device share clock signal. If set to False (default), you must provide clk48_device clock in test.
reset()

Reset DUT.

wait(time, units='us')

Simple wait function with heartbeat messages. This is suitable for longer waits (i.e. bus reset) to make sure simulation still proceeds.

Parameters:
  • time (int) – Time to wait.
  • units (str, optional) – One of None, 'fs', 'ps', 'ns', 'us', 'ms', 'sec'. When no units is given (None) the timestep is determined by the simulator.
port_reset(time=10000.0, recover=False)

Send USB port reset - SE0 condition. According to USB Specification section 11.5.1.5, the duration of the Resetting state is nominally 10 ms to 20 ms (10 ms is preferred).

Parameters:
  • time (int, optional) – Duration of reset in us.
  • recover (bool, optional) – Wait for allowed recovery period (10 ms) after reset.
connect()

Simulate FS connect to DUT - DP pulled high.

disconnect()

Simulate device disconnect, both lines pulled low.

host_send(data01, addr, epnum, data, expected=<PID.ACK: 2>)

Send data out the virtual USB connection, including an OUT token.

host_setup(addr, epnum, data)

Send data out the virtual USB connection, including a SETUP token.

host_recv(data01, addr, epnum, data)

Send data out the virtual USB connection, including an IN token.

host_expect_ack()

Expect an ACK packet.

host_expect_nak()

Expect a NAK packet.

host_expect_stall()

Expect a STALL packet.

host_expect_data_packet(pid, data)

Expect to receive a data packet.

Parameters:
  • pid – Either PID.DATA0 or PID.DATA1.
  • data – Expected values as list of bytes.
control_transfer_out(addr, setup_data, descriptor_data=None)

Perform an OUT control transfer.

Parameters:
  • addr (int) – Device address.
  • setup_data – Request to be sent, as list of bytes.
  • descriptor_data (optional) – Data to be sent, as list of bytes.
control_transfer_in(addr, setup_data, descriptor_data=None)

Perform an IN control transfer.

Parameters:
  • addr (int) – Device address.
  • setup_data – Request to be sent, as list of bytes.
  • descriptor_data (optional) – Data expected to be received, as list of bytes.
set_device_address(address, skip_recovery=False)

Set USB device address. After the transaction host will wait for 2 ms recovery period, during which device is not required to respond.

Parameters:
  • address (int) – Value to be set.
  • skip_recovery (bool, optional) – Skip the recovery period wait.
get_device_descriptor(response, length=18)

Read the device descriptor from DUT.

Parameters:response – Expected descriptor contents as list of bytes.
get_configuration_descriptor(length, response)

Read a configuration descriptor from DUT.

Parameters:
  • length (int) – Number of bytes to be read.
  • response – Expected descriptor contents as list of bytes.
get_string_descriptor(lang_id, idx, response, length=255)

Read a string descriptor from DUT.

Parameters:
  • lang_id (int) – Language ID of descriptor.
  • idx (int) – Descriptor index.
  • response – Expected descriptor contents as list of bytes.
get_device_qualifier(length, response)

Read a device qualifier descriptor from DUT.

Parameters:
  • length (int) – Number of bytes to be read.
  • response – Expected descriptor contents as list of bytes.
set_configuration(idx)

Send a SET_CONFIGURATION standard device request to DUT.

Parameters:idx (int) – Configuration number to be set.
class cocotb_usb.host_valenty.UsbTestValenty(dut, csr_file, **kwargs)

Class for testing ValentyUSB IP core. Includes functions to communicate and generate responses without a CPU, making use of a Wishbone bridge.

Parameters:
  • dut – Object under test as passed by cocotb.
  • csr_file (str) – Path to a CSV file containing CSR register addresses, generated by Litex.
  • decouple_clocks (bool, optional) – Indicates whether host and device share clock signal. If set to False, you must provide clk48_device clock in test.
reset()

Reset DUT.

connect()

Simulate FS connect to DUT - DP pulled high.

disconnect()

Simulate device disconnect, both lines pulled low.

control_transfer_out(addr, setup_data, descriptor_data=None)

Perform an OUT control transfer.

Parameters:
  • addr (int) – Device address.
  • setup_data – Request to be sent, as list of bytes.
  • descriptor_data (optional) – Data to be sent, as list of bytes.
control_transfer_in(addr, setup_data, descriptor_data=None)

Perform an IN control transfer.

Parameters:
  • addr (int) – Device address.
  • setup_data – Request to be sent, as list of bytes.
  • descriptor_data (optional) – Data expected to be received, as list of bytes.
set_device_address(address)

Set USB device address. After the transaction host will wait for 2 ms recovery period, during which device is not required to respond.

Parameters:
  • address (int) – Value to be set.
  • skip_recovery (bool, optional) – Skip the recovery period wait.

Monitor

This module provides an object that checks the bus state and returns detected packets.

class cocotb_usb.monitor.UsbMonitor(*args, **kwargs)

USB bus monitor.

Listens for SYNC token then tries to capture the following frame up to EOP.

Parameters:oversampling (int) – How many times the signal is sampled on each cycle.
prime()

Notify the object that a transaction is expected

Harness

This module provides a function for dynamically assigning a test harness.

cocotb_usb.harness.get_harness(dut, **kwargs)

Helper function to assign test harness object. Object is chosen using TARGET environment variable.