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