sergiotarxz/nuttx
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
c10f5b9dbd
nuttx/include/nuttx/usbdev.h
patacongo 77c22b0d7f Fix to handler transfers larger than one request 
git-svn-id: svn://svn.code.sf.net/p/nuttx/code/trunk@1077 42af7a65-404d-4744-a932-0658087f49c3
2008-10-25 14:40:37 +00:00

450 lines
16 KiB
C
Raw Blame History

/************************************************************************************
* include/nuttx/usbdev.h
*
* Copyright (C) 2008 Gregory Nutt. All rights reserved.
* Author: Gregory Nutt <spudmonkey@racsa.co.cr>
*
* 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 <nuttx/config.h>
#include <sys/types.h>
/************************************************************************************
* 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 */
Reference in New Issue View Git Blame Copy Permalink