USBHost.h

00001 
00002 /*
00003 I changed a bit the code but all credit goes to the amazing work of :
00004 
00005 Copyright (c) 2010 Peter Barrett
00006 
00007 Permission is hereby granted, free of charge, to any person obtaining a copy
00008 of this software and associated documentation files (the "Software"), to deal
00009 in the Software without restriction, including without limitation the rights
00010 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
00011 copies of the Software, and to permit persons to whom the Software is
00012 furnished to do so, subject to the following conditions:
00013 
00014 The above copyright notice and this permission notice shall be included in
00015 all copies or substantial portions of the Software.
00016 
00017 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00018 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00019 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00020 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00021 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00022 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
00023 THE SOFTWARE.
00024 */
00025 
00026 #ifndef USBHOST_H
00027 #define USBHOST_H
00028 
00029 #ifndef u8
00030 typedef unsigned char u8;
00031 typedef unsigned short u16;
00032 typedef unsigned long u32;
00033 
00034 typedef char s8;
00035 typedef short s16;
00036 typedef char s32;
00037 #endif
00038 
00039 #define ENDPOINT_CONTROL 0
00040 #define ENDPOINT_ISOCRONOUS 1
00041 #define ENDPOINT_BULK 2
00042 #define ENDPOINT_INTERRUPT 3
00043 
00044 #define  DESCRIPTOR_TYPE_DEVICE            1
00045 #define  DESCRIPTOR_TYPE_CONFIGURATION    2
00046 #define  DESCRIPTOR_TYPE_STRING            3
00047 #define  DESCRIPTOR_TYPE_INTERFACE        4
00048 #define  DESCRIPTOR_TYPE_ENDPOINT        5
00049 
00050 #define DESCRIPTOR_TYPE_HID         0x21
00051 #define DESCRIPTOR_TYPE_REPORT      0x22
00052 #define DESCRIPTOR_TYPE_PHYSICAL    0x23
00053 #define DESCRIPTOR_TYPE_HUB         0x29
00054 
00055 enum USB_CLASS_CODE
00056 {
00057     CLASS_DEVICE,  
00058     CLASS_AUDIO,
00059     CLASS_COMM_AND_CDC_CONTROL,
00060     CLASS_HID,
00061     CLASS_PHYSICAL = 0x05,
00062     CLASS_STILL_IMAGING,
00063     CLASS_PRINTER,
00064     CLASS_MASS_STORAGE,
00065     CLASS_HUB,
00066     CLASS_CDC_DATA,
00067     CLASS_SMART_CARD,
00068     CLASS_CONTENT_SECURITY = 0x0D,
00069     CLASS_VIDEO = 0x0E,
00070     CLASS_DIAGNOSTIC_DEVICE = 0xDC,
00071     CLASS_WIRELESS_CONTROLLER = 0xE0,
00072     CLASS_MISCELLANEOUS = 0xEF,
00073     CLASS_APP_SPECIFIC = 0xFE,
00074     CLASS_VENDOR_SPECIFIC = 0xFF
00075 };
00076 //CLASS=0x00=DEVICE // This means that the use of the device comes in the Interface Descriptors
00077 
00078 #define  DEVICE_TO_HOST         0x80
00079 #define  HOST_TO_DEVICE         0x00
00080 #define  REQUEST_TYPE_CLASS     0x20
00081 #define  RECIPIENT_DEVICE       0x00
00082 #define  RECIPIENT_INTERFACE    0x01
00083 #define  RECIPIENT_ENDPOINT        0x02
00084 #define  RECIPIENT_OTHER        0x03
00085 
00086 #define  GET_STATUS                0
00087 #define  CLEAR_FEATURE            1
00088 #define  SET_FEATURE            3
00089 #define  SET_ADDRESS            5
00090 #define  GET_DESCRIPTOR            6
00091 #define  SET_DESCRIPTOR            7
00092 #define  GET_CONFIGURATION        8
00093 #define  SET_CONFIGURATION        9
00094 #define  GET_INTERFACE            10
00095 #define  SET_INTERFACE            11
00096 #define  SYNCH_FRAME            11
00097 
00098 //        -5 is nak
00099 /*
00100 0010 ACK Handshake
00101 1010 NAK Handshake
00102 1110 STALL Handshake
00103 0110 NYET (No Response Yet)
00104 */
00105 
00106 #define IO_PENDING -100
00107 #define ERR_ENDPOINT_NONE_LEFT -101
00108 #define ERR_ENDPOINT_NOT_FOUND -102
00109 #define ERR_DEVICE_NOT_FOUND -103
00110 #define ERR_DEVICE_NONE_LEFT -104
00111 #define ERR_HUB_INIT_FAILED -105
00112 #define ERR_INTERFACE_NOT_FOUND -106
00113 
00114 
00115 //prefixeds indicators:
00116 //  b = byte(8bits)
00117 //  w = word(16bits)
00118 //  bm= bit map
00119 //  bcd = binary-coded-decimal
00120 //  i = index
00121 //  id = identifier.
00122 
00123    // bDescriptorType values:
00124           //    01h device  
00125           //    02h configuration
00126           //    03h string -just for optional descriptive test
00127           //    04h interface
00128           //    05h endpoint
00129           //    06h device_qualifier -for devices theat support both full and high speeds. 
00130           //    07h other_speed_configuration
00131           //    08h interface_powr
00132           //    09h OTG -for On-The-Go devices only
00133           //    0Ah debug
00134           //    0Bh interface association -for composite devices
00135 
00136 
00137 // This is the device decriptor:
00138 typedef struct
00139 {
00140     u8    bLength; // the length in bytes of the descriptor
00141     u8    bDescriptorType; //descriptor! (01h)
00142     u16 bcdUSB; // usb specs version
00143                // usb 2.0 -> 0x0200
00144                // usb 1.1 -> 0x0110
00145                // usb 1.0 -> 0x0100
00146     u8 bDeviceClass; //class code
00147     u8 bDeviceSubClass; //subclass code
00148     u8 bDeviceProtocol; //protocol code
00149     u8 bMaxPacketSize;  //maximun packet size for endpoint 0
00150     u16 idVendor; //vendor ID
00151     u16 idProduct; //product ID
00152     u16 bcdDevice;    // device release number
00153     u8 iManufacturer; //index that points a string describing the manufacturer. zero if no string description.
00154     u8 iProduct; //index that points a string describing the product. zero if no string decription
00155     u8 iSerialNumber; //index to a string with the serial number.
00156     u8 bNumConfigurations; //number of possible configurations.
00157 } DeviceDescriptor;    // 16 bytes
00158 
00159 
00160 //after retrieving the device decriptor the host can
00161 //ask for device configuration.
00162 //When the configuration descriptor is read, it returns
00163 //the entire configuration hierarchy which includes all
00164 //related interface and endpoint descriptors.
00165 // The wTotalLength field reflects the number of bytes in the hierarchy.
00166 typedef struct
00167 {
00168     u8    bLength; //length in bytes of the descriptor
00169     u8    bDescriptorType; // the constant CONFIGURATION (02h)
00170     u16    wTotalLength;
00171     u8    bNumInterfaces; //specifies the number of interfaces present for this configuration.
00172     u8    bConfigurationValue;   //is used by the SetConfiguration request to select this configuration.
00173     u8    iConfiguration;            // Index of String Descriptor describing this configuration
00174     u8    bmAttributes;            // Bitmap D7 Reserved, set to 1. (USB 1.0 Bus Powered),D6 Self Powered,D5 Remote Wakeup,D4..0 = 0
00175     u8    bMaxPower;                // Maximum Power Consumption in 2mA units
00176 } ConfigurationDescriptor;
00177 
00178 
00179 // the InterfaceDescriptor provides information
00180 //or features implemented.
00181 //The interface descriptor could be seen as a header
00182 // or grouping of the endpoints into a functional group
00183 // performing a single feature of the device.
00184 typedef struct
00185 {
00186     u8    bLength; //descriptor size in bytes.
00187     u8    bDescriptorType; // the constant INTERFACE (04h)
00188     u8    bInterfaceNumber; //number identifing this interface
00189     u8    bAlternateSetting; //Can be used to specify alternative interfaces.
00190                              //These alternative interfaces can be selected with the Set Interface request.
00191     u8    bNumEndpoints; //number of endpoint supported, not counting the endpoint 0
00192     u8    bInterfaceClass; //class code
00193             //bInterfaceClass values:
00194             //01 Audio
00195             //02 Comunication interface
00196             //03 HID-> Human Interface Device
00197             //05 Physical
00198             //06 Image
00199             //07 Printer
00200             //08 Mass storage
00201             //09 Hub
00202             //0A Data interface
00203             //0B Smart Card
00204             //0D Content security
00205             //0E Video
00206             //DC diagnostic divice
00207             //E0 wirelless controler
00208             //FE Application specific
00209             //FF vendor specific    
00210     u8    bInterfaceSubClass; //subclass code
00211     u8    bInterfaceProtocol; //protocol code
00212     u8    iInterface;                // Index of String Descriptor Describing this interface
00213 } InterfaceDescriptor;
00214 
00215 
00216 //Each endpoint in an interface descriptor must have
00217 //an endpoint descriptor.
00218 //Endpoint descriptors are used to describe endpoints
00219 //other than endpoint zero. Endpoint zero is always
00220 //assumed to be a control endpoint and is configured
00221 // before any descriptors are even requested. The host
00222 // will use the information returned from these descriptors
00223 // to determine the bandwidth requirements of the bus.
00224 typedef struct
00225 {
00226     u8    bLength; //descriptor size in bytes.
00227     u8    bDescriptorType; //the constant ENDPOINT(05h)
00228     u8    bEndpointAddress; //Endpoint number and direction
00229        // Bits 0:3 endpoint, Bits 7 Direction 0 = Out, 1 = In (Ignored for Control Endpoints)
00230     u8    bmAttributes;  //specifies the transfer type.
00231        // Bits 0:1 00 = Control, 01 = Isochronous, 10 = Bulk, 11 = Interrupt
00232     u16 wMaxPacketSize; //maximun packet size supported.
00233     u8    bInterval;   // Interval for polling endpoint data transfers.
00234 } EndpointDescriptor;
00235 
00236 typedef struct {
00237   u8    bLength;
00238   u8    bDescriptorType; //(0x21h)
00239   u16   bcdHID; // HID specs release number
00240   u8    bCountryCode; //0X00 for no country-code
00241   u8    bNumDescriptors;//the number of class descriptors that
00242                         //are subordinated to this descriptor.
00243   u8    bDescriptorType2; //2? the type of descriptor that is subordinated
00244                           //to the class descriptor. Minimun 1, due it 
00245                           //has to have at least 1 report descriptor and/Or
00246                           //one or more phsical descriptors.
00247                           //A report descriptionr (required) is type 22h.
00248   u16   wDescriptorLength;
00249   
00250   //u8 bDescriptorTyepe;  //<- Optional; The type of descriptor that follows
00251                           //A physical descriptior is 0x23h
00252   //u16 wDescriptorLength2;   
00253   
00254 } HIDDescriptor;
00255  
00256 //============================================================================
00257 //============================================================================
00258 
00259 
00260 void USBInit();
00261 void USBLoop();
00262 u8* USBGetBuffer(u32* len);
00263 
00264 //    Optional callback for transfers, called at interrupt time
00265 typedef void (*USBCallback)(int device, int endpoint, int status, u8* data, int len, void* userData);
00266 
00267 //    Transfers
00268 int USBControlTransfer(int device, int request_type, int request, int value, int index, u8* data, int length, USBCallback callback = 0, void* userData = 0);
00269 int USBInterruptTransfer(int device, int ep, u8* data, int length, USBCallback callback = 0, void* userData = 0);
00270 int USBBulkTransfer(int device, int ep, u8* data, int length, USBCallback callback = 0, void* userData = 0);
00271 
00272 //    Standard Device methods
00273 int GetDescriptor(int device, int descType, int descIndex, u8* data, int length);
00274 int GetString(int device, int index, char* dst, int length);
00275 int SetAddress(int device, int new_addr);
00276 int SetConfiguration(int device, int configNum);
00277 int SetInterface(int device, int ifNum, int altNum);
00278 
00279 //    Implemented to notify app of the arrival of a device
00280 void OnLoadDevice(int device, DeviceDescriptor* deviceDesc, InterfaceDescriptor* interfaceDesc);
00281 
00282 #endif