USBDevice.h

00001 /* Copyright (c) 2010-2011 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 USBDEVICE_H
00020 #define USBDEVICE_H
00021 
00022 #include "mbed.h"
00023 #include "USBDevice_Types.h"
00024 #include "USBHAL.h"
00025 
00026 #define Fastspeed_Interface 0
00027 #define Highspeed_Interface 1
00028 
00029 
00030 class USBDevice: public USBHAL
00031 {
00032 public:
00033     USBDevice(uint16_t HW_Interface,uint16_t vendor_id, uint16_t product_id, uint16_t product_release);
00034 
00035     /*
00036     * Check if the device is configured
00037     *
00038     * @returns true if configured, false otherwise
00039     */
00040     bool configured(void);
00041 
00042     /*
00043     * Connect a device
00044     *
00045     * @param blocking: block if not configured
00046     */
00047     void connect(bool blocking = true);
00048 
00049     /*
00050     * Disconnect a device
00051     */
00052     void disconnect(void);
00053 
00054     /*
00055     * Add an endpoint
00056     *
00057     * @param endpoint endpoint which will be added
00058     * @param maxPacket Maximum size of a packet which can be sent for this endpoint
00059     * @returns true if successful, false otherwise
00060     */
00061     bool addEndpoint(uint8_t endpoint, uint32_t maxPacket);
00062 
00063     /*
00064     * Start a reading on a certain endpoint.
00065     * You can access the result of the reading by USBDevice_read
00066     *
00067     * @param endpoint endpoint which will be read
00068     * @param maxSize the maximum length that can be read
00069     * @return true if successful
00070     */
00071     bool readStart(uint8_t endpoint, uint32_t maxSize);
00072 
00073     /*
00074     * Read a certain endpoint. Before calling this function, USBUSBDevice_readStart
00075     * must be called.
00076     *
00077     * Warning: blocking
00078     *
00079     * @param endpoint endpoint which will be read
00080     * @param buffer buffer will be filled with the data received
00081     * @param size the number of bytes read will be stored in *size
00082     * @param maxSize the maximum length that can be read
00083     * @returns true if successful
00084     */
00085     bool readEP(uint8_t endpoint, uint8_t * buffer, uint32_t * size, uint32_t maxSize);
00086 
00087     /*
00088     * Read a certain endpoint.
00089     *
00090     * Warning: non blocking
00091     *
00092     * @param endpoint endpoint which will be read
00093     * @param buffer buffer will be filled with the data received (if data are available)
00094     * @param size the number of bytes read will be stored in *size
00095     * @param maxSize the maximum length that can be read
00096     * @returns true if successful
00097     */
00098     bool readEP_NB(uint8_t endpoint, uint8_t * buffer, uint32_t * size, uint32_t maxSize);
00099 
00100     /*
00101     * Write a certain endpoint.
00102     *
00103     * Warning: blocking
00104     *
00105     * @param endpoint endpoint to write
00106     * @param buffer data contained in buffer will be write
00107     * @param size the number of bytes to write
00108     * @param maxSize the maximum length that can be written on this endpoint
00109     */
00110     bool write(uint8_t endpoint, uint8_t * buffer, uint32_t size, uint32_t maxSize);
00111 
00112 
00113     /*
00114     * Write a certain endpoint.
00115     *
00116     * Warning: non blocking
00117     *
00118     * @param endpoint endpoint to write
00119     * @param buffer data contained in buffer will be write
00120     * @param size the number of bytes to write
00121     * @param maxSize the maximum length that can be written on this endpoint
00122     */
00123     bool writeNB(uint8_t endpoint, uint8_t * buffer, uint32_t size, uint32_t maxSize);
00124 
00125 
00126     /*
00127     * Called by USBDevice layer on bus reset. Warning: Called in ISR context
00128     *
00129     * May be used to reset state
00130     */
00131     virtual void USBCallback_busReset(void) {};
00132 
00133     /*
00134     * Called by USBDevice on Endpoint0 request. Warning: Called in ISR context
00135     * This is used to handle extensions to standard requests
00136     * and class specific requests
00137     *
00138     * @returns true if class handles this request
00139     */
00140     virtual bool USBCallback_request() { return false; };
00141 
00142     /*
00143     * Called by USBDevice on Endpoint0 request completion
00144     * if the 'notify' flag has been set to true. Warning: Called in ISR context
00145     *
00146     * In this case it is used to indicate that a HID report has
00147     * been received from the host on endpoint 0
00148     *
00149     * @param buf buffer received on endpoint 0
00150     * @param length length of this buffer
00151     */
00152     virtual void USBCallback_requestCompleted(uint8_t * buf, uint32_t length) {};
00153 
00154     /*
00155     * Called by USBDevice layer. Set configuration of the device.
00156     * For instance, you can add all endpoints that you need on this function.
00157     *
00158     * @param configuration Number of the configuration
00159     */
00160     virtual bool USBCallback_setConfiguration(uint8_t configuration) { return false; };
00161 
00162     /*
00163      * Called by USBDevice layer. Set interface/alternate of the device.
00164      *
00165      * @param interface Number of the interface to be configured
00166      * @param alternate Number of the alternate to be configured
00167      * @returns true if class handles this request
00168      */
00169     virtual bool USBCallback_setInterface(uint16_t interface, uint8_t alternate) { return false; };
00170 
00171     /*
00172     * Get device descriptor. Warning: this method has to store the length of the report descriptor in reportLength.
00173     *
00174     * @returns pointer to the device descriptor
00175     */
00176     virtual uint8_t * deviceDesc();
00177 
00178     /*
00179     * Get configuration descriptor
00180     *
00181     * @returns pointer to the configuration descriptor
00182     */
00183     virtual uint8_t * configurationDesc(){return NULL;};
00184 
00185     /*
00186     * Get string lang id descriptor
00187     *
00188     * @return pointer to the string lang id descriptor
00189     */
00190     virtual uint8_t * stringLangidDesc();
00191 
00192     /*
00193     * Get string manufacturer descriptor
00194     *
00195     * @returns pointer to the string manufacturer descriptor
00196     */
00197     virtual uint8_t * stringImanufacturerDesc();
00198 
00199     /*
00200     * Get string product descriptor
00201     *
00202     * @returns pointer to the string product descriptor
00203     */
00204     virtual uint8_t * stringIproductDesc();
00205 
00206     /*
00207     * Get string serial descriptor
00208     *
00209     * @returns pointer to the string serial descriptor
00210     */
00211     virtual uint8_t * stringIserialDesc();
00212 
00213     /*
00214     * Get string configuration descriptor
00215     *
00216     * @returns pointer to the string configuration descriptor
00217     */
00218     virtual uint8_t * stringIConfigurationDesc();
00219 
00220     /*
00221     * Get string interface descriptor
00222     *
00223     * @returns pointer to the string interface descriptor
00224     */
00225     virtual uint8_t * stringIinterfaceDesc();
00226 
00227     /*
00228     * Get the length of the report descriptor
00229     *
00230     * @returns length of the report descriptor
00231     */
00232     virtual uint16_t reportDescLength() { return 0; };
00233 
00234 
00235 
00236 protected:
00237     virtual void busReset(void);
00238     virtual void EP0setupCallback(void);
00239     virtual void EP0out(void);
00240     virtual void EP0in(void);
00241     virtual void connectStateChanged(unsigned int connected);
00242     virtual void suspendStateChanged(unsigned int suspended);
00243     uint8_t * findDescriptor(uint8_t descriptorType);
00244     CONTROL_TRANSFER * getTransferPtr(void);
00245 
00246     uint16_t HW_INTERFACE;
00247     uint16_t VENDOR_ID;
00248     uint16_t PRODUCT_ID;
00249     uint16_t PRODUCT_RELEASE;
00250 
00251 private:
00252     bool addRateFeedbackEndpoint(uint8_t endpoint, uint32_t maxPacket);
00253     bool requestGetDescriptor(void);
00254     bool controlOut(void);
00255     bool controlIn(void);
00256     bool requestSetAddress(void);
00257     bool requestSetConfiguration(void);
00258     bool requestSetFeature(void);
00259     bool requestClearFeature(void);
00260     bool requestGetStatus(void);
00261     bool requestSetup(void);
00262     bool controlSetup(void);
00263     void decodeSetupPacket(uint8_t *data, SETUP_PACKET *packet);
00264     bool requestGetConfiguration(void);
00265     bool requestGetInterface(void);
00266     bool requestSetInterface(void);
00267 
00268     CONTROL_TRANSFER transfer;
00269     USB_DEVICE device;
00270 
00271     uint16_t currentInterface;
00272     uint8_t currentAlternate;
00273 };
00274 
00275 
00276 #endif