Maintainer | Bas van Dijk <v.dijk.bas@gmail.com> |
---|---|
Safe Haskell | Trustworthy |
USB devices report their attributes using descriptors. A descriptor is a data structure with a defined format. Using descriptors allows concise storage of the attributes of individual configurations because each configuration may reuse descriptors or portions of descriptors from other configurations that have the same characteristics. In this manner, the descriptors resemble individual data records in a relational database.
Where appropriate, descriptors contain references to string descriptors
(StrIx
) that provide textual information describing a descriptor in
human-readable form. Note that the inclusion of string descriptors is
optional.
- getDeviceDesc :: Device -> IO DeviceDesc
- data DeviceDesc = DeviceDesc {
- deviceUSBSpecReleaseNumber :: !ReleaseNumber
- deviceClass :: !Word8
- deviceSubClass :: !Word8
- deviceProtocol :: !Word8
- deviceMaxPacketSize0 :: !Word8
- deviceVendorId :: !VendorId
- deviceProductId :: !ProductId
- deviceReleaseNumber :: !ReleaseNumber
- deviceManufacturerStrIx :: !(Maybe StrIx)
- deviceProductStrIx :: !(Maybe StrIx)
- deviceSerialNumberStrIx :: !(Maybe StrIx)
- deviceNumConfigs :: !Word8
- type ReleaseNumber = (Int, Int, Int, Int)
- type VendorId = Word16
- type ProductId = Word16
- getConfigDesc :: Device -> Word8 -> IO ConfigDesc
- data ConfigDesc = ConfigDesc {
- configValue :: !ConfigValue
- configStrIx :: !(Maybe StrIx)
- configAttribs :: !ConfigAttribs
- configMaxPower :: !Word8
- configInterfaces :: !(Vector Interface)
- configExtra :: !ByteString
- type ConfigAttribs = DeviceStatus
- data DeviceStatus = DeviceStatus {
- remoteWakeup :: !Bool
- selfPowered :: !Bool
- type Interface = Vector InterfaceDesc
- data InterfaceDesc = InterfaceDesc {}
- data EndpointDesc = EndpointDesc {}
- data EndpointAddress = EndpointAddress {}
- data TransferDirection
- type EndpointAttribs = TransferType
- data TransferType
- = Control
- | Isochronous !Synchronization !Usage
- | Bulk
- | Interrupt
- data Synchronization
- data Usage
- data MaxPacketSize = MaxPacketSize {}
- data TransactionOpportunities
- maxIsoPacketSize :: EndpointDesc -> Size
- getLanguages :: DeviceHandle -> IO (Vector LangId)
- type LangId = (PrimaryLangId, SubLangId)
- type PrimaryLangId = Word16
- type SubLangId = Word16
- type StrIx = Word8
- getStrDesc :: DeviceHandle -> StrIx -> LangId -> Int -> IO Text
- getStrDescFirstLang :: DeviceHandle -> StrIx -> Int -> IO Text
Device descriptor
getDeviceDesc :: Device -> IO DeviceDescSource
Get the USB device descriptor for a given device.
This is a non-blocking function; the device descriptor is cached in memory.
This function may throw USBException
s.
data DeviceDesc Source
A structure representing the standard USB device descriptor.
This descriptor is documented in section 9.6.1 of the USB 2.0 specification.
This structure can be retrieved by deviceDesc
.
DeviceDesc | |
|
For a database of USB vendors and products see the usb-id-database
package at: http://hackage.haskell.org/package/usb-id-database
Configuration descriptor
getConfigDesc :: Device -> Word8 -> IO ConfigDescSource
Get a USB configuration descriptor based on its index.
This is a non-blocking function which does not involve any requests being sent to the device.
Exceptions:
-
NotFoundException
if the configuration does not exist. - Another
USBException
.
data ConfigDesc Source
A structure representing the standard USB configuration descriptor.
This descriptor is documented in section 9.6.3 of the USB 2.0 specification.
This structure can be retrieved by getConfigDesc
.
ConfigDesc | |
|
Configuration attributes
type ConfigAttribs = DeviceStatusSource
The USB 2.0 specification specifies that the configuration attributes only describe the device status.
data DeviceStatus Source
DeviceStatus | |
|
Interface descriptor
type Interface = Vector InterfaceDescSource
An interface is represented as a vector of alternate interface settings.
data InterfaceDesc Source
A structure representing the standard USB interface descriptor.
This descriptor is documented in section 9.6.5 of the USB 2.0 specification.
This structure can be retrieved using configInterfaces
.
InterfaceDesc | |
|
Endpoint descriptor
data EndpointDesc Source
A structure representing the standard USB endpoint descriptor.
This descriptor is documented in section 9.6.3 of the USB 2.0 specification.
This structure can be retrieved by using interfaceEndpoints
.
EndpointDesc | |
|
Endpoint address
data EndpointAddress Source
The address of an endpoint.
EndpointAddress | |
|
data TransferDirection Source
The direction of data transfer relative to the host.
Endpoint attributes
type EndpointAttribs = TransferTypeSource
The USB 2.0 specification specifies that the endpoint attributes only describe the endpoint transfer type.
data TransferType Source
Describes what types of transfers are allowed on the endpoint.
Control | Control transfers are typically used for command and status operations. |
Isochronous !Synchronization !Usage | Isochronous transfers occur continuously and periodically. |
Bulk | Bulk transfers can be used for large bursty data. |
Interrupt | Interrupt transfers are typically non-periodic, small device "initiated" communication requiring bounded latency. |
Isochronous transfer attributes
data Synchronization Source
See section 5.12.4.1 of the USB 2.0 specification.
NoSynchronization | |
Asynchronous | Unsynchronized, although sinks provide data rate feedback. |
Adaptive | Synchronized using feedback or feedforward data rate information |
Synchronous | Synchronized to the USB’s SOF (Start Of Frame) |
See section 5.12.4.2 of the USB 2.0 specification.
Endpoint max packet size
data MaxPacketSize Source
data TransactionOpportunities Source
Number of additional transaction oppurtunities per microframe.
See table 9-13 of the USB 2.0 specification.
maxIsoPacketSize :: EndpointDesc -> SizeSource
Calculate the maximum packet size which a specific endpoint is capable of sending or receiving in the duration of 1 microframe.
If acting on an Isochronous
or Interrupt
endpoint, this function will
multiply the maxPacketSize
by the additional transactionOpportunities
.
If acting on another type of endpoint only the maxPacketSize
is returned.
This function is mainly useful for setting up isochronous transfers.
String descriptors
getLanguages :: DeviceHandle -> IO (Vector LangId)Source
Retrieve a vector of supported languages.
This function may throw USBException
s.
type LangId = (PrimaryLangId, SubLangId)Source
The language ID consists of the primary language identifier and the sublanguage identififier as described in:
http://www.usb.org/developers/docs/USB_LANGIDs.pdf
For a mapping between IDs and languages see the usb-id-database package.
To see which LangId
s are supported by a device see getLanguages
.
type PrimaryLangId = Word16Source
Type of indici of string descriptors.
Can be retrieved by all the *StrIx functions.
:: DeviceHandle | |
-> StrIx | |
-> LangId | |
-> Int | Maximum number of characters in the requested string. An
|
-> IO Text |
Retrieve a string descriptor from a device.
This function may throw USBException
s.
:: DeviceHandle | |
-> StrIx | |
-> Int | Maximum number of characters in the requested
string. An |
-> IO Text |
Retrieve a string descriptor from a device using the first supported language.
This function may throw USBException
s.