diff options
Diffstat (limited to 'Documentation/userspace-api/media/drivers')
7 files changed, 925 insertions, 0 deletions
diff --git a/Documentation/userspace-api/media/drivers/cx2341x-uapi.rst b/Documentation/userspace-api/media/drivers/cx2341x-uapi.rst new file mode 100644 index 000000000000..8a7977af79d5 --- /dev/null +++ b/Documentation/userspace-api/media/drivers/cx2341x-uapi.rst @@ -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) + diff --git a/Documentation/userspace-api/media/drivers/imx-uapi.rst b/Documentation/userspace-api/media/drivers/imx-uapi.rst new file mode 100644 index 000000000000..8d47712dea9f --- /dev/null +++ b/Documentation/userspace-api/media/drivers/imx-uapi.rst @@ -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. diff --git a/Documentation/userspace-api/media/drivers/index.rst b/Documentation/userspace-api/media/drivers/index.rst new file mode 100644 index 000000000000..05a82f8c0c99 --- /dev/null +++ b/Documentation/userspace-api/media/drivers/index.rst @@ -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 diff --git a/Documentation/userspace-api/media/drivers/max2175.rst b/Documentation/userspace-api/media/drivers/max2175.rst new file mode 100644 index 000000000000..35d3c4b41fc7 --- /dev/null +++ b/Documentation/userspace-api/media/drivers/max2175.rst @@ -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. diff --git a/Documentation/userspace-api/media/drivers/meye-uapi.rst b/Documentation/userspace-api/media/drivers/meye-uapi.rst new file mode 100644 index 000000000000..66b1c142f920 --- /dev/null +++ b/Documentation/userspace-api/media/drivers/meye-uapi.rst @@ -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. diff --git a/Documentation/userspace-api/media/drivers/omap3isp-uapi.rst b/Documentation/userspace-api/media/drivers/omap3isp-uapi.rst new file mode 100644 index 000000000000..5f966a874a3c --- /dev/null +++ b/Documentation/userspace-api/media/drivers/omap3isp-uapi.rst @@ -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 diff --git a/Documentation/userspace-api/media/drivers/uvcvideo.rst b/Documentation/userspace-api/media/drivers/uvcvideo.rst new file mode 100644 index 000000000000..e5fd8fad333c --- /dev/null +++ b/Documentation/userspace-api/media/drivers/uvcvideo.rst @@ -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 |