Eric Lee / linux-smarc-t335x-v3.2

Download as
Browse Code ยป

Commit fb08a5cd57bfd6daf90a850c8081d6805a8b9900

Authored by Martin Rubli
Committed by Mauro Carvalho Chehab
1 parent 9eb30d2fa9
Exists in master and in 4 other branches v3.2_AM335xPSP_04.06.00.11, v3.2_NEWT335xPSP_04.06.00.11, v3.2_SBC_SMARTMEN, v3.2_SMARCT335xPSP_04.06.00.11

[media] uvcvideo: Add driver documentation 

This adds detailed documentation about the driver's extension unit control
features. Part of it has been adopted from the dynctrl.txt that used to be
available in the driver's previous Subversion repository.

The documentation has been rewritten to match the current implementation, in
particular to capture the new XU control support including UVCIOC_CTRL_QUERY.

Signed-off-by: Martin Rubli <martin_rubli@logitech.com>
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>

Showing 1 changed file with 239 additions and 0 deletions Side-by-side Diff

Documentation/video4linux/uvcvideo.txt
Diff comments   View file @ fb08a5c
  1 +Linux USB Video Class (UVC) driver
  2 +==================================
  3 +
  4 +This file documents some driver-specific aspects of the UVC driver, such as
  5 +driver-specific ioctls and implementation notes.
  6 +
  7 +Questions and remarks can be sent to the Linux UVC development mailing list at
  8 +linux-uvc-devel@lists.berlios.de.
  9 +
  10 +
  11 +Extension Unit (XU) support
  12 +---------------------------
  13 +
  14 +1. Introduction
  15 +
  16 +The UVC specification allows for vendor-specific extensions through extension
  17 +units (XUs). The Linux UVC driver supports extension unit controls (XU controls)
  18 +through two separate mechanisms:
  19 +
  20 + - through mappings of XU controls to V4L2 controls
  21 + - through a driver-specific ioctl interface
  22 +
  23 +The first one allows generic V4L2 applications to use XU controls by mapping
  24 +certain XU controls onto V4L2 controls, which then show up during ordinary
  25 +control enumeration.
  26 +
  27 +The second mechanism requires uvcvideo-specific knowledge for the application to
  28 +access XU controls but exposes the entire UVC XU concept to user space for
  29 +maximum flexibility.
  30 +
  31 +Both mechanisms complement each other and are described in more detail below.
  32 +
  33 +
  34 +2. Control mappings
  35 +
  36 +The UVC driver provides an API for user space applications to define so-called
  37 +control mappings at runtime. These allow for individual XU controls or byte
  38 +ranges thereof to be mapped to new V4L2 controls. Such controls appear and
  39 +function exactly like normal V4L2 controls (i.e. the stock controls, such as
  40 +brightness, contrast, etc.). However, reading or writing of such a V4L2 controls
  41 +triggers a read or write of the associated XU control.
  42 +
  43 +The ioctl used to create these control mappings is called UVCIOC_CTRL_MAP.
  44 +Previous driver versions (before 0.2.0) required another ioctl to be used
  45 +beforehand (UVCIOC_CTRL_ADD) to pass XU control information to the UVC driver.
  46 +This is no longer necessary as newer uvcvideo versions query the information
  47 +directly from the device.
  48 +
  49 +For details on the UVCIOC_CTRL_MAP ioctl please refer to the section titled
  50 +"IOCTL reference" below.
  51 +
  52 +
  53 +3. Driver specific XU control interface
  54 +
  55 +For applications that need to access XU controls directly, e.g. for testing
  56 +purposes, firmware upload, or accessing binary controls, a second mechanism to
  57 +access XU controls is provided in the form of a driver-specific ioctl, namely
  58 +UVCIOC_CTRL_QUERY.
  59 +
  60 +A call to this ioctl allows applications to send queries to the UVC driver that
  61 +directly map to the low-level UVC control requests.
  62 +
  63 +In order to make such a request the UVC unit ID of the control's extension unit
  64 +and the control selector need to be known. This information either needs to be
  65 +hardcoded in the application or queried using other ways such as by parsing the
  66 +UVC descriptor or, if available, using the media controller API to enumerate a
  67 +device's entities.
  68 +
  69 +Unless the control size is already known it is necessary to first make a
  70 +UVC_GET_LEN requests in order to be able to allocate a sufficiently large buffer
  71 +and set the buffer size to the correct value. Similarly, to find out whether
  72 +UVC_GET_CUR or UVC_SET_CUR are valid requests for a given control, a
  73 +UVC_GET_INFO request should be made. The bits 0 (GET supported) and 1 (SET
  74 +supported) of the resulting byte indicate which requests are valid.
  75 +
  76 +With the addition of the UVCIOC_CTRL_QUERY ioctl the UVCIOC_CTRL_GET and
  77 +UVCIOC_CTRL_SET ioctls have become obsolete since their functionality is a
  78 +subset of the former ioctl. For the time being they are still supported but
  79 +application developers are encouraged to use UVCIOC_CTRL_QUERY instead.
  80 +
  81 +For details on the UVCIOC_CTRL_QUERY ioctl please refer to the section titled
  82 +"IOCTL reference" below.
  83 +
  84 +
  85 +4. Security
  86 +
  87 +The API doesn't currently provide a fine-grained access control facility. The
  88 +UVCIOC_CTRL_ADD and UVCIOC_CTRL_MAP ioctls require super user permissions.
  89 +
  90 +Suggestions on how to improve this are welcome.
  91 +
  92 +
  93 +5. Debugging
  94 +
  95 +In order to debug problems related to XU controls or controls in general it is
  96 +recommended to enable the UVC_TRACE_CONTROL bit in the module parameter 'trace'.
  97 +This causes extra output to be written into the system log.
  98 +
  99 +
  100 +6. IOCTL reference
  101 +
  102 +---- UVCIOC_CTRL_MAP - Map a UVC control to a V4L2 control ----
  103 +
  104 +Argument: struct uvc_xu_control_mapping
  105 +
  106 +Description:
  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.
  111 +
  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.
  115 +
  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 independantly mapped to
  120 + V4L2 control.
  121 +
  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.
  124 +
  125 +Return value:
  126 + On success 0 is returned. On error -1 is returned and errno is set
  127 + appropriately.
  128 +
  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.
  139 +
  140 +Data types:
  141 + * struct uvc_xu_control_mapping
  142 +
  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)
  156 +
  157 + * struct uvc_menu_info
  158 +
  159 + __u32 value Menu entry value used by the device
  160 + __u8 name[32] Menu entry name
  161 +
  162 +
  163 + * enum uvc_control_data_type
  164 +
  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
  171 +
  172 +
  173 +---- UVCIOC_CTRL_QUERY - Query a UVC XU control ----
  174 +
  175 +Argument: struct uvc_xu_control_query
  176 +
  177 +Description:
  178 + This ioctl queries a UVC XU control identified by its extension unit ID
  179 + and control selector.
  180 +
  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:
  184 +
  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.
  203 +
  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.
  209 +
  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.
  215 +
  216 +Return value:
  217 + On success 0 is returned. On error -1 is returned and errno is set
  218 + appropriately.
  219 +
  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.
  231 +
  232 +Data types:
  233 + * struct uvc_xu_control_query
  234 +
  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