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 | |