/************************************************************************************ * include/nuttx/usbdev.h * * Copyright (C) 2008 Gregory Nutt. All rights reserved. * Author: Gregory Nutt * * NOTE: This interface was inspired by the Linux gadget interface by * David Brownell. That work was very helpful in determining a usable * partitioning of functionality between standard class drivers and various * implementations of USB controller drivers. This work, however, does * not derive directly from that work and is licensed differently. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in * the documentation and/or other materials provided with the * distribution. * 3. Neither the name NuttX nor the names of its contributors may be * used to endorse or promote products derived from this software * without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. * ************************************************************************************/ #ifndef _INCLUDE_NUTTX_USBDEV_H #define _INCLUDE_NUTTX_USBDEV_H /************************************************************************************ * Included Files ************************************************************************************/ #include #include /************************************************************************************ * Definitions ************************************************************************************/ /* Endpoint helpers *****************************************************************/ /* Configure endpoint, making it usable. The class driver may deallocate or re-use * the 'desc' structure after returning: * * ep - the struct usbdev_ep_s instance obtained from allocep() * desc - A struct usb_epdesc_s instance describing the endpoint * last - TRUE if this this last endpoint to be configured. Some hardware needs * to take special action when all of the endpoints have been configured. */ #define EP_CONFIGURE(ep,desc,last) (ep)->ops->configure(ep,desc,last) /* The endpoint will no longer be used */ #define EP_DISABLE(ep) (ep)->ops->disable(ep) /* Allocate/free I/O requests. Should not be called from interrupt processing! */ #define EP_ALLOCREQ(ep) (ep)->ops->allocreq(ep) #define EP_FREEREQ(ep,req) (ep)->ops->freereq(ep,req) /* Allocate/free an I/O buffer. Should not be called from interrupt processing! */ #ifdef CONFIG_ARCH_USBDEV_DMA # define EP_ALLOCBUFFER(ep,nb) (ep)->ops->alloc(ep,nb) # define EP_FREEBUFFER(ep,buff) (ep)->ops->free(ep,buf) #else # define EP_ALLOCBUFFER(ep,nb) malloc(nb) # define EP_FREEBUFFER(ep,buf) free(buf) #endif /* Submit an I/O request to the endpoint */ #define EP_SUBMIT(ep,req) (ep)->ops->submit(ep,req) /* Cancel an I/O request previously sent to an endpoint */ #define EP_CANCEL(ep,req) (ep)->ops->cancel(ep,req) /* Stall or resume an endpoint */ #define EP_STALL(ep) (ep)->ops->stall(ep,FALSE) #define EP_RESUME(ep) (ep)->ops->stall(ep,TRUE) /* USB Device Driver Helpers ********************************************************/ /* Allocate an endpoint: * * ep - 7-bit logical endpoint number (direction bit ignored). Zero means * that any endpoint matching the other requirements will suffice. The * assigned endpoint can be found in the eplog field. * in - TRUE: IN (device-to-host) endpoint requested * eptype - Endpoint type. One of {USB_EP_ATTR_XFER_ISOC, USB_EP_ATTR_XFER_BULK, * USB_EP_ATTR_XFER_INT} */ #define DEV_ALLOCEP(dev,ep,in,type) (dev)->ops->allocep(dev,ep,in,type) /* Release an endpoint */ #define DEV_FREEEP(dev,ep) (dev)->ops->freeep(dev,ep) /* Returns the current frame number */ #define DEV_GETFRAME(dev) (dev)->ops->getframe(dev) /* Tries to wake up the host connected to this device */ #define DEV_WAKEUP(dev) (dev)->ops->wakeup(dev) /* Sets the device selfpowered feature */ #define DEV_SETSELFPOWERED(dev) (dev)->ops->selfpowered(dev,TRUE) /* Clears the device selfpowered feature */ #define DEV_CLRSELFPOWERED(dev) (dev)->ops->selfpowered(dev, FALSE) /* Software-controlled connect to USB host */ #define DEV_CONNECT(dev) (dev)->ops->pullup ? (dev)->ops->pullup(dev,TRUE) : -EOPNOTSUPP /* Software-controlled disconnect from USB host */ #define DEV_DISCONNECT(dev) (dev)->ops->pullup ? (dev)->ops->pullup(dev,FALSE) : -EOPNOTSUPP /* USB Class Driver Helpsers ********************************************************/ /* All may be called from interupt handling logic except bind() and unbind() */ /* Invoked when the driver is bound to a USB device driver. */ #define CLASS_BIND(drvr,dev) (drvr)->ops->bind(dev, drvr) /* Invoked when the driver is unbound from a USB device driver */ #define CLASS_UNBIND(drvr,dev) (drvr)->ops->unbind(dev) /* Invoked after all transfers have been stopped, when the host is disconnected. */ #define CLASS_DISCONNECT(drvr,dev) (drvr)->ops->disconnect(dev) /* Invoked for ep0 control requests */ #define CLASS_SETUP(drvr,dev,ctrl) (drvr)->ops->setup(dev, ctrl) /* Invoked on USB suspend. */ #define CLASS_SUSPEND(drvr,dev) (drvr)->ops->suspend ? (drvr)->ops->suspend(dev) : (void) /* Invoked on USB resume */ #define CLASS_RESUME(drvr,dev) (drvr)->ops->resume ? (drvr)->ops->resume(dev) : (void) /* Device speeds */ #define USB_SPEED_UNKNOWN 0 /* Transfer rate not yet set */ #define USB_SPEED_LOW 1 /* USB 1.1 */ #define USB_SPEED_FULL 2 /* USB 1.1 */ #define USB_SPEED_HIGH 3 /* USB 2.0 */ #define USB_SPEED_VARIABLE 4 /* Wireless USB 2.5 */ /* Request flags */ #define USBDEV_REQFLAGS_NULLPKT 0 /* Terminate w/short packet; null packet if necessary */ /************************************************************************************ * Public Types ************************************************************************************/ /* USB Controller Structures ********************************************************/ /* struct usbdev_req_s - describes one i/o request */ struct usbdev_ep_s; struct usbdev_req_s { char *buf; /* Call: Buffer used for data; Return: Unchanged */ ubyte flags; /* See USBDEV_REQFLAGS_* definitions */ uint16 len; /* Call: Total length of data in buf; Return: Unchanged */ uint16 xfrd; /* Call: zero; Return: Bytes transferred so far */ sint16 result; /* Call: zero; Return: Result of transfer (O or -errno) */ /* Callback when the transfer completes */ void (*callback)(FAR struct usbdev_ep_s *ep, FAR struct usbdev_req_s *req); void *private; /* Used only by callee */ }; /* Endpoint-specific interface to USB controller hardware. */ struct usbdev_epops_s { /* Configure/enable and disable endpoint */ int (*configure)(FAR struct usbdev_ep_s *ep, FAR const struct usb_epdesc_s *desc, boolean last); int (*disable)(FAR struct usbdev_ep_s *ep); /* Allocate and free I/O requests */ FAR struct usbdev_req_s *(*allocreq)(FAR struct usbdev_ep_s *ep); void (*freereq)(FAR struct usbdev_ep_s *ep, FAR struct usbdev_req_s *req); /* Allocate and free I/O buffers */ #ifdef CONFIG_ARCH_USBDEV_DMA FAR void *(*allocbuffer)(FAR struct usbdev_ep_s *ep, uint16 nbytes); void (*freebuffer)(FAR struct usbdev_ep_s *ep, FAR void *buf); #endif /* Submit and cancel I/O requests */ int (*submit)(FAR struct usbdev_ep_s *ep, FAR struct usbdev_req_s *req); int (*cancel)(FAR struct usbdev_ep_s *ep, FAR struct usbdev_req_s *req); /* Stall or resume an endpoint */ int (*stall)(FAR struct usbdev_ep_s *ep, boolean resume); }; /* Representation of one USB endpoint */ struct usbdev_ep_s { const struct usbdev_epops_s *ops; /* Endpoint operations */ ubyte eplog; /* Logical endpoint address */ uint16 maxpacket; /* Maximum packet size for this endpoint */ void *private; /* For use by class driver */ }; /* struct usbdev_s represents a usb device */ struct usbdev_s; struct usbdev_ops_s { /* Allocate and free endpoints */ FAR struct usbdev_ep_s *(*allocep)(FAR struct usbdev_s *dev, ubyte epphy, boolean in, ubyte eptype); void (*freeep)(FAR struct usbdev_s *dev, FAR struct usbdev_ep_s *ep); /* Get the frame number from the last SOF */ int (*getframe)(FAR struct usbdev_s *dev); /* Hardware specific features */ int (*wakeup)(FAR struct usbdev_s *dev); int (*selfpowered)(FAR struct usbdev_s *dev, boolean selfpowered); int (*pullup)(FAR struct usbdev_s *dev, boolean enable); /* Device-specific I/O command support */ int (*ioctl)(FAR struct usbdev_s *dev, unsigned code, unsigned long param); }; struct usbdev_s { const struct usbdev_ops_s *ops; /* Access to hardware specific features */ struct usbdev_ep_s *ep0; /* Endpoint zero */ ubyte speed; /* Current speed of host connection */ ubyte dualspeed:1; /* 1:supports high and full speed operation */ }; /* USB Device Class Implementations *************************************************/ struct usbdevclass_driverops_s { int (*bind)(FAR struct usbdev_s *dev, FAR struct usbdevclass_driver_s *driver); void (*unbind)(FAR struct usbdev_s *dev); int (*setup)(FAR struct usbdev_s *dev, const struct usb_ctrlreq_s *ctrl); void (*disconnect)(FAR struct usbdev_s *dev); void (*suspend)(FAR struct usbdev_s *dev); void (*resume)(FAR struct usbdev_s *dev); }; struct usbdevclass_driver_s { const struct usbdevclass_driverops_s *ops; ubyte speed; /* Highest speed that the driver handles */ }; /************************************************************************************ * Public Data ************************************************************************************/ #undef EXTERN #if defined(__cplusplus) # define EXTERN extern "C" extern "C" { #else # define EXTERN extern #endif /************************************************************************************ * Public Functions ************************************************************************************/ /************************************************************************************ * Name: usbdevclass_register * * Description: * Register a USB device class driver. The class driver's bind() method will be * called to bind it to a USB device driver. * ************************************************************************************/ EXTERN int usbdev_register(FAR struct usbdevclass_driver_s *driver); /************************************************************************************ * Name: usbdev_unregister * * Description: * Un-register usbdev class driver.If the USB device is connected to a USB host, * it will first disconnect(). The driver is also requested to unbind() and clean * up any device state, before this procedure finally returns. * ************************************************************************************/ EXTERN int usbdev_unregister(FAR struct usbdevclass_driver_s *driver); /**************************************************************************** * Name: usbdev_serialinit * * Description: * Register USB serial port (and USB serial console if so configured). * ****************************************************************************/ EXTERN int usbdev_serialinitialize(int minor); /**************************************************************************** * Name: usbstrg_configure * * Description: * One-time initialization of the USB storage driver. The initialization * sequence is as follows: * * 1. Call usbstrg_configure to perform one-time initialization specifying * the number of luns. * 2. Call usbstrg_bindlun to configure each supported LUN * 3. Call usbstrg_exportluns when all LUNs are configured * * Input Parameters: * nluns - the number of LUNs that will be registered * handle - Location to return a handle that is used in other API calls. * * Returned Value: * 0 on success; a negated errno on failure * ****************************************************************************/ EXTERN int usbstrg_configure(unsigned int nluns, void **handle); /**************************************************************************** * Name: usbstrg_bindlun * * Description: * Bind the block driver specified by drvrpath to a USB storage LUN. * * Input Parameters: * handle - The handle returned by a previous call to usbstrg_configure(). * drvrpath - the full path to the block driver * startsector - A sector offset into the block driver to the start of the * partition on drvrpath (0 if no partitions) * nsectors - The number of sectors in the partition (if 0, all sectors * to the end of the media will be exported). * lunno - the LUN to bind to * * Returned Value: * 0 on success; a negated errno on failure. * ****************************************************************************/ EXTERN int usbstrg_bindlun(FAR void *handle, FAR const char *drvrpath, unsigned int lunno, off_t startsector, size_t nsectors, boolean readonly); /**************************************************************************** * Name: usbstrg_unbindlun * * Description: * Un-bind the block driver for the specified LUN * * Input Parameters: * handle - The handle returned by a previous call to usbstrg_configure(). * lun - the LUN to unbind from * * Returned Value: * 0 on success; a negated errno on failure. * ****************************************************************************/ EXTERN int usbstrg_unbindlun(FAR void *handle, unsigned int lunno); /**************************************************************************** * Name: usbstrg_exportluns * * Description: * After all of the LUNs have been bound, this function may be called * in order to export those LUNs in the USB storage device. * * Input Parameters: * handle - The handle returned by a previous call to usbstrg_configure(). * * Returned Value: * 0 on success; a negated errno on failure * ****************************************************************************/ EXTERN int usbstrg_exportluns(FAR void *handle); /**************************************************************************** * Name: usbstrg_uninitialize * * Description: * Un-initialize the USB storage class driver * * Input Parameters: * handle - The handle returned by a previous call to usbstrg_configure(). * * Returned Value: * None * ****************************************************************************/ EXTERN void usbstrg_uninitialize(FAR void *handle); #undef EXTERN #if defined(__cplusplus) } #endif #endif /* _INCLUDE_NUTTX_USBDEV_H */