| /* | |
| * Copyright 2017, Data61 | |
| * Commonwealth Scientific and Industrial Research Organisation (CSIRO) | |
| * ABN 41 687 119 230. | |
| * | |
| * This software may be distributed and modified according to the terms of | |
| * the BSD 2-Clause license. Note that NO WARRANTY is provided. | |
| * See "LICENSE_BSD2.txt" for details. | |
| * | |
| * @TAG(DATA61_BSD) | |
| */ | |
| #ifndef _USB_USB_H_ | |
| #define _USB_USB_H_ | |
| #include <platsupport/io.h> | |
| #include <platsupport/sync/sync.h> | |
| #include <usb/usb_host.h> | |
| // Maximum number of devices a host can manage | |
| #define USB_NDEVICES 32 | |
| // Maximum number of endpoints per device | |
| #define USB_MAX_EPS 32 | |
| // Maximum size of a string descriptor | |
| #define MAX_STRING_SIZE 255 | |
| struct usb_dev; | |
| typedef struct usb_dev usb_dev_t; | |
| struct usb { | |
| usb_host_t hdev; | |
| /// Bitmap representation of used addresses | |
| uint32_t addrbm; | |
| /// Next address: delays address recycling | |
| int next_addr; | |
| /// List of devices connected to this host | |
| usb_dev_t *devlist; | |
| }; | |
| typedef struct usb usb_t; | |
| enum usb_class { | |
| USB_CLASS_UNSPECIFIED = 0x00, | |
| USB_CLASS_AUDIO = 0x01, | |
| USB_CLASS_COMM = 0x02, | |
| USB_CLASS_HID = 0x03, | |
| /* ------------------------*/ | |
| USB_CLASS_PID = 0x05, | |
| USB_CLASS_IMAGE = 0x06, | |
| USB_CLASS_PRINTER = 0x07, | |
| USB_CLASS_STORAGE = 0x08, | |
| USB_CLASS_HUB = 0x09, | |
| USB_CLASS_CDCDATA = 0x0A, | |
| USB_CLASS_CARDREADER = 0x0B, | |
| /* ------------------------*/ | |
| USB_CLASS_SECURITY = 0x0D, | |
| USB_CLASS_VIDEO = 0x0E, | |
| USB_CLASS_HEALTH = 0x0F, | |
| USB_CLASS_AV = 0x10, | |
| /* ------------------------*/ | |
| USB_CLASS_DIAGNOSTIC = 0xDC, | |
| /* ------------------------*/ | |
| USB_CLASS_WIRELESS = 0xE0, | |
| /* ------------------------*/ | |
| USB_CLASS_MISC = 0xEF, | |
| /* ------------------------*/ | |
| USB_CLASS_APPSPEC = 0xFE, | |
| USB_CLASS_VEND = 0xFF | |
| }; | |
| struct usb_dev { | |
| /* Filled on creation */ | |
| usb_t *host; | |
| usb_dev_t *hub; | |
| uint8_t port; | |
| uint8_t tt_addr; | |
| uint8_t tt_port; | |
| enum usb_speed speed; | |
| ps_dma_man_t* dman; | |
| /* Filled on creation/init */ | |
| uint16_t prod_id; | |
| uint16_t vend_id; | |
| uint8_t class; | |
| uint8_t addr; | |
| /* Filled by driver */ | |
| int (*connect)(struct usb_dev* udev); | |
| int (*disconnect)(struct usb_dev* udev); | |
| struct udev_priv *dev_data; | |
| /* | |
| * A device can have up to 32 data endpoints(16 IN, 16 OUT and only 4 for | |
| * low speed devices). The control endpoint is separate and is shared by all | |
| * interfaces. | |
| */ | |
| struct endpoint *ep_ctrl; // Control endpoint of the device | |
| struct endpoint *ep[USB_MAX_EPS]; // Data endpoints of the device | |
| /* For device lists */ | |
| struct usb_dev *next; | |
| }; | |
| /* | |
| * USB requests | |
| */ | |
| /* Data transfer direction, bit 7 of bmRequestType */ | |
| #define USB_DIR_OUT 0 | |
| #define USB_DIR_IN BIT(7) | |
| /* Request type, bit 6-5 of bmRequestType */ | |
| #define USB_TYPE_STD (0 * BIT(5)) | |
| #define USB_TYPE_CLS (1 * BIT(5)) | |
| #define USB_TYPE_VEN (2 * BIT(5)) | |
| /* Request recipient, bit 4-0 of bmRequestType */ | |
| #define USB_RCPT_DEVICE 0 | |
| #define USB_RCPT_INTERFACE 1 | |
| #define USB_RCPT_ENDPOINT 2 | |
| #define USB_RCPT_OTHER 3 | |
| /* bRequest */ | |
| enum Request { | |
| GET_STATUS = 0, | |
| CLR_FEATURE = 1, | |
| SET_FEATURE = 3, | |
| SET_ADDRESS = 5, | |
| GET_DESCRIPTOR = 6, | |
| SET_DESCRIPTOR = 7, | |
| GET_CONFIGURATION = 8, | |
| SET_CONFIGURATION = 9, | |
| GET_INTERFACE = 10, | |
| SET_INTERFACE = 11, | |
| SYNCH_FRAME = 12 | |
| }; | |
| /*** bmRequestType ***/ | |
| struct usbreq { | |
| uint8_t bmRequestType; | |
| uint8_t bRequest; | |
| uint16_t wValue; | |
| uint16_t wIndex; | |
| uint16_t wLength; | |
| } __attribute__ ((packed)); | |
| /* | |
| * USB descriptors | |
| */ | |
| /* bDescriptorType */ | |
| enum DescriptorType { | |
| DEVICE = 0x01, | |
| CONFIGURATION = 0x02, | |
| STRING = 0x03, | |
| INTERFACE = 0x04, | |
| ENDPOINT = 0x05, | |
| DEVICE_QUALIFIER = 0x06, | |
| OTHER_SPEED_CONFIGURATION = 0x07, | |
| INTERFACE_POWER = 0x08, | |
| /* Class specific types */ | |
| HID = 0x21, | |
| HID_REPORT = 0x22, | |
| HID_PHYSICAL = 0x23, | |
| CS_INTERFACE = 0x24, //USB class-specific | |
| CS_ENDPOINT = 0x25, //USB class-specific | |
| HUB = 0x29 | |
| }; | |
| struct device_desc { | |
| uint8_t bLength; | |
| uint8_t bDescriptorType; | |
| uint16_t bcdUSB; | |
| uint8_t bDeviceClass; | |
| uint8_t bDeviceSubClass; | |
| uint8_t bDeviceProtocol; | |
| uint8_t bMaxPacketSize0; | |
| uint16_t idVendor; | |
| uint16_t idProduct; | |
| uint16_t bcdDevice; | |
| uint8_t iManufacturer; | |
| uint8_t iProduct; | |
| uint8_t iSerialNumber; | |
| uint8_t bNumConfigurations; | |
| } __attribute__ ((packed)); | |
| struct device_qualifier_desc { | |
| uint8_t bLength; | |
| uint8_t bDescriptorType; | |
| uint16_t bcdUSB; | |
| uint8_t bDeviceClass; | |
| uint8_t bDeviceSubClass; | |
| uint8_t bDeviceProtocol; | |
| uint8_t bMaxPacketSize0; | |
| uint8_t bNumConfigurations; | |
| uint8_t bReserved; | |
| } __attribute__ ((packed)); | |
| /* Descriptors */ | |
| struct anon_desc { | |
| uint8_t bLength; | |
| uint8_t bDescriptorType; | |
| } __attribute__ ((packed)); | |
| struct config_desc { | |
| uint8_t bLength; | |
| uint8_t bDescriptorType; | |
| uint16_t wTotalLength; | |
| uint8_t bNumInterfaces; | |
| uint8_t bConfigurationValue; | |
| uint8_t iConfigurationIndex; | |
| uint8_t bmAttributes; | |
| uint8_t bMaxPower; | |
| } __attribute__ ((packed)); | |
| struct iface_desc { | |
| uint8_t bLength; | |
| uint8_t bDescriptorType; | |
| uint8_t bInterfaceNumber; | |
| uint8_t bAlternateSetting; | |
| uint8_t bNumEndpoints; | |
| uint8_t bInterfaceClass; | |
| uint8_t bInterfaceSubClass; | |
| uint8_t bInterfaceProtocol; | |
| uint8_t iInterface; | |
| } __attribute__ ((packed)); | |
| struct endpoint_desc { | |
| uint8_t bLength; | |
| uint8_t bDescriptorType; | |
| uint8_t bEndpointAddress; | |
| uint8_t bmAttributes; | |
| uint16_t wMaxPacketSize; | |
| uint8_t bInterval; | |
| } __attribute__ ((packed)); | |
| struct string_desc { | |
| uint8_t bLength; | |
| uint8_t bDescriptorType; | |
| uint8_t bString[MAX_STRING_SIZE]; | |
| } __attribute__ ((packed)); | |
| /* Class HID */ | |
| struct hid_desc { | |
| uint8_t bLength; | |
| uint8_t bDescriptorType; | |
| uint16_t bcdHID; | |
| uint8_t bCountryCode; | |
| uint8_t bNumDescriptors; | |
| uint8_t bReportDescriptorType; | |
| uint16_t wReportDescriptorLength; | |
| } __attribute__ ((packed)); | |
| static inline struct usbreq | |
| __get_descriptor_req(enum DescriptorType t, int value, int index, int size) { | |
| struct usbreq r = { | |
| .bmRequestType = (USB_DIR_IN | USB_TYPE_STD | USB_RCPT_DEVICE), | |
| .bRequest = GET_DESCRIPTOR, | |
| .wValue = (t << 8) + value, | |
| .wIndex = index, | |
| .wLength = size | |
| }; | |
| return r; | |
| } | |
| static inline struct usbreq | |
| __set_configuration_req(int index) { | |
| struct usbreq r = { | |
| .bmRequestType = (USB_DIR_OUT | USB_TYPE_STD | USB_RCPT_DEVICE), | |
| .bRequest = SET_CONFIGURATION, | |
| .wValue = index, | |
| .wIndex = 0, | |
| .wLength = 0 | |
| }; | |
| return r; | |
| } | |
| static inline struct usbreq | |
| __set_interface_req(int index) { | |
| struct usbreq r = { | |
| .bmRequestType = (USB_DIR_OUT | USB_TYPE_STD | USB_RCPT_INTERFACE), | |
| .bRequest = SET_INTERFACE, | |
| .wValue = 0, | |
| .wIndex = index, | |
| .wLength = 0 | |
| }; | |
| return r; | |
| } | |
| /****************************************/ | |
| /** Initialise usb | |
| * @param[in] id the ID of the USB host to | |
| * initialise | |
| * @param[in] ioops a structure defining operations for | |
| * device access. | |
| * @param[in] sync a structure defining operations for | |
| * mutex operations access. | |
| * @param[out] host On success, this will be filled with | |
| * a handle to the usb host controller | |
| * associated with @ref{id}. | |
| * @return 0 on success. | |
| */ | |
| int usb_init(enum usb_host_id id, ps_io_ops_t* ioops, ps_mutex_ops_t *sync, usb_t* host); | |
| /** Probe for a new device on the BUS. | |
| * This function is typically called by a HUB device when it | |
| * detects a new connection. The new device inherits the DMA | |
| * allocator of host device. On success, key device parameters | |
| * will have been cached and the device will have been assigned | |
| * a new address on the bus. | |
| * @param[in] hub The USB hub that the new device is connected | |
| * to. | |
| * @param[in] port The port on the provided hub that the new | |
| * device is connected to. | |
| * @param[in] speed The connection speed of the new device. | |
| * @param[out] d On success, d will contain a reference to | |
| * the new device. | |
| * @return 0 on success. | |
| */ | |
| int usb_new_device(usb_dev_t *hub, int port, | |
| enum usb_speed speed, usb_dev_t **d); | |
| /** A call back for the configuration parser. This function is | |
| * called for each descriptor. | |
| * @param[in] token An unmodified token as passed to the | |
| * configuration parser. | |
| * @param[in] cfg The current configuration number. -1 for | |
| * none. | |
| * @param[in] iface The current interface number. -1 for none. | |
| * @param[in] desc The current descriptor to be parsed. | |
| * @return 0 for next descriptor, otherwise an error | |
| * code to return to the caller. | |
| */ | |
| typedef int (*usb_config_cb)(void* token, int cfg, int iface, | |
| struct anon_desc* desc); | |
| /** Iteratively passed all descriptors to a caller provided | |
| * function. | |
| * Configuring a device is tedious because not only do | |
| * all descriptors come as a giant blob, but they may not | |
| * be aligned correctly and must be copied to aligned memory | |
| * before use. | |
| */ | |
| int usbdev_parse_config(usb_dev_t *udev, usb_config_cb cb, | |
| void* token); | |
| /** Disconnect a USB device. Usually a call to this function | |
| * is driven by the physical disconnection of the device | |
| * from the bus. | |
| * @param[in] dev A reference to the device to disconnect | |
| */ | |
| void usbdev_disconnect(usb_dev_t *dev); | |
| /** Return the class reported by a USB device | |
| * @param[in] The USB device in question | |
| * @return The class ID | |
| */ | |
| enum usb_class usbdev_get_class(usb_dev_t *dev); | |
| /** | |
| * Returns a string representation of the provided USB class code. | |
| * the string contains no leading or trailing white space and does | |
| * not end in a new line character. | |
| * @param[in] usb_class the class id in question. | |
| * @return a string representation of the USB class. | |
| */ | |
| const char* usb_class_get_description(enum usb_class usb_class); | |
| /** Schedule a transaction on the provided USB device | |
| * @param[in] udev The USB device which is to receive the | |
| * transaction. | |
| * @param[in] ep The endpoint to deliver the | |
| * packets to. | |
| * @param[in] xact A structure describing the packets to be | |
| * sent. | |
| * @param[in] nxact The number of entries in the xact | |
| * structure to use. | |
| * @param[in] cb A call back function to call once the | |
| * packet is delivered or if there was a | |
| * transmission error. NULL if blocking | |
| * behaviour is required. | |
| * @param[in] token Passed unmodified to the call back | |
| * function. | |
| * @return 0 on success. | |
| */ | |
| int usbdev_schedule_xact(usb_dev_t *udev, struct endpoint *ep, struct xact* xact, | |
| int nxact, usb_cb_t cb, void* token); | |
| /** Print a list of registered devices | |
| * @param[in] host the USB host device in question | |
| * @param[in] v the level of information to print. | |
| */ | |
| void usb_lsusb(usb_t* host, int v); | |
| /** Retrieve a USB device from the bus | |
| * @param[in] host The USB host device that the USB device is attached to. | |
| * @param[in] addr The address of the USB device requested. | |
| * @return A handle to the device or NULL if there is no device at | |
| * that address. | |
| */ | |
| usb_dev_t *usb_get_device(usb_t *host, int addr); | |
| /** Probes and prints the descriptors for the given device | |
| * @param[in] dev The usb device to probe | |
| */ | |
| void usb_probe_device(usb_dev_t *dev); | |
| /** Pass control to the devices IRQ handler | |
| * @param[in] host The USB host that triggered | |
| * the interrupt event. | |
| */ | |
| void usb_handle_irq(usb_t *host); | |
| /** Allocate transaction buffers for requests | |
| * @param[in] dman A dma allocator instance | |
| * @param[in/out] xact A array structure which provides the sizes of buffers | |
| * to allocate. On success, this array will be filled | |
| * with references to the allocated DMA memory. | |
| * @param[in] nxact The size, in array indexes, of xact. | |
| * @return 0 on success | |
| */ | |
| int usb_alloc_xact(ps_dma_man_t* dman, struct xact* xact, int nxact); | |
| /** Frees transaction buffers | |
| * @param[in] dman The dma allocator instance that was used for the allocation | |
| * @param[in] xact The description of the transaction | |
| * @param[in] nxact The number of entries in xact | |
| */ | |
| void usb_destroy_xact(ps_dma_man_t* dman, struct xact* xact, int nxact); | |
| #endif /* _USB_USB_H_ */ |