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 
usb_raw_io_flags_valid(__u16 flags)69 static inline int usb_raw_io_flags_valid(__u16 flags)
70 {
71 	return (flags & ~USB_RAW_IO_FLAGS_MASK) == 0;
72 }
73 
usb_raw_io_flags_zero(__u16 flags)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