hwtLib.peripheral.usb package

This package contains components, interfaces, data types and other utils related to Universal Serial Bus (USB) protocol.

The USB bus is composed of Host (the main device which controls the bus), Hub(s) (a port extender) and a Device(s). The USB protocol stack (v3.2) is composed of multiple layers as depicted in:

_images/USB-Protocol-Stack-V3.png

  • Functional Layer:

    • This layer generates requests which are converted into transactions containing different packets. It also manages end to end data flow between host and device.

Protocol Layer:

  • Packets originates at transmit part of protocol layer and terminates at receive part of protocol layer. It has various functions which include following.

    • Ensure end to end reliability of packets.

    • Ensure effective management of power.

    • Ensure effective use of Bandwidth.

Link Layer:

  • This layer manages port to port flow of data between USB host and device. Link layer commands ensure link level data integrity, flow control and power management. This layer handles packet acknowledgement and takes care of error recovery. The Link Layer also handles Header Packet Framing. Its functions are similar to MAC layer of OSI model.

Physical Layer:

note:

USB Documentation, Christopher D. Leary and Devrin TalenDecember 17, 2007

Bus Enumeration

  1. Host waits for at least 100 ms to account for the insertion process.

  2. Host resets the device. Device should now be at address 0 and the defaultcontrol pipe will be open (default state).

  3. Host queries the device descriptor from the devices default control pipe.

  4. The host controller assigns a unique address to the device.

  5. Host queries all configuration descriptors from the device, then sets one.At this point, the device will begin to draw the amount of power requestedby the assigned interface.

  6. Host queries all other remaining descriptors (interface, endpoint, etc.) andsets up any requested interrupt transfers.

USB Endpoints

In the USB specification, a device endpoint is a uniquely addressable portion of a USB device that is the source or sink of information in a communication flow between the host and device. The Ep0 has is dedicated to control and and it provides descriptors for other endpoints.

The Endpoints may support following types of transfer:

  • Control

  • Interrupt

  • Bulk

  • Isochronous

_images/usb_transaction_example.png

Similar projects: * https://github.com/WangXuan95/FPGA-USB-Device * https://github.com/im-tomu/valentyusb USB stack written in LiteX * https://github.com/SinSiXX/luna-1 usb sniffer

Subpackages

Submodules

hwtLib.peripheral.usb.constants module

attention:

on USB the LSB bits are sent first

class hwtLib.peripheral.usb.constants.USB_LINE_STATE[source]

Bases: object

J = 1
K = 2
SE0 = 0
SE1 = 3
class hwtLib.peripheral.usb.constants.USB_PID[source]

Bases: object

USB Protocol layer packet identifier values (Specifies the type of transaction)

Attention:

visualy written in msb-first, transmited in lsb first

Note:

packet formats are described in structs in this file

Note:

if the PID is in 8b format the other 4 bits (check field) are a bitwise inversion of original 4b PID field

DATA_0 = 3
DATA_1 = 11
DATA_2 = 7
DATA_M = 15
ERR = 12
HS_ACK = 2
HS_NACK = 10
HS_NYET = 6
HS_STALL = 14
PING = 4
PREAMBLE = 12
SPLIT = 8
TOKEN_IN = 9
TOKEN_OUT = 1
TOKEN_SETUP = 13
TOKEN_SOF = 5
classmethod is_data(v: int | RtlSignalBase)[source]
classmethod is_hs(v: int | RtlSignalBase)[source]
classmethod is_token(v: int | RtlSignalBase)[source]
class hwtLib.peripheral.usb.constants.USB_VER[source]

Bases: object

USB_VER

Speed

1.0 - 2.0

Low Speed 1.5 Mbit/s

1.0 - 2.0

Full Speed 12 Mbit/s

2.0

High Speed 480 Mbit/s

3.0

SuperSpeed 5Gbit/s

3.1

SuperSpeed+ 10Gbit/s

3.2

SuperSpeed+ 20Gbit/s

4.0

SuperSpeed+ 40Gbit/s
USB1_0 = '1.0'
USB1_1 = '1.1'
USB2_0 = '2.0'
USB3_0 = '3.0'
USB3_1 = '3.1'
USB3_2 = '3.2'
USB4_0 = '4.0'
static from_uint16_t(usbVer: int)[source]
static to_uint16_t(usbVer: str)[source]
values = ['1.0', '1.1', '2.0', '3.0', '3.1', '3.2', '4.0']
hwtLib.peripheral.usb.constants.usb2_0_packet_data_t = struct {     <HBits, 4bits> pid     <HStream len:(1, 1024), align:(0,)         <HBits, 8bits>> data     <HBits, 16bits> crc }

There are three type of handshake packets which consist simply of the USB_PID

  • ACK - Acknowledgment that the packet has been successfully received.

  • NAK - Reports that the device temporary cannot send or received data. Also used during interrupt transactions to inform the host there is no data to send.

  • STALL - The device finds its in a state that it requires intervention from the host.

hwtLib.peripheral.usb.constants.usb_packet_hs_t = struct {     <HBits, 4bits> pid }

The SOF (Start of Frame) packet consisting of an 11-bit frame number is sent by the host every 1ms ± 500ns on a full speed bus or every 125 µs ± 0.0625 µs on a high speed bus.

hwtLib.peripheral.usb.constants.usb_pid_t = <HBits, 4bits>
Attention:

every packet starts with sync and ends in EOP, which is not in data structures below

hwtLib.peripheral.usb.device_request module

class hwtLib.peripheral.usb.device_request.USB_REQUEST[source]

Bases: object

Values for usb_device_request_t.bRequest

CLEAR_FEATURE = 1
GET_CONFIGURATION = 8
GET_DESCRIPTOR = 6
GET_INTERFACE = 10
GET_STATUS = 0
SET_ADDRESS = 5
SET_CONFIGURATION = 9
SET_DESCRIPTOR = 7
SET_FEATURE = 3
SET_INTERFACE = 17
SYNCH_FRAME = 18
class hwtLib.peripheral.usb.device_request.USB_REQUEST_TYPE_DIRECTION[source]

Bases: object

Values for usb_request_type_t.recipient

DEV_TO_HOST = 1
HOST_TO_DEV = 0
class hwtLib.peripheral.usb.device_request.USB_REQUEST_TYPE_RECIPIENT[source]

Bases: object

Values for usb_request_type_t.data_transfer_direction

DEVICE = 0
ENDPOINT = 2
INTERFACE = 1
OTHER = 3
class hwtLib.peripheral.usb.device_request.USB_REQUEST_TYPE_TYPE[source]

Bases: object

Values for usb_request_type_t.type

CLASS = 1
STANDARD = 0
VENDOR = 2
hwtLib.peripheral.usb.device_request.make_usb_device_request(bmRequestType_recipient: USB_REQUEST_TYPE_RECIPIENT, bmRequestType_type: USB_REQUEST_TYPE_TYPE, bmRequestType_data_transfer_direction: USB_REQUEST_TYPE_DIRECTION, bRequest: USB_REQUEST, wValue: int, wIndex: int, wLength: int)[source]