usb

package
v0.0.0-...-9547062 Latest Latest
Warning

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

 Go to latest Published: Jan 8, 2023 License: BSD-3-Clause Imports: 12 Imported by: 0

Documentation

Overview

Package usb implements a driver for the USB PHY designated as NXP USBOH3USBO2, included in several i.MX SoCs, adopting the following specifications:

  • IMX6ULLRM - i.MX 6ULL Applications Processor Reference Manual - Rev 1 2017/11
  • USB2.0 - USB Specification Revision 2.0

This package is only meant to be used with `GOOS=tamago GOARCH=arm` as supported by the TamaGo framework for bare metal Go on ARM SoCs, see https://github.com/usbarmory/tamago.

Index

Constants

View Source 
const (
	USB_ANALOG_USBx_CHRG_DETECT = 0x10
	CHRG_DETECT_EN_B            = 20
	CHRG_DETECT_CHK_CHRG_B      = 19

	USBPHYx_PWD = 0x00

	USBPHYx_CTRL            = 0x30
	CTRL_SFTRST             = 31
	CTRL_CLKGATE            = 30
	CTRL_ENUTMILEVEL3       = 15
	CTRL_ENUTMILEVEL2       = 14
	CTRL_ENHOSTDISCONDETECT = 1

	USB_UOGx_USBCMD = 0x140
	USBCMD_RST      = 1
	USBCMD_RS       = 0

	USB_UOGx_USBSTS = 0x144
	USBSTS_URI      = 6
	USBSTS_UI       = 0

	USB_UOGx_DEVICEADDR = 0x154
	DEVICEADDR_USBADR   = 25
	DEVICEADDR_USBADRA  = 24

	USB_UOGx_ENDPTLISTADDR = 0x158
	ENDPTLISTADDR_EPBASE   = 11

	USB_UOGx_PORTSC1 = 0x184
	PORTSC_PTS_1     = 30
	PORTSC_PSPD      = 26
	PORTSC_PR        = 8

	USB_UOGx_OTGSC = 0x1a4
	OTGSC_OT       = 3

	USB_UOGx_USBMODE  = 0x1a8
	USBMODE_SDIS      = 4
	USBMODE_SLOM      = 3
	USBMODE_CM        = 0
	USBMODE_CM_DEVICE = 0b10
	USBMODE_CM_HOST   = 0b11

	USB_UOGx_ENDPTSETUPSTAT = 0x1ac

	USB_UOGx_ENDPTPRIME = 0x1b0
	ENDPTPRIME_PETB     = 16
	ENDPTPRIME_PERB     = 0

	USB_UOGx_ENDPTFLUSH = 0x1b4
	ENDPTFLUSH_FETB     = 16
	ENDPTFLUSH_FERB     = 0

	USB_UOGx_ENDPTSTAT = 0x1b8

	USB_UOGx_ENDPTCOMPLETE = 0x1bc
	ENDPTCOMPLETE_ETBR     = 16
	ENDPTCOMPLETE_ERBR     = 0

	USB_UOGx_ENDPTCTRL = 0x1c0
	ENDPTCTRL_TXE      = 23
	ENDPTCTRL_TXR      = 22
	ENDPTCTRL_TXI      = 21
	ENDPTCTRL_TXT      = 18
	ENDPTCTRL_TXS      = 16
	ENDPTCTRL_RXE      = 7
	ENDPTCTRL_RXR      = 6
	ENDPTCTRL_RXI      = 5
	ENDPTCTRL_RXT      = 2
	ENDPTCTRL_RXS      = 0
)

USB registers

View Source 
const (
	DEVICE_LENGTH                = 18
	CONFIGURATION_LENGTH         = 9
	INTERFACE_ASSOCIATION_LENGTH = 8
	INTERFACE_LENGTH             = 9
	ENDPOINT_LENGTH              = 7
	DEVICE_QUALIFIER_LENGTH      = 10
)

Standard USB descriptor sizes

View Source 
const (
	// p17, Table 5.1-1, CCID Rev1.1
	CCID_INTERFACE         = 0x21
	CCID_DESCRIPTOR_LENGTH = 54
)

CCID descriptor constants

View Source 
const (
	// p44, Table 24: Type Values for the bDescriptorType Field,
	// USB Class Definitions for Communication Devices 1.1
	CS_INTERFACE = 0x24

	HEADER_LENGTH              = 5
	UNION_LENGTH               = 5
	ETHERNET_NETWORKING_LENGTH = 13

	// p64, Table 46: Class-Specific Request Codes,
	// USB Class Definitions for Communication Devices 1.1
	SET_ETHERNET_PACKET_FILTER = 0x43

	HEADER              = 0
	UNION               = 6
	ETHERNET_NETWORKING = 15

	// Maximum Segment Size
	MSS = 1500 + 14
)

CDC descriptor constants

View Source 
const (
	CBW_LENGTH        = 31
	CBW_CB_MAX_LENGTH = 16

	CBW_SIGNATURE = 0x43425355
	CSW_SIGNATURE = 0x53425355

	// p15, Table 5.3 - Command Block Status Values, USB Mass Storage Class 1.0
	CSW_STATUS_COMMAND_PASSED = 0x00
	CSW_STATUS_COMMAND_FAILED = 0x01
	CSW_STATUS_PHASE_ERROR    = 0x02

	// p7, 3.1 - 3.2, USB Mass Storage Class 1.0
	BULK_ONLY_MASS_STORAGE_RESET = 0xff
	GET_MAX_LUN                  = 0xfe
)

Mass Storage constants

View Source 
const (
	// The USB OTG device controller hardware supports up to 8 endpoint
	// numbers.
	MAX_ENDPOINTS = 8

	// Host -> Device
	OUT = 0
	// Device -> Host
	IN = 1

	// Transfer Type
	CONTROL     = 0
	ISOCHRONOUS = 1
	BULK        = 2
	INTERRUPT   = 3

	// p3784, 56.4.5.1 Endpoint Queue Head (dQH), IMX6ULLRM
	DQH_LIST_ALIGN = 2048
	DQH_ALIGN      = 64
	DQH_SIZE       = 64
	DQH_INFO       = 0
	DQH_CURRENT    = 4
	DQH_NEXT       = 8
	DQH_TOKEN      = 12

	// p3787, 56.4.5.2 Endpoint Transfer Descriptor (dTD), IMX6ULLRM
	DTD_ALIGN     = 32
	DTD_SIZE      = 28
	DTD_PAGES     = 5
	DTD_PAGE_SIZE = 4096
	DTD_NEXT      = 0

	DTD_TOKEN    = 4
	TOKEN_TOTAL  = 16
	TOKEN_IOC    = 15
	TOKEN_MULTO  = 10
	TOKEN_ACTIVE = 7
)

Endpoint constants

View Source 
const (
	GET_STATUS        = 0
	CLEAR_FEATURE     = 1
	SET_FEATURE       = 3
	SET_ADDRESS       = 5
	GET_DESCRIPTOR    = 6
	SET_DESCRIPTOR    = 7
	GET_CONFIGURATION = 8
	SET_CONFIGURATION = 9
	GET_INTERFACE     = 10
	SET_INTERFACE     = 11
	SYNCH_FRAME       = 12
)

Standard request codes (p279, Table 9-4, USB2.0)

View Source 
const (
	DEVICE                    = 1
	CONFIGURATION             = 2
	STRING                    = 3
	INTERFACE                 = 4
	ENDPOINT                  = 5
	DEVICE_QUALIFIER          = 6
	OTHER_SPEED_CONFIGURATION = 7
	INTERFACE_POWER           = 8

	// Engineering Change Notices (ECN)
	OTG                   = 9
	DEBUG                 = 10
	INTERFACE_ASSOCIATION = 11
)

Descriptor types (p279, Table 9-5, USB2.0)

View Source 
const (
	ENDPOINT_HALT        = 0
	DEVICE_REMOTE_WAKEUP = 1
	TEST_MODE            = 2
)

Standard feature selectors (p280, Table 9-6, USB2.0)

Variables

This section is empty.

Functions

This section is empty.

Types

type CBW 

type CBW struct {
	Signature          uint32
	Tag                uint32
	DataTransferLength uint32
	Flags              uint8
	LUN                uint8
	Length             uint8
	CommandBlock       [16]byte
}

CBW implements p13, 5.1 Command Block Wrapper (CBW), USB Mass Storage Class 1.0

func (*CBW) Bytes 

func (d *CBW) Bytes() []byte

Bytes converts the descriptor structure to byte array format.

func (*CBW) SetDefaults 

func (d *CBW) SetDefaults()

SetDefaults initializes default values for the CBW descriptor.

type CCIDDescriptor 

type CCIDDescriptor struct {
	Length                uint8
	DescriptorType        uint8
	CCID                  uint16
	MaxSlotIndex          uint8
	VoltageSupport        uint8
	Protocols             uint32
	DefaultClock          uint32
	MaximumClock          uint32
	NumClockSupported     uint8
	DataRate              uint32
	MaxDataRate           uint32
	NumDataRatesSupported uint8
	MaxIFSD               uint32
	SynchProtocols        uint32
	Mechanical            uint32
	Features              uint32
	MaxCCIDMessageLength  uint32
	ClassGetResponse      uint8
	ClassEnvelope         uint8
	LcdLayout             uint16
	PINSupport            uint8
	MaxCCIDBusySlots      uint8
}

CCIDDescriptor implements p17, Table 5.1-1, CCID Rev1.1

func (*CCIDDescriptor) Bytes 

func (d *CCIDDescriptor) Bytes() []byte

Bytes converts the descriptor structure to byte array format.

func (*CCIDDescriptor) SetDefaults 

func (d *CCIDDescriptor) SetDefaults()

SetDefaults initializes default values for the USB Smart Card Device Class Descriptor.

type CDCEthernetDescriptor 

type CDCEthernetDescriptor struct {
	Length             uint8
	DescriptorType     uint8
	DescriptorSubType  uint8
	MacAddress         uint8
	EthernetStatistics uint32
	MaxSegmentSize     uint16
	NumberMCFilters    uint16
	NumberPowerFilters uint8
}

CDCEthernetDescriptor implements p56, Table 41: Ethernet Networking Functional Descriptor, USB Class Definitions for Communication Devices 1.1.

func (*CDCEthernetDescriptor) Bytes 

func (d *CDCEthernetDescriptor) Bytes() []byte

Bytes converts the descriptor structure to byte array format.

func (*CDCEthernetDescriptor) SetDefaults 

func (d *CDCEthernetDescriptor) SetDefaults()

SetDefaults initializes default values for the USB CDC Ethernet Networking Functional Descriptor.

type CDCHeaderDescriptor 

type CDCHeaderDescriptor struct {
	Length            uint8
	DescriptorType    uint8
	DescriptorSubType uint8
	// contains filtered or unexported fields
}

CDCHeaderDescriptor implements p45, Table 26: Class-Specific Descriptor Header Format, USB Class Definitions for Communication Devices 1.1.

func (*CDCHeaderDescriptor) Bytes 

func (d *CDCHeaderDescriptor) Bytes() []byte

Bytes converts the descriptor structure to byte array format.

func (*CDCHeaderDescriptor) SetDefaults 

func (d *CDCHeaderDescriptor) SetDefaults()

SetDefaults initializes default values for the USB CDC Header Functional Descriptor.

type CDCUnionDescriptor 

type CDCUnionDescriptor struct {
	Length            uint8
	DescriptorType    uint8
	DescriptorSubType uint8
	MasterInterface   uint8
	SlaveInterface0   uint8
}

CDCUnionDescriptor implements p51, Table 33: Union Interface Functional Descriptor, USB Class Definitions for Communication Devices 1.1.

func (*CDCUnionDescriptor) Bytes 

func (d *CDCUnionDescriptor) Bytes() []byte

Bytes converts the descriptor structure to byte array format.

func (*CDCUnionDescriptor) SetDefaults 

func (d *CDCUnionDescriptor) SetDefaults()

SetDefaults initializes default values for the USB CDC Union Functional Descriptor.

type CSW 

type CSW struct {
	Signature   uint32
	Tag         uint32
	DataResidue uint32
	Status      uint8
}

CSW implements p14, 5.2 Command Status Wrapper (CSW), USB Mass Storage Class 1.0

func (*CSW) Bytes 

func (d *CSW) Bytes() []byte

Bytes converts the descriptor structure to byte array format.

func (*CSW) SetDefaults 

func (d *CSW) SetDefaults()

SetDefaults initializes default values for the CSW descriptor.

type ConfigurationDescriptor 

type ConfigurationDescriptor struct {
	Length             uint8
	DescriptorType     uint8
	TotalLength        uint16
	NumInterfaces      uint8
	ConfigurationValue uint8
	Configuration      uint8
	Attributes         uint8
	MaxPower           uint8

	Interfaces []*InterfaceDescriptor
}

ConfigurationDescriptor implements p293, Table 9-10. Standard Configuration Descriptor, USB2.0.

func (*ConfigurationDescriptor) AddInterface 

func (d *ConfigurationDescriptor) AddInterface(iface *InterfaceDescriptor)

AddInterface adds an Interface Descriptor to a configuration, updating the interface number and Configuration Descriptor interface count accordingly.

func (*ConfigurationDescriptor) Bytes 

func (d *ConfigurationDescriptor) Bytes() []byte

Bytes converts the descriptor structure to byte array format.

func (*ConfigurationDescriptor) SetDefaults 

func (d *ConfigurationDescriptor) SetDefaults()

SetDefaults initializes default values for the USB configuration descriptor.

type Device 

type Device struct {
	Descriptor     *DeviceDescriptor
	Qualifier      *DeviceQualifierDescriptor
	Configurations []*ConfigurationDescriptor
	Strings        [][]byte

	// Host requested settings
	ConfigurationValue uint8
	AlternateSetting   uint8

	// Optional class-specific setup handler
	Setup SetupFunction
}

Device is a collection of USB device descriptors and host driven settings to represent a USB device.

func (*Device) AddConfiguration 

func (d *Device) AddConfiguration(conf *ConfigurationDescriptor) (err error)

AddConfiguration adds a Configuration Descriptor to a device, updating its Device Descriptor configuration count accordingly.

func (*Device) AddString 

func (d *Device) AddString(s string) (uint8, error)

AddString adds a string descriptor to a USB device. The returned index can be used to fill string descriptor index value in configuration descriptors (p274, Table 9-16. UNICODE String Descriptor, USB2.0).

func (*Device) Configuration 

func (d *Device) Configuration(wIndex uint16) (buf []byte, err error)

Configuration converts the device configuration hierarchy to a buffer, as expected by Get Descriptor for configuration descriptor type (p281, 9.4.3 Get Descriptor, USB2.0).

func (*Device) SetLanguageCodes 

func (d *Device) SetLanguageCodes(codes []uint16) (err error)

SetLanguageCodes configures String Descriptor Zero language codes (p273, Table 9-15. String Descriptor Zero, Specifying Languages Supported by the Device, USB2.0).

type DeviceDescriptor 

type DeviceDescriptor struct {
	Length         uint8
	DescriptorType uint8

	DeviceClass       uint8
	DeviceSubClass    uint8
	DeviceProtocol    uint8
	MaxPacketSize     uint8
	VendorId          uint16
	ProductId         uint16
	Device            uint16
	Manufacturer      uint8
	Product           uint8
	SerialNumber      uint8
	NumConfigurations uint8
	// contains filtered or unexported fields
}

DeviceDescriptor implements p290, Table 9-8. Standard Device Descriptor, USB2.0.

func (*DeviceDescriptor) Bytes 

func (d *DeviceDescriptor) Bytes() []byte

Bytes converts the descriptor structure to byte array format.

func (*DeviceDescriptor) SetDefaults 

func (d *DeviceDescriptor) SetDefaults()

SetDefaults initializes default values for the USB device descriptor.

type DeviceQualifierDescriptor 

type DeviceQualifierDescriptor struct {
	Length         uint8
	DescriptorType uint8

	DeviceClass       uint8
	DeviceSubClass    uint8
	DeviceProtocol    uint8
	MaxPacketSize     uint8
	NumConfigurations uint8
	Reserved          uint8
	// contains filtered or unexported fields
}

DeviceQualifierDescriptor implements p292, 9.6.2 Device_Qualifier, USB2.0.

func (*DeviceQualifierDescriptor) Bytes 

func (d *DeviceQualifierDescriptor) Bytes() []byte

Bytes converts the descriptor structure to byte array format.

func (*DeviceQualifierDescriptor) SetDefaults 

func (d *DeviceQualifierDescriptor) SetDefaults()

SetDefaults initializes default values for the USB device qualifier descriptor.

type Endpoint 

type Endpoint struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Endpoint represents a USB 2.0 endpoint.

func (*Endpoint) Flush 

func (ep *Endpoint) Flush()

Flush clears the endpoint receive and transmit buffers.

func (*Endpoint) Init 

func (ep *Endpoint) Init()

Init initializes an endpoint.

func (*Endpoint) Start 

func (ep *Endpoint) Start()

Start initializes and runs an USB endpoint.

type EndpointDescriptor 

type EndpointDescriptor struct {
	Length          uint8
	DescriptorType  uint8
	EndpointAddress uint8
	Attributes      uint8
	MaxPacketSize   uint16
	Interval        uint8

	// Automatic Zero Length Termination
	Zero bool

	Function EndpointFunction
}

EndpointDescriptor implements p297, Table 9-13. Standard Endpoint Descriptor, USB2.0.

func (*EndpointDescriptor) Bytes 

func (d *EndpointDescriptor) Bytes() []byte

Bytes converts the descriptor structure to byte array format.

func (*EndpointDescriptor) Direction 

func (d *EndpointDescriptor) Direction() int

Direction returns the endpoint direction.

func (*EndpointDescriptor) Number 

func (d *EndpointDescriptor) Number() int

Number returns the endpoint number.

func (*EndpointDescriptor) SetDefaults 

func (d *EndpointDescriptor) SetDefaults()

SetDefaults initializes default values for the USB endpoint descriptor.

func (*EndpointDescriptor) TransferType 

func (d *EndpointDescriptor) TransferType() int

TransferType returns the endpoint transfer type.

type EndpointFunction 

type EndpointFunction func(buf []byte, lastErr error) (res []byte, err error)

EndpointFunction represents the function to process either IN or OUT transfers, depending on the endpoint configuration.

On OUT endpoints the function is expected to receive data from the host in the input buffer. The expected size, or a reserved DMA buffer (see `dma.Reserve`), for the next OUT transfer can be passed as a result buffer, otherwise a short or single packet is assumed. In case a reserved DMA buffer is returned the next OUT transfer `buf` argument represents a slice of it, care must be taken not to use such slice (without a copy) after the reserved buffer is released.

On IN endpoints the function is expected to return data, or reserved and filled DMA buffer, for transmission to the host, such data is used to fill the transmission queue in advance, to respond to IN requests. The function is invoked by the EndpointHandler to fill the buffer as needed.

type InterfaceAssociationDescriptor 

type InterfaceAssociationDescriptor struct {
	Length           uint8
	DescriptorType   uint8
	FirstInterface   uint8
	InterfaceCount   uint8
	FunctionClass    uint8
	FunctionSubClass uint8
	FunctionProtocol uint8
	Function         uint8
}

InterfaceAssociationDescriptor implements p4, Table 9-Z. Interface Association Descriptors, USB2.0 (ECN).

func (*InterfaceAssociationDescriptor) Bytes 

func (d *InterfaceAssociationDescriptor) Bytes() []byte

Bytes converts the descriptor structure to byte array format.

func (*InterfaceAssociationDescriptor) SetDefaults 

func (d *InterfaceAssociationDescriptor) SetDefaults()

SetDefaults initializes default values for the USB interface descriptor.

type InterfaceDescriptor 

type InterfaceDescriptor struct {
	IAD *InterfaceAssociationDescriptor

	Length            uint8
	DescriptorType    uint8
	InterfaceNumber   uint8
	AlternateSetting  uint8
	NumEndpoints      uint8
	InterfaceClass    uint8
	InterfaceSubClass uint8
	InterfaceProtocol uint8
	Interface         uint8

	Endpoints        []*EndpointDescriptor
	ClassDescriptors [][]byte
}

InterfaceDescriptor implements p296, Table 9-12. Standard Interface Descriptor, USB2.0.

func (*InterfaceDescriptor) Bytes 

func (d *InterfaceDescriptor) Bytes() []byte

Bytes converts the descriptor structure to byte array format,

func (*InterfaceDescriptor) SetDefaults 

func (d *InterfaceDescriptor) SetDefaults()

SetDefaults initializes default values for the USB interface descriptor.

type SetupData 

type SetupData struct {
	RequestType uint8
	Request     uint8
	Value       uint16
	Index       uint16
	Length      uint16
}

SetupData implements p276, Table 9-2. Format of Setup Data, USB2.0.

type SetupFunction 

type SetupFunction func(setup *SetupData) (in []byte, ack bool, done bool, err error)

SetupFunction represents the function to process class-specific setup requests.

The function is invoked before standard setup handlers and is expected to return an `in` buffer for transmission on IN endpoint 0, the `ack` boolean can be used to signal whether a zero length packet should be sent (true) in case the `in` buffer returned empty.

A non-nil `err` results in a stall. The `done` flag can be used to signal whether standard setup handlers should be invoked (false) or not (true) if function returns with a non-nil error.

type StringDescriptor 

type StringDescriptor struct {
	Length         uint8
	DescriptorType uint8
}

StringDescriptor implements p273, 9.6.7 String, USB2.0.

func (*StringDescriptor) Bytes 

func (d *StringDescriptor) Bytes() []byte

Bytes converts the descriptor structure to byte array format.

func (*StringDescriptor) SetDefaults 

func (d *StringDescriptor) SetDefaults()

SetDefaults initializes default values for the USB string descriptor.

type USB 

type USB struct {
	sync.Mutex

	// Controller index
	Index int
	// Base register
	Base uint32
	// Clock gate register
	CCGR uint32
	// Clock gate
	CG int
	// Analog base register
	Analog uint32
	// PHY base register
	PHY uint32
	// PLL enable function
	EnablePLL func(index int) error
	// contains filtered or unexported fields
}

USB represents a USB controller instance.

func (*USB) DeviceMode 

func (hw *USB) DeviceMode()

DeviceMode sets the USB controller in device mode.

func (*USB) Init 

func (hw *USB) Init()

Init initializes the USB controller.

func (*USB) PowerDown 

func (hw *USB) PowerDown()

PowerDown shuts down the USB PHY.

func (*USB) Reset 

func (hw *USB) Reset()

Reset waits for and handles a bus reset.

func (*USB) Run 

func (hw *USB) Run()

Run sets the controller in run mode.

func (*USB) Speed 

func (hw *USB) Speed() (speed string)

Speed returns the port speed.

func (*USB) Start 

func (hw *USB) Start(dev *Device)

Start waits and handles configured USB endpoints in device mode, it should never return. Note that isochronous endpoints are not supported.

func (*USB) Stop 

func (hw *USB) Stop()

Stop sets the controller in stop mode.

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.