| Copyright | (c) 2009–2014 Bas van Dijk |
|---|---|
| License | BSD3 (see the file LICENSE) |
| Maintainer | Bas van Dijk <v.dijk.bas@gmail.com> |
| Safe Haskell | Trustworthy |
| Language | Haskell98 |
System.USB.Descriptors
Contents
Description
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
- 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 DeviceDesc Source
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 USBExceptions.
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 getDeviceDesc.
Constructors
| DeviceDesc | |
Fields
| |
Instances
type ReleaseNumber = (Int, Int, Int, Int) Source
Release / version number of the USB specification / device.
For a database of USB vendors and products see the usb-id-database
package at: http://hackage.haskell.org/package/usb-id-database
A 16-bit number used to identify a USB device. Each vendor ID is assigned by the USB Implementers Forum to a specific company.
type ProductId = Word16 Source
A 16-bit number used to identify a USB device. Each company which is
assigned a VendorId can assign a product ID to its USB-based products.
Configuration descriptor
getConfigDesc :: Device -> Word8 -> IO ConfigDesc Source
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:
NotFoundExceptionif 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.
Constructors
| ConfigDesc | |
Fields
| |
Instances
Configuration attributes
type ConfigAttribs = DeviceStatus Source
The USB 2.0 specification specifies that the configuration attributes only describe the device status.
data DeviceStatus Source
The status of a USB device.
Constructors
| DeviceStatus | |
Fields
| |
Instances
Interface descriptor
type Interface = Vector InterfaceDesc Source
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.
Constructors
| InterfaceDesc | |
Fields
| |
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.
Constructors
| EndpointDesc | |
Fields
| |
Instances
Endpoint address
data EndpointAddress Source
The address of an endpoint.
Constructors
| EndpointAddress | |
Fields
| |
data TransferDirection Source
The direction of data transfer relative to the host.
Endpoint attributes
type EndpointAttribs = TransferType Source
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.
Constructors
| 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. |
Instances
Isochronous transfer attributes
data Synchronization Source
See section 5.12.4.1 of the USB 2.0 specification.
Constructors
| NoSynchronization | No Synchonisation. |
| 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 TransactionOpportunities Source
Number of additional transaction oppurtunities per microframe.
See table 9-13 of the USB 2.0 specification.
maxIsoPacketSize :: EndpointDesc -> Size Source
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 USBExceptions.
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 LangIds are supported by a device see getLanguages.
type PrimaryLangId = Word16 Source
The primary language identifier.
Type of indici of string descriptors.
Can be retrieved by all the *StrIx functions.
Arguments
| :: 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 USBExceptions.
Arguments
| :: 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 USBExceptions.