0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 The Linux USB Video Class (UVC) driver
0004 ======================================
0005
0006 This file documents some driver-specific aspects of the UVC driver, such as
0007 driver-specific ioctls and implementation notes.
0008
0009 Questions and remarks can be sent to the Linux UVC development mailing list at
0010 linux-media@vger.kernel.org.
0011
0012
0013 Extension Unit (XU) support
0014 ---------------------------
0015
0016 Introduction
0017 ~~~~~~~~~~~~
0018
0019 The UVC specification allows for vendor-specific extensions through extension
0020 units (XUs). The Linux UVC driver supports extension unit controls (XU controls)
0021 through two separate mechanisms:
0022
0023 - through mappings of XU controls to V4L2 controls
0024 - through a driver-specific ioctl interface
0025
0026 The first one allows generic V4L2 applications to use XU controls by mapping
0027 certain XU controls onto V4L2 controls, which then show up during ordinary
0028 control enumeration.
0029
0030 The second mechanism requires uvcvideo-specific knowledge for the application to
0031 access XU controls but exposes the entire UVC XU concept to user space for
0032 maximum flexibility.
0033
0034 Both mechanisms complement each other and are described in more detail below.
0035
0036
0037 Control mappings
0038 ~~~~~~~~~~~~~~~~
0039
0040 The UVC driver provides an API for user space applications to define so-called
0041 control mappings at runtime. These allow for individual XU controls or byte
0042 ranges thereof to be mapped to new V4L2 controls. Such controls appear and
0043 function exactly like normal V4L2 controls (i.e. the stock controls, such as
0044 brightness, contrast, etc.). However, reading or writing of such a V4L2 controls
0045 triggers a read or write of the associated XU control.
0046
0047 The ioctl used to create these control mappings is called UVCIOC_CTRL_MAP.
0048 Previous driver versions (before 0.2.0) required another ioctl to be used
0049 beforehand (UVCIOC_CTRL_ADD) to pass XU control information to the UVC driver.
0050 This is no longer necessary as newer uvcvideo versions query the information
0051 directly from the device.
0052
0053 For details on the UVCIOC_CTRL_MAP ioctl please refer to the section titled
0054 "IOCTL reference" below.
0055
0056
0057 3. Driver specific XU control interface
0058
0059 For applications that need to access XU controls directly, e.g. for testing
0060 purposes, firmware upload, or accessing binary controls, a second mechanism to
0061 access XU controls is provided in the form of a driver-specific ioctl, namely
0062 UVCIOC_CTRL_QUERY.
0063
0064 A call to this ioctl allows applications to send queries to the UVC driver that
0065 directly map to the low-level UVC control requests.
0066
0067 In order to make such a request the UVC unit ID of the control's extension unit
0068 and the control selector need to be known. This information either needs to be
0069 hardcoded in the application or queried using other ways such as by parsing the
0070 UVC descriptor or, if available, using the media controller API to enumerate a
0071 device's entities.
0072
0073 Unless the control size is already known it is necessary to first make a
0074 UVC_GET_LEN requests in order to be able to allocate a sufficiently large buffer
0075 and set the buffer size to the correct value. Similarly, to find out whether
0076 UVC_GET_CUR or UVC_SET_CUR are valid requests for a given control, a
0077 UVC_GET_INFO request should be made. The bits 0 (GET supported) and 1 (SET
0078 supported) of the resulting byte indicate which requests are valid.
0079
0080 With the addition of the UVCIOC_CTRL_QUERY ioctl the UVCIOC_CTRL_GET and
0081 UVCIOC_CTRL_SET ioctls have become obsolete since their functionality is a
0082 subset of the former ioctl. For the time being they are still supported but
0083 application developers are encouraged to use UVCIOC_CTRL_QUERY instead.
0084
0085 For details on the UVCIOC_CTRL_QUERY ioctl please refer to the section titled
0086 "IOCTL reference" below.
0087
0088
0089 Security
0090 ~~~~~~~~
0091
0092 The API doesn't currently provide a fine-grained access control facility. The
0093 UVCIOC_CTRL_ADD and UVCIOC_CTRL_MAP ioctls require super user permissions.
0094
0095 Suggestions on how to improve this are welcome.
0096
0097
0098 Debugging
0099 ~~~~~~~~~
0100
0101 In order to debug problems related to XU controls or controls in general it is
0102 recommended to enable the UVC_TRACE_CONTROL bit in the module parameter 'trace'.
0103 This causes extra output to be written into the system log.
0104
0105
0106 IOCTL reference
0107 ~~~~~~~~~~~~~~~
0108
0109 UVCIOC_CTRL_MAP - Map a UVC control to a V4L2 control
0110 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0111
0112 Argument: struct uvc_xu_control_mapping
0113
0114 **Description**:
0115
0116 This ioctl creates a mapping between a UVC control or part of a UVC
0117 control and a V4L2 control. Once mappings are defined, userspace
0118 applications can access vendor-defined UVC control through the V4L2
0119 control API.
0120
0121 To create a mapping, applications fill the uvc_xu_control_mapping
0122 structure with information about an existing UVC control defined with
0123 UVCIOC_CTRL_ADD and a new V4L2 control.
0124
0125 A UVC control can be mapped to several V4L2 controls. For instance,
0126 a UVC pan/tilt control could be mapped to separate pan and tilt V4L2
0127 controls. The UVC control is divided into non overlapping fields using
0128 the 'size' and 'offset' fields and are then independently mapped to
0129 V4L2 control.
0130
0131 For signed integer V4L2 controls the data_type field should be set to
0132 UVC_CTRL_DATA_TYPE_SIGNED. Other values are currently ignored.
0133
0134 **Return value**:
0135
0136 On success 0 is returned. On error -1 is returned and errno is set
0137 appropriately.
0138
0139 ENOMEM
0140 Not enough memory to perform the operation.
0141 EPERM
0142 Insufficient privileges (super user privileges are required).
0143 EINVAL
0144 No such UVC control.
0145 EOVERFLOW
0146 The requested offset and size would overflow the UVC control.
0147 EEXIST
0148 Mapping already exists.
0149
0150 **Data types**:
0151
0152 .. code-block:: none
0153
0154 * struct uvc_xu_control_mapping
0155
0156 __u32 id V4L2 control identifier
0157 __u8 name[32] V4L2 control name
0158 __u8 entity[16] UVC extension unit GUID
0159 __u8 selector UVC control selector
0160 __u8 size V4L2 control size (in bits)
0161 __u8 offset V4L2 control offset (in bits)
0162 enum v4l2_ctrl_type
0163 v4l2_type V4L2 control type
0164 enum uvc_control_data_type
0165 data_type UVC control data type
0166 struct uvc_menu_info
0167 *menu_info Array of menu entries (for menu controls only)
0168 __u32 menu_count Number of menu entries (for menu controls only)
0169
0170 * struct uvc_menu_info
0171
0172 __u32 value Menu entry value used by the device
0173 __u8 name[32] Menu entry name
0174
0175
0176 * enum uvc_control_data_type
0177
0178 UVC_CTRL_DATA_TYPE_RAW Raw control (byte array)
0179 UVC_CTRL_DATA_TYPE_SIGNED Signed integer
0180 UVC_CTRL_DATA_TYPE_UNSIGNED Unsigned integer
0181 UVC_CTRL_DATA_TYPE_BOOLEAN Boolean
0182 UVC_CTRL_DATA_TYPE_ENUM Enumeration
0183 UVC_CTRL_DATA_TYPE_BITMASK Bitmask
0184
0185
0186 UVCIOC_CTRL_QUERY - Query a UVC XU control
0187 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0188 Argument: struct uvc_xu_control_query
0189
0190 **Description**:
0191
0192 This ioctl queries a UVC XU control identified by its extension unit ID
0193 and control selector.
0194
0195 There are a number of different queries available that closely
0196 correspond to the low-level control requests described in the UVC
0197 specification. These requests are:
0198
0199 UVC_GET_CUR
0200 Obtain the current value of the control.
0201 UVC_GET_MIN
0202 Obtain the minimum value of the control.
0203 UVC_GET_MAX
0204 Obtain the maximum value of the control.
0205 UVC_GET_DEF
0206 Obtain the default value of the control.
0207 UVC_GET_RES
0208 Query the resolution of the control, i.e. the step size of the
0209 allowed control values.
0210 UVC_GET_LEN
0211 Query the size of the control in bytes.
0212 UVC_GET_INFO
0213 Query the control information bitmap, which indicates whether
0214 get/set requests are supported.
0215 UVC_SET_CUR
0216 Update the value of the control.
0217
0218 Applications must set the 'size' field to the correct length for the
0219 control. Exceptions are the UVC_GET_LEN and UVC_GET_INFO queries, for
0220 which the size must be set to 2 and 1, respectively. The 'data' field
0221 must point to a valid writable buffer big enough to hold the indicated
0222 number of data bytes.
0223
0224 Data is copied directly from the device without any driver-side
0225 processing. Applications are responsible for data buffer formatting,
0226 including little-endian/big-endian conversion. This is particularly
0227 important for the result of the UVC_GET_LEN requests, which is always
0228 returned as a little-endian 16-bit integer by the device.
0229
0230 **Return value**:
0231
0232 On success 0 is returned. On error -1 is returned and errno is set
0233 appropriately.
0234
0235 ENOENT
0236 The device does not support the given control or the specified
0237 extension unit could not be found.
0238 ENOBUFS
0239 The specified buffer size is incorrect (too big or too small).
0240 EINVAL
0241 An invalid request code was passed.
0242 EBADRQC
0243 The given request is not supported by the given control.
0244 EFAULT
0245 The data pointer references an inaccessible memory area.
0246
0247 **Data types**:
0248
0249 .. code-block:: none
0250
0251 * struct uvc_xu_control_query
0252
0253 __u8 unit Extension unit ID
0254 __u8 selector Control selector
0255 __u8 query Request code to send to the device
0256 __u16 size Control data size (in bytes)
0257 __u8 *data Control value
