linux/usb/functionfs.h

0001 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
0002 #ifndef _UAPI__LINUX_FUNCTIONFS_H__
0003 #define _UAPI__LINUX_FUNCTIONFS_H__
0004
0005
0006 #include <linux/types.h>
0007 #include <linux/ioctl.h>
0008
0009 #include <linux/usb/ch9.h>
0010
0011
0012 enum {
0013     FUNCTIONFS_DESCRIPTORS_MAGIC = 1,
0014     FUNCTIONFS_STRINGS_MAGIC = 2,
0015     FUNCTIONFS_DESCRIPTORS_MAGIC_V2 = 3,
0016 };
0017
0018 enum functionfs_flags {
0019     FUNCTIONFS_HAS_FS_DESC = 1,
0020     FUNCTIONFS_HAS_HS_DESC = 2,
0021     FUNCTIONFS_HAS_SS_DESC = 4,
0022     FUNCTIONFS_HAS_MS_OS_DESC = 8,
0023     FUNCTIONFS_VIRTUAL_ADDR = 16,
0024     FUNCTIONFS_EVENTFD = 32,
0025     FUNCTIONFS_ALL_CTRL_RECIP = 64,
0026     FUNCTIONFS_CONFIG0_SETUP = 128,
0027 };
0028
0029 /* Descriptor of an non-audio endpoint */
0030 struct usb_endpoint_descriptor_no_audio {
0031     __u8  bLength;
0032     __u8  bDescriptorType;
0033
0034     __u8  bEndpointAddress;
0035     __u8  bmAttributes;
0036     __le16 wMaxPacketSize;
0037     __u8  bInterval;
0038 } __attribute__((packed));
0039
0040 struct usb_functionfs_descs_head_v2 {
0041     __le32 magic;
0042     __le32 length;
0043     __le32 flags;
0044     /*
0045      * __le32 fs_count, hs_count, fs_count; must be included manually in
0046      * the structure taking flags into consideration.
0047      */
0048 } __attribute__((packed));
0049
0050 /* Legacy format, deprecated as of 3.14. */
0051 struct usb_functionfs_descs_head {
0052     __le32 magic;
0053     __le32 length;
0054     __le32 fs_count;
0055     __le32 hs_count;
0056 } __attribute__((packed, deprecated));
0057
0058 /* MS OS Descriptor header */
0059 struct usb_os_desc_header {
0060     __u8    interface;
0061     __le32  dwLength;
0062     __le16  bcdVersion;
0063     __le16  wIndex;
0064     union {
0065         struct {
0066             __u8    bCount;
0067             __u8    Reserved;
0068         };
0069         __le16  wCount;
0070     };
0071 } __attribute__((packed));
0072
0073 struct usb_ext_compat_desc {
0074     __u8    bFirstInterfaceNumber;
0075     __u8    Reserved1;
0076     __u8    CompatibleID[8];
0077     __u8    SubCompatibleID[8];
0078     __u8    Reserved2[6];
0079 };
0080
0081 struct usb_ext_prop_desc {
0082     __le32  dwSize;
0083     __le32  dwPropertyDataType;
0084     __le16  wPropertyNameLength;
0085 } __attribute__((packed));
0086
0087 #ifndef __KERNEL__
0088
0089 /*
0090  * Descriptors format:
0091  *
0092  * | off | name      | type         | description                          |
0093  * |-----+-----------+--------------+--------------------------------------|
0094  * |   0 | magic     | LE32         | FUNCTIONFS_DESCRIPTORS_MAGIC_V2      |
0095  * |   4 | length    | LE32         | length of the whole data chunk       |
0096  * |   8 | flags     | LE32         | combination of functionfs_flags      |
0097  * |     | eventfd   | LE32         | eventfd file descriptor              |
0098  * |     | fs_count  | LE32         | number of full-speed descriptors     |
0099  * |     | hs_count  | LE32         | number of high-speed descriptors     |
0100  * |     | ss_count  | LE32         | number of super-speed descriptors    |
0101  * |     | os_count  | LE32         | number of MS OS descriptors          |
0102  * |     | fs_descrs | Descriptor[] | list of full-speed descriptors       |
0103  * |     | hs_descrs | Descriptor[] | list of high-speed descriptors       |
0104  * |     | ss_descrs | Descriptor[] | list of super-speed descriptors      |
0105  * |     | os_descrs | OSDesc[]     | list of MS OS descriptors            |
0106  *
0107  * Depending on which flags are set, various fields may be missing in the
0108  * structure.  Any flags that are not recognised cause the whole block to be
0109  * rejected with -ENOSYS.
0110  *
0111  * Legacy descriptors format (deprecated as of 3.14):
0112  *
0113  * | off | name      | type         | description                          |
0114  * |-----+-----------+--------------+--------------------------------------|
0115  * |   0 | magic     | LE32         | FUNCTIONFS_DESCRIPTORS_MAGIC         |
0116  * |   4 | length    | LE32         | length of the whole data chunk       |
0117  * |   8 | fs_count  | LE32         | number of full-speed descriptors     |
0118  * |  12 | hs_count  | LE32         | number of high-speed descriptors     |
0119  * |  16 | fs_descrs | Descriptor[] | list of full-speed descriptors       |
0120  * |     | hs_descrs | Descriptor[] | list of high-speed descriptors       |
0121  *
0122  * All numbers must be in little endian order.
0123  *
0124  * Descriptor[] is an array of valid USB descriptors which have the following
0125  * format:
0126  *
0127  * | off | name            | type | description              |
0128  * |-----+-----------------+------+--------------------------|
0129  * |   0 | bLength         | U8   | length of the descriptor |
0130  * |   1 | bDescriptorType | U8   | descriptor type          |
0131  * |   2 | payload         |      | descriptor's payload     |
0132  *
0133  * OSDesc[] is an array of valid MS OS Feature Descriptors which have one of
0134  * the following formats:
0135  *
0136  * | off | name            | type | description              |
0137  * |-----+-----------------+------+--------------------------|
0138  * |   0 | inteface        | U8   | related interface number |
0139  * |   1 | dwLength        | U32  | length of the descriptor |
0140  * |   5 | bcdVersion      | U16  | currently supported: 1   |
0141  * |   7 | wIndex          | U16  | currently supported: 4   |
0142  * |   9 | bCount          | U8   | number of ext. compat.   |
0143  * |  10 | Reserved        | U8   | 0                        |
0144  * |  11 | ExtCompat[]     |      | list of ext. compat. d.  |
0145  *
0146  * | off | name            | type | description              |
0147  * |-----+-----------------+------+--------------------------|
0148  * |   0 | inteface        | U8   | related interface number |
0149  * |   1 | dwLength        | U32  | length of the descriptor |
0150  * |   5 | bcdVersion      | U16  | currently supported: 1   |
0151  * |   7 | wIndex          | U16  | currently supported: 5   |
0152  * |   9 | wCount          | U16  | number of ext. compat.   |
0153  * |  11 | ExtProp[]       |      | list of ext. prop. d.    |
0154  *
0155  * ExtCompat[] is an array of valid Extended Compatiblity descriptors
0156  * which have the following format:
0157  *
0158  * | off | name                  | type | description                         |
0159  * |-----+-----------------------+------+-------------------------------------|
0160  * |   0 | bFirstInterfaceNumber | U8   | index of the interface or of the 1st|
0161  * |     |                       |      | interface in an IAD group           |
0162  * |   1 | Reserved              | U8   | 1                                   |
0163  * |   2 | CompatibleID          | U8[8]| compatible ID string                |
0164  * |  10 | SubCompatibleID       | U8[8]| subcompatible ID string             |
0165  * |  18 | Reserved              | U8[6]| 0                                   |
0166  *
0167  * ExtProp[] is an array of valid Extended Properties descriptors
0168  * which have the following format:
0169  *
0170  * | off | name                  | type | description                         |
0171  * |-----+-----------------------+------+-------------------------------------|
0172  * |   0 | dwSize                | U32  | length of the descriptor            |
0173  * |   4 | dwPropertyDataType    | U32  | 1..7                                |
0174  * |   8 | wPropertyNameLength   | U16  | bPropertyName length (NL)           |
0175  * |  10 | bPropertyName         |U8[NL]| name of this property               |
0176  * |10+NL| dwPropertyDataLength  | U32  | bPropertyData length (DL)           |
0177  * |14+NL| bProperty             |U8[DL]| payload of this property            |
0178  */
0179
0180 struct usb_functionfs_strings_head {
0181     __le32 magic;
0182     __le32 length;
0183     __le32 str_count;
0184     __le32 lang_count;
0185 } __attribute__((packed));
0186
0187 /*
0188  * Strings format:
0189  *
0190  * | off | name       | type                  | description                |
0191  * |-----+------------+-----------------------+----------------------------|
0192  * |   0 | magic      | LE32                  | FUNCTIONFS_STRINGS_MAGIC   |
0193  * |   4 | length     | LE32                  | length of the data chunk   |
0194  * |   8 | str_count  | LE32                  | number of strings          |
0195  * |  12 | lang_count | LE32                  | number of languages        |
0196  * |  16 | stringtab  | StringTab[lang_count] | table of strings per lang  |
0197  *
0198  * For each language there is one stringtab entry (ie. there are lang_count
0199  * stringtab entires).  Each StringTab has following format:
0200  *
0201  * | off | name    | type              | description                        |
0202  * |-----+---------+-------------------+------------------------------------|
0203  * |   0 | lang    | LE16              | language code                      |
0204  * |   2 | strings | String[str_count] | array of strings in given language |
0205  *
0206  * For each string there is one strings entry (ie. there are str_count
0207  * string entries).  Each String is a NUL terminated string encoded in
0208  * UTF-8.
0209  */
0210
0211 #endif
0212
0213
0214 /*
0215  * Events are delivered on the ep0 file descriptor, when the user mode driver
0216  * reads from this file descriptor after writing the descriptors.  Don't
0217  * stop polling this descriptor.
0218  */
0219
0220 enum usb_functionfs_event_type {
0221     FUNCTIONFS_BIND,
0222     FUNCTIONFS_UNBIND,
0223
0224     FUNCTIONFS_ENABLE,
0225     FUNCTIONFS_DISABLE,
0226
0227     FUNCTIONFS_SETUP,
0228
0229     FUNCTIONFS_SUSPEND,
0230     FUNCTIONFS_RESUME
0231 };
0232
0233 /* NOTE:  this structure must stay the same size and layout on
0234  * both 32-bit and 64-bit kernels.
0235  */
0236 struct usb_functionfs_event {
0237     union {
0238         /* SETUP: packet; DATA phase i/o precedes next event
0239          *(setup.bmRequestType & USB_DIR_IN) flags direction */
0240         struct usb_ctrlrequest  setup;
0241     } __attribute__((packed)) u;
0242
0243     /* enum usb_functionfs_event_type */
0244     __u8                type;
0245     __u8                _pad[3];
0246 } __attribute__((packed));
0247
0248
0249 /* Endpoint ioctls */
0250 /* The same as in gadgetfs */
0251
0252 /* IN transfers may be reported to the gadget driver as complete
0253  *  when the fifo is loaded, before the host reads the data;
0254  * OUT transfers may be reported to the host's "client" driver as
0255  *  complete when they're sitting in the FIFO unread.
0256  * THIS returns how many bytes are "unclaimed" in the endpoint fifo
0257  * (needed for precise fault handling, when the hardware allows it)
0258  */
0259 #define FUNCTIONFS_FIFO_STATUS  _IO('g', 1)
0260
0261 /* discards any unclaimed data in the fifo. */
0262 #define FUNCTIONFS_FIFO_FLUSH   _IO('g', 2)
0263
0264 /* resets endpoint halt+toggle; used to implement set_interface.
0265  * some hardware (like pxa2xx) can't support this.
0266  */
0267 #define FUNCTIONFS_CLEAR_HALT   _IO('g', 3)
0268
0269 /* Specific for functionfs */
0270
0271 /*
0272  * Returns reverse mapping of an interface.  Called on EP0.  If there
0273  * is no such interface returns -EDOM.  If function is not active
0274  * returns -ENODEV.
0275  */
0276 #define FUNCTIONFS_INTERFACE_REVMAP _IO('g', 128)
0277
0278 /*
0279  * Returns real bEndpointAddress of an endpoint. If endpoint shuts down
0280  * during the call, returns -ESHUTDOWN.
0281  */
0282 #define FUNCTIONFS_ENDPOINT_REVMAP  _IO('g', 129)
0283
0284 /*
0285  * Returns endpoint descriptor. If endpoint shuts down during the call,
0286  * returns -ESHUTDOWN.
0287  */
0288 #define FUNCTIONFS_ENDPOINT_DESC    _IOR('g', 130, \
0289                          struct usb_endpoint_descriptor)
0290
0291
0292
0293 #endif /* _UAPI__LINUX_FUNCTIONFS_H__ */