usb

Documentation

Overview

Package usb contains helpers for building USB descriptors and data.

Index

• Constants
• func EncodeStringDescriptor(s string) []byte
• type ClassSpecificDescriptor
  • func (d ClassSpecificDescriptor) Bytes() Data
• type ConfigHeader
  • func (h ConfigHeader) Write(b *bytes.Buffer)
• type ControlDevice
• type Data
• type Descriptor
  • func (d Descriptor) Bytes() []byte
• type Device
• type DeviceDescriptor
• type EndpointDescriptor
  • func (e EndpointDescriptor) Write(b *bytes.Buffer)
• type HIDDescriptor
  • func (h HIDDescriptor) IsZero() bool
  • func (h HIDDescriptor) Write(b *bytes.Buffer, reportLen uint16) error
• type HIDFunction
  • func (f HIDFunction) DescriptorBytes() (Data, error)
  • func (f HIDFunction) ReportBytes() (Data, error)
• type HIDSubDescriptor
• type InterfaceConfig
• type InterfaceDescriptor
  • func (i InterfaceDescriptor) Write(b *bytes.Buffer)

Constants

const (
	DeviceDescType    = 0x01
	ConfigDescType    = 0x02
	InterfaceDescType = 0x04
	EndpointDescType  = 0x05
	HIDDescType       = 0x21
	ReportDescType    = 0x22
)

USB descriptor type constants

const (
	DeviceDescLen    = 18
	ConfigDescLen    = 9
	InterfaceDescLen = 9
	EndpointDescLen  = 7
	HIDDescLen       = 9
)

Descriptor lengths in bytes (fixed values from USB spec)

Functions

func EncodeStringDescriptor

func EncodeStringDescriptor(s string) []byte

EncodeStringDescriptor converts a UTF-8 string to a USB string descriptor byte array. The resulting descriptor has the format:

Byte 0: bLength (total descriptor length)
Byte 1: bDescriptorType (0x03 for string)
Bytes 2+: UTF-16LE encoded string

Types

type ClassSpecificDescriptor

type ClassSpecificDescriptor struct {
	DescriptorType uint8
	Payload        Data
}

ClassSpecificDescriptor represents an opaque class-specific interface descriptor.

It auto-calculates bLength and hardcodes bDescriptorType. Payload contains all bytes after the (bLength,bDescriptorType) header.

func (ClassSpecificDescriptor) Bytes

func (d ClassSpecificDescriptor) Bytes() Data

type ConfigHeader

type ConfigHeader struct {
	WTotalLength        uint16 // LE, to be patched after building
	BNumInterfaces      uint8
	BConfigurationValue uint8
	IConfiguration      uint8
	BMAttributes        uint8
	BMaxPower           uint8
}

ConfigHeader represents the USB configuration descriptor header (9 bytes).

func (ConfigHeader) Write

func (h ConfigHeader) Write(b *bytes.Buffer)

type ControlDevice

type ControlDevice interface {
	// HandleControl handles a control request.
	//
	// - bmRequestType, bRequest, wValue, wIndex, wLength are the raw setup packet fields.
	// - data is the OUT data stage payload (for host-to-device requests), and is nil for
	//   device-to-host requests.
	//
	// If handled is false, the server will fall back to its default behavior.
	// If handled is true, the returned bytes (if any) will be used as the IN data stage.
	HandleControl(bmRequestType, bRequest uint8, wValue, wIndex, wLength uint16, data []byte) (resp []byte, handled bool)
}

ControlDevice is an optional interface for devices that need to handle control transfers on endpoint 0 (EP0).

This is primarily used for class-specific requests that are not covered by the server's built-in standard request handling (e.g. HID GET_REPORT/ SET_REPORT).

type Data

type Data []uint8

type Descriptor

type Descriptor struct {
	Device     DeviceDescriptor
	Interfaces []InterfaceConfig
	Strings    map[uint8]string
}

Descriptor holds all static descriptor/config data for a device.

func (Descriptor) Bytes

func (d Descriptor) Bytes() []byte

Bytes returns the binary representation of the DeviceDescriptor with BLength auto-filled.

type Device

type Device interface {
	// HandleTransfer processes a non-EP0 transfer (interrupt/bulk).
	// ep is the endpoint number (without direction). dir is usbip.DirIn or usbip.DirOut.
	// For IN transfers, return the payload to send; for OUT, consume 'out' and return nil.
	HandleTransfer(ep uint32, dir uint32, out []byte) []byte
	GetDescriptor() *Descriptor
}

Device is the minimal interface a device must implement. It only handles non-EP0 (interrupt/bulk) transfers.

type DeviceDescriptor

type DeviceDescriptor struct {
	BcdUSB             uint16 // LE
	BDeviceClass       uint8
	BDeviceSubClass    uint8
	BDeviceProtocol    uint8
	BMaxPacketSize0    uint8
	IDVendor           uint16 // LE; may get overridden
	IDProduct          uint16 // LE; may get overridden
	BcdDevice          uint16 // LE
	IManufacturer      uint8
	IProduct           uint8
	ISerialNumber      uint8
	BNumConfigurations uint8
	Speed              uint32 // USB speed: 1=low, 2=full, 3=high, 4=super
}

DeviceDescriptor represents the standard USB device descriptor. BLength is computed dynamically; BDescriptorType is implied DeviceDescType.

type EndpointDescriptor

type EndpointDescriptor struct {
	BEndpointAddress uint8
	BMAttributes     uint8
	WMaxPacketSize   uint16 // LE
	BInterval        uint8
}

EndpointDescriptor (7 bytes) for each endpoint.

func (EndpointDescriptor) Write

func (e EndpointDescriptor) Write(b *bytes.Buffer)

type HIDDescriptor

type HIDDescriptor struct {
	BcdHID       uint16 // LE
	BCountryCode uint8
	Descriptors  []HIDSubDescriptor
}

HIDDescriptor is the HID class descriptor (0x21) for HID-class interfaces.

bDescriptorType is fixed to HIDDescType (0x21). bLength is auto-calculated as: 6 + 3*len(Descriptors).

func (HIDDescriptor) IsZero

func (h HIDDescriptor) IsZero() bool

func (HIDDescriptor) Write

func (h HIDDescriptor) Write(b *bytes.Buffer, reportLen uint16) error

type HIDFunction

type HIDFunction struct {
	Descriptor HIDDescriptor
	Report     hid.Report
}

HIDFunction bundles the HID class descriptor (0x21) and the report descriptor (0x22) for a HID-class interface.

func (HIDFunction) DescriptorBytes

func (f HIDFunction) DescriptorBytes() (Data, error)

DescriptorBytes returns the HID class descriptor (0x21) bytes.

func (HIDFunction) ReportBytes

func (f HIDFunction) ReportBytes() (Data, error)

ReportBytes returns the HID report descriptor (0x22) bytes.

type HIDSubDescriptor

type HIDSubDescriptor struct {
	Type   uint8
	Length uint16 // LE
}

HIDSubDescriptor is one subordinate descriptor entry in the HID class descriptor.

Type is typically ReportDescType (0x22). If Type==ReportDescType and Length==0, the server will auto-fill Length from the associated HID report descriptor at serialization time.

type InterfaceConfig

type InterfaceConfig struct {
	Descriptor InterfaceDescriptor
	Endpoints  []EndpointDescriptor

	// HID describes a HID-class interface (bInterfaceClass=0x03).
	// If set, the server will emit the HID descriptor (0x21) in the configuration
	// descriptor and serve the report descriptor (0x22) via GET_DESCRIPTOR.
	HID *HIDFunction

	// ClassDescriptors are additional interface-level class-specific descriptors
	// emitted as part of the configuration descriptor (after the interface descriptor
	// and before the endpoints).
	//
	// This is also used for vendor-specific interfaces that need to expose opaque
	// descriptors (e.g. type 0x21 blobs on Xbox360).
	ClassDescriptors []ClassSpecificDescriptor
}

InterfaceConfig holds all descriptors for a single interface for bus management.

type InterfaceDescriptor

type InterfaceDescriptor struct {
	BInterfaceNumber   uint8
	BAlternateSetting  uint8
	BNumEndpoints      uint8
	BInterfaceClass    uint8
	BInterfaceSubClass uint8
	BInterfaceProtocol uint8
	IInterface         uint8
}

InterfaceDescriptor (9 bytes) for each interface altsetting.

func (InterfaceDescriptor) Write

func (i InterfaceDescriptor) Write(b *bytes.Buffer)