xiaomi-sm8450/android_kernel_xiaomi_sm8450
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

media: docs: add an uAPI chapter for driver-specific stuff

Browse Source 
There are some uAPI stuff that are driver-specific. Add them
to the main media uAPI body.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
This commit is contained in:
Mauro Carvalho Chehab
2020-03-06 08:50:46 +01:00
parent 577a7ad33a
commit b36343861b
14 changed files with 13 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

179
Documentation/userspace-api/media/drivers/cx2341x-uapi.rst Normal file
View File

@@ -0,0 +1,179 @@
.. SPDX-License-Identifier: GPL-2.0
The cx2341x driver
==================
Non-compressed file format
--------------------------
The cx23416 can produce (and the cx23415 can also read) raw YUV output. The
format of a YUV frame is specific to this chip and is called HM12. 'HM' stands
for 'Hauppauge Macroblock', which is a misnomer as 'Conexant Macroblock' would
be more accurate.
The format is YUV 4:2:0 which uses 1 Y byte per pixel and 1 U and V byte per
four pixels.
The data is encoded as two macroblock planes, the first containing the Y
values, the second containing UV macroblocks.
The Y plane is divided into blocks of 16x16 pixels from left to right
and from top to bottom. Each block is transmitted in turn, line-by-line.
So the first 16 bytes are the first line of the top-left block, the
second 16 bytes are the second line of the top-left block, etc. After
transmitting this block the first line of the block on the right to the
first block is transmitted, etc.
The UV plane is divided into blocks of 16x8 UV values going from left
to right, top to bottom. Each block is transmitted in turn, line-by-line.
So the first 16 bytes are the first line of the top-left block and
contain 8 UV value pairs (16 bytes in total). The second 16 bytes are the
second line of 8 UV pairs of the top-left block, etc. After transmitting
this block the first line of the block on the right to the first block is
transmitted, etc.
The code below is given as an example on how to convert HM12 to separate
Y, U and V planes. This code assumes frames of 720x576 (PAL) pixels.
The width of a frame is always 720 pixels, regardless of the actual specified
width.
If the height is not a multiple of 32 lines, then the captured video is
missing macroblocks at the end and is unusable. So the height must be a
multiple of 32.
Raw format c example
~~~~~~~~~~~~~~~~~~~~
.. code-block:: c
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
static unsigned char frame[576*720*3/2];
static unsigned char framey[576*720];
static unsigned char frameu[576*720 / 4];
static unsigned char framev[576*720 / 4];
static void de_macro_y(unsigned char* dst, unsigned char *src, int dstride, int w, int h)
{
unsigned int y, x, i;
// descramble Y plane
// dstride = 720 = w
// The Y plane is divided into blocks of 16x16 pixels
// Each block in transmitted in turn, line-by-line.
for (y = 0; y < h; y += 16) {
for (x = 0; x < w; x += 16) {
for (i = 0; i < 16; i++) {
memcpy(dst + x + (y + i) * dstride, src, 16);
src += 16;
}
}
}
}
static void de_macro_uv(unsigned char *dstu, unsigned char *dstv, unsigned char *src, int dstride, int w, int h)
{
unsigned int y, x, i;
// descramble U/V plane
// dstride = 720 / 2 = w
// The U/V values are interlaced (UVUV...).
// Again, the UV plane is divided into blocks of 16x16 UV values.
// Each block in transmitted in turn, line-by-line.
for (y = 0; y < h; y += 16) {
for (x = 0; x < w; x += 8) {
for (i = 0; i < 16; i++) {
int idx = x + (y + i) * dstride;
dstu[idx+0] = src[0]; dstv[idx+0] = src[1];
dstu[idx+1] = src[2]; dstv[idx+1] = src[3];
dstu[idx+2] = src[4]; dstv[idx+2] = src[5];
dstu[idx+3] = src[6]; dstv[idx+3] = src[7];
dstu[idx+4] = src[8]; dstv[idx+4] = src[9];
dstu[idx+5] = src[10]; dstv[idx+5] = src[11];
dstu[idx+6] = src[12]; dstv[idx+6] = src[13];
dstu[idx+7] = src[14]; dstv[idx+7] = src[15];
src += 16;
}
}
}
}
/*************************************************************************/
int main(int argc, char **argv)
{
FILE *fin;
int i;
if (argc == 1) fin = stdin;
else fin = fopen(argv[1], "r");
if (fin == NULL) {
fprintf(stderr, "cannot open input\n");
exit(-1);
}
while (fread(frame, sizeof(frame), 1, fin) == 1) {
de_macro_y(framey, frame, 720, 720, 576);
de_macro_uv(frameu, framev, frame + 720 * 576, 720 / 2, 720 / 2, 576 / 2);
fwrite(framey, sizeof(framey), 1, stdout);
fwrite(framev, sizeof(framev), 1, stdout);
fwrite(frameu, sizeof(frameu), 1, stdout);
}
fclose(fin);
return 0;
}
Format of embedded V4L2_MPEG_STREAM_VBI_FMT_IVTV VBI data
---------------------------------------------------------
Author: Hans Verkuil <hverkuil@xs4all.nl>
This section describes the V4L2_MPEG_STREAM_VBI_FMT_IVTV format of the VBI data
embedded in an MPEG-2 program stream. This format is in part dictated by some
hardware limitations of the ivtv driver (the driver for the Conexant cx23415/6
chips), in particular a maximum size for the VBI data. Anything longer is cut
off when the MPEG stream is played back through the cx23415.
The advantage of this format is it is very compact and that all VBI data for
all lines can be stored while still fitting within the maximum allowed size.
The stream ID of the VBI data is 0xBD. The maximum size of the embedded data is
4 + 43 * 36, which is 4 bytes for a header and 2 * 18 VBI lines with a 1 byte
header and a 42 bytes payload each. Anything beyond this limit is cut off by
the cx23415/6 firmware. Besides the data for the VBI lines we also need 36 bits
for a bitmask determining which lines are captured and 4 bytes for a magic cookie,
signifying that this data package contains V4L2_MPEG_STREAM_VBI_FMT_IVTV VBI data.
If all lines are used, then there is no longer room for the bitmask. To solve this
two different magic numbers were introduced:
'itv0': After this magic number two unsigned longs follow. Bits 0-17 of the first
unsigned long denote which lines of the first field are captured. Bits 18-31 of
the first unsigned long and bits 0-3 of the second unsigned long are used for the
second field.
'ITV0': This magic number assumes all VBI lines are captured, i.e. it implicitly
implies that the bitmasks are 0xffffffff and 0xf.
After these magic cookies (and the 8 byte bitmask in case of cookie 'itv0') the
captured VBI lines start:
For each line the least significant 4 bits of the first byte contain the data type.
Possible values are shown in the table below. The payload is in the following 42
bytes.
Here is the list of possible data types:
.. code-block:: c
#define IVTV_SLICED_TYPE_TELETEXT 0x1 // Teletext (uses lines 6-22 for PAL)
#define IVTV_SLICED_TYPE_CC 0x4 // Closed Captions (line 21 NTSC)
#define IVTV_SLICED_TYPE_WSS 0x5 // Wide Screen Signal (line 23 PAL)
#define IVTV_SLICED_TYPE_VPS 0x7 // Video Programming System (PAL) (line 16)

125
Documentation/userspace-api/media/drivers/imx-uapi.rst Normal file
View File

@@ -0,0 +1,125 @@
.. SPDX-License-Identifier: GPL-2.0
=========================
i.MX Video Capture Driver
=========================
Events
======
.. _imx_api_ipuX_csiY:
ipuX_csiY
---------
This subdev can generate the following event when enabling the second
IDMAC source pad:
- V4L2_EVENT_IMX_FRAME_INTERVAL_ERROR
The user application can subscribe to this event from the ipuX_csiY
subdev node. This event is generated by the Frame Interval Monitor
(see below for more on the FIM).
Controls
========
.. _imx_api_FIM:
Frame Interval Monitor in ipuX_csiY
-----------------------------------
The adv718x decoders can occasionally send corrupt fields during
NTSC/PAL signal re-sync (too little or too many video lines). When
this happens, the IPU triggers a mechanism to re-establish vertical
sync by adding 1 dummy line every frame, which causes a rolling effect
from image to image, and can last a long time before a stable image is
recovered. Or sometimes the mechanism doesn't work at all, causing a
permanent split image (one frame contains lines from two consecutive
captured images).
From experiment it was found that during image rolling, the frame
intervals (elapsed time between two EOF's) drop below the nominal
value for the current standard, by about one frame time (60 usec),
and remain at that value until rolling stops.
While the reason for this observation isn't known (the IPU dummy
line mechanism should show an increase in the intervals by 1 line
time every frame, not a fixed value), we can use it to detect the
corrupt fields using a frame interval monitor. If the FIM detects a
bad frame interval, the ipuX_csiY subdev will send the event
V4L2_EVENT_IMX_FRAME_INTERVAL_ERROR. Userland can register with
the FIM event notification on the ipuX_csiY subdev device node.
Userland can issue a streaming restart when this event is received
to correct the rolling/split image.
The ipuX_csiY subdev includes custom controls to tweak some dials for
FIM. If one of these controls is changed during streaming, the FIM will
be reset and will continue at the new settings.
- V4L2_CID_IMX_FIM_ENABLE
Enable/disable the FIM.
- V4L2_CID_IMX_FIM_NUM
How many frame interval measurements to average before comparing against
the nominal frame interval reported by the sensor. This can reduce noise
caused by interrupt latency.
- V4L2_CID_IMX_FIM_TOLERANCE_MIN
If the averaged intervals fall outside nominal by this amount, in
microseconds, the V4L2_EVENT_IMX_FRAME_INTERVAL_ERROR event is sent.
- V4L2_CID_IMX_FIM_TOLERANCE_MAX
If any intervals are higher than this value, those samples are
discarded and do not enter into the average. This can be used to
discard really high interval errors that might be due to interrupt
latency from high system load.
- V4L2_CID_IMX_FIM_NUM_SKIP
How many frames to skip after a FIM reset or stream restart before
FIM begins to average intervals.
- V4L2_CID_IMX_FIM_ICAP_CHANNEL / V4L2_CID_IMX_FIM_ICAP_EDGE
These controls will configure an input capture channel as the method
for measuring frame intervals. This is superior to the default method
of measuring frame intervals via EOF interrupt, since it is not subject
to uncertainty errors introduced by interrupt latency.
Input capture requires hardware support. A VSYNC signal must be routed
to one of the i.MX6 input capture channel pads.
V4L2_CID_IMX_FIM_ICAP_CHANNEL configures which i.MX6 input capture
channel to use. This must be 0 or 1.
V4L2_CID_IMX_FIM_ICAP_EDGE configures which signal edge will trigger
input capture events. By default the input capture method is disabled
with a value of IRQ_TYPE_NONE. Set this control to IRQ_TYPE_EDGE_RISING,
IRQ_TYPE_EDGE_FALLING, or IRQ_TYPE_EDGE_BOTH to enable input capture,
triggered on the given signal edge(s).
When input capture is disabled, frame intervals will be measured via
EOF interrupt.
File list
---------
drivers/staging/media/imx/
include/media/imx.h
include/linux/imx-media.h
Authors
-------
- Steve Longerbeam <steve_longerbeam@mentor.com>
- Philipp Zabel <kernel@pengutronix.de>
- Russell King <linux@armlinux.org.uk>
Copyright (C) 2012-2017 Mentor Graphics Inc.

39
Documentation/userspace-api/media/drivers/index.rst Normal file
View File

@@ -0,0 +1,39 @@
.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>
.. _v4l-drivers_uapi:
################################################
Video4Linux (V4L) driver-specific documentation
################################################
**Copyright** |copy| 1999-2016 : LinuxTV Developers
This documentation is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation version 2 of the License.
This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.
For more details see the file COPYING in the source distribution of Linux.
.. only:: html
.. class:: toc-title
Table of Contents
.. toctree::
:maxdepth: 5
:numbered:
cx2341x-uapi
imx-uapi
max2175
meye-uapi
omap3isp-uapi
uvcvideo

64
Documentation/userspace-api/media/drivers/max2175.rst Normal file
View File

@@ -0,0 +1,64 @@
.. SPDX-License-Identifier: GPL-2.0
Maxim Integrated MAX2175 RF to bits tuner driver
================================================
The MAX2175 driver implements the following driver-specific controls:
``V4L2_CID_MAX2175_I2S_ENABLE``
-------------------------------
Enable/Disable I2S output of the tuner. This is a private control
that can be accessed only using the subdev interface.
Refer to Documentation/driver-api/media/v4l2-controls.rst for more details.
.. flat-table::
:header-rows: 0
:stub-columns: 0
:widths: 1 4
* - ``(0)``
- I2S output is disabled.
* - ``(1)``
- I2S output is enabled.
``V4L2_CID_MAX2175_HSLS``
-------------------------
The high-side/low-side (HSLS) control of the tuner for a given band.
.. flat-table::
:header-rows: 0
:stub-columns: 0
:widths: 1 4
* - ``(0)``
- The LO frequency position is below the desired frequency.
* - ``(1)``
- The LO frequency position is above the desired frequency.
``V4L2_CID_MAX2175_RX_MODE (menu)``
-----------------------------------
The Rx mode controls a number of preset parameters of the tuner like
sample clock (sck), sampling rate etc. These multiple settings are
provided under one single label called Rx mode in the datasheet. The
list below shows the supported modes with a brief description.
.. flat-table::
:header-rows: 0
:stub-columns: 0
:widths: 1 4
* - ``"Europe modes"``
* - ``"FM 1.2" (0)``
- This configures FM band with a sample rate of 0.512 million
samples/sec with a 10.24 MHz sck.
* - ``"DAB 1.2" (1)``
- This configures VHF band with a sample rate of 2.048 million
samples/sec with a 32.768 MHz sck.
* - ``"North America modes"``
* - ``"FM 1.0" (0)``
- This configures FM band with a sample rate of 0.7441875 million
samples/sec with a 14.88375 MHz sck.
* - ``"DAB 1.2" (1)``
- This configures FM band with a sample rate of 0.372 million
samples/sec with a 7.441875 MHz sck.

53
Documentation/userspace-api/media/drivers/meye-uapi.rst Normal file
View File

@@ -0,0 +1,53 @@
.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>
Vaio Picturebook Motion Eye Camera Driver
=========================================
Copyright |copy| 2001-2004 Stelian Pop <stelian@popies.net>
Copyright |copy| 2001-2002 Alcôve <www.alcove.com>
Copyright |copy| 2000 Andrew Tridgell <tridge@samba.org>
Private API
-----------
The driver supports frame grabbing with the video4linux API,
so all video4linux tools (like xawtv) should work with this driver.
Besides the video4linux interface, the driver has a private interface
for accessing the Motion Eye extended parameters (camera sharpness,
agc, video framerate), the snapshot and the MJPEG capture facilities.
This interface consists of several ioctls (prototypes and structures
can be found in include/linux/meye.h):
MEYEIOC_G_PARAMS and MEYEIOC_S_PARAMS
Get and set the extended parameters of the motion eye camera.
The user should always query the current parameters with
MEYEIOC_G_PARAMS, change what he likes and then issue the
MEYEIOC_S_PARAMS call (checking for -EINVAL). The extended
parameters are described by the meye_params structure.
MEYEIOC_QBUF_CAPT
Queue a buffer for capture (the buffers must have been
obtained with a VIDIOCGMBUF call and mmap'ed by the
application). The argument to MEYEIOC_QBUF_CAPT is the
buffer number to queue (or -1 to end capture). The first
call to MEYEIOC_QBUF_CAPT starts the streaming capture.
MEYEIOC_SYNC
Takes as an argument the buffer number you want to sync.
This ioctl blocks until the buffer is filled and ready
for the application to use. It returns the buffer size.
MEYEIOC_STILLCAPT and MEYEIOC_STILLJCAPT
Takes a snapshot in an uncompressed or compressed jpeg format.
This ioctl blocks until the snapshot is done and returns (for
jpeg snapshot) the size of the image. The image data is
available from the first mmap'ed buffer.
Look at the 'motioneye' application code for an actual example.

208
Documentation/userspace-api/media/drivers/omap3isp-uapi.rst Normal file
View File

@@ -0,0 +1,208 @@
.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>
OMAP 3 Image Signal Processor (ISP) driver
==========================================
Copyright |copy| 2010 Nokia Corporation
Copyright |copy| 2009 Texas Instruments, Inc.
Contacts: Laurent Pinchart <laurent.pinchart@ideasonboard.com>,
Sakari Ailus <sakari.ailus@iki.fi>, David Cohen <dacohen@gmail.com>
Events
------
The OMAP 3 ISP driver does support the V4L2 event interface on CCDC and
statistics (AEWB, AF and histogram) subdevs.
The CCDC subdev produces V4L2_EVENT_FRAME_SYNC type event on HS_VS
interrupt which is used to signal frame start. Earlier version of this
driver used V4L2_EVENT_OMAP3ISP_HS_VS for this purpose. The event is
triggered exactly when the reception of the first line of the frame starts
in the CCDC module. The event can be subscribed on the CCDC subdev.
(When using parallel interface one must pay account to correct configuration
of the VS signal polarity. This is automatically correct when using the serial
receivers.)
Each of the statistics subdevs is able to produce events. An event is
generated whenever a statistics buffer can be dequeued by a user space
application using the VIDIOC_OMAP3ISP_STAT_REQ IOCTL. The events available
are:
- V4L2_EVENT_OMAP3ISP_AEWB
- V4L2_EVENT_OMAP3ISP_AF
- V4L2_EVENT_OMAP3ISP_HIST
The type of the event data is struct omap3isp_stat_event_status for these
ioctls. If there is an error calculating the statistics, there will be an
event as usual, but no related statistics buffer. In this case
omap3isp_stat_event_status.buf_err is set to non-zero.
Private IOCTLs
--------------
The OMAP 3 ISP driver supports standard V4L2 IOCTLs and controls where
possible and practical. Much of the functions provided by the ISP, however,
does not fall under the standard IOCTLs --- gamma tables and configuration of
statistics collection are examples of such.
In general, there is a private ioctl for configuring each of the blocks
containing hardware-dependent functions.
The following private IOCTLs are supported:
- VIDIOC_OMAP3ISP_CCDC_CFG
- VIDIOC_OMAP3ISP_PRV_CFG
- VIDIOC_OMAP3ISP_AEWB_CFG
- VIDIOC_OMAP3ISP_HIST_CFG
- VIDIOC_OMAP3ISP_AF_CFG
- VIDIOC_OMAP3ISP_STAT_REQ
- VIDIOC_OMAP3ISP_STAT_EN
The parameter structures used by these ioctls are described in
include/linux/omap3isp.h. The detailed functions of the ISP itself related to
a given ISP block is described in the Technical Reference Manuals (TRMs) ---
see the end of the document for those.
While it is possible to use the ISP driver without any use of these private
IOCTLs it is not possible to obtain optimal image quality this way. The AEWB,
AF and histogram modules cannot be used without configuring them using the
appropriate private IOCTLs.
CCDC and preview block IOCTLs
-----------------------------
The VIDIOC_OMAP3ISP_CCDC_CFG and VIDIOC_OMAP3ISP_PRV_CFG IOCTLs are used to
configure, enable and disable functions in the CCDC and preview blocks,
respectively. Both IOCTLs control several functions in the blocks they
control. VIDIOC_OMAP3ISP_CCDC_CFG IOCTL accepts a pointer to struct
omap3isp_ccdc_update_config as its argument. Similarly VIDIOC_OMAP3ISP_PRV_CFG
accepts a pointer to struct omap3isp_prev_update_config. The definition of
both structures is available in [#]_.
The update field in the structures tells whether to update the configuration
for the specific function and the flag tells whether to enable or disable the
function.
The update and flag bit masks accept the following values. Each separate
functions in the CCDC and preview blocks is associated with a flag (either
disable or enable; part of the flag field in the structure) and a pointer to
configuration data for the function.
Valid values for the update and flag fields are listed here for
VIDIOC_OMAP3ISP_CCDC_CFG. Values may be or'ed to configure more than one
function in the same IOCTL call.
- OMAP3ISP_CCDC_ALAW
- OMAP3ISP_CCDC_LPF
- OMAP3ISP_CCDC_BLCLAMP
- OMAP3ISP_CCDC_BCOMP
- OMAP3ISP_CCDC_FPC
- OMAP3ISP_CCDC_CULL
- OMAP3ISP_CCDC_CONFIG_LSC
- OMAP3ISP_CCDC_TBL_LSC
The corresponding values for the VIDIOC_OMAP3ISP_PRV_CFG are here:
- OMAP3ISP_PREV_LUMAENH
- OMAP3ISP_PREV_INVALAW
- OMAP3ISP_PREV_HRZ_MED
- OMAP3ISP_PREV_CFA
- OMAP3ISP_PREV_CHROMA_SUPP
- OMAP3ISP_PREV_WB
- OMAP3ISP_PREV_BLKADJ
- OMAP3ISP_PREV_RGB2RGB
- OMAP3ISP_PREV_COLOR_CONV
- OMAP3ISP_PREV_YC_LIMIT
- OMAP3ISP_PREV_DEFECT_COR
- OMAP3ISP_PREV_GAMMABYPASS
- OMAP3ISP_PREV_DRK_FRM_CAPTURE
- OMAP3ISP_PREV_DRK_FRM_SUBTRACT
- OMAP3ISP_PREV_LENS_SHADING
- OMAP3ISP_PREV_NF
- OMAP3ISP_PREV_GAMMA
The associated configuration pointer for the function may not be NULL when
enabling the function. When disabling a function the configuration pointer is
ignored.
Statistic blocks IOCTLs
-----------------------
The statistics subdevs do offer more dynamic configuration options than the
other subdevs. They can be enabled, disable and reconfigured when the pipeline
is in streaming state.
The statistics blocks always get the input image data from the CCDC (as the
histogram memory read isn't implemented). The statistics are dequeueable by
the user from the statistics subdev nodes using private IOCTLs.
The private IOCTLs offered by the AEWB, AF and histogram subdevs are heavily
reflected by the register level interface offered by the ISP hardware. There
are aspects that are purely related to the driver implementation and these are
discussed next.
VIDIOC_OMAP3ISP_STAT_EN
-----------------------
This private IOCTL enables/disables a statistic module. If this request is
done before streaming, it will take effect as soon as the pipeline starts to
stream. If the pipeline is already streaming, it will take effect as soon as
the CCDC becomes idle.
VIDIOC_OMAP3ISP_AEWB_CFG, VIDIOC_OMAP3ISP_HIST_CFG and VIDIOC_OMAP3ISP_AF_CFG
-----------------------------------------------------------------------------
Those IOCTLs are used to configure the modules. They require user applications
to have an in-depth knowledge of the hardware. Most of the fields explanation
can be found on OMAP's TRMs. The two following fields common to all the above
configure private IOCTLs require explanation for better understanding as they
are not part of the TRM.
omap3isp_[h3a_af/h3a_aewb/hist]\_config.buf_size:
The modules handle their buffers internally. The necessary buffer size for the
module's data output depends on the requested configuration. Although the
driver supports reconfiguration while streaming, it does not support a
reconfiguration which requires bigger buffer size than what is already
internally allocated if the module is enabled. It will return -EBUSY on this
case. In order to avoid such condition, either disable/reconfigure/enable the
module or request the necessary buffer size during the first configuration
while the module is disabled.
The internal buffer size allocation considers the requested configuration's
minimum buffer size and the value set on buf_size field. If buf_size field is
out of [minimum, maximum] buffer size range, it's clamped to fit in there.
The driver then selects the biggest value. The corrected buf_size value is
written back to user application.
omap3isp_[h3a_af/h3a_aewb/hist]\_config.config_counter:
As the configuration doesn't take effect synchronously to the request, the
driver must provide a way to track this information to provide more accurate
data. After a configuration is requested, the config_counter returned to user
space application will be an unique value associated to that request. When
user application receives an event for buffer availability or when a new
buffer is requested, this config_counter is used to match a buffer data and a
configuration.
VIDIOC_OMAP3ISP_STAT_REQ
------------------------
Send to user space the oldest data available in the internal buffer queue and
discards such buffer afterwards. The field omap3isp_stat_data.frame_number
matches with the video buffer's field_count.
References
----------
.. [#] include/linux/omap3isp.h

257
Documentation/userspace-api/media/drivers/uvcvideo.rst Normal file
View File

@@ -0,0 +1,257 @@
.. SPDX-License-Identifier: GPL-2.0
The Linux USB Video Class (UVC) driver
======================================
This file documents some driver-specific aspects of the UVC driver, such as
driver-specific ioctls and implementation notes.
Questions and remarks can be sent to the Linux UVC development mailing list at
linux-uvc-devel@lists.berlios.de.
Extension Unit (XU) support
---------------------------
Introduction
~~~~~~~~~~~~
The UVC specification allows for vendor-specific extensions through extension
units (XUs). The Linux UVC driver supports extension unit controls (XU controls)
through two separate mechanisms:
- through mappings of XU controls to V4L2 controls
- through a driver-specific ioctl interface
The first one allows generic V4L2 applications to use XU controls by mapping
certain XU controls onto V4L2 controls, which then show up during ordinary
control enumeration.
The second mechanism requires uvcvideo-specific knowledge for the application to
access XU controls but exposes the entire UVC XU concept to user space for
maximum flexibility.
Both mechanisms complement each other and are described in more detail below.
Control mappings
~~~~~~~~~~~~~~~~
The UVC driver provides an API for user space applications to define so-called
control mappings at runtime. These allow for individual XU controls or byte
ranges thereof to be mapped to new V4L2 controls. Such controls appear and
function exactly like normal V4L2 controls (i.e. the stock controls, such as
brightness, contrast, etc.). However, reading or writing of such a V4L2 controls
triggers a read or write of the associated XU control.
The ioctl used to create these control mappings is called UVCIOC_CTRL_MAP.
Previous driver versions (before 0.2.0) required another ioctl to be used
beforehand (UVCIOC_CTRL_ADD) to pass XU control information to the UVC driver.
This is no longer necessary as newer uvcvideo versions query the information
directly from the device.
For details on the UVCIOC_CTRL_MAP ioctl please refer to the section titled
"IOCTL reference" below.
3. Driver specific XU control interface
For applications that need to access XU controls directly, e.g. for testing
purposes, firmware upload, or accessing binary controls, a second mechanism to
access XU controls is provided in the form of a driver-specific ioctl, namely
UVCIOC_CTRL_QUERY.
A call to this ioctl allows applications to send queries to the UVC driver that
directly map to the low-level UVC control requests.
In order to make such a request the UVC unit ID of the control's extension unit
and the control selector need to be known. This information either needs to be
hardcoded in the application or queried using other ways such as by parsing the
UVC descriptor or, if available, using the media controller API to enumerate a
device's entities.
Unless the control size is already known it is necessary to first make a
UVC_GET_LEN requests in order to be able to allocate a sufficiently large buffer
and set the buffer size to the correct value. Similarly, to find out whether
UVC_GET_CUR or UVC_SET_CUR are valid requests for a given control, a
UVC_GET_INFO request should be made. The bits 0 (GET supported) and 1 (SET
supported) of the resulting byte indicate which requests are valid.
With the addition of the UVCIOC_CTRL_QUERY ioctl the UVCIOC_CTRL_GET and
UVCIOC_CTRL_SET ioctls have become obsolete since their functionality is a
subset of the former ioctl. For the time being they are still supported but
application developers are encouraged to use UVCIOC_CTRL_QUERY instead.
For details on the UVCIOC_CTRL_QUERY ioctl please refer to the section titled
"IOCTL reference" below.
Security
~~~~~~~~
The API doesn't currently provide a fine-grained access control facility. The
UVCIOC_CTRL_ADD and UVCIOC_CTRL_MAP ioctls require super user permissions.
Suggestions on how to improve this are welcome.
Debugging
~~~~~~~~~
In order to debug problems related to XU controls or controls in general it is
recommended to enable the UVC_TRACE_CONTROL bit in the module parameter 'trace'.
This causes extra output to be written into the system log.
IOCTL reference
~~~~~~~~~~~~~~~
UVCIOC_CTRL_MAP - Map a UVC control to a V4L2 control
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Argument: struct uvc_xu_control_mapping
**Description**:
This ioctl creates a mapping between a UVC control or part of a UVC
control and a V4L2 control. Once mappings are defined, userspace
applications can access vendor-defined UVC control through the V4L2
control API.
To create a mapping, applications fill the uvc_xu_control_mapping
structure with information about an existing UVC control defined with
UVCIOC_CTRL_ADD and a new V4L2 control.
A UVC control can be mapped to several V4L2 controls. For instance,
a UVC pan/tilt control could be mapped to separate pan and tilt V4L2
controls. The UVC control is divided into non overlapping fields using
the 'size' and 'offset' fields and are then independently mapped to
V4L2 control.
For signed integer V4L2 controls the data_type field should be set to
UVC_CTRL_DATA_TYPE_SIGNED. Other values are currently ignored.
**Return value**:
On success 0 is returned. On error -1 is returned and errno is set
appropriately.
ENOMEM
Not enough memory to perform the operation.
EPERM
Insufficient privileges (super user privileges are required).
EINVAL
No such UVC control.
EOVERFLOW
The requested offset and size would overflow the UVC control.
EEXIST
Mapping already exists.
**Data types**:
.. code-block:: none
* struct uvc_xu_control_mapping
__u32 id V4L2 control identifier
__u8 name[32] V4L2 control name
__u8 entity[16] UVC extension unit GUID
__u8 selector UVC control selector
__u8 size V4L2 control size (in bits)
__u8 offset V4L2 control offset (in bits)
enum v4l2_ctrl_type
v4l2_type V4L2 control type
enum uvc_control_data_type
data_type UVC control data type
struct uvc_menu_info
*menu_info Array of menu entries (for menu controls only)
__u32 menu_count Number of menu entries (for menu controls only)
* struct uvc_menu_info
__u32 value Menu entry value used by the device
__u8 name[32] Menu entry name
* enum uvc_control_data_type
UVC_CTRL_DATA_TYPE_RAW Raw control (byte array)
UVC_CTRL_DATA_TYPE_SIGNED Signed integer
UVC_CTRL_DATA_TYPE_UNSIGNED Unsigned integer
UVC_CTRL_DATA_TYPE_BOOLEAN Boolean
UVC_CTRL_DATA_TYPE_ENUM Enumeration
UVC_CTRL_DATA_TYPE_BITMASK Bitmask
UVCIOC_CTRL_QUERY - Query a UVC XU control
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Argument: struct uvc_xu_control_query
**Description**:
This ioctl queries a UVC XU control identified by its extension unit ID
and control selector.
There are a number of different queries available that closely
correspond to the low-level control requests described in the UVC
specification. These requests are:
UVC_GET_CUR
Obtain the current value of the control.
UVC_GET_MIN
Obtain the minimum value of the control.
UVC_GET_MAX
Obtain the maximum value of the control.
UVC_GET_DEF
Obtain the default value of the control.
UVC_GET_RES
Query the resolution of the control, i.e. the step size of the
allowed control values.
UVC_GET_LEN
Query the size of the control in bytes.
UVC_GET_INFO
Query the control information bitmap, which indicates whether
get/set requests are supported.
UVC_SET_CUR
Update the value of the control.
Applications must set the 'size' field to the correct length for the
control. Exceptions are the UVC_GET_LEN and UVC_GET_INFO queries, for
which the size must be set to 2 and 1, respectively. The 'data' field
must point to a valid writable buffer big enough to hold the indicated
number of data bytes.
Data is copied directly from the device without any driver-side
processing. Applications are responsible for data buffer formatting,
including little-endian/big-endian conversion. This is particularly
important for the result of the UVC_GET_LEN requests, which is always
returned as a little-endian 16-bit integer by the device.
**Return value**:
On success 0 is returned. On error -1 is returned and errno is set
appropriately.
ENOENT
The device does not support the given control or the specified
extension unit could not be found.
ENOBUFS
The specified buffer size is incorrect (too big or too small).
EINVAL
An invalid request code was passed.
EBADRQC
The given request is not supported by the given control.
EFAULT
The data pointer references an inaccessible memory area.
**Data types**:
.. code-block:: none
* struct uvc_xu_control_query
__u8 unit Extension unit ID
__u8 selector Control selector
__u8 query Request code to send to the device
__u16 size Control data size (in bytes)
__u8 *data Control value

2
Documentation/userspace-api/media/index.rst
View File

@@ -31,3 +31,5 @@ entitled "GNU Free Documentation License".
cec/cec-api
gen-errors
fdl-appendix
drivers/index

2
Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst
View File

@@ -438,7 +438,7 @@ MPEG stream.
*Historical context*: This format specification originates from a
custom, embedded, sliced VBI data format used by the ``ivtv`` driver.
This format has already been informally specified in the kernel sources
in the file ``Documentation/media/v4l-drivers/cx2341x-uapi.rst`` . The
in the file ``Documentation/userspace-api/media/drivers/cx2341x-uapi.rst`` . The
maximum size of the payload and other aspects of this format are driven
by the CX23415 MPEG decoder's capabilities and limitations with respect
to extracting, decoding, and displaying sliced VBI data embedded within

2
Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst
View File

@@ -116,7 +116,7 @@ enum v4l2_mpeg_stream_vbi_fmt -
* - ``V4L2_MPEG_STREAM_VBI_FMT_IVTV``
- VBI in private packets, IVTV format (documented in the kernel
sources in the file
``Documentation/media/v4l-drivers/cx2341x-uapi.rst``)
``Documentation/userspace-api/media/drivers/cx2341x-uapi.rst``)

2
Documentation/userspace-api/media/v4l/pixfmt-reserved.rst
View File

@@ -58,7 +58,7 @@ please make a proposal on the linux-media mailing list.
- YUV 4:2:0 format used by the IVTV driver.
The format is documented in the kernel sources in the file
``Documentation/media/v4l-drivers/cx2341x-uapi.rst``
``Documentation/userspace-api/media/drivers/cx2341x-uapi.rst``
* .. _V4L2-PIX-FMT-CPIA1:
- ``V4L2_PIX_FMT_CPIA1``