Documentation/media/v4l-drivers/uvcvideo.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 The Linux USB Video Class (UVC) driver
   4 ======================================
   5
   6 This file documents some driver-specific aspects of the UVC driver, such as
   7 driver-specific ioctls and implementation notes.
   8
   9 Questions and remarks can be sent to the Linux UVC development mailing list at
  10 linux-uvc-devel@lists.berlios.de.
  11
  12
  13 Extension Unit (XU) support
  14 ---------------------------
  15
  16 Introduction
  17 ~~~~~~~~~~~~
  18
  19 The UVC specification allows for vendor-specific extensions through extension
  20 units (XUs). The Linux UVC driver supports extension unit controls (XU controls)
  21 through two separate mechanisms:
  22
  23   - through mappings of XU controls to V4L2 controls
  24   - through a driver-specific ioctl interface
  25
  26 The first one allows generic V4L2 applications to use XU controls by mapping
  27 certain XU controls onto V4L2 controls, which then show up during ordinary
  28 control enumeration.
  29
  30 The second mechanism requires uvcvideo-specific knowledge for the application to
  31 access XU controls but exposes the entire UVC XU concept to user space for
  32 maximum flexibility.
  33
  34 Both mechanisms complement each other and are described in more detail below.
  35
  36
  37 Control mappings
  38 ~~~~~~~~~~~~~~~~
  39
  40 The UVC driver provides an API for user space applications to define so-called
  41 control mappings at runtime. These allow for individual XU controls or byte
  42 ranges thereof to be mapped to new V4L2 controls. Such controls appear and
  43 function exactly like normal V4L2 controls (i.e. the stock controls, such as
  44 brightness, contrast, etc.). However, reading or writing of such a V4L2 controls
  45 triggers a read or write of the associated XU control.
  46
  47 The ioctl used to create these control mappings is called UVCIOC_CTRL_MAP.
  48 Previous driver versions (before 0.2.0) required another ioctl to be used
  49 beforehand (UVCIOC_CTRL_ADD) to pass XU control information to the UVC driver.
  50 This is no longer necessary as newer uvcvideo versions query the information
  51 directly from the device.
  52
  53 For details on the UVCIOC_CTRL_MAP ioctl please refer to the section titled
  54 "IOCTL reference" below.
  55
  56
  57 3. Driver specific XU control interface
  58
  59 For applications that need to access XU controls directly, e.g. for testing
  60 purposes, firmware upload, or accessing binary controls, a second mechanism to
  61 access XU controls is provided in the form of a driver-specific ioctl, namely
  62 UVCIOC_CTRL_QUERY.
  63
  64 A call to this ioctl allows applications to send queries to the UVC driver that
  65 directly map to the low-level UVC control requests.
  66
  67 In order to make such a request the UVC unit ID of the control's extension unit
  68 and the control selector need to be known. This information either needs to be
  69 hardcoded in the application or queried using other ways such as by parsing the
  70 UVC descriptor or, if available, using the media controller API to enumerate a
  71 device's entities.
  72
  73 Unless the control size is already known it is necessary to first make a
  74 UVC_GET_LEN requests in order to be able to allocate a sufficiently large buffer
  75 and set the buffer size to the correct value. Similarly, to find out whether
  76 UVC_GET_CUR or UVC_SET_CUR are valid requests for a given control, a
  77 UVC_GET_INFO request should be made. The bits 0 (GET supported) and 1 (SET
  78 supported) of the resulting byte indicate which requests are valid.
  79
  80 With the addition of the UVCIOC_CTRL_QUERY ioctl the UVCIOC_CTRL_GET and
  81 UVCIOC_CTRL_SET ioctls have become obsolete since their functionality is a
  82 subset of the former ioctl. For the time being they are still supported but
  83 application developers are encouraged to use UVCIOC_CTRL_QUERY instead.
  84
  85 For details on the UVCIOC_CTRL_QUERY ioctl please refer to the section titled
  86 "IOCTL reference" below.
  87
  88
  89 Security
  90 ~~~~~~~~
  91
  92 The API doesn't currently provide a fine-grained access control facility. The
  93 UVCIOC_CTRL_ADD and UVCIOC_CTRL_MAP ioctls require super user permissions.
  94
  95 Suggestions on how to improve this are welcome.
  96
  97
  98 Debugging
  99 ~~~~~~~~~
 100
 101 In order to debug problems related to XU controls or controls in general it is
 102 recommended to enable the UVC_TRACE_CONTROL bit in the module parameter 'trace'.
 103 This causes extra output to be written into the system log.
 104
 105
 106 IOCTL reference
 107 ~~~~~~~~~~~~~~~
 108
 109 UVCIOC_CTRL_MAP - Map a UVC control to a V4L2 control
 110 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 111
 112 Argument: struct uvc_xu_control_mapping
 113
 114 **Description**:
 115
 116         This ioctl creates a mapping between a UVC control or part of a UVC
 117         control and a V4L2 control. Once mappings are defined, userspace
 118         applications can access vendor-defined UVC control through the V4L2
 119         control API.
 120
 121         To create a mapping, applications fill the uvc_xu_control_mapping
 122         structure with information about an existing UVC control defined with
 123         UVCIOC_CTRL_ADD and a new V4L2 control.
 124
 125         A UVC control can be mapped to several V4L2 controls. For instance,
 126         a UVC pan/tilt control could be mapped to separate pan and tilt V4L2
 127         controls. The UVC control is divided into non overlapping fields using
 128         the 'size' and 'offset' fields and are then independently mapped to
 129         V4L2 control.
 130
 131         For signed integer V4L2 controls the data_type field should be set to
 132         UVC_CTRL_DATA_TYPE_SIGNED. Other values are currently ignored.
 133
 134 **Return value**:
 135
 136         On success 0 is returned. On error -1 is returned and errno is set
 137         appropriately.
 138
 139         ENOMEM
 140                 Not enough memory to perform the operation.
 141         EPERM
 142                 Insufficient privileges (super user privileges are required).
 143         EINVAL
 144                 No such UVC control.
 145         EOVERFLOW
 146                 The requested offset and size would overflow the UVC control.
 147         EEXIST
 148                 Mapping already exists.
 149
 150 **Data types**:
 151
 152 .. code-block:: none
 153
 154         * struct uvc_xu_control_mapping
 155
 156         __u32   id              V4L2 control identifier
 157         __u8    name[32]        V4L2 control name
 158         __u8    entity[16]      UVC extension unit GUID
 159         __u8    selector        UVC control selector
 160         __u8    size            V4L2 control size (in bits)
 161         __u8    offset          V4L2 control offset (in bits)
 162         enum v4l2_ctrl_type
 163                 v4l2_type       V4L2 control type
 164         enum uvc_control_data_type
 165                 data_type       UVC control data type
 166         struct uvc_menu_info
 167                 *menu_info      Array of menu entries (for menu controls only)
 168         __u32   menu_count      Number of menu entries (for menu controls only)
 169
 170         * struct uvc_menu_info
 171
 172         __u32   value           Menu entry value used by the device
 173         __u8    name[32]        Menu entry name
 174
 175
 176         * enum uvc_control_data_type
 177
 178         UVC_CTRL_DATA_TYPE_RAW          Raw control (byte array)
 179         UVC_CTRL_DATA_TYPE_SIGNED       Signed integer
 180         UVC_CTRL_DATA_TYPE_UNSIGNED     Unsigned integer
 181         UVC_CTRL_DATA_TYPE_BOOLEAN      Boolean
 182         UVC_CTRL_DATA_TYPE_ENUM         Enumeration
 183         UVC_CTRL_DATA_TYPE_BITMASK      Bitmask
 184
 185
 186 UVCIOC_CTRL_QUERY - Query a UVC XU control
 187 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 188 Argument: struct uvc_xu_control_query
 189
 190 **Description**:
 191
 192         This ioctl queries a UVC XU control identified by its extension unit ID
 193         and control selector.
 194
 195         There are a number of different queries available that closely
 196         correspond to the low-level control requests described in the UVC
 197         specification. These requests are:
 198
 199         UVC_GET_CUR
 200                 Obtain the current value of the control.
 201         UVC_GET_MIN
 202                 Obtain the minimum value of the control.
 203         UVC_GET_MAX
 204                 Obtain the maximum value of the control.
 205         UVC_GET_DEF
 206                 Obtain the default value of the control.
 207         UVC_GET_RES
 208                 Query the resolution of the control, i.e. the step size of the
 209                 allowed control values.
 210         UVC_GET_LEN
 211                 Query the size of the control in bytes.
 212         UVC_GET_INFO
 213                 Query the control information bitmap, which indicates whether
 214                 get/set requests are supported.
 215         UVC_SET_CUR
 216                 Update the value of the control.
 217
 218         Applications must set the 'size' field to the correct length for the
 219         control. Exceptions are the UVC_GET_LEN and UVC_GET_INFO queries, for
 220         which the size must be set to 2 and 1, respectively. The 'data' field
 221         must point to a valid writable buffer big enough to hold the indicated
 222         number of data bytes.
 223
 224         Data is copied directly from the device without any driver-side
 225         processing. Applications are responsible for data buffer formatting,
 226         including little-endian/big-endian conversion. This is particularly
 227         important for the result of the UVC_GET_LEN requests, which is always
 228         returned as a little-endian 16-bit integer by the device.
 229
 230 **Return value**:
 231
 232         On success 0 is returned. On error -1 is returned and errno is set
 233         appropriately.
 234
 235         ENOENT
 236                 The device does not support the given control or the specified
 237                 extension unit could not be found.
 238         ENOBUFS
 239                 The specified buffer size is incorrect (too big or too small).
 240         EINVAL
 241                 An invalid request code was passed.
 242         EBADRQC
 243                 The given request is not supported by the given control.
 244         EFAULT
 245                 The data pointer references an inaccessible memory area.
 246
 247 **Data types**:
 248
 249 .. code-block:: none
 250
 251         * struct uvc_xu_control_query
 252
 253         __u8    unit            Extension unit ID
 254         __u8    selector        Control selector
 255         __u8    query           Request code to send to the device
 256         __u16   size            Control data size (in bytes)
 257         __u8    *data           Control value