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