diff options
author | Mauro Carvalho Chehab <mchehab+huawei@kernel.org> | 2020-03-06 08:50:46 +0100 |
---|---|---|
committer | Mauro Carvalho Chehab <mchehab+huawei@kernel.org> | 2020-04-14 10:36:50 +0200 |
commit | b36343861b218d24d4e568c4de8921b15c2cc8a8 (patch) | |
tree | e1ab546bd142de0f7d3e40b794f71d90c9e09506 /Documentation/media | |
parent | 577a7ad33aeff86f6c97277b12b122a0a2ad97d7 (diff) | |
download | linux-b36343861b218d24d4e568c4de8921b15c2cc8a8.tar.bz2 |
media: docs: add an uAPI chapter for driver-specific stuff
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>
Diffstat (limited to 'Documentation/media')
-rw-r--r-- | Documentation/media/index.rst | 2 | ||||
-rw-r--r-- | Documentation/media/v4l-drivers/cx2341x-uapi.rst | 179 | ||||
-rw-r--r-- | Documentation/media/v4l-drivers/imx-uapi.rst | 125 | ||||
-rw-r--r-- | Documentation/media/v4l-drivers/index.rst | 40 | ||||
-rw-r--r-- | Documentation/media/v4l-drivers/max2175.rst | 64 | ||||
-rw-r--r-- | Documentation/media/v4l-drivers/meye-uapi.rst | 53 | ||||
-rw-r--r-- | Documentation/media/v4l-drivers/omap3isp-uapi.rst | 208 | ||||
-rw-r--r-- | Documentation/media/v4l-drivers/uvcvideo.rst | 257 |
8 files changed, 0 insertions, 928 deletions
diff --git a/Documentation/media/index.rst b/Documentation/media/index.rst index a5cd600e0b04..e93fd88881af 100644 --- a/Documentation/media/index.rst +++ b/Documentation/media/index.rst @@ -15,8 +15,6 @@ Linux Media Subsystem Documentation ../userspace-api/media/index ../driver-api/media/index - v4l-drivers/index - .. only:: html and subproject Indices diff --git a/Documentation/media/v4l-drivers/cx2341x-uapi.rst b/Documentation/media/v4l-drivers/cx2341x-uapi.rst deleted file mode 100644 index 8a7977af79d5..000000000000 --- a/Documentation/media/v4l-drivers/cx2341x-uapi.rst +++ /dev/null @@ -1,179 +0,0 @@ -.. 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) - diff --git a/Documentation/media/v4l-drivers/imx-uapi.rst b/Documentation/media/v4l-drivers/imx-uapi.rst deleted file mode 100644 index 8d47712dea9f..000000000000 --- a/Documentation/media/v4l-drivers/imx-uapi.rst +++ /dev/null @@ -1,125 +0,0 @@ -.. 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. diff --git a/Documentation/media/v4l-drivers/index.rst b/Documentation/media/v4l-drivers/index.rst deleted file mode 100644 index ee7faff88a33..000000000000 --- a/Documentation/media/v4l-drivers/index.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -.. include:: <isonum.txt> - -.. _v4l-drivers: - -################################################ -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: - - max2175 - uvcvideo - - cx2341x-uapi - imx-uapi - meye-uapi - omap3isp-uapi diff --git a/Documentation/media/v4l-drivers/max2175.rst b/Documentation/media/v4l-drivers/max2175.rst deleted file mode 100644 index 35d3c4b41fc7..000000000000 --- a/Documentation/media/v4l-drivers/max2175.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. 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. diff --git a/Documentation/media/v4l-drivers/meye-uapi.rst b/Documentation/media/v4l-drivers/meye-uapi.rst deleted file mode 100644 index 66b1c142f920..000000000000 --- a/Documentation/media/v4l-drivers/meye-uapi.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. 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. diff --git a/Documentation/media/v4l-drivers/omap3isp-uapi.rst b/Documentation/media/v4l-drivers/omap3isp-uapi.rst deleted file mode 100644 index 5f966a874a3c..000000000000 --- a/Documentation/media/v4l-drivers/omap3isp-uapi.rst +++ /dev/null @@ -1,208 +0,0 @@ -.. 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 diff --git a/Documentation/media/v4l-drivers/uvcvideo.rst b/Documentation/media/v4l-drivers/uvcvideo.rst deleted file mode 100644 index e5fd8fad333c..000000000000 --- a/Documentation/media/v4l-drivers/uvcvideo.rst +++ /dev/null @@ -1,257 +0,0 @@ -.. 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 |