gusb

package
v0.0.0-...-96ba11e Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 19, 2022 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package gusb contains lower-level USB interaction. If you want to parse descriptors, send Ioctls manually, or other inspections, use this.

Descriptors

This is generally what you see when running lsusb, especially with the verbose flag. It reads the classification information the USB device provides to describe itself. The second byte of a descriptor header is a type constant. In C those IDs are USB_DT_* constants. In Go, they begin with DT. The struct types themselves are: 

DeviceDescriptor
ConfigDescriptor
InterfaceDescriptor
EndpointDescriptor
StringDescriptor
DevQualifierDescriptor

Index

Constants

View Source 
const (
	USBDescTypeHID      = 0x21
	USBDescTypeReport   = 0x22
	USBDescTypePhysical = 0x23
	USBDescTypeHub      = 0x29
)

@todo: what are these defining?

View Source 
const MAXDRIVERNAME = 255

Variables

This section is empty.

Functions

func Claim 

func Claim(f *os.File, ifno int32) error

func GetDriver 

func GetDriver(f *os.File, ifno int32) (string, error)

func Ioctl 

func Ioctl(f *os.File, ioctl IoctlRequest, data interface{}) (int, error)

Hand-craft an IOCTL to send to an open file descriptor. data must be a pointer.

func Ioctlnum 

func Ioctlnum(read bool, write bool, num uint8, size uint16) uint32

Can be used to calculate an IOCTL number dynamically. Here's an example translation from the C def for USBDEVFS_CONTROL 

#define USBDEVFS_CONTROL     _IOWR('U', 0, struct usbdevfs_ctrltransfer)

WR means read and write, so both should be set to true. char is 'U', which is true for all the usbfs subsystem. num is 0 (second param). size is: sizeof that struct (0x18 on 64 bit).

so call Ioctlnum(true, true, 0, 0x18) will give you 0xC0185500 = USBDEVFS_CONTROL.

func Release 

func Release(f *os.File, ifno int32) error

func SetLogger 

func SetLogger(l *log.Logger)

Types

type BulkTransfer 

type BulkTransfer struct {
	Ep      uint32
	Len     uint32
	Timeout uint32 //ms

	Data VoidPtr
	// contains filtered or unexported fields
}

type ConfigDescriptor 

type ConfigDescriptor struct {
	DescHeader
	TotalLength    uint16 // wTotalLength
	NumInterfaces  uint8  // bNumInterfaces
	Value          uint8  // bConfigurationValue
	StrIndex       uint8  // iConfiguration
	Attributes     uint8  // bmAttributes
	MaxPower       uint8  // MaxPower
	SelfPowered    bool   // Attributes https://www.beyondlogic.org/usbnutshell/usb5.shtml#ConfigurationDescriptors
	RemoteWakeup   bool   // Attributes
	BatteryPowered bool   // Attributes (ch9.h)
	Interfaces     []InterfaceDescriptor
	// contains filtered or unexported fields
}

struct usb_config_descriptor

func NewConfig 

func NewConfig(b []byte) (ConfigDescriptor, error)

func (ConfigDescriptor) String 

func (cf ConfigDescriptor) String() string

type ConnectInfo 

type ConnectInfo struct {
	Devnum uint32
	Slow   uint8 // unsigned char
}

type CtrlTransfer 

type CtrlTransfer struct {
	RequestType uint8
	Request     uint8
	Value       uint16
	Index       uint16
	Length      uint16
	Timeout     uint32 // milliseconds

	Data VoidPtr // void *
	// contains filtered or unexported fields
}

type DT 

type DT uint8
const (
	DTDevice              DT = 0x01 // usb 1.0+
	DTConfig              DT = 0x02
	DTString              DT = 0x03
	DTInterface           DT = 0x04
	DTEndpoint            DT = 0x05
	DTDeviceQualifier     DT = 0x06 // usb 2.0+
	DTOtherSpeed          DT = 0x07
	DTInterfacePower      DT = 0x08
	DTOTG                 DT = 0x09
	DTDebug               DT = 0x0a
	DTInterfaceAssoc      DT = 0x0b
	DTSecurity            DT = 0x0c // wireless USB
	DTKey                 DT = 0x0d
	DTEncType             DT = 0x0e
	DTBOS                 DT = 0x0f
	DTDeviceCapability    DT = 0x10
	DTWirelessEPComp      DT = 0x11
	DTWireAdapter         DT = 0x21 // should these be class-specific?
	DTRPipe               DT = 0x22
	DTCsRadioControl      DT = 0x23
	DTPipeUsage           DT = 0x24 // T10 UAS Spec
	DTSSEndpointComp      DT = 0x30 // usb 3.0+
	DTSSPISOCEndpointComp DT = 0x31 // usb 3.1+
)

Equivalent to USB_DT_* constants. determines type via bDescriptorType (aka <descriptor>.Descriptor)

func (DT) String 

func (d DT) String() string

type DescClasses 

type DescClasses struct {
	Class    USBClass        // b<thing>Class    uint8
	SubClass USBSubClass     // b<thing>SubClass uint8
	Protocol USBProtocolDesc // b<thing>Protocol uint8
}

defines the class,subclass,protocol triplet found in Device and Interface Descriptors

func (DescClasses) String 

func (dc DescClasses) String() string

type DescHeader 

type DescHeader struct {
	Length     uint8 // bLength
	Descriptor DT    // bDescriptorType, uint8
}

struct usb_descriptor_header

type DescriptorRange 

type DescriptorRange uint8
const (
	DescRangeGlobal   DescriptorRange = 0x00
	DescRangeClass    DescriptorRange = 0x20
	DescRangeVendor   DescriptorRange = 0x40
	DescRangeReserved DescriptorRange = 0x60
)

USB Descriptor classification mask. refers to bDescriptorType

type DevQualifierDescriptor 

type DevQualifierDescriptor struct {
	DescHeader
	Version       USBVer
	DescClasses   // 3 * uint8. Class, SubClass, Protocol
	MaxPacketSize uint8
	NumConfigs    uint8
	Reserved      uint8
}

struct usb_qualifer_descriptor

func NewDevQualifier 

func NewDevQualifier(b []byte) (DevQualifierDescriptor, error)

type DeviceDescriptor 

type DeviceDescriptor struct {
	DescHeader
	USBVer        USBVer // bcdUSB, uint16
	DescClasses          // 3 * uint8. Class, Subclass, Protocol
	MaxPacketSize uint8  // for endpoint 0. One of 8,16,32,64
	Vendor        USBID  // idVendor,  uint16
	Product       USBID  // idProduct, uint16
	Version       USBVer // bcdDevice, uint16
	ManufStr      uint8  // iManufacturer
	ProductStr    uint8  // iProduct
	SerialStr     uint8  // iSerial
	NumConfigs    uint8  // bNumConfigurations

	Configs []ConfigDescriptor

	// internal use, not part of Descriptor spec
	PathInfo DevicePath
	// contains filtered or unexported fields
}

USB_DT_DEVICE, aka DTDevice. (struct usb_device_descriptor)

func NewDevice 

func NewDevice(b []byte) (DeviceDescriptor, error)

func ParseDescriptor 

func ParseDescriptor(r io.Reader) (DeviceDescriptor, error)

func Walk 

func Walk(cb walkCB) ([]DeviceDescriptor, error)

func (DeviceDescriptor) String 

func (d DeviceDescriptor) String() string

type DevicePath 

type DevicePath struct {
	Bus     int
	Dev     int
	SysPath string
}

type DeviceSpeed 

type DeviceSpeed int
const (
	SpeedUnknown DeviceSpeed = iota
	SpeedLow
	SpeedFull
	SpeedHigh
	SpeedWireless
	SpeedSuper
	SpeedSuperPlus
)

func GetSpeed 

func GetSpeed(f *os.File) (DeviceSpeed, error)

type DisconnectClaim 

type DisconnectClaim struct {
	Interface uint32
	Flags     uint32
	Driver    [MAXDRIVERNAME + 1]byte
}

type DisconnectSignal 

type DisconnectSignal struct {
	Signr uint32 // unsigned int

	Data VoidPtr
	// contains filtered or unexported fields
}

8 on pi (4 + 4), 16 on desktop (4 + _4 + 8)

type EndpointAddress 

type EndpointAddress uint8

func (EndpointAddress) Dir 

func (e EndpointAddress) Dir() EndpointDirection

func (EndpointAddress) Num 

func (e EndpointAddress) Num() int

func (EndpointAddress) String 

func (e EndpointAddress) String() string

type EndpointDescriptor 

type EndpointDescriptor struct {
	//@todo: bRefresh && bSynchAddress provided via audio endpoints. See ch9.h, line 410
	DescHeader
	Address       EndpointAddress //uint8
	Attributes    uint8
	MaxPacketSize uint16
	Interval      uint8
	TransferType  TransferType // parsed from Attributes
	ISOSyncType   ISOSyncType  // parsed from Attributes
	ISOSyncMode   ISOSyncMode  // parsed from Attributes
	// contains filtered or unexported fields
}
struct usb_endpoint_descriptor

bDescriptorType: C: USB_DT_ENDPOINT, Go: DescEndpoint

func NewEndpoint 

func NewEndpoint(b []byte) (EndpointDescriptor, error)

func (EndpointDescriptor) String 

func (e EndpointDescriptor) String() string

type EndpointDirection 

type EndpointDirection uint8
const (
	EndpointDirOUT EndpointDirection = iota
	EndpointDirIN
)

func (EndpointDirection) String 

func (ed EndpointDirection) String() string

type GetDriverS 

type GetDriverS struct {
	Interface uint32
	Driver    [MAXDRIVERNAME + 1]byte
}

type HubPortinfo 

type HubPortinfo struct {
	NPorts int8
	Port   [127]int8
}

type ISOSyncMode 

type ISOSyncMode int
const (
	ISOUsageData ISOSyncMode = iota
	ISOUsageFeedback
	ISOUsageImplicit
)

type ISOSyncType 

type ISOSyncType int
const (
	ISOSyncTypeNone ISOSyncType = iota
	ISOSyncTypeAsync
	ISOSyncTypeAdaptive
	ISOSyncTypeSync
)

type InterfaceDescriptor 

type InterfaceDescriptor struct {
	DescHeader
	InterfaceNumber  uint8
	AlternateSetting uint8
	NumEndpoints     uint8
	DescClasses      // 3 * uint8. Class,Subclass,Protocol
	StrIndex         uint8
	Endpoints        []EndpointDescriptor
	// contains filtered or unexported fields
}

struct usb_interface_descriptor

func NewInterface 

func NewInterface(b []byte) (InterfaceDescriptor, error)

func (InterfaceDescriptor) String 

func (i InterfaceDescriptor) String() string

type IoctlPacket 

type IoctlPacket struct {
	IfNo      int32 //interface number
	IoctlCode int32
	Data      VoidPtr
}

type IoctlRequest 

type IoctlRequest uint32
const (
	USBDEVFS_SETINTERFACE     IoctlRequest = 0x80085504
	USBDEVFS_SETCONFIGURATION IoctlRequest = 0x80045505
	USBDEVFS_GETDRIVER        IoctlRequest = 0x41045508
	USBDEVFS_CONNECTINFO      IoctlRequest = 0x40085511
	USBDEVFS_CLAIMINTERFACE   IoctlRequest = 0x8004550f
	USBDEVFS_RELEASEINTERFACE IoctlRequest = 0x80045510
	USBDEVFS_DISCONNECT_CLAIM IoctlRequest = 0x8108551b
	USBDEVFS_RESETEP          IoctlRequest = 0x80045503
	USBDEVFS_CLEAR_HALT       IoctlRequest = 0x80045515
	USBDEVFS_CLAIM_PORT       IoctlRequest = 0x80045518
	USBDEVFS_RELEASE_PORT     IoctlRequest = 0x80045519
	USBDEVFS_HUB_PORTINFO     IoctlRequest = 0x80805513
	USBDEVFS_GET_CAPABILITIES IoctlRequest = 0x8004551a
	USBDEVFS_ALLOC_STREAMS    IoctlRequest = 0x8008551c
	USBDEVFS_FREE_STREAMS     IoctlRequest = 0x8008551d
	USBDEVFS_DROP_PRIVILEGES  IoctlRequest = 0x4004551e
	USBDEVFS_DISCARDURB       IoctlRequest = 0x0000550b
	USBDEVFS_RESET            IoctlRequest = 0x00005514
	USBDEVFS_DISCONNECT       IoctlRequest = 0x00005516
	USBDEVFS_CONNECT          IoctlRequest = 0x00005517
	USBDEVFS_GET_SPEED        IoctlRequest = 0x0000551f
)

Universal IOCTL numbers 

const (
	USBDEVFS_CONTROL       IoctlRequest = 0xc0185500 // struct CtrlTransfer
	USBDEVFS_BULK          IoctlRequest = 0xc0185502 // struct BulkTransfer
	USBDEVFS_SUBMITURB     IoctlRequest = 0x8038550a // struct Urb
	USBDEVFS_REAPURB       IoctlRequest = 0x4008550c // void *
	USBDEVFS_REAPURBNDELAY IoctlRequest = 0x4008550d // void *
	USBDEVFS_DISCSIGNAL    IoctlRequest = 0x8010550e // struct DisconnectSignal
	USBDEVFS_IOCTL         IoctlRequest = 0xc0105512 // struct IoctlPacket
)

64-bit specific IOCTL numbers

type SetInterface 

type SetInterface struct {
	Interface  uint32
	AltSetting uint32
}

type Streams 

type Streams struct {
	NumStreams uint32 //not used by FREE_STREAMS
	NumEps     uint32
	Eps        []uint8
}

type StringDescriptor 

type StringDescriptor struct {
	DescHeader
	S string
}
struct usb_string_descriptor

bDescriptorType, C: USB_DT_STRING, Go: DescString

func NewString 

func NewString(b []byte) (StringDescriptor, error)

func (StringDescriptor) String 

func (s StringDescriptor) String() string

type TransferType 

type TransferType int
const (
	EndpointTypeControl TransferType = iota
	EndpointTypeIsochronous
	EndpointTypeBulk
	EndpointTypeInterrupt
	EndpointTypeBulkStream
)

func (TransferType) String 

func (t TransferType) String() string

type URB 

type URB struct {
	Type         uint8
	Endpoint     uint8
	Status       int32
	Flags        uint32
	Buffer       VoidPtr
	BufferLength int32
	ActualLength int32
	StartFrame   int32
	//fucking, a union?!
	ErrorCount   int32
	Signr        uint32
	UserContext  VoidPtr
	IsoFrameDesc struct {
		Length       uint32
		ActualLength uint32
		Status       uint32
	}
}

this is super not correct 44,56

type USBClass 

type USBClass uint8
const (
	USBClassSeeInterface       USBClass = 0x00 // device, use class information from the interface descriptors
	USBClassAudio              USBClass = 0x01 // interface
	USBClassComm               USBClass = 0x02 // both
	USBClassHID                USBClass = 0x03 // interface
	USBClassPhysical           USBClass = 0x05 // interface
	USBClassStillImage         USBClass = 0x06 // interface
	USBClassPrinter            USBClass = 0x07 // interface
	USBClassMassStorage        USBClass = 0x08 // interface
	USBClassHub                USBClass = 0x09 // device
	USBClassCDCData            USBClass = 0x0a // interface
	USBClassCSCId              USBClass = 0x0b // interface, chip+ smart card
	USBClassContentSec         USBClass = 0x0d // interface, content security
	USBClassVideo              USBClass = 0x0e // interface
	USBClassHealth             USBClass = 0x0f // interface
	USBClassAV                 USBClass = 0x10 // interface
	USBClassBillboard          USBClass = 0x11 // device
	USBClassCBridge            USBClass = 0x12 // interface
	USBClassDiagnostic         USBClass = 0xdc // both
	USBClassWirelessController USBClass = 0xe0 // interface
	USBClassMisc               USBClass = 0xef // both
	USBClassAppSpecific        USBClass = 0xfe // interface
	USBClassVendorSpecific     USBClass = 0xff // both
)

USB class IDs https://www.usb.org/defined-class-codes . refers to C: bDeviceClass and bInterfaceClass or Go: DeviceDescriptor.Class and InterfaceDescriptor.Class.

func (USBClass) String 

func (c USBClass) String() string

type USBID 

type USBID uint16

func (USBID) String 

func (id USBID) String() string

type USBProtocolDesc 

type USBProtocolDesc uint8
const (
	// for USBClassHub
	HubProtocolFullSpeed     USBProtocolDesc = 0x00
	HubProtocolHiSpeed       USBProtocolDesc = 0x01
	HubProtocolHiSpeedManyTT USBProtocolDesc = 0x02

	// for HID, only defines role for boot interface (if supported)
	HIDBootAsNone     USBProtocolDesc = 0x0
	HIDBootAsKeyboard USBProtocolDesc = 0x1
	HIDBootAsMouse    USBProtocolDesc = 0x2 // 3-255 are reserved
)

class/vendor specific protocol values. refers to C: bDeviceProtocol, bInterfaceProtocol or Go: DeviceDescriptor.Protocol, InterfaceDescriptor.Protocol

type USBSubClass 

type USBSubClass uint8
const (
	// for USBClassAV
	AVSubclassControlIntf USBSubClass = 0x01 // interface
	AVSubclassVideoStream USBSubClass = 0x02 // interface
	AVSubclassAudioStream USBSubClass = 0x03 // interface

	// for HID, it is used as a boot interface support flag
	HIDBootSupportFalse USBSubClass = 0
	HIDBootSupportTrue  USBSubClass = 1 // 2-255 are reserved

	SubclassVendorSpecific USBSubClass = 0xff
)

USB Subclassifications. refers to C: bDeviceSubClass, bInterfaceSubClass or Go: DeviceDescriptor.SubClass, InterfaceDescriptor.SubClass

type USBVer 

type USBVer uint16

func (USBVer) String 

func (u USBVer) String() string

type VoidPtr 

type VoidPtr uint64 // 64-bit width

Matches width of Kernel void * on each platform.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.