USBHost.h

00001 /* Copyright (c) 2010-2012 mbed.org, MIT License
00002 *
00003 * Permission is hereby granted, free of charge, to any person obtaining a copy of this software
00004 * and associated documentation files (the "Software"), to deal in the Software without
00005 * restriction, including without limitation the rights to use, copy, modify, merge, publish,
00006 * distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the
00007 * Software is furnished to do so, subject to the following conditions:
00008 *
00009 * The above copyright notice and this permission notice shall be included in all copies or
00010 * substantial portions of the Software.
00011 *
00012 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
00013 * BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
00014 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
00015 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00016 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
00017 */
00018 
00019 #ifndef USBHOST_H
00020 #define USBHOST_H
00021 
00022 #include "USBHALHost.h"
00023 #include "USBDeviceConnected.h"
00024 #include "USBEndpoint.h"
00025 #include "IUSBEnumerator.h"
00026 
00027 #define MAX_DEVICE_NB 1
00028 
00029 // singleton class
00030 class USBHost : public USBHALHost {
00031 public:
00032     /*
00033     * Static method to create or retrieve the single USBHost instance
00034     */
00035     static USBHost * getHostInst();
00036     
00037     USB_TYPE getDeviceDescriptor(USBDeviceConnected * dev, uint8_t * buf) ;
00038     USB_TYPE getConfigurationDescriptor(USBDeviceConnected * dev, uint8_t * buf, uint16_t * len_conf_descr = NULL) ;
00039     USB_TYPE setConfiguration(USBDeviceConnected * dev, uint8_t conf) ;
00040     USB_TYPE getStringDescriptor(USBDeviceConnected * dev, uint8_t index, uint8_t * buf) ;
00041     USB_TYPE getReportDescriptor(USBDeviceConnected * dev, uint8_t * buf, uint8_t len) ;
00042 
00043     /*
00044     * Control read: setup stage, data stage and status stage
00045     *
00046     * @param dev the control read will be done for this device
00047     * @param requestType request type
00048     * @param request request
00049     * @param value value
00050     * @param index index
00051     * @param buf pointer on a buffer where will be store the data received
00052     * @param len length of the transfer
00053     *
00054     * @returns status of the control read
00055     */
00056     USB_TYPE controlRead(USBDeviceConnected * dev, uint8_t requestType, uint8_t request, uint32_t value, uint32_t index, uint8_t * buf, uint32_t len) ;
00057 
00058     /*
00059     * Control write: setup stage, data stage and status stage
00060     *
00061     * @param dev the control write will be done for this device
00062     * @param requestType request type
00063     * @param request request
00064     * @param value value
00065     * @param index index
00066     * @param buf pointer on a buffer which will be written
00067     * @param len length of the transfer
00068     *
00069     * @returns status of the control write
00070     */
00071     USB_TYPE controlWrite(USBDeviceConnected * dev, uint8_t requestType, uint8_t request, uint32_t value, uint32_t index, uint8_t * buf, uint32_t len) ;
00072 
00073 
00074     /*
00075     * Bulk read
00076     *
00077     * @param dev the bulk transfer will be done for this device
00078     * @param ep USBEndpoint which will be used to read a packet
00079     * @param buf pointer on a buffer where will be store the data received
00080     * @param len length of the transfer
00081     * @param blocking if true, the read is blocking (wait for completion)
00082     *
00083     * @returns status of the bulk read
00084     */
00085     USB_TYPE bulkRead(USBDeviceConnected * dev, USBEndpoint * ep, uint8_t * buf, uint32_t len, bool blocking = true) ;
00086 
00087     /*
00088     * Bulk write
00089     *
00090     * @param dev the bulk transfer will be done for this device
00091     * @param ep USBEndpoint which will be used to write a packet
00092     * @param buf pointer on a buffer which will be written
00093     * @param len length of the transfer
00094     * @param blocking if true, the write is blocking (wait for completion)
00095     *
00096     * @returns status of the bulk write
00097     */
00098     USB_TYPE bulkWrite(USBDeviceConnected * dev, USBEndpoint * ep, uint8_t * buf, uint32_t len, bool blocking = true) ;
00099 
00100     /*
00101     * Interrupt read
00102     *
00103     * @param dev the bulk transfer will be done for this device
00104     * @param ep USBEndpoint which will be used to write a packet
00105     * @param buf pointer on a buffer which will be written
00106     * @param len length of the transfer
00107     * @param blocking if true, the read is blocking (wait for completion)
00108     *
00109     * @returns status of the interrupt read
00110     */
00111     USB_TYPE interruptRead(USBDeviceConnected * dev, USBEndpoint * ep, uint8_t * buf, uint32_t len, bool blocking = true) ;
00112 
00113     /*
00114     * Interrupt write
00115     *
00116     * @param dev the bulk transfer will be done for this device
00117     * @param ep USBEndpoint which will be used to write a packet
00118     * @param buf pointer on a buffer which will be written
00119     * @param len length of the transfer
00120     * @param blocking if true, the write is blocking (wait for completion)
00121     *
00122     * @returns status of the interrupt write
00123     */
00124     USB_TYPE interruptWrite(USBDeviceConnected * dev, USBEndpoint * ep, uint8_t * buf, uint32_t len, bool blocking = true) ;
00125 
00126     /*
00127     * Enumerate a device. This method is responsible for:
00128     *   - set the address of the device
00129     *   - fill a USBDeviceConnected object:
00130     *       - add interfaces, endpoints, ...
00131     *   - set a configuration
00132     *
00133     * @param dev device which will be enumerated
00134     *
00135     * @returns status of the enumeration
00136     */
00137     USB_TYPE enumerate(USBDeviceConnected * dev, IUSBEnumerator* pEnumerator) ;
00138 
00139     /*
00140     * Get a device
00141     *
00142     * @param index index of the device which will be returned
00143     *
00144     * @returns pointer on the "index" device
00145     */
00146     USBDeviceConnected * getDevice(uint8_t index) ;
00147 
00148     /*
00149     * reset port and hub of a specific device
00150     *
00151     * @param pointer on the device hich will be reseted
00152     */
00153     USB_TYPE resetDevice(USBDeviceConnected * dev) ;
00154 
00155     /*
00156     * If there is a HID device connected, the host stores the length of the report descriptor.
00157     * This avoid to the driver to re-ask the configuration descriptor to request the report descriptor
00158     *
00159     * @returns length of the report descriptor
00160     */
00161     uint16_t getLengthReportDescr()  {
00162         return lenReportDescr;
00163     };
00164 
00165     /**
00166      *  register a driver into the host associated with a callback function called when the device is disconnected
00167      *
00168      *  @param dev device
00169      *  @param tptr pointer to the object to call the member function on
00170      *  @param mptr pointer to the member function to be called
00171      */
00172     template<typename T>
00173     void registerDriver(USBDeviceConnected * dev, uint8_t intf, T* tptr, void (T::*mptr)(void))  {
00174         int index = findDevice(dev);
00175         if ((index != -1) && (mptr != NULL) && (tptr != NULL)) {
00176             dev->onDisconnect(intf, tptr, mptr);
00177         }
00178     }
00179 
00180     /**
00181      * register a driver into the host associated with a callback function called when the device is disconnected
00182      *
00183      * @param dev device
00184      * @param fn callback called when the specified device has been disconnected
00185      */
00186     void registerDriver(USBDeviceConnected * dev, uint8_t intf, void (*fn)(void))  {
00187         int index = findDevice(dev);
00188         if ((index != -1) && (fn != NULL)) {
00189             dev->onDisconnect(intf, fn);
00190         }
00191     }
00192 
00193 
00194 protected:
00195 
00196     /*
00197     * Virtual method called when a device has been connected
00198     *
00199     * @param hub hub number of the device
00200     * @param port port number of the device
00201     * @param lowSpeed 1 if low speed, 0 otherwise
00202     */
00203     virtual void deviceConnected(int hub, int port, bool lowSpeed) ;
00204 
00205     /*
00206     * Virtuel method called when a device has been disconnected
00207     *
00208     * @param hub hub number of the device
00209     * @param port port number of the device
00210     * @param addr list of the TDs which have been completed to dequeue freed TDs
00211     */
00212     virtual void deviceDisconnected(int hub, int port, volatile uint32_t addr) ;
00213 
00214     /*
00215     * Virtual method called when a transfer has been completed
00216     *
00217     * @param addr list of the TDs which have been completed
00218     */
00219     virtual void transferCompleted(volatile uint32_t addr) ;
00220 
00221 
00222 private:
00223     // singleton class -> constructor is private
00224     USBHost();
00225 
00226     static USBHost * instHost;
00227 
00228     uint8_t  nb_devices;
00229     uint16_t  lenReportDescr;
00230 
00231     void fillControlBuf(uint8_t requestType, uint8_t request, uint32_t value, uint32_t index, int len) ;
00232     void parseConfDescr(USBDeviceConnected * dev, uint8_t * conf_descr, uint32_t len, IUSBEnumerator* pEnumerator) ;
00233     void freeDevice(USBDeviceConnected * dev) ;
00234     int findDevice(USBDeviceConnected * dev) ;
00235 
00236 
00237     // endpoints
00238     void unqueueEndpoint(USBEndpoint * ep) ;
00239     USBEndpoint  endpoints[MAX_ENDPOINT];
00240     USBEndpoint* volatile  control;
00241 
00242     USBEndpoint* volatile  headControlEndpoint;
00243     USBEndpoint* volatile  headBulkEndpoint;
00244     USBEndpoint* volatile  headInterruptEndpoint;
00245 
00246     USBEndpoint* volatile  tailControlEndpoint;
00247     USBEndpoint* volatile  tailBulkEndpoint;
00248     USBEndpoint* volatile  tailInterruptEndpoint;
00249 
00250     bool controlEndpointAllocated;
00251 
00252 
00253     // devices connected
00254     USBDeviceConnected  devices[MAX_DEVICE_NB];
00255     volatile bool  deviceInUse[MAX_DEVICE_NB];
00256     volatile bool  deviceReset[MAX_DEVICE_NB];
00257     
00258     /*
00259     * Add a transfer on the TD linked list associated to an ED
00260     *
00261     * @param ed the transfer is associated to this ed
00262     * @param buf pointer on a buffer where will be read/write data to send or receive
00263     * @param len transfer length
00264     *
00265     * @return status of the transfer
00266     */
00267     USB_TYPE addTransfer(USBEndpoint * ed, uint8_t * buf, uint32_t len) ;
00268     
00269     /*
00270     * Link the USBEndpoint to the linked list and attach an USBEndpoint this USBEndpoint to a device
00271     *
00272     * @param dev pointer on a USBDeviceConnected object
00273     * @param ep pointer on the USBEndpoint which will be added
00274     *
00275     * return true if successful
00276     */
00277     bool addEndpoint(USBDeviceConnected * dev, uint8_t intf_nb, USBEndpoint * ep) ;
00278 
00279     /*
00280     * Create an USBEndpoint descriptor. Warning: the USBEndpoint is not linked.
00281     *
00282     * @param type USBEndpoint type (CONTROL_ENDPOINT, BULK_ENDPOINT, INTERRUPT_ENDPOINT)
00283     * @param dir USBEndpoint direction (no meaning for CONTROL_ENDPOINT)
00284     * @param size USBEndpoint max packet size
00285     * @param addr USBEndpoint address
00286     *
00287     * @returns pointer on the USBEndpoint created
00288     */
00289     USBEndpoint * newEndpoint(ENDPOINT_TYPE type, ENDPOINT_DIRECTION dir, uint32_t size, uint8_t addr) ;
00290 
00291 
00292     // to store a setup packet
00293     uint8_t  setupPacket[8];
00294 
00295 
00296     /////////////////////////
00297     /// FOR DEBUG
00298     /////////////////////////
00299     public:
00300     void printBulk();
00301     void printInt();
00302 
00303 };
00304 
00305 #endif