1 /* 2 * 3 * Copyright (C) 2015 Google Inc. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 1. Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer. 10 * 2. Redistributions in binary form must reproduce the above copyright 11 * notice, this list of conditions and the following disclaimer in the 12 * documentation and/or other materials provided with the distribution. 13 * 3. The name of the author may not be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26 * SUCH DAMAGE. 27 */ 28 29 #ifndef __UDC_H__ 30 #define __UDC_H__ 31 32 #include <queue.h> 33 #include <usb/usb.h> 34 35 struct usbdev_ctrl; 36 37 struct usbdev_interface { 38 interface_descriptor_t descriptor; 39 void (*init)(struct usbdev_ctrl *); 40 41 /** 42 * handle_packet: called by the controller driver for incoming packets 43 * 44 * @param ep endpoint the packet is for 45 * 46 * @param in_dir 1, if it's an IN or INTR transfer. 47 * 0 for OUT, SETUP is handled in handle_setup 48 * 49 * @param len Actual transfer length in bytes. Can differ from the 50 * scheduled length if the host requested a smaller 51 * transfer than we prepared for. 52 */ 53 void (*handle_packet)(struct usbdev_ctrl *, int ep, int in_dir, 54 void *data, int len); 55 56 /** 57 * handle_setup: called by the controller driver for setup packets 58 * 59 * @param ep endpoint the SETUP request came up on 60 * @param dr SETUP request data 61 */ 62 int (*handle_setup)(struct usbdev_ctrl *, int ep, dev_req_t *dr); 63 endpoint_descriptor_t *eps; 64 }; 65 66 struct usbdev_configuration { 67 configuration_descriptor_t descriptor; 68 SLIST_ENTRY(usbdev_configuration) list; 69 struct usbdev_interface interfaces[]; 70 }; 71 72 SLIST_HEAD(configuration_list, usbdev_configuration); 73 74 struct usbdev_ctrl { 75 /* private data */ 76 void *pdata; 77 78 int initialized; 79 int remote_wakeup; 80 81 struct usbdev_configuration *current_config; 82 struct usbdev_interface *current_iface; 83 int current_config_id; 84 85 struct configuration_list configs; 86 int config_count; 87 device_descriptor_t device_descriptor; 88 89 int ep_halted[16][2]; 90 int ep_mps[16][2]; 91 92 /** returns 0 if an error occurred */ 93 int (*poll)(struct usbdev_ctrl *); 94 95 /** 96 * Add a gadget driver that exposes properties described in config. 97 * 98 * Each gadget driver is registered and exposed as separate USB 99 * "configuration", so the host can choose between them. 100 */ 101 void (*add_gadget)(struct usbdev_ctrl *, 102 struct usbdev_configuration *config); 103 104 /** 105 * Add a set of strings to use for string descriptors. 106 * 107 * 's' must point to an array of strings of which the first 108 * element is unused, with at most 255 elements. 109 * 110 * 'm' is the size of 'strings' (ie. the index of the last entry). 111 * 112 * 'l' is the USB language code, of which some are defined below, 113 * eg. LANG_EN_US. 114 * 115 * For now, only one language is ever exposed: Calling add_strings overwrites 116 * older configuration. 117 */ 118 void (*add_strings)(unsigned short l, unsigned char m, const char **s); 119 120 /** 121 * Add packet to process by the controller. 122 * zlp: zero length packet, if such a termination is necessary 123 * autofree: free data after use 124 */ 125 void (*enqueue_packet)(struct usbdev_ctrl *this, int endpoint, 126 int in_dir, void *data, int len, int zlp, int autofree); 127 128 /** 129 * Tell the hardware that it should listen to a new address 130 */ 131 void (*set_address)(struct usbdev_ctrl *, int address); 132 133 void (*halt_ep)(struct usbdev_ctrl *this, int ep, int in_dir); 134 void (*start_ep)(struct usbdev_ctrl *this, 135 int ep, int in_dir, int ep_type, int mps); 136 137 /** 138 * Set or clear endpoint ep's STALL state 139 */ 140 void (*stall)(struct usbdev_ctrl *, uint8_t ep, int in_dir, int set); 141 142 /** 143 * Disable controller and deallocate data structures. 144 */ 145 void (*force_shutdown)(struct usbdev_ctrl *this); 146 147 /** 148 * Let queues run out, then disable controller and deallocate data 149 * structures. 150 */ 151 void (*shutdown)(struct usbdev_ctrl *this); 152 153 /** 154 * Allocate n bytes for use as data 155 */ 156 void *(*alloc_data)(size_t n); 157 /** 158 * Free memory object allocated with alloc_data() 159 */ 160 void (*free_data)(void *); 161 }; 162 163 #define LANG_DE_DE 0x0407 164 #define LANG_EN_US 0x0409 165 166 void udc_add_gadget(struct usbdev_ctrl *this, 167 struct usbdev_configuration *config); 168 void udc_add_strings(unsigned short id, unsigned char count, 169 const char *strings[]); 170 void udc_handle_setup(struct usbdev_ctrl *this, int ep, dev_req_t *dr); 171 172 #endif 173