linux/usb/raw_gadget.h

0001 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
0002 /*
0003  * USB Raw Gadget driver.
0004  *
0005  * See Documentation/usb/raw-gadget.rst for more details.
0006  */
0007
0008 #ifndef _UAPI__LINUX_USB_RAW_GADGET_H
0009 #define _UAPI__LINUX_USB_RAW_GADGET_H
0010
0011 #include <asm/ioctl.h>
0012 #include <linux/types.h>
0013 #include <linux/usb/ch9.h>
0014
0015 /* Maximum length of driver_name/device_name in the usb_raw_init struct. */
0016 #define UDC_NAME_LENGTH_MAX 128
0017
0018 /*
0019  * struct usb_raw_init - argument for USB_RAW_IOCTL_INIT ioctl.
0020  * @speed: The speed of the emulated USB device, takes the same values as
0021  *     the usb_device_speed enum: USB_SPEED_FULL, USB_SPEED_HIGH, etc.
0022  * @driver_name: The name of the UDC driver.
0023  * @device_name: The name of a UDC instance.
0024  *
0025  * The last two fields identify a UDC the gadget driver should bind to.
0026  * For example, Dummy UDC has "dummy_udc" as its driver_name and "dummy_udc.N"
0027  * as its device_name, where N in the index of the Dummy UDC instance.
0028  * At the same time the dwc2 driver that is used on Raspberry Pi Zero, has
0029  * "20980000.usb" as both driver_name and device_name.
0030  */
0031 struct usb_raw_init {
0032     __u8    driver_name[UDC_NAME_LENGTH_MAX];
0033     __u8    device_name[UDC_NAME_LENGTH_MAX];
0034     __u8    speed;
0035 };
0036
0037 /* The type of event fetched with the USB_RAW_IOCTL_EVENT_FETCH ioctl. */
0038 enum usb_raw_event_type {
0039     USB_RAW_EVENT_INVALID = 0,
0040
0041     /* This event is queued when the driver has bound to a UDC. */
0042     USB_RAW_EVENT_CONNECT = 1,
0043
0044     /* This event is queued when a new control request arrived to ep0. */
0045     USB_RAW_EVENT_CONTROL = 2,
0046
0047     /* The list might grow in the future. */
0048 };
0049
0050 /*
0051  * struct usb_raw_event - argument for USB_RAW_IOCTL_EVENT_FETCH ioctl.
0052  * @type: The type of the fetched event.
0053  * @length: Length of the data buffer. Updated by the driver and set to the
0054  *     actual length of the fetched event data.
0055  * @data: A buffer to store the fetched event data.
0056  *
0057  * Currently the fetched data buffer is empty for USB_RAW_EVENT_CONNECT,
0058  * and contains struct usb_ctrlrequest for USB_RAW_EVENT_CONTROL.
0059  */
0060 struct usb_raw_event {
0061     __u32       type;
0062     __u32       length;
0063     __u8        data[];
0064 };
0065
0066 #define USB_RAW_IO_FLAGS_ZERO   0x0001
0067 #define USB_RAW_IO_FLAGS_MASK   0x0001
0068
0069 static inline int usb_raw_io_flags_valid(__u16 flags)
0070 {
0071     return (flags & ~USB_RAW_IO_FLAGS_MASK) == 0;
0072 }
0073
0074 static inline int usb_raw_io_flags_zero(__u16 flags)
0075 {
0076     return (flags & USB_RAW_IO_FLAGS_ZERO);
0077 }
0078
0079 /*
0080  * struct usb_raw_ep_io - argument for USB_RAW_IOCTL_EP0/EP_WRITE/READ ioctls.
0081  * @ep: Endpoint handle as returned by USB_RAW_IOCTL_EP_ENABLE for
0082  *     USB_RAW_IOCTL_EP_WRITE/READ. Ignored for USB_RAW_IOCTL_EP0_WRITE/READ.
0083  * @flags: When USB_RAW_IO_FLAGS_ZERO is specified, the zero flag is set on
0084  *     the submitted USB request, see include/linux/usb/gadget.h for details.
0085  * @length: Length of data.
0086  * @data: Data to send for USB_RAW_IOCTL_EP0/EP_WRITE. Buffer to store received
0087  *     data for USB_RAW_IOCTL_EP0/EP_READ.
0088  */
0089 struct usb_raw_ep_io {
0090     __u16       ep;
0091     __u16       flags;
0092     __u32       length;
0093     __u8        data[];
0094 };
0095
0096 /* Maximum number of non-control endpoints in struct usb_raw_eps_info. */
0097 #define USB_RAW_EPS_NUM_MAX 30
0098
0099 /* Maximum length of UDC endpoint name in struct usb_raw_ep_info. */
0100 #define USB_RAW_EP_NAME_MAX 16
0101
0102 /* Used as addr in struct usb_raw_ep_info if endpoint accepts any address. */
0103 #define USB_RAW_EP_ADDR_ANY 0xff
0104
0105 /*
0106  * struct usb_raw_ep_caps - exposes endpoint capabilities from struct usb_ep
0107  *     (technically from its member struct usb_ep_caps).
0108  */
0109 struct usb_raw_ep_caps {
0110     __u32   type_control    : 1;
0111     __u32   type_iso    : 1;
0112     __u32   type_bulk   : 1;
0113     __u32   type_int    : 1;
0114     __u32   dir_in      : 1;
0115     __u32   dir_out     : 1;
0116 };
0117
0118 /*
0119  * struct usb_raw_ep_limits - exposes endpoint limits from struct usb_ep.
0120  * @maxpacket_limit: Maximum packet size value supported by this endpoint.
0121  * @max_streams: maximum number of streams supported by this endpoint
0122  *     (actual number is 2^n).
0123  * @reserved: Empty, reserved for potential future extensions.
0124  */
0125 struct usb_raw_ep_limits {
0126     __u16   maxpacket_limit;
0127     __u16   max_streams;
0128     __u32   reserved;
0129 };
0130
0131 /*
0132  * struct usb_raw_ep_info - stores information about a gadget endpoint.
0133  * @name: Name of the endpoint as it is defined in the UDC driver.
0134  * @addr: Address of the endpoint that must be specified in the endpoint
0135  *     descriptor passed to USB_RAW_IOCTL_EP_ENABLE ioctl.
0136  * @caps: Endpoint capabilities.
0137  * @limits: Endpoint limits.
0138  */
0139 struct usb_raw_ep_info {
0140     __u8                name[USB_RAW_EP_NAME_MAX];
0141     __u32               addr;
0142     struct usb_raw_ep_caps      caps;
0143     struct usb_raw_ep_limits    limits;
0144 };
0145
0146 /*
0147  * struct usb_raw_eps_info - argument for USB_RAW_IOCTL_EPS_INFO ioctl.
0148  * eps: Structures that store information about non-control endpoints.
0149  */
0150 struct usb_raw_eps_info {
0151     struct usb_raw_ep_info  eps[USB_RAW_EPS_NUM_MAX];
0152 };
0153
0154 /*
0155  * Initializes a Raw Gadget instance.
0156  * Accepts a pointer to the usb_raw_init struct as an argument.
0157  * Returns 0 on success or negative error code on failure.
0158  */
0159 #define USB_RAW_IOCTL_INIT      _IOW('U', 0, struct usb_raw_init)
0160
0161 /*
0162  * Instructs Raw Gadget to bind to a UDC and start emulating a USB device.
0163  * Returns 0 on success or negative error code on failure.
0164  */
0165 #define USB_RAW_IOCTL_RUN       _IO('U', 1)
0166
0167 /*
0168  * A blocking ioctl that waits for an event and returns fetched event data to
0169  * the user.
0170  * Accepts a pointer to the usb_raw_event struct.
0171  * Returns 0 on success or negative error code on failure.
0172  */
0173 #define USB_RAW_IOCTL_EVENT_FETCH   _IOR('U', 2, struct usb_raw_event)
0174
0175 /*
0176  * Queues an IN (OUT for READ) request as a response to the last setup request
0177  * received on endpoint 0 (provided that was an IN (OUT for READ) request), and
0178  * waits until the request is completed. Copies received data to user for READ.
0179  * Accepts a pointer to the usb_raw_ep_io struct as an argument.
0180  * Returns length of transferred data on success or negative error code on
0181  * failure.
0182  */
0183 #define USB_RAW_IOCTL_EP0_WRITE     _IOW('U', 3, struct usb_raw_ep_io)
0184 #define USB_RAW_IOCTL_EP0_READ      _IOWR('U', 4, struct usb_raw_ep_io)
0185
0186 /*
0187  * Finds an endpoint that satisfies the parameters specified in the provided
0188  * descriptors (address, transfer type, etc.) and enables it.
0189  * Accepts a pointer to the usb_raw_ep_descs struct as an argument.
0190  * Returns enabled endpoint handle on success or negative error code on failure.
0191  */
0192 #define USB_RAW_IOCTL_EP_ENABLE     _IOW('U', 5, struct usb_endpoint_descriptor)
0193
0194 /*
0195  * Disables specified endpoint.
0196  * Accepts endpoint handle as an argument.
0197  * Returns 0 on success or negative error code on failure.
0198  */
0199 #define USB_RAW_IOCTL_EP_DISABLE    _IOW('U', 6, __u32)
0200
0201 /*
0202  * Queues an IN (OUT for READ) request as a response to the last setup request
0203  * received on endpoint usb_raw_ep_io.ep (provided that was an IN (OUT for READ)
0204  * request), and waits until the request is completed. Copies received data to
0205  * user for READ.
0206  * Accepts a pointer to the usb_raw_ep_io struct as an argument.
0207  * Returns length of transferred data on success or negative error code on
0208  * failure.
0209  */
0210 #define USB_RAW_IOCTL_EP_WRITE      _IOW('U', 7, struct usb_raw_ep_io)
0211 #define USB_RAW_IOCTL_EP_READ       _IOWR('U', 8, struct usb_raw_ep_io)
0212
0213 /*
0214  * Switches the gadget into the configured state.
0215  * Returns 0 on success or negative error code on failure.
0216  */
0217 #define USB_RAW_IOCTL_CONFIGURE     _IO('U', 9)
0218
0219 /*
0220  * Constrains UDC VBUS power usage.
0221  * Accepts current limit in 2 mA units as an argument.
0222  * Returns 0 on success or negative error code on failure.
0223  */
0224 #define USB_RAW_IOCTL_VBUS_DRAW     _IOW('U', 10, __u32)
0225
0226 /*
0227  * Fills in the usb_raw_eps_info structure with information about non-control
0228  * endpoints available for the currently connected UDC.
0229  * Returns the number of available endpoints on success or negative error code
0230  * on failure.
0231  */
0232 #define USB_RAW_IOCTL_EPS_INFO      _IOR('U', 11, struct usb_raw_eps_info)
0233
0234 /*
0235  * Stalls a pending control request on endpoint 0.
0236  * Returns 0 on success or negative error code on failure.
0237  */
0238 #define USB_RAW_IOCTL_EP0_STALL     _IO('U', 12)
0239
0240 /*
0241  * Sets or clears halt or wedge status of the endpoint.
0242  * Accepts endpoint handle as an argument.
0243  * Returns 0 on success or negative error code on failure.
0244  */
0245 #define USB_RAW_IOCTL_EP_SET_HALT   _IOW('U', 13, __u32)
0246 #define USB_RAW_IOCTL_EP_CLEAR_HALT _IOW('U', 14, __u32)
0247 #define USB_RAW_IOCTL_EP_SET_WEDGE  _IOW('U', 15, __u32)
0248
0249 #endif /* _UAPI__LINUX_USB_RAW_GADGET_H */