v4.19.13 snapshot.
diff --git a/Documentation/media/uapi/v4l/control.rst b/Documentation/media/uapi/v4l/control.rst
new file mode 100644
index 0000000..c1e6adb
--- /dev/null
+++ b/Documentation/media/uapi/v4l/control.rst
@@ -0,0 +1,505 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _control:
+
+*************
+User Controls
+*************
+
+Devices typically have a number of user-settable controls such as
+brightness, saturation and so on, which would be presented to the user
+on a graphical user interface. But, different devices will have
+different controls available, and furthermore, the range of possible
+values, and the default value will vary from device to device. The
+control ioctls provide the information and a mechanism to create a nice
+user interface for these controls that will work correctly with any
+device.
+
+All controls are accessed using an ID value. V4L2 defines several IDs
+for specific purposes. Drivers can also implement their own custom
+controls using ``V4L2_CID_PRIVATE_BASE`` [#f1]_ and higher values. The
+pre-defined control IDs have the prefix ``V4L2_CID_``, and are listed in
+:ref:`control-id`. The ID is used when querying the attributes of a
+control, and when getting or setting the current value.
+
+Generally applications should present controls to the user without
+assumptions about their purpose. Each control comes with a name string
+the user is supposed to understand. When the purpose is non-intuitive
+the driver writer should provide a user manual, a user interface plug-in
+or a driver specific panel application. Predefined IDs were introduced
+to change a few controls programmatically, for example to mute a device
+during a channel switch.
+
+Drivers may enumerate different controls after switching the current
+video input or output, tuner or modulator, or audio input or output.
+Different in the sense of other bounds, another default and current
+value, step size or other menu items. A control with a certain *custom*
+ID can also change name and type.
+
+If a control is not applicable to the current configuration of the
+device (for example, it doesn't apply to the current video input)
+drivers set the ``V4L2_CTRL_FLAG_INACTIVE`` flag.
+
+Control values are stored globally, they do not change when switching
+except to stay within the reported bounds. They also do not change e. g.
+when the device is opened or closed, when the tuner radio frequency is
+changed or generally never without application request.
+
+V4L2 specifies an event mechanism to notify applications when controls
+change value (see
+:ref:`VIDIOC_SUBSCRIBE_EVENT`, event
+``V4L2_EVENT_CTRL``), panel applications might want to make use of that
+in order to always reflect the correct control value.
+
+All controls use machine endianness.
+
+
+.. _control-id:
+
+Control IDs
+===========
+
+``V4L2_CID_BASE``
+ First predefined ID, equal to ``V4L2_CID_BRIGHTNESS``.
+
+``V4L2_CID_USER_BASE``
+ Synonym of ``V4L2_CID_BASE``.
+
+``V4L2_CID_BRIGHTNESS`` ``(integer)``
+ Picture brightness, or more precisely, the black level.
+
+``V4L2_CID_CONTRAST`` ``(integer)``
+ Picture contrast or luma gain.
+
+``V4L2_CID_SATURATION`` ``(integer)``
+ Picture color saturation or chroma gain.
+
+``V4L2_CID_HUE`` ``(integer)``
+ Hue or color balance.
+
+``V4L2_CID_AUDIO_VOLUME`` ``(integer)``
+ Overall audio volume. Note some drivers also provide an OSS or ALSA
+ mixer interface.
+
+``V4L2_CID_AUDIO_BALANCE`` ``(integer)``
+ Audio stereo balance. Minimum corresponds to all the way left,
+ maximum to right.
+
+``V4L2_CID_AUDIO_BASS`` ``(integer)``
+ Audio bass adjustment.
+
+``V4L2_CID_AUDIO_TREBLE`` ``(integer)``
+ Audio treble adjustment.
+
+``V4L2_CID_AUDIO_MUTE`` ``(boolean)``
+ Mute audio, i. e. set the volume to zero, however without affecting
+ ``V4L2_CID_AUDIO_VOLUME``. Like ALSA drivers, V4L2 drivers must mute
+ at load time to avoid excessive noise. Actually the entire device
+ should be reset to a low power consumption state.
+
+``V4L2_CID_AUDIO_LOUDNESS`` ``(boolean)``
+ Loudness mode (bass boost).
+
+``V4L2_CID_BLACK_LEVEL`` ``(integer)``
+ Another name for brightness (not a synonym of
+ ``V4L2_CID_BRIGHTNESS``). This control is deprecated and should not
+ be used in new drivers and applications.
+
+``V4L2_CID_AUTO_WHITE_BALANCE`` ``(boolean)``
+ Automatic white balance (cameras).
+
+``V4L2_CID_DO_WHITE_BALANCE`` ``(button)``
+ This is an action control. When set (the value is ignored), the
+ device will do a white balance and then hold the current setting.
+ Contrast this with the boolean ``V4L2_CID_AUTO_WHITE_BALANCE``,
+ which, when activated, keeps adjusting the white balance.
+
+``V4L2_CID_RED_BALANCE`` ``(integer)``
+ Red chroma balance.
+
+``V4L2_CID_BLUE_BALANCE`` ``(integer)``
+ Blue chroma balance.
+
+``V4L2_CID_GAMMA`` ``(integer)``
+ Gamma adjust.
+
+``V4L2_CID_WHITENESS`` ``(integer)``
+ Whiteness for grey-scale devices. This is a synonym for
+ ``V4L2_CID_GAMMA``. This control is deprecated and should not be
+ used in new drivers and applications.
+
+``V4L2_CID_EXPOSURE`` ``(integer)``
+ Exposure (cameras). [Unit?]
+
+``V4L2_CID_AUTOGAIN`` ``(boolean)``
+ Automatic gain/exposure control.
+
+``V4L2_CID_GAIN`` ``(integer)``
+ Gain control.
+
+ Primarily used to control gain on e.g. TV tuners but also on
+ webcams. Most devices control only digital gain with this control
+ but on some this could include analogue gain as well. Devices that
+ recognise the difference between digital and analogue gain use
+ controls ``V4L2_CID_DIGITAL_GAIN`` and ``V4L2_CID_ANALOGUE_GAIN``.
+
+``V4L2_CID_HFLIP`` ``(boolean)``
+ Mirror the picture horizontally.
+
+``V4L2_CID_VFLIP`` ``(boolean)``
+ Mirror the picture vertically.
+
+.. _v4l2-power-line-frequency:
+
+``V4L2_CID_POWER_LINE_FREQUENCY`` ``(enum)``
+ Enables a power line frequency filter to avoid flicker. Possible
+ values for ``enum v4l2_power_line_frequency`` are:
+ ``V4L2_CID_POWER_LINE_FREQUENCY_DISABLED`` (0),
+ ``V4L2_CID_POWER_LINE_FREQUENCY_50HZ`` (1),
+ ``V4L2_CID_POWER_LINE_FREQUENCY_60HZ`` (2) and
+ ``V4L2_CID_POWER_LINE_FREQUENCY_AUTO`` (3).
+
+``V4L2_CID_HUE_AUTO`` ``(boolean)``
+ Enables automatic hue control by the device. The effect of setting
+ ``V4L2_CID_HUE`` while automatic hue control is enabled is
+ undefined, drivers should ignore such request.
+
+``V4L2_CID_WHITE_BALANCE_TEMPERATURE`` ``(integer)``
+ This control specifies the white balance settings as a color
+ temperature in Kelvin. A driver should have a minimum of 2800
+ (incandescent) to 6500 (daylight). For more information about color
+ temperature see
+ `Wikipedia <http://en.wikipedia.org/wiki/Color_temperature>`__.
+
+``V4L2_CID_SHARPNESS`` ``(integer)``
+ Adjusts the sharpness filters in a camera. The minimum value
+ disables the filters, higher values give a sharper picture.
+
+``V4L2_CID_BACKLIGHT_COMPENSATION`` ``(integer)``
+ Adjusts the backlight compensation in a camera. The minimum value
+ disables backlight compensation.
+
+``V4L2_CID_CHROMA_AGC`` ``(boolean)``
+ Chroma automatic gain control.
+
+``V4L2_CID_CHROMA_GAIN`` ``(integer)``
+ Adjusts the Chroma gain control (for use when chroma AGC is
+ disabled).
+
+``V4L2_CID_COLOR_KILLER`` ``(boolean)``
+ Enable the color killer (i. e. force a black & white image in case
+ of a weak video signal).
+
+.. _v4l2-colorfx:
+
+``V4L2_CID_COLORFX`` ``(enum)``
+ Selects a color effect. The following values are defined:
+
+
+
+.. tabularcolumns:: |p{5.5cm}|p{12cm}|
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 11 24
+
+ * - ``V4L2_COLORFX_NONE``
+ - Color effect is disabled.
+ * - ``V4L2_COLORFX_ANTIQUE``
+ - An aging (old photo) effect.
+ * - ``V4L2_COLORFX_ART_FREEZE``
+ - Frost color effect.
+ * - ``V4L2_COLORFX_AQUA``
+ - Water color, cool tone.
+ * - ``V4L2_COLORFX_BW``
+ - Black and white.
+ * - ``V4L2_COLORFX_EMBOSS``
+ - Emboss, the highlights and shadows replace light/dark boundaries
+ and low contrast areas are set to a gray background.
+ * - ``V4L2_COLORFX_GRASS_GREEN``
+ - Grass green.
+ * - ``V4L2_COLORFX_NEGATIVE``
+ - Negative.
+ * - ``V4L2_COLORFX_SEPIA``
+ - Sepia tone.
+ * - ``V4L2_COLORFX_SKETCH``
+ - Sketch.
+ * - ``V4L2_COLORFX_SKIN_WHITEN``
+ - Skin whiten.
+ * - ``V4L2_COLORFX_SKY_BLUE``
+ - Sky blue.
+ * - ``V4L2_COLORFX_SOLARIZATION``
+ - Solarization, the image is partially reversed in tone, only color
+ values above or below a certain threshold are inverted.
+ * - ``V4L2_COLORFX_SILHOUETTE``
+ - Silhouette (outline).
+ * - ``V4L2_COLORFX_VIVID``
+ - Vivid colors.
+ * - ``V4L2_COLORFX_SET_CBCR``
+ - The Cb and Cr chroma components are replaced by fixed coefficients
+ determined by ``V4L2_CID_COLORFX_CBCR`` control.
+
+
+
+``V4L2_CID_COLORFX_CBCR`` ``(integer)``
+ Determines the Cb and Cr coefficients for ``V4L2_COLORFX_SET_CBCR``
+ color effect. Bits [7:0] of the supplied 32 bit value are
+ interpreted as Cr component, bits [15:8] as Cb component and bits
+ [31:16] must be zero.
+
+``V4L2_CID_AUTOBRIGHTNESS`` ``(boolean)``
+ Enable Automatic Brightness.
+
+``V4L2_CID_ROTATE`` ``(integer)``
+ Rotates the image by specified angle. Common angles are 90, 270 and
+ 180. Rotating the image to 90 and 270 will reverse the height and
+ width of the display window. It is necessary to set the new height
+ and width of the picture using the
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl according to the
+ rotation angle selected.
+
+``V4L2_CID_BG_COLOR`` ``(integer)``
+ Sets the background color on the current output device. Background
+ color needs to be specified in the RGB24 format. The supplied 32 bit
+ value is interpreted as bits 0-7 Red color information, bits 8-15
+ Green color information, bits 16-23 Blue color information and bits
+ 24-31 must be zero.
+
+``V4L2_CID_ILLUMINATORS_1 V4L2_CID_ILLUMINATORS_2`` ``(boolean)``
+ Switch on or off the illuminator 1 or 2 of the device (usually a
+ microscope).
+
+``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE`` ``(integer)``
+ This is a read-only control that can be read by the application and
+ used as a hint to determine the number of CAPTURE buffers to pass to
+ REQBUFS. The value is the minimum number of CAPTURE buffers that is
+ necessary for hardware to work.
+
+``V4L2_CID_MIN_BUFFERS_FOR_OUTPUT`` ``(integer)``
+ This is a read-only control that can be read by the application and
+ used as a hint to determine the number of OUTPUT buffers to pass to
+ REQBUFS. The value is the minimum number of OUTPUT buffers that is
+ necessary for hardware to work.
+
+.. _v4l2-alpha-component:
+
+``V4L2_CID_ALPHA_COMPONENT`` ``(integer)``
+ Sets the alpha color component. When a capture device (or capture
+ queue of a mem-to-mem device) produces a frame format that includes
+ an alpha component (e.g.
+ :ref:`packed RGB image formats <rgb-formats>`) and the alpha value
+ is not defined by the device or the mem-to-mem input data this
+ control lets you select the alpha component value of all pixels.
+ When an output device (or output queue of a mem-to-mem device)
+ consumes a frame format that doesn't include an alpha component and
+ the device supports alpha channel processing this control lets you
+ set the alpha component value of all pixels for further processing
+ in the device.
+
+``V4L2_CID_LASTP1``
+ End of the predefined control IDs (currently
+ ``V4L2_CID_ALPHA_COMPONENT`` + 1).
+
+``V4L2_CID_PRIVATE_BASE``
+ ID of the first custom (driver specific) control. Applications
+ depending on particular custom controls should check the driver name
+ and version, see :ref:`querycap`.
+
+Applications can enumerate the available controls with the
+:ref:`VIDIOC_QUERYCTRL` and
+:ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>` ioctls, get and set a
+control value with the :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
+:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls. Drivers must implement
+``VIDIOC_QUERYCTRL``, ``VIDIOC_G_CTRL`` and ``VIDIOC_S_CTRL`` when the
+device has one or more controls, ``VIDIOC_QUERYMENU`` when it has one or
+more menu type controls.
+
+
+.. _enum_all_controls:
+
+Example: Enumerating all controls
+=================================
+
+.. code-block:: c
+
+ struct v4l2_queryctrl queryctrl;
+ struct v4l2_querymenu querymenu;
+
+ static void enumerate_menu(__u32 id)
+ {
+ printf(" Menu items:\\n");
+
+ memset(&querymenu, 0, sizeof(querymenu));
+ querymenu.id = id;
+
+ for (querymenu.index = queryctrl.minimum;
+ querymenu.index <= queryctrl.maximum;
+ querymenu.index++) {
+ if (0 == ioctl(fd, VIDIOC_QUERYMENU, &querymenu)) {
+ printf(" %s\\n", querymenu.name);
+ }
+ }
+ }
+
+ memset(&queryctrl, 0, sizeof(queryctrl));
+
+ queryctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL;
+ while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
+ if (!(queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)) {
+ printf("Control %s\\n", queryctrl.name);
+
+ if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
+ enumerate_menu(queryctrl.id);
+ }
+
+ queryctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
+ }
+ if (errno != EINVAL) {
+ perror("VIDIOC_QUERYCTRL");
+ exit(EXIT_FAILURE);
+ }
+
+Example: Enumerating all controls including compound controls
+=============================================================
+
+.. code-block:: c
+
+ struct v4l2_query_ext_ctrl query_ext_ctrl;
+
+ memset(&query_ext_ctrl, 0, sizeof(query_ext_ctrl));
+
+ query_ext_ctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL | V4L2_CTRL_FLAG_NEXT_COMPOUND;
+ while (0 == ioctl(fd, VIDIOC_QUERY_EXT_CTRL, &query_ext_ctrl)) {
+ if (!(query_ext_ctrl.flags & V4L2_CTRL_FLAG_DISABLED)) {
+ printf("Control %s\\n", query_ext_ctrl.name);
+
+ if (query_ext_ctrl.type == V4L2_CTRL_TYPE_MENU)
+ enumerate_menu(query_ext_ctrl.id);
+ }
+
+ query_ext_ctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL | V4L2_CTRL_FLAG_NEXT_COMPOUND;
+ }
+ if (errno != EINVAL) {
+ perror("VIDIOC_QUERY_EXT_CTRL");
+ exit(EXIT_FAILURE);
+ }
+
+Example: Enumerating all user controls (old style)
+==================================================
+
+.. code-block:: c
+
+
+ memset(&queryctrl, 0, sizeof(queryctrl));
+
+ for (queryctrl.id = V4L2_CID_BASE;
+ queryctrl.id < V4L2_CID_LASTP1;
+ queryctrl.id++) {
+ if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
+ if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
+ continue;
+
+ printf("Control %s\\n", queryctrl.name);
+
+ if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
+ enumerate_menu(queryctrl.id);
+ } else {
+ if (errno == EINVAL)
+ continue;
+
+ perror("VIDIOC_QUERYCTRL");
+ exit(EXIT_FAILURE);
+ }
+ }
+
+ for (queryctrl.id = V4L2_CID_PRIVATE_BASE;;
+ queryctrl.id++) {
+ if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
+ if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
+ continue;
+
+ printf("Control %s\\n", queryctrl.name);
+
+ if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
+ enumerate_menu(queryctrl.id);
+ } else {
+ if (errno == EINVAL)
+ break;
+
+ perror("VIDIOC_QUERYCTRL");
+ exit(EXIT_FAILURE);
+ }
+ }
+
+
+Example: Changing controls
+==========================
+
+.. code-block:: c
+
+ struct v4l2_queryctrl queryctrl;
+ struct v4l2_control control;
+
+ memset(&queryctrl, 0, sizeof(queryctrl));
+ queryctrl.id = V4L2_CID_BRIGHTNESS;
+
+ if (-1 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
+ if (errno != EINVAL) {
+ perror("VIDIOC_QUERYCTRL");
+ exit(EXIT_FAILURE);
+ } else {
+ printf("V4L2_CID_BRIGHTNESS is not supportedn");
+ }
+ } else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) {
+ printf("V4L2_CID_BRIGHTNESS is not supportedn");
+ } else {
+ memset(&control, 0, sizeof (control));
+ control.id = V4L2_CID_BRIGHTNESS;
+ control.value = queryctrl.default_value;
+
+ if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)) {
+ perror("VIDIOC_S_CTRL");
+ exit(EXIT_FAILURE);
+ }
+ }
+
+ memset(&control, 0, sizeof(control));
+ control.id = V4L2_CID_CONTRAST;
+
+ if (0 == ioctl(fd, VIDIOC_G_CTRL, &control)) {
+ control.value += 1;
+
+ /* The driver may clamp the value or return ERANGE, ignored here */
+
+ if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)
+ && errno != ERANGE) {
+ perror("VIDIOC_S_CTRL");
+ exit(EXIT_FAILURE);
+ }
+ /* Ignore if V4L2_CID_CONTRAST is unsupported */
+ } else if (errno != EINVAL) {
+ perror("VIDIOC_G_CTRL");
+ exit(EXIT_FAILURE);
+ }
+
+ control.id = V4L2_CID_AUDIO_MUTE;
+ control.value = 1; /* silence */
+
+ /* Errors ignored */
+ ioctl(fd, VIDIOC_S_CTRL, &control);
+
+.. [#f1]
+ The use of ``V4L2_CID_PRIVATE_BASE`` is problematic because different
+ drivers may use the same ``V4L2_CID_PRIVATE_BASE`` ID for different
+ controls. This makes it hard to programatically set such controls
+ since the meaning of the control with that ID is driver dependent. In
+ order to resolve this drivers use unique IDs and the
+ ``V4L2_CID_PRIVATE_BASE`` IDs are mapped to those unique IDs by the
+ kernel. Consider these ``V4L2_CID_PRIVATE_BASE`` IDs as aliases to
+ the real IDs.
+
+ Many applications today still use the ``V4L2_CID_PRIVATE_BASE`` IDs
+ instead of using :ref:`VIDIOC_QUERYCTRL` with
+ the ``V4L2_CTRL_FLAG_NEXT_CTRL`` flag to enumerate all IDs, so
+ support for ``V4L2_CID_PRIVATE_BASE`` is still around.