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 /*
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 */
70 struct 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
79 static inline int usb_raw_io_flags_valid(__u16 flags)
80 {
81 return (flags & ~USB_RAW_IO_FLAGS_MASK) == 0;
82 }
83
84 static 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 */
99 struct 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 */
119 struct 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 */
135 struct 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 */
149 struct 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 */
160 struct 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
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.