include/uapi/linux/usb/raw_gadget.h

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