2007-01-23 18:55:34 +03:00
|
|
|
/*
|
2008-04-06 20:22:59 +04:00
|
|
|
* Copyright 2007-2008, Haiku Inc. All rights reserved.
|
2007-01-23 18:55:34 +03:00
|
|
|
* Distributed under the terms of the MIT License.
|
|
|
|
*/
|
|
|
|
#ifndef _USBKIT_H
|
|
|
|
#define _USBKIT_H
|
|
|
|
|
|
|
|
#include <SupportDefs.h>
|
2007-07-18 00:00:53 +04:00
|
|
|
#include <USB3.h>
|
2007-01-23 18:55:34 +03:00
|
|
|
#include <USB_spec.h>
|
|
|
|
|
|
|
|
|
|
|
|
class BUSBRoster;
|
|
|
|
class BUSBDevice;
|
|
|
|
class BUSBConfiguration;
|
|
|
|
class BUSBInterface;
|
|
|
|
class BUSBEndpoint;
|
|
|
|
|
|
|
|
|
|
|
|
/* The BUSBRoster class can be used to watch for devices that get attached or
|
|
|
|
removed from the USB bus.
|
|
|
|
You subclass the roster and implement the pure virtual DeviceAdded() and
|
|
|
|
DeviceRemoved() hooks. */
|
|
|
|
class BUSBRoster {
|
|
|
|
public:
|
|
|
|
BUSBRoster();
|
|
|
|
virtual ~BUSBRoster();
|
|
|
|
|
|
|
|
// The DeviceAdded() hook will be called when a new device gets
|
|
|
|
// attached to the USB bus. The hook is called with an initialized
|
|
|
|
// BUSBDevice object. If you return B_OK from your hook the object
|
2011-06-13 17:06:45 +04:00
|
|
|
// will stay valid and the DeviceRemoved() hook will be called for
|
|
|
|
// it. Otherwise the object is deleted and DeviceRemoved() is not
|
|
|
|
// called.
|
2007-01-23 18:55:34 +03:00
|
|
|
virtual status_t DeviceAdded(BUSBDevice *device) = 0;
|
|
|
|
|
|
|
|
// When a device gets detached from the bus that you hold a
|
|
|
|
// BUSBDevice object for (gotten through DeviceAdded()) the
|
|
|
|
// DeviceRemoved() hook will be called. The device object gets
|
|
|
|
// invalid and will be deleted as soon as you return from the hook
|
|
|
|
// so be sure to remove all references to it.
|
|
|
|
virtual void DeviceRemoved(BUSBDevice *device) = 0;
|
|
|
|
|
|
|
|
void Start();
|
|
|
|
void Stop();
|
|
|
|
|
|
|
|
private:
|
2008-04-06 23:59:24 +04:00
|
|
|
virtual void _ReservedUSBRoster1();
|
|
|
|
virtual void _ReservedUSBRoster2();
|
|
|
|
virtual void _ReservedUSBRoster3();
|
|
|
|
virtual void _ReservedUSBRoster4();
|
|
|
|
virtual void _ReservedUSBRoster5();
|
|
|
|
|
2008-09-11 01:52:32 +04:00
|
|
|
void * fLooper;
|
2008-04-06 23:59:24 +04:00
|
|
|
uint32 fReserved[10];
|
2007-01-23 18:55:34 +03:00
|
|
|
};
|
|
|
|
|
|
|
|
|
2011-06-13 17:06:45 +04:00
|
|
|
/* The BUSBDevice presents an interface to a USB device. You can either get
|
2007-01-23 18:55:34 +03:00
|
|
|
it through the BUSBRoster or by creating one yourself and setting it to
|
|
|
|
a valid raw usb device (with a path of "/dev/bus/usb/x").
|
|
|
|
The device class provides direct accessors for descriptor fields as well
|
|
|
|
as convenience functions to directly get string representations of fields.
|
|
|
|
The BUSBDevice also provides access for the BUSBConfiguration objects of
|
|
|
|
a device. These objects and all of their child objects depend on the
|
|
|
|
parent device and will be deleted as soon as the device object is
|
2011-06-13 17:06:45 +04:00
|
|
|
destroyed. */
|
2007-01-23 18:55:34 +03:00
|
|
|
class BUSBDevice {
|
|
|
|
public:
|
|
|
|
BUSBDevice(const char *path = NULL);
|
|
|
|
virtual ~BUSBDevice();
|
|
|
|
|
|
|
|
virtual status_t InitCheck();
|
|
|
|
|
|
|
|
status_t SetTo(const char *path);
|
|
|
|
void Unset();
|
|
|
|
|
2011-06-13 17:06:45 +04:00
|
|
|
// Returns the location on the bus represented as hub/device sequence.
|
2008-09-11 01:52:32 +04:00
|
|
|
const char * Location() const;
|
2007-01-23 18:55:34 +03:00
|
|
|
bool IsHub() const;
|
|
|
|
|
2011-06-13 17:06:45 +04:00
|
|
|
// These are direct accessors to descriptor fields.
|
2007-01-23 18:55:34 +03:00
|
|
|
uint16 USBVersion() const;
|
|
|
|
uint8 Class() const;
|
|
|
|
uint8 Subclass() const;
|
|
|
|
uint8 Protocol() const;
|
|
|
|
uint8 MaxEndpoint0PacketSize() const;
|
|
|
|
uint16 VendorID() const;
|
|
|
|
uint16 ProductID() const;
|
|
|
|
uint16 Version() const;
|
|
|
|
|
|
|
|
// The string functions return the string representation of the
|
|
|
|
// descriptor data. The strings are decoded to normal 0 terminated
|
2011-06-13 17:06:45 +04:00
|
|
|
// C strings and are cached and owned by the object.
|
2007-01-23 18:55:34 +03:00
|
|
|
// If a string is not available an empty string is returned.
|
2008-09-11 01:52:32 +04:00
|
|
|
const char * ManufacturerString() const;
|
|
|
|
const char * ProductString() const;
|
|
|
|
const char * SerialNumberString() const;
|
2007-01-23 18:55:34 +03:00
|
|
|
|
2008-09-11 01:52:32 +04:00
|
|
|
const usb_device_descriptor *
|
|
|
|
Descriptor() const;
|
2007-01-23 18:55:34 +03:00
|
|
|
|
|
|
|
// GetStringDescriptor() can be used to retrieve the raw
|
|
|
|
// usb_string_descriptor with a given index. The strings contained
|
|
|
|
// in these descriptors are usually two-byte unicode encoded.
|
|
|
|
size_t GetStringDescriptor(uint32 index,
|
|
|
|
usb_string_descriptor *descriptor,
|
|
|
|
size_t length) const;
|
|
|
|
|
|
|
|
// Use the DecodeStringDescriptor() convenience function to get a
|
|
|
|
// 0-terminated c string for a given string index. Note that this
|
|
|
|
// will allocate the string as "new char[];" and needs to be deleted
|
|
|
|
// like "delete[] string;" by the caller.
|
2008-09-11 01:52:32 +04:00
|
|
|
char * DecodeStringDescriptor(uint32 index) const;
|
2007-01-23 18:55:34 +03:00
|
|
|
|
|
|
|
size_t GetDescriptor(uint8 type, uint8 index,
|
|
|
|
uint16 languageID, void *data,
|
|
|
|
size_t length) const;
|
|
|
|
|
|
|
|
// With ConfigurationAt() or ActiveConfiguration() you can get an
|
|
|
|
// object that represents the configuration at a certain index or at
|
|
|
|
// the index that is currently configured. Note that the index does not
|
2011-06-13 17:06:45 +04:00
|
|
|
// necessarily correspond to the configuration_value present in the
|
|
|
|
// configuration descriptor.
|
2007-01-23 18:55:34 +03:00
|
|
|
// Use the returned object as an argument to SetConfiguration() to
|
|
|
|
// change the active configuration of a device.
|
|
|
|
uint32 CountConfigurations() const;
|
2008-09-11 01:52:32 +04:00
|
|
|
const BUSBConfiguration * ConfigurationAt(uint32 index) const;
|
2007-01-23 18:55:34 +03:00
|
|
|
|
2008-09-11 01:52:32 +04:00
|
|
|
const BUSBConfiguration * ActiveConfiguration() const;
|
2007-01-23 18:55:34 +03:00
|
|
|
status_t SetConfiguration(
|
|
|
|
const BUSBConfiguration *configuration);
|
|
|
|
|
2011-06-13 17:06:45 +04:00
|
|
|
// ControlTransfer() sends requests using the default pipe.
|
2007-01-23 18:55:34 +03:00
|
|
|
ssize_t ControlTransfer(uint8 requestType,
|
|
|
|
uint8 request, uint16 value,
|
|
|
|
uint16 index, uint16 length,
|
|
|
|
void *data) const;
|
|
|
|
|
|
|
|
private:
|
2008-04-06 23:59:24 +04:00
|
|
|
virtual void _ReservedUSBDevice1();
|
|
|
|
virtual void _ReservedUSBDevice2();
|
|
|
|
virtual void _ReservedUSBDevice3();
|
|
|
|
virtual void _ReservedUSBDevice4();
|
|
|
|
virtual void _ReservedUSBDevice5();
|
|
|
|
|
2008-09-11 01:52:32 +04:00
|
|
|
char * fPath;
|
2007-01-23 18:55:34 +03:00
|
|
|
int fRawFD;
|
|
|
|
|
|
|
|
usb_device_descriptor fDescriptor;
|
2008-09-11 01:52:32 +04:00
|
|
|
BUSBConfiguration ** fConfigurations;
|
2007-01-23 18:55:34 +03:00
|
|
|
uint32 fActiveConfiguration;
|
|
|
|
|
2008-09-11 01:52:32 +04:00
|
|
|
mutable char * fManufacturerString;
|
|
|
|
mutable char * fProductString;
|
|
|
|
mutable char * fSerialNumberString;
|
2008-04-06 23:59:24 +04:00
|
|
|
|
|
|
|
uint32 fReserved[10];
|
2007-01-23 18:55:34 +03:00
|
|
|
};
|
|
|
|
|
|
|
|
|
|
|
|
/* A BUSBConfiguration object represents one of possibly multiple
|
|
|
|
configurations a device might have. A valid object can only be gotten
|
2011-06-13 17:06:45 +04:00
|
|
|
through the ConfigurationAt() or ActiveConfiguration() methods of a
|
2007-01-23 18:55:34 +03:00
|
|
|
BUSBDevice.
|
|
|
|
The BUSBConfiguration provides further access into the configuration by
|
|
|
|
providing CountInterfaces() and InterfaceAt() to retrieve BUSBInterface
|
|
|
|
objects. */
|
|
|
|
class BUSBConfiguration {
|
|
|
|
public:
|
|
|
|
// Device() returns the parent device of this configuration. This
|
|
|
|
// configuration is located at the index returned by Index() within
|
|
|
|
// that parent device.
|
|
|
|
uint32 Index() const;
|
2008-09-11 01:52:32 +04:00
|
|
|
const BUSBDevice * Device() const;
|
2007-01-23 18:55:34 +03:00
|
|
|
|
2011-06-13 17:06:45 +04:00
|
|
|
// Gets a descriptive string for this configuration, if available.
|
2007-01-23 18:55:34 +03:00
|
|
|
// Otherwise an empty string is returned.
|
2008-09-11 01:52:32 +04:00
|
|
|
const char * ConfigurationString() const;
|
2007-01-23 18:55:34 +03:00
|
|
|
|
2008-09-11 01:52:32 +04:00
|
|
|
const usb_configuration_descriptor *
|
|
|
|
Descriptor() const;
|
2007-01-23 18:55:34 +03:00
|
|
|
|
|
|
|
// With CountInterfaces() and InterfaceAt() you can iterate through
|
|
|
|
// the child interfaces of this configuration. It is the only valid
|
|
|
|
// way to get a BUSBInterface object.
|
|
|
|
// Note that the interface objects retrieved using InterfaceAt() will
|
|
|
|
// be invalid and deleted as soon as this configuration gets deleted.
|
|
|
|
uint32 CountInterfaces() const;
|
2008-09-11 01:52:32 +04:00
|
|
|
const BUSBInterface * InterfaceAt(uint32 index) const;
|
2007-01-23 18:55:34 +03:00
|
|
|
|
|
|
|
private:
|
|
|
|
friend class BUSBDevice;
|
|
|
|
BUSBConfiguration(BUSBDevice *device,
|
|
|
|
uint32 index, int rawFD);
|
|
|
|
~BUSBConfiguration();
|
|
|
|
|
2008-09-11 01:52:32 +04:00
|
|
|
BUSBDevice * fDevice;
|
2007-01-23 18:55:34 +03:00
|
|
|
uint32 fIndex;
|
|
|
|
int fRawFD;
|
|
|
|
|
|
|
|
usb_configuration_descriptor fDescriptor;
|
2008-09-11 01:52:32 +04:00
|
|
|
BUSBInterface ** fInterfaces;
|
2007-01-23 18:55:34 +03:00
|
|
|
|
2008-09-11 01:52:32 +04:00
|
|
|
mutable char * fConfigurationString;
|
2008-04-06 23:59:24 +04:00
|
|
|
|
|
|
|
uint32 fReserved[10];
|
2007-01-23 18:55:34 +03:00
|
|
|
};
|
|
|
|
|
|
|
|
|
|
|
|
/* The BUSBInterface class can be used to access the descriptor fields of
|
|
|
|
an underleying USB interface. Most importantly though it can be used to
|
|
|
|
iterate over and retrieve BUSBEndpoint objects that can be used to
|
|
|
|
transfer data over the bus. */
|
|
|
|
class BUSBInterface {
|
|
|
|
public:
|
|
|
|
// Configuration() returns the parent configuration of this interface.
|
|
|
|
// This interface is located at the index returned by Index() in that
|
2008-09-11 01:52:32 +04:00
|
|
|
// parent configuration and represents the alternate interface returned
|
|
|
|
// by AlternateIndex().
|
2007-01-23 18:55:34 +03:00
|
|
|
// Device() is a convenience function to directly reach the parent
|
|
|
|
// device of this interface instead of going through the configuration.
|
|
|
|
uint32 Index() const;
|
2008-09-11 01:52:32 +04:00
|
|
|
uint32 AlternateIndex() const;
|
|
|
|
const BUSBConfiguration * Configuration() const;
|
|
|
|
const BUSBDevice * Device() const;
|
2007-01-23 18:55:34 +03:00
|
|
|
|
|
|
|
// These are accessors to descriptor fields. InterfaceString() tries
|
2011-06-13 17:06:45 +04:00
|
|
|
// to return a descriptive string for the interface. If no string is
|
|
|
|
// available an empty string is returned.
|
2007-01-23 18:55:34 +03:00
|
|
|
uint8 Class() const;
|
|
|
|
uint8 Subclass() const;
|
|
|
|
uint8 Protocol() const;
|
2008-09-11 01:52:32 +04:00
|
|
|
const char * InterfaceString() const;
|
2007-01-23 18:55:34 +03:00
|
|
|
|
2008-09-11 01:52:32 +04:00
|
|
|
const usb_interface_descriptor *
|
|
|
|
Descriptor() const;
|
2007-01-23 18:55:34 +03:00
|
|
|
|
|
|
|
// Use OtherDescriptorAt() to get generic descriptors of an interface.
|
2011-06-13 17:06:45 +04:00
|
|
|
// These are usually device/interface class specific or they may
|
|
|
|
// represent vendor specific extensions.
|
2007-01-23 18:55:34 +03:00
|
|
|
status_t OtherDescriptorAt(uint32 index,
|
|
|
|
usb_descriptor *descriptor,
|
|
|
|
size_t length) const;
|
|
|
|
|
|
|
|
// CountEndpoints() and EndpointAt() can be used to iterate over the
|
|
|
|
// available endpoints within an interface. EndpointAt() is the only
|
|
|
|
// valid way to get BUSBEndpoint object. Note that these objects will
|
|
|
|
// get invalid and deleted as soon as the parent interface is deleted.
|
|
|
|
uint32 CountEndpoints() const;
|
2008-09-11 01:52:32 +04:00
|
|
|
const BUSBEndpoint * EndpointAt(uint32 index) const;
|
2007-01-23 18:55:34 +03:00
|
|
|
|
2008-04-06 20:22:59 +04:00
|
|
|
// Using CountAlternates() you can retrieve the number of alternate
|
2008-04-06 23:59:24 +04:00
|
|
|
// interfaces for this interface. Note that this interface itself
|
2008-04-06 20:22:59 +04:00
|
|
|
// counts as an alternate so an alternate count of one really means
|
|
|
|
// that you are currently using the sole interface present.
|
2008-04-06 23:59:24 +04:00
|
|
|
// AlternateAt() returns the interface descriptor of the alternate
|
|
|
|
// interface with the specified index. Using that you can peek at the
|
2008-09-11 01:52:32 +04:00
|
|
|
// attributes of that alternate (including endpoints) without having to
|
|
|
|
// switch to this alternate interface.
|
|
|
|
// Note that you cannot use any endpoint you retrieve through an
|
|
|
|
// interface you get through AlternateAt(). Even if you switch to that
|
|
|
|
// alternate later on, you cannot use an interface returned by
|
|
|
|
// AlternateAt(). Instead switch to that alternate using the interface
|
|
|
|
// you got from the configuration and then use this switched interface
|
|
|
|
// to enumerate the endpoints.
|
|
|
|
// ActiveAlternateIndex() returns the index of the currently active
|
|
|
|
// alternate interface.
|
2008-04-06 20:22:59 +04:00
|
|
|
// With SetAlternate() you can switch this BUSBInterface object to the
|
2008-04-06 23:59:24 +04:00
|
|
|
// alternate interface at the specified index. Note that all endpoints
|
|
|
|
// retrieved through EndpointAt() will become invalid and will be
|
|
|
|
// deleted as soon as you set an alternate interface (even if the
|
|
|
|
// resulting interface is the same you were using before).
|
2008-04-06 20:22:59 +04:00
|
|
|
uint32 CountAlternates() const;
|
2008-09-11 01:52:32 +04:00
|
|
|
uint32 ActiveAlternateIndex() const;
|
|
|
|
const BUSBInterface * AlternateAt(uint32 alternateIndex) const;
|
2008-04-06 20:22:59 +04:00
|
|
|
status_t SetAlternate(uint32 alternateIndex);
|
|
|
|
|
2007-01-23 18:55:34 +03:00
|
|
|
private:
|
|
|
|
friend class BUSBConfiguration;
|
|
|
|
BUSBInterface(BUSBConfiguration *config,
|
2008-09-11 01:52:32 +04:00
|
|
|
uint32 index, uint32 alternate,
|
|
|
|
int rawFD);
|
2007-01-23 18:55:34 +03:00
|
|
|
~BUSBInterface();
|
|
|
|
|
2008-04-06 20:22:59 +04:00
|
|
|
void _UpdateDescriptorAndEndpoints();
|
|
|
|
|
2008-09-11 01:52:32 +04:00
|
|
|
BUSBConfiguration * fConfiguration;
|
2007-01-23 18:55:34 +03:00
|
|
|
uint32 fIndex;
|
2008-09-11 01:52:32 +04:00
|
|
|
uint32 fAlternate;
|
2007-01-23 18:55:34 +03:00
|
|
|
int fRawFD;
|
|
|
|
|
|
|
|
usb_interface_descriptor fDescriptor;
|
2008-09-11 01:52:32 +04:00
|
|
|
BUSBEndpoint ** fEndpoints;
|
|
|
|
|
|
|
|
mutable uint32 fAlternateCount;
|
|
|
|
mutable BUSBInterface ** fAlternates;
|
2007-01-23 18:55:34 +03:00
|
|
|
|
2008-09-11 01:52:32 +04:00
|
|
|
mutable char * fInterfaceString;
|
2008-04-06 23:59:24 +04:00
|
|
|
|
|
|
|
uint32 fReserved[10];
|
2007-01-23 18:55:34 +03:00
|
|
|
};
|
|
|
|
|
|
|
|
|
|
|
|
/* The BUSBEndpoint represent a device endpoint that can be used to send or
|
2007-07-18 00:00:53 +04:00
|
|
|
receive data. It also allows to query endpoint characteristics like
|
2007-01-23 18:55:34 +03:00
|
|
|
endpoint type or direction. */
|
|
|
|
class BUSBEndpoint {
|
|
|
|
public:
|
|
|
|
// Interface() returns the parent interface of this endpoint.
|
|
|
|
// This endpoint is located at the index returned by Index() in the
|
|
|
|
// parent interface.
|
|
|
|
// Configuration() and Device() are convenience functions to directly
|
|
|
|
// reach the parent configuration or device of this endpoint instead
|
|
|
|
// of going through the parent objects.
|
|
|
|
uint32 Index() const;
|
2008-09-11 01:52:32 +04:00
|
|
|
const BUSBInterface * Interface() const;
|
|
|
|
const BUSBConfiguration * Configuration() const;
|
|
|
|
const BUSBDevice * Device() const;
|
2007-01-23 18:55:34 +03:00
|
|
|
|
|
|
|
// These methods can be used to check for endpoint characteristics.
|
|
|
|
bool IsBulk() const;
|
|
|
|
bool IsInterrupt() const;
|
|
|
|
bool IsIsochronous() const;
|
|
|
|
bool IsControl() const;
|
|
|
|
|
|
|
|
bool IsInput() const;
|
|
|
|
bool IsOutput() const;
|
|
|
|
|
|
|
|
uint16 MaxPacketSize() const;
|
|
|
|
uint8 Interval() const;
|
|
|
|
|
2008-09-11 01:52:32 +04:00
|
|
|
const usb_endpoint_descriptor *
|
|
|
|
Descriptor() const;
|
2007-01-23 18:55:34 +03:00
|
|
|
|
|
|
|
// These methods initiate transfers to or from the endpoint. All
|
|
|
|
// transfers are synchronous and the actually transfered amount of
|
|
|
|
// data is returned as a result. A negative value indicates an error.
|
|
|
|
// Which transfer type to use depends on the endpoint type.
|
|
|
|
ssize_t ControlTransfer(uint8 requestType,
|
|
|
|
uint8 request, uint16 value,
|
|
|
|
uint16 index, uint16 length,
|
|
|
|
void *data) const;
|
|
|
|
ssize_t InterruptTransfer(void *data,
|
|
|
|
size_t length) const;
|
|
|
|
ssize_t BulkTransfer(void *data,
|
|
|
|
size_t length) const;
|
2007-07-18 00:00:53 +04:00
|
|
|
ssize_t IsochronousTransfer(void *data,
|
|
|
|
size_t length,
|
|
|
|
usb_iso_packet_descriptor *packetDescriptors,
|
|
|
|
uint32 packetCount) const;
|
2007-01-23 18:55:34 +03:00
|
|
|
|
2008-04-06 20:22:59 +04:00
|
|
|
// These are convenience methods for getting and clearing the halt
|
|
|
|
// state of an endpoint. They use the control pipe of the device to
|
|
|
|
// send the corresponding requests.
|
|
|
|
bool IsStalled() const;
|
|
|
|
status_t ClearStall() const;
|
2008-09-11 01:52:32 +04:00
|
|
|
|
2007-01-23 18:55:34 +03:00
|
|
|
private:
|
|
|
|
friend class BUSBInterface;
|
|
|
|
BUSBEndpoint(BUSBInterface *interface,
|
|
|
|
uint32 index, int rawFD);
|
|
|
|
~BUSBEndpoint();
|
|
|
|
|
2008-09-11 01:52:32 +04:00
|
|
|
BUSBInterface * fInterface;
|
2007-01-23 18:55:34 +03:00
|
|
|
uint32 fIndex;
|
|
|
|
int fRawFD;
|
|
|
|
|
|
|
|
usb_endpoint_descriptor fDescriptor;
|
2008-04-06 23:59:24 +04:00
|
|
|
|
|
|
|
uint32 fReserved[10];
|
2007-01-23 18:55:34 +03:00
|
|
|
};
|
|
|
|
|
2011-06-13 17:06:45 +04:00
|
|
|
#endif // _USB_KIT_H
|