| /* |
| * 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_ */ |
