1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261 |
- /************************************************************************************
- * include/nuttx/usb/usbhost.h
- *
- * Licensed to the Apache Software Foundation (ASF) under one or more
- * contributor license agreements. See the NOTICE file distributed with
- * this work for additional information regarding copyright ownership. The
- * ASF licenses this file to you under the Apache License, Version 2.0 (the
- * "License"); you may not use this file except in compliance with the
- * License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
- * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
- * License for the specific language governing permissions and limitations
- * under the License.
- *
- ************************************************************************************/
- /* References:
- * "Universal Serial Bus Mass Storage Class, Specification Overview,"
- * Revision 1.2, USB Implementer's Forum, June 23, 2003.
- *
- * "Universal Serial Bus Mass Storage Class, Bulk-Only Transport,"
- * Revision 1.0, USB Implementer's Forum, September 31, 1999.
- */
- #ifndef __INCLUDE_NUTTX_USB_USBHOST_H
- #define __INCLUDE_NUTTX_USB_USBHOST_H
- /************************************************************************************
- * Included Files
- ************************************************************************************/
- #include <nuttx/config.h>
- #include <sys/types.h>
- #include <stdint.h>
- #include <stdbool.h>
- #ifdef CONFIG_USBHOST_MSC_NOTIFIER
- # include <nuttx/wqueue.h>
- #endif
- #include <nuttx/usb/usbhost_devaddr.h>
- /************************************************************************************
- * Pre-processor Definitions
- ************************************************************************************/
- /************************************************************************************
- * Name: ROOTHUB
- *
- * Description:
- * Check if a hub instance is the root hub.
- *
- ************************************************************************************/
- #ifdef CONFIG_USBHOST_HUB
- # define ROOTHUB(hub) ((hub)->parent == NULL)
- #else
- # define ROOTHUB(hub) true
- #endif
- /************************************************************************************
- * Name: CLASS_CREATE
- *
- * Description:
- * This macro will call the create() method of struct usbhost_registry_s.
- * The create() method is a callback into the class implementation. It is used
- * to (1) create a new instance of the USB host class state and to (2) bind a
- * USB host driver "session" to the class instance. Use of this create() method
- * will support environments where there may be multiple USB ports and multiple
- * USB devices simultaneously connected.
- *
- * Input Parameters:
- * reg - The USB host class registry entry previously obtained from a call to
- * usbhost_findclass().
- * hport - The hub hat manages the new class instance.
- * id - In the case where the device supports multiple base classes, subclasses, or
- * protocols, this specifies which to configure for.
- *
- * Returned Value:
- * On success, this function will return a non-NULL instance of struct
- * usbhost_class_s that can be used by the USB host driver to communicate with the
- * USB host class. NULL is returned on failure; this function will fail only if
- * the drvr input parameter is NULL or if there are insufficient resources to
- * create another USB host class instance.
- *
- * Assumptions:
- * If this function is called from an interrupt handler, it will be unable to
- * allocate memory and CONFIG_USBHOST_NPREALLOC should be defined to be a value
- * greater than zero specify a number of pre-allocated class structures.
- *
- ************************************************************************************/
- #define CLASS_CREATE(reg,hport,id) ((reg)->create(hport,id))
- /************************************************************************************
- * Name: CLASS_CONNECT
- *
- * Description:
- * This macro will call the connect() method of struct usbhost_class_s. This
- * method is a callback into the devclass implementation. It is used to provide
- * the device's configuration descriptor to the devclass so that the devclass may
- * initialize properly.
- *
- * Input Parameters:
- * devclass - The USB host class entry previously obtained from a call
- * to create().
- * configdesc - A pointer to a uint8_t buffer containing the configuration
- * descriptor.
- * desclen - The length in bytes of the configuration descriptor.
- *
- * Returned Value:
- * On success, zero (OK) is returned. On a failure, a negated errno value is
- * returned indicating the nature of the failure
- *
- * NOTE that the class instance remains valid upon return with a failure. It is
- * the responsibility of the higher level enumeration logic to call
- * CLASS_DISCONNECTED to free up the class driver resources.
- *
- * Assumptions:
- * - This function is probably called on the same thread that called the driver
- * enumerate() method. This function will *not* be called from an interrupt
- * handler.
- * - If this function returns an error, the USB host controller driver
- * must call to DISCONNECTED method to recover from the error
- *
- ************************************************************************************/
- #define CLASS_CONNECT(devclass,configdesc,desclen) \
- ((devclass)->connect(devclass,configdesc,desclen))
- /************************************************************************************
- * Name: CLASS_DISCONNECTED
- *
- * Description:
- * This macro will call the disconnected() method of struct usbhost_class_s. This
- * method is a callback into the class implementation. It is used to inform the
- * class that the USB device has been disconnected.
- *
- * Input Parameters:
- * devclass - The USB host class entry previously obtained from a call to create().
- *
- * Returned Value:
- * On success, zero (OK) is returned. On a failure, a negated errno value is
- * returned indicating the nature of the failure
- *
- * Assumptions:
- * This function will *not* be called from an interrupt handler.
- *
- ************************************************************************************/
- #define CLASS_DISCONNECTED(devclass) ((devclass)->disconnected(devclass))
- /************************************************************************************
- * Name: CONN_WAIT
- *
- * Description:
- * Wait for a device to be connected or disconnected to/from a hub port.
- *
- * Input Parameters:
- * conn - The USB host connection instance obtained as a parameter from the call to
- * the USB driver initialization logic.
- * hport - The location to return the hub port descriptor that detected the
- * connection related event.
- *
- * Returned Value:
- * Zero (OK) is returned on success when a device is connected or
- * disconnected. This function will not return until either (1) a device is
- * connected or disconnect to/from any hub port or until (2) some failure
- * occurs. On a failure, a negated errno value is returned indicating the
- * nature of the failure
- *
- * Assumptions:
- * - Called from a single thread so no mutual exclusion is required.
- * - Never called from an interrupt handler.
- *
- ************************************************************************************/
- #define CONN_WAIT(conn,hport) ((conn)->wait(conn,hport))
- /************************************************************************************
- * Name: CONN_ENUMERATE
- *
- * Description:
- * Enumerate the connected device. As part of this enumeration process,
- * the driver will (1) get the device's configuration descriptor, (2)
- * extract the class ID info from the configuration descriptor, (3) call
- * usbhost_findclass() to find the class that supports this device, (4)
- * call the create() method on the struct usbhost_registry_s interface
- * to get a class instance, and finally (5) call the connect() method
- * of the struct usbhost_class_s interface. After that, the class is in
- * charge of the sequence of operations.
- *
- * Input Parameters:
- * conn - The USB host connection instance obtained as a parameter from
- * the call to the USB driver initialization logic.
- * hport - The descriptor of the hub port that has the newly connected
- * device.
- *
- * Returned Value:
- * On success, zero (OK) is returned. On a failure, a negated errno value is
- * returned indicating the nature of the failure
- *
- * Assumptions:
- * This function will *not* be called from an interrupt handler.
- *
- ************************************************************************************/
- #define CONN_ENUMERATE(conn,rhpndx) ((conn)->enumerate(conn,rhpndx))
- /************************************************************************************
- * Name: DRVR_EP0CONFIGURE
- *
- * Description:
- * Configure endpoint 0. This method is normally used internally by the
- * enumerate() method but is made available at the interface to support
- * an external implementation of the enumeration logic.
- *
- * Input Parameters:
- * drvr - The USB host driver instance obtained as a parameter from the call to
- * the class create() method.
- * ep0 - The (opaque) EP0 endpoint instance
- * funcaddr - The USB address of the function containing the endpoint that EP0
- * controls
- * speed - The speed of the port USB_SPEED_LOW, _FULL, or _HIGH
- * mps (maxpacketsize) - The maximum number of bytes that can be sent to or
- * received from the endpoint in a single data packet
- *
- * Returned Value:
- * On success, zero (OK) is returned. On a failure, a negated errno value is
- * returned indicating the nature of the failure
- *
- * Assumptions:
- * This function will *not* be called from an interrupt handler.
- *
- ************************************************************************************/
- #define DRVR_EP0CONFIGURE(drvr,ep0,funcaddr,speed,mps) \
- ((drvr)->ep0configure(drvr,ep0,funcaddr,speed,mps))
- /************************************************************************************
- * Name: DRVR_GETDEVINFO
- *
- * Description:
- * Get information about the connected device.
- *
- * Input Parameters:
- * drvr - The USB host driver instance obtained as a parameter from the call to
- * the class create() method.
- * devinfo - A pointer to memory provided by the caller in which to return the
- * device information.
- *
- * Returned Value:
- * On success, zero (OK) is returned. On a failure, a negated errno value is
- * returned indicating the nature of the failure
- *
- * Assumptions:
- * This function will *not* be called from an interrupt handler.
- *
- ************************************************************************************/
- #define DRVR_GETDEVINFO(drvr,devinfo) ((drvr)->getdevinfo(drvr,devinfo))
- /************************************************************************************
- * Name: DRVR_EPALLOC
- *
- * Description:
- * Allocate and configure one endpoint.
- *
- * Input Parameters:
- * drvr - The USB host driver instance obtained as a parameter from the call to
- * the class create() method.
- * epdesc - Describes the endpoint to be allocated.
- * ep - A memory location provided by the caller in which to receive the
- * allocated endpoint descriptor.
- *
- * Returned Value:
- * On success, zero (OK) is returned. On a failure, a negated errno value is
- * returned indicating the nature of the failure
- *
- * Assumptions:
- * This function will *not* be called from an interrupt handler.
- *
- ************************************************************************************/
- #define DRVR_EPALLOC(drvr,epdesc,ep) ((drvr)->epalloc(drvr,epdesc,ep))
- /************************************************************************************
- * Name: DRVR_EPFREE
- *
- * Description:
- * Free and endpoint previously allocated by DRVR_EPALLOC.
- *
- * Input Parameters:
- * drvr - The USB host driver instance obtained as a parameter from the call to
- * the class create() method.
- * ep - The endpoint to be freed.
- *
- * Returned Value:
- * On success, zero (OK) is returned. On a failure, a negated errno value is
- * returned indicating the nature of the failure
- *
- * Assumptions:
- * This function will *not* be called from an interrupt handler.
- *
- ************************************************************************************/
- #define DRVR_EPFREE(drvr,ep) ((drvr)->epfree(drvr,ep))
- /************************************************************************************
- * Name: DRVR_ALLOC
- *
- * Description:
- * Some hardware supports special memory in which request and descriptor data can
- * be accessed more efficiently. This method provides a mechanism to allocate
- * the request/descriptor memory. If the underlying hardware does not support
- * such "special" memory, this functions may simply map to kmm_malloc.
- *
- * This interface was optimized under a particular assumption. It was assumed
- * that the driver maintains a pool of small, pre-allocated buffers for descriptor
- * traffic. NOTE that size is not an input, but an output: The size of the
- * pre-allocated buffer is returned.
- *
- * Input Parameters:
- * drvr - The USB host driver instance obtained as a parameter from the call to
- * the class create() method.
- * buffer - The address of a memory location provided by the caller in which to
- * return the allocated buffer memory address.
- * maxlen - The address of a memory location provided by the caller in which to
- * return the maximum size of the allocated buffer memory.
- *
- * Returned Value:
- * On success, zero (OK) is returned. On a failure, a negated errno value is
- * returned indicating the nature of the failure
- *
- * Assumptions:
- * This function will *not* be called from an interrupt handler.
- *
- ************************************************************************************/
- #define DRVR_ALLOC(drvr,buffer,maxlen) ((drvr)->alloc(drvr,buffer,maxlen))
- /************************************************************************************
- * Name: DRVR_FREE
- *
- * Description:
- * Some hardware supports special memory in which request and descriptor data can
- * be accessed more efficiently. This method provides a mechanism to free that
- * request/descriptor memory. If the underlying hardware does not support
- * such "special" memory, this functions may simply map to kmm_free().
- *
- * Input Parameters:
- * drvr - The USB host driver instance obtained as a parameter from the call to
- * the class create() method.
- * buffer - The address of the allocated buffer memory to be freed.
- *
- * Returned Value:
- * On success, zero (OK) is returned. On a failure, a negated errno value is
- * returned indicating the nature of the failure
- *
- * Assumptions:
- * This function will *not* be called from an interrupt handler.
- *
- ************************************************************************************/
- #define DRVR_FREE(drvr,buffer) ((drvr)->free(drvr,buffer))
- /************************************************************************************
- * Name: DRVR_IOALLOC
- *
- * Description:
- * Some hardware supports special memory in which larger IO buffers can
- * be accessed more efficiently. This method provides a mechanism to allocate
- * the request/descriptor memory. If the underlying hardware does not support
- * such "special" memory, this functions may simply map to kmm_malloc.
- *
- * This interface differs from DRVR_ALLOC in that the buffers are variable-sized.
- *
- * Input Parameters:
- * drvr - The USB host driver instance obtained as a parameter from the call to
- * the class create() method.
- * buffer - The address of a memory location provided by the caller in which to
- * return the allocated buffer memory address.
- * buflen - The size of the buffer required.
- *
- * Returned Value:
- * On success, zero (OK) is returned. On a failure, a negated errno value is
- * returned indicating the nature of the failure
- *
- * Assumptions:
- * This function will *not* be called from an interrupt handler.
- *
- ************************************************************************************/
- #define DRVR_IOALLOC(drvr,buffer,buflen) ((drvr)->ioalloc(drvr,buffer,buflen))
- /************************************************************************************
- * Name: DRVR_IOFREE
- *
- * Description:
- * Some hardware supports special memory in which IO data can be accessed more
- * efficiently. This method provides a mechanism to free that IO buffer
- * memory. If the underlying hardware does not support such "special" memory,
- * this functions may simply map to kmm_free().
- *
- * Input Parameters:
- * drvr - The USB host driver instance obtained as a parameter from the call to
- * the class create() method.
- * buffer - The address of the allocated buffer memory to be freed.
- *
- * Returned Value:
- * On success, zero (OK) is returned. On a failure, a negated errno value is
- * returned indicating the nature of the failure
- *
- * Assumptions:
- * This function will *not* be called from an interrupt handler.
- *
- ************************************************************************************/
- #define DRVR_IOFREE(drvr,buffer) ((drvr)->iofree(drvr,buffer))
- /************************************************************************************
- * Name: DRVR_CTRLIN and DRVR_CTRLOUT
- *
- * Description:
- * Process a IN or OUT request on the control endpoint. These methods
- * will enqueue the request and wait for it to complete. Only one transfer may be
- * queued; Neither these methods nor the transfer() method can be called again
- * until the control transfer functions returns.
- *
- * These are blocking methods; these functions will not return until the
- * control transfer has completed.
- *
- * Input Parameters:
- * drvr - The USB host driver instance obtained as a parameter from the call to
- * the class create() method.
- * ep0 - The control endpoint to send/receive the control request.
- * req - Describes the request to be sent. This request must lie in memory
- * created by DRVR_ALLOC.
- * buffer - A buffer used for sending the request and for returning any
- * responses. This buffer must be large enough to hold the length value
- * in the request description. buffer must have been allocated using DRVR_ALLOC.
- *
- * NOTE: On an IN transaction, req and buffer may refer to the same allocated
- * memory.
- *
- * Returned Value:
- * On success, zero (OK) is returned. On a failure, a negated errno value is
- * returned indicating the nature of the failure
- *
- * Assumptions:
- * This function will *not* be called from an interrupt handler.
- *
- ************************************************************************************/
- #define DRVR_CTRLIN(drvr,ep0,req,buffer) ((drvr)->ctrlin(drvr,ep0,req,buffer))
- #define DRVR_CTRLOUT(drvr,ep0,req,buffer) ((drvr)->ctrlout(drvr,ep0,req,buffer))
- /************************************************************************************
- * Name: DRVR_TRANSFER
- *
- * Description:
- * Process a request to handle a transfer descriptor. This method will
- * enqueue the transfer request and wait for it to complete. Only one
- * transfer may be queued; Neither this method nor the ctrlin nor ctrlout
- * methods can be called) again until this function returns.
- *
- * This is a blocking method; this method will not return until the
- * transfer has completed.
- *
- * Input Parameters:
- * drvr - The USB host driver instance obtained as a parameter from the call to
- * the class create() method.
- * ep - The IN or OUT endpoint descriptor for the device endpoint on which to
- * perform the transfer.
- * buffer - A buffer containing the data to be sent (OUT endpoint) or received
- * (IN endpoint). buffer must have been allocated using DRVR_ALLOC
- * buflen - The length of the data to be sent or received.
- *
- * Returned Value:
- * On success, a non-negative value is returned that indicates the number
- * of bytes successfully transferred. On a failure, a negated errno value is
- * returned that indicates the nature of the failure:
- *
- * EAGAIN - If devices NAKs the transfer (or NYET or other error where
- * it may be appropriate to restart the entire transaction).
- * EPERM - If the endpoint stalls
- * EIO - On a TX or data toggle error
- * EPIPE - Overrun errors
- *
- * Assumptions:
- * This function will *not* be called from an interrupt handler.
- *
- ************************************************************************************/
- #define DRVR_TRANSFER(drvr,ep,buffer,buflen) \
- ((drvr)->transfer(drvr,ep,buffer,buflen))
- /************************************************************************************
- * Name: DRVR_ASYNCH
- *
- * Description:
- * Process a request to handle a transfer asynchronously. This method
- * will enqueue the transfer request and return immediately. Only one
- * transfer may be queued on a given endpoint/
- *
- * When the transfer completes, the callback will be invoked with the
- * provided argument.
- *
- * This method is useful for receiving interrupt transfers which may come
- * infrequently.
- *
- * Input Parameters:
- * drvr - The USB host driver instance obtained as a parameter from the call to
- * the class create() method.
- * ep - The IN or OUT endpoint descriptor for the device endpoint on which to
- * perform the transfer.
- * buffer - A buffer containing the data to be sent (OUT endpoint) or received
- * (IN endpoint). buffer must have been allocated using DRVR_ALLOC
- * buflen - The length of the data to be sent or received.
- * callback - This function will be called when the transfer completes.
- * arg - The arbitrary parameter that will be passed to the callback function
- * when the transfer completes.
- *
- * Returned Value:
- * On success, zero (OK) is returned. On a failure, a negated errno value is
- * returned indicating the nature of the failure.
- *
- * Assumptions:
- * This function will *not* be called from an interrupt handler.
- *
- ************************************************************************************/
- #ifdef CONFIG_USBHOST_ASYNCH
- # define DRVR_ASYNCH(drvr,ep,buffer,buflen,callback,arg) \
- ((drvr)->asynch(drvr,ep,buffer,buflen,callback,arg))
- #endif
- /************************************************************************************
- * Name: DRVR_CANCEL
- *
- * Description:
- * Cancel a pending transfer on an endpoint. Cancelled synchronous or
- * asynchronous transfer will complete normally with the error -ESHUTDOWN.
- *
- * Input Parameters:
- * drvr - The USB host driver instance obtained as a parameter from the call to
- * the class create() method.
- * ep - The IN or OUT endpoint descriptor for the device endpoint on which an
- * asynchronous transfer should be transferred.
- *
- * Returned Value:
- * On success, zero (OK) is returned. On a failure, a negated errno value is
- * returned indicating the nature of the failure.
- *
- ************************************************************************************/
- #define DRVR_CANCEL(drvr,ep) ((drvr)->cancel(drvr,ep))
- /************************************************************************************
- * Name: DRVR_CONNECT
- *
- * Description:
- * New connections may be detected by an attached hub. This method is the
- * mechanism that is used by the hub class to introduce a new connection
- * and port description to the system.
- *
- * Input Parameters:
- * drvr - The USB host driver instance obtained as a parameter from the call to
- * the class create() method.
- * hport - The descriptor of the hub port that detected the connection
- * related event
- * connected - True: device connected; false: device disconnected
- *
- * Returned Value:
- * On success, zero (OK) is returned. On a failure, a negated errno value is
- * returned indicating the nature of the failure.
- *
- ************************************************************************************/
- #ifdef CONFIG_USBHOST_HUB
- # define DRVR_CONNECT(drvr,hport,connected) \
- ((drvr)->connect(drvr,hport,connected))
- #endif
- /************************************************************************************
- * Name: DRVR_DISCONNECT
- *
- * Description:
- * Called by the class when an error occurs and driver has been disconnected.
- * The USB host driver should discard the handle to the class instance (it is
- * stale) and not attempt any further interaction with the class driver instance
- * (until a new instance is received from the create() method). The driver
- * should not called the class' disconnected() method.
- *
- * Input Parameters:
- * drvr - The USB host driver instance obtained as a parameter from the call to
- * the class create() method.
- * hport - The port from which the device is being disconnected. Might be a port
- * on a hub.
- *
- * Returned Value:
- * None
- *
- * Assumptions:
- * This function will *not* be called from an interrupt handler.
- *
- ************************************************************************************/
- #define DRVR_DISCONNECT(drvr, hport) ((drvr)->disconnect(drvr, hport))
- /************************************************************************************
- * Public Types
- ************************************************************************************/
- /* This struct contains all of the information that is needed to associate a device
- * this is connected via a USB port to a class.
- */
- struct usbhost_id_s
- {
- uint8_t base; /* Base device class code (see USB_CLASS_* defines in usb.h) */
- uint8_t subclass; /* Sub-class, depends on base class. Eg., See USBMSC_SUBCLASS_* */
- uint8_t proto; /* Protocol, depends on base class. Eg., See USBMSC_PROTO_* */
- uint16_t vid; /* Vendor ID (for vendor/product specific devices) */
- uint16_t pid; /* Product ID (for vendor/product specific devices) */
- };
- /* The struct usbhost_registry_s type describes information that is kept in the
- * USB host registry. USB host class implementations register this information so
- * that USB host drivers can later find the class that matches the device that is
- * connected to the USB port.
- */
- struct usbhost_hubport_s; /* Forward reference to the hub state structure */
- struct usbhost_class_s; /* Forward reference to the class state structure */
- struct usbhost_registry_s
- {
- /* This field is used to implement a singly-link registry structure. Because of
- * the presence of this link, provides of struct usbhost_registry_s instances must
- * provide those instances in write-able memory (RAM).
- */
- FAR struct usbhost_registry_s *flink;
- /* This is a callback into the class implementation. It is used to (1) create
- * a new instance of the USB host class state and to (2) bind a USB host driver
- * "session" to the class instance. Use of this create() method will support
- * environments where there may be multiple USB ports and multiple USB devices
- * simultaneously connected (see the CLASS_CREATE() macro above).
- */
- CODE FAR struct usbhost_class_s *(*create)(FAR struct usbhost_hubport_s *hub,
- FAR const struct usbhost_id_s *id);
- /* This information uniquely identifies the USB host class implementation that
- * goes with a specific USB device.
- */
- uint8_t nids; /* Number of IDs in the id[] array */
- FAR const struct usbhost_id_s *id; /* An array of ID info. Actual dimension is nids */
- };
- /* This type represents one endpoint configured by the epalloc() method.
- * The actual form is known only internally to the USB host controller
- * (for example, for an OHCI driver, this would probably be a pointer
- * to an endpoint descriptor).
- */
- typedef FAR void *usbhost_ep_t;
- /* In the hierarchy of things, there is the host control driver (HCD),
- * represented by struct usbhost_driver_s. Connected to the HCD are one
- * or more hubs. At a minimum, the root hub is always present. Each hub
- * has from 1 to 4 ports.
- */
- /* Every class connects to the host controller driver (HCD) via a port on a
- * hub. That hub may be an external hub or the internal, root hub. The
- * root hub is managed by the HCD. This structure describes that state of
- * that port and provides the linkage to the parent hub in that event that
- * the port is on an external hub.
- *
- * The root hub port can be distinguish because it has parent == NULL.
- */
- struct usbhost_hubport_s
- {
- FAR struct usbhost_driver_s *drvr; /* Common host driver */
- #ifdef CONFIG_USBHOST_HUB
- FAR struct usbhost_hubport_s *parent; /* Parent hub (NULL=root hub) */
- #endif
- FAR struct usbhost_class_s *devclass; /* The bound device class driver */
- usbhost_ep_t ep0; /* Control endpoint, ep0 */
- bool connected; /* True: device connected; false: disconnected */
- uint8_t port; /* Hub port index */
- uint8_t funcaddr; /* Device function address */
- uint8_t speed; /* Device speed */
- };
- /* The root hub port differs in that it includes a data set that is used to
- * manage the generation of unique device function addresses on all
- * downstream ports.
- */
- struct usbhost_roothubport_s
- {
- /* This structure must appear first so that this structure is cast-
- * compatible with usbhost_hubport_s.
- */
- struct usbhost_hubport_s hport; /* Common hub port definitions */
- struct usbhost_devaddr_s devgen; /* Address generation data */
- };
- /* struct usbhost_class_s provides access from the USB host driver to the
- * USB host class implementation.
- */
- struct usbhost_class_s
- {
- /* Class instances are associated with devices connected on one port on a
- * hub and are represented by this structure.
- */
- FAR struct usbhost_hubport_s *hport; /* The port used by this class instance */
- /* Provides the configuration descriptor to the class. The configuration
- * descriptor contains critical information needed by the class in order to
- * initialize properly (such as endpoint selections).
- */
- CODE int (*connect)(FAR struct usbhost_class_s *devclass,
- FAR const uint8_t *configdesc,
- int desclen);
- /* This method informs the class that the USB device has been disconnected. */
- CODE int (*disconnected)(FAR struct usbhost_class_s *devclass);
- };
- /* This structure describes one endpoint. It is used as an input to the
- * epalloc() method. Most of this information comes from the endpoint
- * descriptor.
- */
- struct usbhost_epdesc_s
- {
- FAR struct usbhost_hubport_s *hport; /* Hub port that supports the endpoint */
- uint8_t addr; /* Endpoint address */
- bool in; /* Direction: true->IN */
- uint8_t xfrtype; /* Transfer type. See USB_EP_ATTR_XFER_*
- * in usb.h */
- uint8_t interval; /* Polling interval */
- uint16_t mxpacketsize; /* Max packetsize */
- };
- /* struct usbhost_connection_s provides as interface between platform-specific
- * connection monitoring and the USB host driver connection and enumeration
- * logic.
- */
- struct usbhost_connection_s
- {
- /* Wait for a device to connect or disconnect. */
- CODE int (*wait)(FAR struct usbhost_connection_s *conn,
- FAR struct usbhost_hubport_s **hport);
- /* Enumerate the device connected on a hub port. As part of this
- * enumeration process, the driver will (1) get the device's configuration
- * descriptor, (2) extract the class ID info from the configuration
- * descriptor, (3) call usbhost_findclass() to find the class that supports
- * this device, (4) call the create() method on the struct usbhost_registry_s
- * interface to get a class instance, and finally (5) call the connect()
- * method of the struct usbhost_class_s interface. After that, the class is
- * in charge of the sequence of operations.
- */
- CODE int (*enumerate)(FAR struct usbhost_connection_s *conn,
- FAR struct usbhost_hubport_s *hport);
- };
- /* Callback type used with asynchronous transfers. The result of the
- * transfer is provided by the 'result' parameters. If >= 0, then 'result'
- * is the number of bytes transfers. If < 0 then the transfer failed and
- * result is a negated errno value that indicates the nature of the failure.
- */
- typedef CODE void (*usbhost_asynch_t)(FAR void *arg, ssize_t result);
- /* struct usbhost_driver_s provides access to the USB host driver from the
- * USB host class implementation.
- */
- struct usbhost_driver_s
- {
- /* Configure endpoint 0. This method is normally used internally by the
- * enumerate() method but is made available at the interface to support
- * an external implementation of the enumeration logic.
- */
- CODE int (*ep0configure)(FAR struct usbhost_driver_s *drvr,
- usbhost_ep_t ep0, uint8_t funcaddr,
- uint8_t speed, uint16_t maxpacketsize);
- /* Allocate and configure an endpoint. */
- CODE int (*epalloc)(FAR struct usbhost_driver_s *drvr,
- FAR const struct usbhost_epdesc_s *epdesc,
- FAR usbhost_ep_t *ep);
- CODE int (*epfree)(FAR struct usbhost_driver_s *drvr,
- FAR usbhost_ep_t ep);
- /* Some hardware supports special memory in which transfer descriptors can
- * be accessed more efficiently. The following methods provide a mechanism
- * to allocate and free the transfer descriptor memory. If the underlying
- * hardware does not support such "special" memory, these functions may
- * simply map to kmm_malloc and kmm_free.
- *
- * This interface was optimized under a particular assumption. It was assumed
- * that the driver maintains a pool of small, pre-allocated buffers for descriptor
- * traffic. NOTE that size is not an input, but an output: The size of the
- * pre-allocated buffer is returned.
- */
- CODE int (*alloc)(FAR struct usbhost_driver_s *drvr,
- FAR uint8_t **buffer, FAR size_t *maxlen);
- CODE int (*free)(FAR struct usbhost_driver_s *drvr, FAR uint8_t *buffer);
- /* Some hardware supports special memory in which larger IO buffers can
- * be accessed more efficiently. This method provides a mechanism to allocate
- * the request/descriptor memory. If the underlying hardware does not support
- * such "special" memory, this functions may simply map to kmm_malloc.
- *
- * This interface differs from DRVR_ALLOC in that the buffers are variable-sized.
- */
- CODE int (*ioalloc)(FAR struct usbhost_driver_s *drvr,
- FAR uint8_t **buffer, size_t buflen);
- CODE int (*iofree)(FAR struct usbhost_driver_s *drvr,
- FAR uint8_t *buffer);
- /* Process a IN or OUT request on the control endpoint. These methods
- * will enqueue the request and wait for it to complete. Only one transfer may
- * be queued; Neither these methods nor the transfer() method can be called again
- * until the control transfer methods returns.
- *
- * These are blocking methods; these methods will not return until the
- * control transfer has completed.
- */
- CODE int (*ctrlin)(FAR struct usbhost_driver_s *drvr, usbhost_ep_t ep0,
- FAR const struct usb_ctrlreq_s *req,
- FAR uint8_t *buffer);
- CODE int (*ctrlout)(FAR struct usbhost_driver_s *drvr, usbhost_ep_t ep0,
- FAR const struct usb_ctrlreq_s *req,
- FAR const uint8_t *buffer);
- /* Process a request to handle a transfer descriptor. This method will
- * enqueue the transfer request and wait for it to complete. Only one
- * transfer may be queued; Neither this method nor the ctrlin nor ctrlout
- * methods can be called) again until this function returns.
- *
- * This is a blocking method; this method will not return until the
- * transfer has completed.
- */
- CODE ssize_t (*transfer)(FAR struct usbhost_driver_s *drvr,
- usbhost_ep_t ep, FAR uint8_t *buffer,
- size_t buflen);
- /* Process a request to handle a transfer asynchronously. This method
- * will enqueue the transfer request and return immediately. Only one
- * transfer may be queued on a given endpoint/
- *
- * When the transfer completes, the callback will be invoked with the
- * provided argument.
- *
- * This method is useful for receiving interrupt transfers which may come
- * infrequently.
- */
- #ifdef CONFIG_USBHOST_ASYNCH
- CODE int (*asynch)(FAR struct usbhost_driver_s *drvr, usbhost_ep_t ep,
- FAR uint8_t *buffer, size_t buflen,
- usbhost_asynch_t callback, FAR void *arg);
- #endif
- /* Cancel any pending syncrhonous or asynchronous transfer on an endpoint */
- CODE int (*cancel)(FAR struct usbhost_driver_s *drvr, usbhost_ep_t ep);
- #ifdef CONFIG_USBHOST_HUB
- /* New connections may be detected by an attached hub. This method is the
- * mechanism that is used by the hub class to introduce a new connection
- * and port description to the system.
- */
- CODE int (*connect)(FAR struct usbhost_driver_s *drvr,
- FAR struct usbhost_hubport_s *hport,
- bool connected);
- #endif
- /* Called by the class when an error occurs and driver has been disconnected.
- * The USB host driver should discard the handle to the class instance (it is
- * stale) and not attempt any further interaction with the class driver instance
- * (until a new instance is received from the create() method).
- */
- CODE void (*disconnect)(FAR struct usbhost_driver_s *drvr,
- FAR struct usbhost_hubport_s *hport);
- };
- /************************************************************************************
- * Public Data
- ************************************************************************************/
- #undef EXTERN
- #if defined(__cplusplus)
- #define EXTERN extern "C"
- extern "C"
- {
- #else
- #define EXTERN extern
- #endif
- /************************************************************************************
- * Public Function Prototypes
- ************************************************************************************/
- /************************************************************************************
- * Name: usbhost_registerclass
- *
- * Description:
- * Register a USB host class implementation. The caller provides an instance of
- * struct usbhost_registry_s that contains all of the information that will be
- * needed later to (1) associate the USB host class implementation with a connected
- * USB device, and (2) to obtain and bind a struct usbhost_class_s instance for
- * the device.
- *
- * Input Parameters:
- * devclass - An write-able instance of struct usbhost_registry_s that will be
- * maintained in a registry.
- *
- * Returned Value:
- * On success, this function will return zero (OK). Otherwise, a negated errno
- * value is returned.
- *
- ************************************************************************************/
- int usbhost_registerclass(FAR struct usbhost_registry_s *devclass);
- /************************************************************************************
- * Name: usbhost_findclass
- *
- * Description:
- * Find a USB host class implementation previously registered by
- * usbhost_registerclass(). On success, an instance of struct usbhost_registry_s
- * will be returned. That instance will contain all of the information that will
- * be needed to obtain and bind a struct usbhost_class_s instance for the device.
- *
- * Input Parameters:
- * id - Identifies the USB device class that has connect to the USB host.
- *
- * Returned Value:
- * On success this function will return a non-NULL instance of struct
- * usbhost_registry_s. NULL will be returned on failure. This function can only
- * fail if (1) id is NULL, or (2) no USB host class is registered that matches the
- * device class ID.
- *
- ************************************************************************************/
- const struct usbhost_registry_s *
- usbhost_findclass(FAR const struct usbhost_id_s *id);
- #ifdef CONFIG_USBHOST_HUB
- /************************************************************************************
- * Name: usbhost_hub_initialize
- *
- * Description:
- * Initialize the USB hub class. This function should be called
- * be platform-specific code in order to initialize and register support
- * for the USB host storage class.
- *
- * Input Parameters:
- * None
- *
- * Returned Value:
- * On success this function will return zero (OK); A negated errno value
- * will be returned on failure.
- *
- ************************************************************************************/
- int usbhost_hub_initialize(void);
- #endif
- #ifdef CONFIG_USBHOST_MSC
- /************************************************************************************
- * Name: usbhost_msc_initialize
- *
- * Description:
- * Initialize the USB host storage class. This function should be called
- * be platform-specific code in order to initialize and register support
- * for the USB host storage class.
- *
- * Input Parameters:
- * None
- *
- * Returned Value:
- * On success this function will return zero (OK); A negated errno value
- * will be returned on failure.
- *
- ************************************************************************************/
- int usbhost_msc_initialize(void);
- # ifdef CONFIG_USBHOST_MSC_NOTIFIER
- /************************************************************************************
- * Name: usbhost_msc_notifier_setup
- *
- * Description:
- * Set up to perform a callback to the worker function when a mass storage
- * device is attached.
- *
- * Input Parameters:
- * worker - The worker function to execute on the low priority work queue
- * when the event occurs.
- * event - Only WORK_USB_MSC_CONNECT and WORK_USB_MSC_DISCONNECT
- * sdchar - sdchar of the connected or disconnected block device
- * arg - A user-defined argument that will be available to the worker
- * function when it runs.
- *
- * Returned Value:
- * > 0 - The notification is in place. The returned value is a key that
- * may be used later in a call to
- * usbmsc_attach_notifier_teardown().
- * == 0 - Not used.
- * < 0 - An unexpected error occurred and no notification will occur. The
- * returned value is a negated errno value that indicates the
- * nature of the failure.
- *
- ************************************************************************************/
- int usbhost_msc_notifier_setup(worker_t worker, uint8_t event, char sdchar,
- FAR void *arg);
- /************************************************************************************
- * Name: usbhost_msc_notifier_teardown
- *
- * Description:
- * Eliminate an USB MSC notification previously setup by
- * usbhost_msc_notifier_setup().
- * This function should only be called if the notification should be
- * aborted prior to the notification. The notification will automatically
- * be torn down after the notification.
- *
- * Input Parameters:
- * key - The key value returned from a previous call to
- * usbhost_msc_notifier_setup().
- *
- * Returned Value:
- * Zero (OK) is returned on success; a negated errno value is returned on
- * any failure.
- *
- ************************************************************************************/
- int usbhost_msc_notifier_teardown(int key);
- /************************************************************************************
- * Name: usbhost_msc_notifier_signal
- *
- * Description:
- * An USB mass storage device has been connected or disconnected.
- * Signal all threads.
- *
- * Input Parameters:
- * event - Currently only USBHOST_MSC_DISCONNECT and USBHOST_MSC_CONNECT
- * sdchar - sdchar of the connected or disconnected block device
- *
- * Returned Value:
- * None.
- *
- ************************************************************************************/
- void usbhost_msc_notifier_signal(uint8_t event, char sdchar);
- # endif
- #endif
- #ifdef CONFIG_USBHOST_CDCACM
- /************************************************************************************
- * Name: usbhost_cdcacm_initialize
- *
- * Description:
- * Initialize the USB host CDC/ACM class. This function should be called
- * be platform-specific code in order to initialize and register support
- * for the USB host CDC/ACM class.
- *
- * Input Parameters:
- * None
- *
- * Returned Value:
- * On success this function will return zero (OK); A negated errno value
- * will be returned on failure.
- *
- ************************************************************************************/
- int usbhost_cdcacm_initialize(void);
- #endif
- #ifdef CONFIG_USBHOST_FT232R
- /************************************************************************************
- * Name: usbhost_ft232r_initialize
- *
- * Description:
- * Initialize the USB FT232R driver. This function should be called
- * be platform-specific code in order to initialize and register support
- * for the FT232R.
- *
- * Input Parameters:
- * None
- *
- * Returned Value:
- * On success this function will return zero (OK); A negated errno value
- * will be returned on failure.
- *
- ************************************************************************************/
- int usbhost_ft232r_initialize(void);
- #endif
- #ifdef CONFIG_USBHOST_HIDKBD
- /************************************************************************************
- * Name: usbhost_kbdinit
- *
- * Description:
- * Initialize the USB storage HID keyboard class driver. This function
- * should be called be platform-specific code in order to initialize and
- * register support for the USB host HID keyboard class device.
- *
- * Input Parameters:
- * None
- *
- * Returned Value:
- * On success this function will return zero (OK); A negated errno value
- * will be returned on failure.
- *
- ************************************************************************************/
- int usbhost_kbdinit(void);
- #endif
- #ifdef CONFIG_USBHOST_HIDMOUSE
- /************************************************************************************
- * Name: usbhost_mouse_init
- *
- * Description:
- * Initialize the USB storage HID mouse class driver. This function
- * should be called be platform-specific code in order to initialize and
- * register support for the USB host HID mouse class device.
- *
- * Input Parameters:
- * None
- *
- * Returned Value:
- * On success this function will return zero (OK); A negated errno value
- * will be returned on failure.
- *
- ************************************************************************************/
- int usbhost_mouse_init(void);
- #endif
- #ifdef CONFIG_USBHOST_XBOXCONTROLLER
- /************************************************************************************
- * Name: usbhost_xboxcontroller_init
- *
- * Description:
- * Initialize the USB XBox controller driver. This function
- * should be called be platform-specific code in order to initialize and
- * register support for the USB XBox controller.
- *
- * Input Parameters:
- * None
- *
- * Returned Value:
- * On success this function will return zero (OK); A negated errno value
- * will be returned on failure.
- *
- ************************************************************************************/
- int usbhost_xboxcontroller_init(void);
- #endif
- /************************************************************************************
- * Name: usbhost_wlaninit
- *
- * Description:
- * Initialize the USB WLAN class driver. This function should be called
- * be platform-specific code in order to initialize and register support
- * for the USB host class device.
- *
- * Input Parameters:
- * None
- *
- * Returned Value:
- * On success this function will return zero (OK); A negated errno value
- * will be returned on failure.
- *
- ************************************************************************************/
- int usbhost_wlaninit(void);
- /************************************************************************************
- * Name: usbhost_enumerate
- *
- * Description:
- * This is a share-able implementation of most of the logic required by the
- * driver enumerate() method. This logic within this method should be common
- * to all USB host drivers.
- *
- * Enumerate the connected device. As part of this enumeration process,
- * the driver will (1) get the device's configuration descriptor, (2)
- * extract the class ID info from the configuration descriptor, (3) call
- * usbhost_findclass() to find the class that supports this device, (4)
- * call the create() method on the struct usbhost_registry_s interface
- * to get a class instance, and finally (5) call the configdesc() method
- * of the struct usbhost_class_s interface. After that, the class is in
- * charge of the sequence of operations.
- *
- * Input Parameters:
- * hub - The hub that manages the new class.
- * devclass - If the class driver for the device is successful located
- * and bound to the hub, the allocated class instance is returned into
- * this caller-provided memory location.
- *
- * Returned Value:
- * On success, zero (OK) is returned. On a failure, a negated errno value is
- * returned indicating the nature of the failure
- *
- * Assumptions:
- * - Only a single class bound to a single device is supported.
- * - Called from a single thread so no mutual exclusion is required.
- * - Never called from an interrupt handler.
- *
- ************************************************************************************/
- int usbhost_enumerate(FAR struct usbhost_hubport_s *hub,
- FAR struct usbhost_class_s **devclass);
- #undef EXTERN
- #if defined(__cplusplus)
- }
- #endif
- #endif /* __INCLUDE_NUTTX_USB_USBHOST_H */
|