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         /* 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[0];
  64 };
  65
  66 #define USB_RAW_IO_FLAGS_ZERO   0x0001
  67 #define USB_RAW_IO_FLAGS_MASK   0x0001
  68
  69 static inline int usb_raw_io_flags_valid(__u16 flags)
  70 {
  71         return (flags & ~USB_RAW_IO_FLAGS_MASK) == 0;
  72 }
  73
  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[0];
  94 };
  95
  96 /*
  97  * Initializes a Raw Gadget instance.
  98  * Accepts a pointer to the usb_raw_init struct as an argument.
  99  * Returns 0 on success or negative error code on failure.
 100  */
 101 #define USB_RAW_IOCTL_INIT              _IOW('U', 0, struct usb_raw_init)
 102
 103 /*
 104  * Instructs Raw Gadget to bind to a UDC and start emulating a USB device.
 105  * Returns 0 on success or negative error code on failure.
 106  */
 107 #define USB_RAW_IOCTL_RUN               _IO('U', 1)
 108
 109 /*
 110  * A blocking ioctl that waits for an event and returns fetched event data to
 111  * the user.
 112  * Accepts a pointer to the usb_raw_event struct.
 113  * Returns 0 on success or negative error code on failure.
 114  */
 115 #define USB_RAW_IOCTL_EVENT_FETCH       _IOR('U', 2, struct usb_raw_event)
 116
 117 /*
 118  * Queues an IN (OUT for READ) urb as a response to the last control request
 119  * received on endpoint 0, provided that was an IN (OUT for READ) request and
 120  * waits until the urb is completed. Copies received data to user for READ.
 121  * Accepts a pointer to the usb_raw_ep_io struct as an argument.
 122  * Returns length of trasferred data on success or negative error code on
 123  * failure.
 124  */
 125 #define USB_RAW_IOCTL_EP0_WRITE         _IOW('U', 3, struct usb_raw_ep_io)
 126 #define USB_RAW_IOCTL_EP0_READ          _IOWR('U', 4, struct usb_raw_ep_io)
 127
 128 /*
 129  * Finds an endpoint that supports the transfer type specified in the
 130  * descriptor and enables it.
 131  * Accepts a pointer to the usb_endpoint_descriptor struct as an argument.
 132  * Returns enabled endpoint handle on success or negative error code on failure.
 133  */
 134 #define USB_RAW_IOCTL_EP_ENABLE         _IOW('U', 5, struct usb_endpoint_descriptor)
 135
 136 /* Disables specified endpoint.
 137  * Accepts endpoint handle as an argument.
 138  * Returns 0 on success or negative error code on failure.
 139  */
 140 #define USB_RAW_IOCTL_EP_DISABLE        _IOW('U', 6, __u32)
 141
 142 /*
 143  * Queues an IN (OUT for READ) urb as a response to the last control request
 144  * received on endpoint usb_raw_ep_io.ep, provided that was an IN (OUT for READ)
 145  * request and waits until the urb is completed. Copies received data to user
 146  * for READ.
 147  * Accepts a pointer to the usb_raw_ep_io struct as an argument.
 148  * Returns length of trasferred data on success or negative error code on
 149  * failure.
 150  */
 151 #define USB_RAW_IOCTL_EP_WRITE          _IOW('U', 7, struct usb_raw_ep_io)
 152 #define USB_RAW_IOCTL_EP_READ           _IOWR('U', 8, struct usb_raw_ep_io)
 153
 154 /*
 155  * Switches the gadget into the configured state.
 156  * Returns 0 on success or negative error code on failure.
 157  */
 158 #define USB_RAW_IOCTL_CONFIGURE         _IO('U', 9)
 159
 160 /*
 161  * Constrains UDC VBUS power usage.
 162  * Accepts current limit in 2 mA units as an argument.
 163  * Returns 0 on success or negative error code on failure.
 164  */
 165 #define USB_RAW_IOCTL_VBUS_DRAW         _IOW('U', 10, __u32)
 166
 167 #endif /* _UAPI__LINUX_USB_RAW_GADGET_H */