1 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */ 2 /* 3 * USB Raw Gadget driver. 4 * 5 * See Documentation/usb/raw-gadget.rst for more details. 6 */ 7 8 #ifndef _UAPI__LINUX_USB_RAW_GADGET_H 9 #define _UAPI__LINUX_USB_RAW_GADGET_H 10 11 #include <asm/ioctl.h> 12 #include <linux/types.h> 13 #include <linux/usb/ch9.h> 14 15 /* Maximum length of driver_name/device_name in the usb_raw_init struct. */ 16 #define UDC_NAME_LENGTH_MAX 128 17 18 /* 19 * struct usb_raw_init - argument for USB_RAW_IOCTL_INIT ioctl. 20 * @speed: The speed of the emulated USB device, takes the same values as 21 * the usb_device_speed enum: USB_SPEED_FULL, USB_SPEED_HIGH, etc. 22 * @driver_name: The name of the UDC driver. 23 * @device_name: The name of a UDC instance. 24 * 25 * The last two fields identify a UDC the gadget driver should bind to. 26 * For example, Dummy UDC has "dummy_udc" as its driver_name and "dummy_udc.N" 27 * as its device_name, where N in the index of the Dummy UDC instance. 28 * At the same time the dwc2 driver that is used on Raspberry Pi Zero, has 29 * "20980000.usb" as both driver_name and device_name. 30 */ 31 struct usb_raw_init { 32 __u8 driver_name[UDC_NAME_LENGTH_MAX]; 33 __u8 device_name[UDC_NAME_LENGTH_MAX]; 34 __u8 speed; 35 }; 36 37 /* The type of event fetched with the USB_RAW_IOCTL_EVENT_FETCH ioctl. */ 38 enum usb_raw_event_type { 39 USB_RAW_EVENT_INVALID = 0, 40 41 /* This event is queued when the driver has bound to a UDC. */ 42 USB_RAW_EVENT_CONNECT = 1, 43 44 /* This event is queued when a new control request arrived to ep0. */ 45 USB_RAW_EVENT_CONTROL = 2, 46 47 /* The list might grow in the future. */ 48 }; 49 50 /* 51 * struct usb_raw_event - argument for USB_RAW_IOCTL_EVENT_FETCH ioctl. 52 * @type: The type of the fetched event. 53 * @length: Length of the data buffer. Updated by the driver and set to the 54 * actual length of the fetched event data. 55 * @data: A buffer to store the fetched event data. 56 * 57 * Currently the fetched data buffer is empty for USB_RAW_EVENT_CONNECT, 58 * and contains struct usb_ctrlrequest for USB_RAW_EVENT_CONTROL. 59 */ 60 struct usb_raw_event { 61 __u32 type; 62 __u32 length; 63 __u8 data[]; 64 }; 65 66 #define USB_RAW_IO_FLAGS_ZERO 0x0001 67 #define USB_RAW_IO_FLAGS_MASK 0x0001 68 69 static inline int usb_raw_io_flags_valid(__u16 flags) 70 { 71 return (flags & ~USB_RAW_IO_FLAGS_MASK) == 0; 72 } 73 74 static inline int usb_raw_io_flags_zero(__u16 flags) 75 { 76 return (flags & USB_RAW_IO_FLAGS_ZERO); 77 } 78 79 /* 80 * struct usb_raw_ep_io - argument for USB_RAW_IOCTL_EP0/EP_WRITE/READ ioctls. 81 * @ep: Endpoint handle as returned by USB_RAW_IOCTL_EP_ENABLE for 82 * USB_RAW_IOCTL_EP_WRITE/READ. Ignored for USB_RAW_IOCTL_EP0_WRITE/READ. 83 * @flags: When USB_RAW_IO_FLAGS_ZERO is specified, the zero flag is set on 84 * the submitted USB request, see include/linux/usb/gadget.h for details. 85 * @length: Length of data. 86 * @data: Data to send for USB_RAW_IOCTL_EP0/EP_WRITE. Buffer to store received 87 * data for USB_RAW_IOCTL_EP0/EP_READ. 88 */ 89 struct usb_raw_ep_io { 90 __u16 ep; 91 __u16 flags; 92 __u32 length; 93 __u8 data[]; 94 }; 95 96 /* Maximum number of non-control endpoints in struct usb_raw_eps_info. */ 97 #define USB_RAW_EPS_NUM_MAX 30 98 99 /* Maximum length of UDC endpoint name in struct usb_raw_ep_info. */ 100 #define USB_RAW_EP_NAME_MAX 16 101 102 /* Used as addr in struct usb_raw_ep_info if endpoint accepts any address. */ 103 #define USB_RAW_EP_ADDR_ANY 0xff 104 105 /* 106 * struct usb_raw_ep_caps - exposes endpoint capabilities from struct usb_ep 107 * (technically from its member struct usb_ep_caps). 108 */ 109 struct usb_raw_ep_caps { 110 __u32 type_control : 1; 111 __u32 type_iso : 1; 112 __u32 type_bulk : 1; 113 __u32 type_int : 1; 114 __u32 dir_in : 1; 115 __u32 dir_out : 1; 116 }; 117 118 /* 119 * struct usb_raw_ep_limits - exposes endpoint limits from struct usb_ep. 120 * @maxpacket_limit: Maximum packet size value supported by this endpoint. 121 * @max_streams: maximum number of streams supported by this endpoint 122 * (actual number is 2^n). 123 * @reserved: Empty, reserved for potential future extensions. 124 */ 125 struct usb_raw_ep_limits { 126 __u16 maxpacket_limit; 127 __u16 max_streams; 128 __u32 reserved; 129 }; 130 131 /* 132 * struct usb_raw_ep_info - stores information about a gadget endpoint. 133 * @name: Name of the endpoint as it is defined in the UDC driver. 134 * @addr: Address of the endpoint that must be specified in the endpoint 135 * descriptor passed to USB_RAW_IOCTL_EP_ENABLE ioctl. 136 * @caps: Endpoint capabilities. 137 * @limits: Endpoint limits. 138 */ 139 struct usb_raw_ep_info { 140 __u8 name[USB_RAW_EP_NAME_MAX]; 141 __u32 addr; 142 struct usb_raw_ep_caps caps; 143 struct usb_raw_ep_limits limits; 144 }; 145 146 /* 147 * struct usb_raw_eps_info - argument for USB_RAW_IOCTL_EPS_INFO ioctl. 148 * eps: Structures that store information about non-control endpoints. 149 */ 150 struct usb_raw_eps_info { 151 struct usb_raw_ep_info eps[USB_RAW_EPS_NUM_MAX]; 152 }; 153 154 /* 155 * Initializes a Raw Gadget instance. 156 * Accepts a pointer to the usb_raw_init struct as an argument. 157 * Returns 0 on success or negative error code on failure. 158 */ 159 #define USB_RAW_IOCTL_INIT _IOW('U', 0, struct usb_raw_init) 160 161 /* 162 * Instructs Raw Gadget to bind to a UDC and start emulating a USB device. 163 * Returns 0 on success or negative error code on failure. 164 */ 165 #define USB_RAW_IOCTL_RUN _IO('U', 1) 166 167 /* 168 * A blocking ioctl that waits for an event and returns fetched event data to 169 * the user. 170 * Accepts a pointer to the usb_raw_event struct. 171 * Returns 0 on success or negative error code on failure. 172 */ 173 #define USB_RAW_IOCTL_EVENT_FETCH _IOR('U', 2, struct usb_raw_event) 174 175 /* 176 * Queues an IN (OUT for READ) request as a response to the last setup request 177 * received on endpoint 0 (provided that was an IN (OUT for READ) request), and 178 * waits until the request is completed. Copies received data to user for READ. 179 * Accepts a pointer to the usb_raw_ep_io struct as an argument. 180 * Returns length of transferred data on success or negative error code on 181 * failure. 182 */ 183 #define USB_RAW_IOCTL_EP0_WRITE _IOW('U', 3, struct usb_raw_ep_io) 184 #define USB_RAW_IOCTL_EP0_READ _IOWR('U', 4, struct usb_raw_ep_io) 185 186 /* 187 * Finds an endpoint that satisfies the parameters specified in the provided 188 * descriptors (address, transfer type, etc.) and enables it. 189 * Accepts a pointer to the usb_raw_ep_descs struct as an argument. 190 * Returns enabled endpoint handle on success or negative error code on failure. 191 */ 192 #define USB_RAW_IOCTL_EP_ENABLE _IOW('U', 5, struct usb_endpoint_descriptor) 193 194 /* 195 * Disables specified endpoint. 196 * Accepts endpoint handle as an argument. 197 * Returns 0 on success or negative error code on failure. 198 */ 199 #define USB_RAW_IOCTL_EP_DISABLE _IOW('U', 6, __u32) 200 201 /* 202 * Queues an IN (OUT for READ) request as a response to the last setup request 203 * received on endpoint usb_raw_ep_io.ep (provided that was an IN (OUT for READ) 204 * request), and waits until the request is completed. Copies received data to 205 * user for READ. 206 * Accepts a pointer to the usb_raw_ep_io struct as an argument. 207 * Returns length of transferred data on success or negative error code on 208 * failure. 209 */ 210 #define USB_RAW_IOCTL_EP_WRITE _IOW('U', 7, struct usb_raw_ep_io) 211 #define USB_RAW_IOCTL_EP_READ _IOWR('U', 8, struct usb_raw_ep_io) 212 213 /* 214 * Switches the gadget into the configured state. 215 * Returns 0 on success or negative error code on failure. 216 */ 217 #define USB_RAW_IOCTL_CONFIGURE _IO('U', 9) 218 219 /* 220 * Constrains UDC VBUS power usage. 221 * Accepts current limit in 2 mA units as an argument. 222 * Returns 0 on success or negative error code on failure. 223 */ 224 #define USB_RAW_IOCTL_VBUS_DRAW _IOW('U', 10, __u32) 225 226 /* 227 * Fills in the usb_raw_eps_info structure with information about non-control 228 * endpoints available for the currently connected UDC. 229 * Returns the number of available endpoints on success or negative error code 230 * on failure. 231 */ 232 #define USB_RAW_IOCTL_EPS_INFO _IOR('U', 11, struct usb_raw_eps_info) 233 234 /* 235 * Stalls a pending control request on endpoint 0. 236 * Returns 0 on success or negative error code on failure. 237 */ 238 #define USB_RAW_IOCTL_EP0_STALL _IO('U', 12) 239 240 /* 241 * Sets or clears halt or wedge status of the endpoint. 242 * Accepts endpoint handle as an argument. 243 * Returns 0 on success or negative error code on failure. 244 */ 245 #define USB_RAW_IOCTL_EP_SET_HALT _IOW('U', 13, __u32) 246 #define USB_RAW_IOCTL_EP_CLEAR_HALT _IOW('U', 14, __u32) 247 #define USB_RAW_IOCTL_EP_SET_WEDGE _IOW('U', 15, __u32) 248 249 #endif /* _UAPI__LINUX_USB_RAW_GADGET_H */ 250