include/uapi/linux/usb/functionfs.h

   1 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
   2 #ifndef _UAPI__LINUX_FUNCTIONFS_H__
   3 #define _UAPI__LINUX_FUNCTIONFS_H__
   4
   5
   6 #include <linux/types.h>
   7 #include <linux/ioctl.h>
   8
   9 #include <linux/usb/ch9.h>
  10
  11
  12 enum {
  13         FUNCTIONFS_DESCRIPTORS_MAGIC = 1,
  14         FUNCTIONFS_STRINGS_MAGIC = 2,
  15         FUNCTIONFS_DESCRIPTORS_MAGIC_V2 = 3,
  16 };
  17
  18 enum functionfs_flags {
  19         FUNCTIONFS_HAS_FS_DESC = 1,
  20         FUNCTIONFS_HAS_HS_DESC = 2,
  21         FUNCTIONFS_HAS_SS_DESC = 4,
  22         FUNCTIONFS_HAS_MS_OS_DESC = 8,
  23         FUNCTIONFS_VIRTUAL_ADDR = 16,
  24         FUNCTIONFS_EVENTFD = 32,
  25         FUNCTIONFS_ALL_CTRL_RECIP = 64,
  26         FUNCTIONFS_CONFIG0_SETUP = 128,
  27 };
  28
  29 /* Descriptor of an non-audio endpoint */
  30 struct usb_endpoint_descriptor_no_audio {
  31         __u8  bLength;
  32         __u8  bDescriptorType;
  33
  34         __u8  bEndpointAddress;
  35         __u8  bmAttributes;
  36         __le16 wMaxPacketSize;
  37         __u8  bInterval;
  38 } __attribute__((packed));
  39
  40 struct usb_functionfs_descs_head_v2 {
  41         __le32 magic;
  42         __le32 length;
  43         __le32 flags;
  44         /*
  45          * __le32 fs_count, hs_count, fs_count; must be included manually in
  46          * the structure taking flags into consideration.
  47          */
  48 } __attribute__((packed));
  49
  50 /* Legacy format, deprecated as of 3.14. */
  51 struct usb_functionfs_descs_head {
  52         __le32 magic;
  53         __le32 length;
  54         __le32 fs_count;
  55         __le32 hs_count;
  56 } __attribute__((packed, deprecated));
  57
  58 /* MS OS Descriptor header */
  59 struct usb_os_desc_header {
  60         __u8    interface;
  61         __le32  dwLength;
  62         __le16  bcdVersion;
  63         __le16  wIndex;
  64         union {
  65                 struct {
  66                         __u8    bCount;
  67                         __u8    Reserved;
  68                 };
  69                 __le16  wCount;
  70         };
  71 } __attribute__((packed));
  72
  73 struct usb_ext_compat_desc {
  74         __u8    bFirstInterfaceNumber;
  75         __u8    Reserved1;
  76         __struct_group(/* no tag */, IDs, /* no attrs */,
  77                 __u8    CompatibleID[8];
  78                 __u8    SubCompatibleID[8];
  79         );
  80         __u8    Reserved2[6];
  81 };
  82
  83 struct usb_ext_prop_desc {
  84         __le32  dwSize;
  85         __le32  dwPropertyDataType;
  86         __le16  wPropertyNameLength;
  87 } __attribute__((packed));
  88
  89 /* Flags for usb_ffs_dmabuf_transfer_req->flags (none for now) */
  90 #define USB_FFS_DMABUF_TRANSFER_MASK    0x0
  91
  92 /**
  93  * struct usb_ffs_dmabuf_transfer_req - Transfer request for a DMABUF object
  94  * @fd:         file descriptor of the DMABUF object
  95  * @flags:      one or more USB_FFS_DMABUF_TRANSFER_* flags
  96  * @length:     number of bytes used in this DMABUF for the data transfer.
  97  *              Should generally be set to the DMABUF's size.
  98  */
  99 struct usb_ffs_dmabuf_transfer_req {
 100         int fd;
 101         __u32 flags;
 102         __u64 length;
 103 } __attribute__((packed));
 104
 105 #ifndef __KERNEL__
 106
 107 /*
 108  * Descriptors format:
 109  *
 110  * | off | name      | type         | description                          |
 111  * |-----+-----------+--------------+--------------------------------------|
 112  * |   0 | magic     | LE32         | FUNCTIONFS_DESCRIPTORS_MAGIC_V2      |
 113  * |   4 | length    | LE32         | length of the whole data chunk       |
 114  * |   8 | flags     | LE32         | combination of functionfs_flags      |
 115  * |     | eventfd   | LE32         | eventfd file descriptor              |
 116  * |     | fs_count  | LE32         | number of full-speed descriptors     |
 117  * |     | hs_count  | LE32         | number of high-speed descriptors     |
 118  * |     | ss_count  | LE32         | number of super-speed descriptors    |
 119  * |     | os_count  | LE32         | number of MS OS descriptors          |
 120  * |     | fs_descrs | Descriptor[] | list of full-speed descriptors       |
 121  * |     | hs_descrs | Descriptor[] | list of high-speed descriptors       |
 122  * |     | ss_descrs | Descriptor[] | list of super-speed descriptors      |
 123  * |     | os_descrs | OSDesc[]     | list of MS OS descriptors            |
 124  *
 125  * Depending on which flags are set, various fields may be missing in the
 126  * structure.  Any flags that are not recognised cause the whole block to be
 127  * rejected with -ENOSYS.
 128  *
 129  * Legacy descriptors format (deprecated as of 3.14):
 130  *
 131  * | off | name      | type         | description                          |
 132  * |-----+-----------+--------------+--------------------------------------|
 133  * |   0 | magic     | LE32         | FUNCTIONFS_DESCRIPTORS_MAGIC         |
 134  * |   4 | length    | LE32         | length of the whole data chunk       |
 135  * |   8 | fs_count  | LE32         | number of full-speed descriptors     |
 136  * |  12 | hs_count  | LE32         | number of high-speed descriptors     |
 137  * |  16 | fs_descrs | Descriptor[] | list of full-speed descriptors       |
 138  * |     | hs_descrs | Descriptor[] | list of high-speed descriptors       |
 139  *
 140  * All numbers must be in little endian order.
 141  *
 142  * Descriptor[] is an array of valid USB descriptors which have the following
 143  * format:
 144  *
 145  * | off | name            | type | description              |
 146  * |-----+-----------------+------+--------------------------|
 147  * |   0 | bLength         | U8   | length of the descriptor |
 148  * |   1 | bDescriptorType | U8   | descriptor type          |
 149  * |   2 | payload         |      | descriptor's payload     |
 150  *
 151  * OSDesc[] is an array of valid MS OS Feature Descriptors which have one of
 152  * the following formats:
 153  *
 154  * | off | name            | type | description              |
 155  * |-----+-----------------+------+--------------------------|
 156  * |   0 | inteface        | U8   | related interface number |
 157  * |   1 | dwLength        | U32  | length of the descriptor |
 158  * |   5 | bcdVersion      | U16  | currently supported: 1   |
 159  * |   7 | wIndex          | U16  | currently supported: 4   |
 160  * |   9 | bCount          | U8   | number of ext. compat.   |
 161  * |  10 | Reserved        | U8   | 0                        |
 162  * |  11 | ExtCompat[]     |      | list of ext. compat. d.  |
 163  *
 164  * | off | name            | type | description              |
 165  * |-----+-----------------+------+--------------------------|
 166  * |   0 | inteface        | U8   | related interface number |
 167  * |   1 | dwLength        | U32  | length of the descriptor |
 168  * |   5 | bcdVersion      | U16  | currently supported: 1   |
 169  * |   7 | wIndex          | U16  | currently supported: 5   |
 170  * |   9 | wCount          | U16  | number of ext. compat.   |
 171  * |  11 | ExtProp[]       |      | list of ext. prop. d.    |
 172  *
 173  * ExtCompat[] is an array of valid Extended Compatiblity descriptors
 174  * which have the following format:
 175  *
 176  * | off | name                  | type | description                         |
 177  * |-----+-----------------------+------+-------------------------------------|
 178  * |   0 | bFirstInterfaceNumber | U8   | index of the interface or of the 1st|
 179  * |     |                       |      | interface in an IAD group           |
 180  * |   1 | Reserved              | U8   | 1                                   |
 181  * |   2 | CompatibleID          | U8[8]| compatible ID string                |
 182  * |  10 | SubCompatibleID       | U8[8]| subcompatible ID string             |
 183  * |  18 | Reserved              | U8[6]| 0                                   |
 184  *
 185  * ExtProp[] is an array of valid Extended Properties descriptors
 186  * which have the following format:
 187  *
 188  * | off | name                  | type | description                         |
 189  * |-----+-----------------------+------+-------------------------------------|
 190  * |   0 | dwSize                | U32  | length of the descriptor            |
 191  * |   4 | dwPropertyDataType    | U32  | 1..7                                |
 192  * |   8 | wPropertyNameLength   | U16  | bPropertyName length (NL)           |
 193  * |  10 | bPropertyName         |U8[NL]| name of this property               |
 194  * |10+NL| dwPropertyDataLength  | U32  | bPropertyData length (DL)           |
 195  * |14+NL| bProperty             |U8[DL]| payload of this property            |
 196  */
 197
 198 struct usb_functionfs_strings_head {
 199         __le32 magic;
 200         __le32 length;
 201         __le32 str_count;
 202         __le32 lang_count;
 203 } __attribute__((packed));
 204
 205 /*
 206  * Strings format:
 207  *
 208  * | off | name       | type                  | description                |
 209  * |-----+------------+-----------------------+----------------------------|
 210  * |   0 | magic      | LE32                  | FUNCTIONFS_STRINGS_MAGIC   |
 211  * |   4 | length     | LE32                  | length of the data chunk   |
 212  * |   8 | str_count  | LE32                  | number of strings          |
 213  * |  12 | lang_count | LE32                  | number of languages        |
 214  * |  16 | stringtab  | StringTab[lang_count] | table of strings per lang  |
 215  *
 216  * For each language there is one stringtab entry (ie. there are lang_count
 217  * stringtab entires).  Each StringTab has following format:
 218  *
 219  * | off | name    | type              | description                        |
 220  * |-----+---------+-------------------+------------------------------------|
 221  * |   0 | lang    | LE16              | language code                      |
 222  * |   2 | strings | String[str_count] | array of strings in given language |
 223  *
 224  * For each string there is one strings entry (ie. there are str_count
 225  * string entries).  Each String is a NUL terminated string encoded in
 226  * UTF-8.
 227  */
 228
 229 #endif
 230
 231
 232 /*
 233  * Events are delivered on the ep0 file descriptor, when the user mode driver
 234  * reads from this file descriptor after writing the descriptors.  Don't
 235  * stop polling this descriptor.
 236  */
 237
 238 enum usb_functionfs_event_type {
 239         FUNCTIONFS_BIND,
 240         FUNCTIONFS_UNBIND,
 241
 242         FUNCTIONFS_ENABLE,
 243         FUNCTIONFS_DISABLE,
 244
 245         FUNCTIONFS_SETUP,
 246
 247         FUNCTIONFS_SUSPEND,
 248         FUNCTIONFS_RESUME
 249 };
 250
 251 /* NOTE:  this structure must stay the same size and layout on
 252  * both 32-bit and 64-bit kernels.
 253  */
 254 struct usb_functionfs_event {
 255         union {
 256                 /* SETUP: packet; DATA phase i/o precedes next event
 257                  *(setup.bmRequestType & USB_DIR_IN) flags direction */
 258                 struct usb_ctrlrequest  setup;
 259         } __attribute__((packed)) u;
 260
 261         /* enum usb_functionfs_event_type */
 262         __u8                            type;
 263         __u8                            _pad[3];
 264 } __attribute__((packed));
 265
 266
 267 /* Endpoint ioctls */
 268 /* The same as in gadgetfs */
 269
 270 /* IN transfers may be reported to the gadget driver as complete
 271  *      when the fifo is loaded, before the host reads the data;
 272  * OUT transfers may be reported to the host's "client" driver as
 273  *      complete when they're sitting in the FIFO unread.
 274  * THIS returns how many bytes are "unclaimed" in the endpoint fifo
 275  * (needed for precise fault handling, when the hardware allows it)
 276  */
 277 #define FUNCTIONFS_FIFO_STATUS  _IO('g', 1)
 278
 279 /* discards any unclaimed data in the fifo. */
 280 #define FUNCTIONFS_FIFO_FLUSH   _IO('g', 2)
 281
 282 /* resets endpoint halt+toggle; used to implement set_interface.
 283  * some hardware (like pxa2xx) can't support this.
 284  */
 285 #define FUNCTIONFS_CLEAR_HALT   _IO('g', 3)
 286
 287 /* Specific for functionfs */
 288
 289 /*
 290  * Returns reverse mapping of an interface.  Called on EP0.  If there
 291  * is no such interface returns -EDOM.  If function is not active
 292  * returns -ENODEV.
 293  */
 294 #define FUNCTIONFS_INTERFACE_REVMAP     _IO('g', 128)
 295
 296 /*
 297  * Returns real bEndpointAddress of an endpoint. If endpoint shuts down
 298  * during the call, returns -ESHUTDOWN.
 299  */
 300 #define FUNCTIONFS_ENDPOINT_REVMAP      _IO('g', 129)
 301
 302 /*
 303  * Returns endpoint descriptor. If endpoint shuts down during the call,
 304  * returns -ESHUTDOWN.
 305  */
 306 #define FUNCTIONFS_ENDPOINT_DESC        _IOR('g', 130, \
 307                                              struct usb_endpoint_descriptor)
 308
 309 /*
 310  * Attach the DMABUF object, identified by its file descriptor, to the
 311  * data endpoint. Returns zero on success, and a negative errno value
 312  * on error.
 313  */
 314 #define FUNCTIONFS_DMABUF_ATTACH        _IOW('g', 131, int)
 315
 316
 317 /*
 318  * Detach the given DMABUF object, identified by its file descriptor,
 319  * from the data endpoint. Returns zero on success, and a negative
 320  * errno value on error. Note that closing the endpoint's file
 321  * descriptor will automatically detach all attached DMABUFs.
 322  */
 323 #define FUNCTIONFS_DMABUF_DETACH        _IOW('g', 132, int)
 324
 325 /*
 326  * Enqueue the previously attached DMABUF to the transfer queue.
 327  * The argument is a structure that packs the DMABUF's file descriptor,
 328  * the size in bytes to transfer (which should generally correspond to
 329  * the size of the DMABUF), and a 'flags' field which is unused
 330  * for now. Returns zero on success, and a negative errno value on
 331  * error.
 332  */
 333 #define FUNCTIONFS_DMABUF_TRANSFER      _IOW('g', 133, \
 334                                              struct usb_ffs_dmabuf_transfer_req)
 335
 336 #endif /* _UAPI__LINUX_FUNCTIONFS_H__ */