luchianmihai/walnux
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
walnux/include/nuttx/usb/usbhost.h
Lwazi Dube d66282a893 usbhost: Fix function address generation for multi-port root hubs. 
Devices connected to the same USB bus should have unique function addresses.
This was not true for root hubs with multiple ports. After this change,
enumeration is more reliable on the sama5d3-xplained board when both root hub
ports are used.

This change amounts to using one usbhost_devaddr_s object per root hub
instead of one per root hub port. For the majority of boards only one
root hub port is available so no change in behavior should be expected.
2023-05-11 09:44:18 +02:00

1289 lines
48 KiB
C
Raw Blame History

/****************************************************************************
* 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 providethe 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 *pdevgen; /* Address generation data pointer */
};
/* 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:
* None.
*
****************************************************************************/
void 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 */
Reference in a new issue View git blame Copy permalink