From 485f9a434c165441fafec9259fa1057c399af903 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 4 Mar 2020 12:53:28 +0100 Subject: media: docs: avermedia.rst: mark a table as such There's a table on this file, with aren't using the ReST markups. Fix that. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/dvb-drivers/avermedia.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'Documentation') diff --git a/Documentation/media/dvb-drivers/avermedia.rst b/Documentation/media/dvb-drivers/avermedia.rst index 14f437ca38d3..bf35fd88e164 100644 --- a/Documentation/media/dvb-drivers/avermedia.rst +++ b/Documentation/media/dvb-drivers/avermedia.rst @@ -172,12 +172,16 @@ Dandenong. The frequencies broadcast by Mount Dandenong are: Table 1. Transponder Frequencies Mount Dandenong, Vic, Aus. + +=========== ======= =========== Broadcaster Channel Frequency +=========== ======= =========== ABC VHF 12 226.5 MHz TEN VHF 11 219.5 MHz NINE VHF 8 191.625 MHz SEVEN VHF 6 177.5 MHz SBS UHF 29 536.5 MHz +=========== ======= =========== The Scan utility has a set of compiled-in defaults for various countries and regions, but if they do not suit, or if you have -- cgit v1.2.3 From c8b667ac517ecb5fada1c085236a9c05d0e303ca Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 5 Mar 2020 07:49:04 +0100 Subject: media: docs: move soc-camera.rst to staging As the entire soc_camera driver is on staging to be removed soon, let's place there its documentation too. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/v4l-drivers/index.rst | 1 - Documentation/media/v4l-drivers/soc-camera.rst | 171 ------------------------ drivers/staging/media/soc_camera/soc-camera.rst | 171 ++++++++++++++++++++++++ 3 files changed, 171 insertions(+), 172 deletions(-) delete mode 100644 Documentation/media/v4l-drivers/soc-camera.rst create mode 100644 drivers/staging/media/soc_camera/soc-camera.rst (limited to 'Documentation') diff --git a/Documentation/media/v4l-drivers/index.rst b/Documentation/media/v4l-drivers/index.rst index b41fea23fe5d..eca22b82de94 100644 --- a/Documentation/media/v4l-drivers/index.rst +++ b/Documentation/media/v4l-drivers/index.rst @@ -61,7 +61,6 @@ For more details see the file COPYING in the source distribution of Linux. si470x si4713 si476x - soc-camera uvcvideo vimc vivid diff --git a/Documentation/media/v4l-drivers/soc-camera.rst b/Documentation/media/v4l-drivers/soc-camera.rst deleted file mode 100644 index 7c39711aebf8..000000000000 --- a/Documentation/media/v4l-drivers/soc-camera.rst +++ /dev/null @@ -1,171 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -The Soc-Camera Drivers -====================== - -Author: Guennadi Liakhovetski - -Terminology ------------ - -The following terms are used in this document: - - camera / camera device / camera sensor - a video-camera sensor chip, capable - of connecting to a variety of systems and interfaces, typically uses i2c for - control and configuration, and a parallel or a serial bus for data. - - camera host - an interface, to which a camera is connected. Typically a - specialised interface, present on many SoCs, e.g. PXA27x and PXA3xx, SuperH, - i.MX27, i.MX31. - - camera host bus - a connection between a camera host and a camera. Can be - parallel or serial, consists of data and control lines, e.g. clock, vertical - and horizontal synchronization signals. - -Purpose of the soc-camera subsystem ------------------------------------ - -The soc-camera subsystem initially provided a unified API between camera host -drivers and camera sensor drivers. Later the soc-camera sensor API has been -replaced with the V4L2 standard subdev API. This also made camera driver re-use -with non-soc-camera hosts possible. The camera host API to the soc-camera core -has been preserved. - -Soc-camera implements a V4L2 interface to the user, currently only the "mmap" -method is supported by host drivers. However, the soc-camera core also provides -support for the "read" method. - -The subsystem has been designed to support multiple camera host interfaces and -multiple cameras per interface, although most applications have only one camera -sensor. - -Existing drivers ----------------- - -As of 3.7 there are seven host drivers in the mainline: atmel-isi.c, -mx1_camera.c (broken, scheduled for removal), mx2_camera.c, mx3_camera.c, -omap1_camera.c, pxa_camera.c, sh_mobile_ceu_camera.c, and multiple sensor -drivers under drivers/media/i2c/soc_camera/. - -Camera host API ---------------- - -A host camera driver is registered using the - -.. code-block:: none - - soc_camera_host_register(struct soc_camera_host *); - -function. The host object can be initialized as follows: - -.. code-block:: none - - struct soc_camera_host *ici; - ici->drv_name = DRV_NAME; - ici->ops = &camera_host_ops; - ici->priv = pcdev; - ici->v4l2_dev.dev = &pdev->dev; - ici->nr = pdev->id; - -All camera host methods are passed in a struct soc_camera_host_ops: - -.. code-block:: none - - static struct soc_camera_host_ops camera_host_ops = { - .owner = THIS_MODULE, - .add = camera_add_device, - .remove = camera_remove_device, - .set_fmt = camera_set_fmt_cap, - .try_fmt = camera_try_fmt_cap, - .init_videobuf2 = camera_init_videobuf2, - .poll = camera_poll, - .querycap = camera_querycap, - .set_bus_param = camera_set_bus_param, - /* The rest of host operations are optional */ - }; - -.add and .remove methods are called when a sensor is attached to or detached -from the host. .set_bus_param is used to configure physical connection -parameters between the host and the sensor. .init_videobuf2 is called by -soc-camera core when a video-device is opened, the host driver would typically -call vb2_queue_init() in this method. Further video-buffer management is -implemented completely by the specific camera host driver. If the host driver -supports non-standard pixel format conversion, it should implement a -.get_formats and, possibly, a .put_formats operations. See below for more -details about format conversion. The rest of the methods are called from -respective V4L2 operations. - -Camera API ----------- - -Sensor drivers can use struct soc_camera_link, typically provided by the -platform, and used to specify to which camera host bus the sensor is connected, -and optionally provide platform .power and .reset methods for the camera. This -struct is provided to the camera driver via the I2C client device platform data -and can be obtained, using the soc_camera_i2c_to_link() macro. Care should be -taken, when using soc_camera_vdev_to_subdev() and when accessing struct -soc_camera_device, using v4l2_get_subdev_hostdata(): both only work, when -running on an soc-camera host. The actual camera driver operation is implemented -using the V4L2 subdev API. Additionally soc-camera camera drivers can use -auxiliary soc-camera helper functions like soc_camera_power_on() and -soc_camera_power_off(), which switch regulators, provided by the platform and call -board-specific power switching methods. soc_camera_apply_board_flags() takes -camera bus configuration capability flags and applies any board transformations, -e.g. signal polarity inversion. soc_mbus_get_fmtdesc() can be used to obtain a -pixel format descriptor, corresponding to a certain media-bus pixel format code. -soc_camera_limit_side() can be used to restrict beginning and length of a frame -side, based on camera capabilities. - -VIDIOC_S_CROP and VIDIOC_S_FMT behaviour ----------------------------------------- - -Above user ioctls modify image geometry as follows: - -VIDIOC_S_CROP: sets location and sizes of the sensor window. Unit is one sensor -pixel. Changing sensor window sizes preserves any scaling factors, therefore -user window sizes change as well. - -VIDIOC_S_FMT: sets user window. Should preserve previously set sensor window as -much as possible by modifying scaling factors. If the sensor window cannot be -preserved precisely, it may be changed too. - -In soc-camera there are two locations, where scaling and cropping can take -place: in the camera driver and in the host driver. User ioctls are first passed -to the host driver, which then generally passes them down to the camera driver. -It is more efficient to perform scaling and cropping in the camera driver to -save camera bus bandwidth and maximise the framerate. However, if the camera -driver failed to set the required parameters with sufficient precision, the host -driver may decide to also use its own scaling and cropping to fulfill the user's -request. - -Camera drivers are interfaced to the soc-camera core and to host drivers over -the v4l2-subdev API, which is completely functional, it doesn't pass any data. -Therefore all camera drivers shall reply to .g_fmt() requests with their current -output geometry. This is necessary to correctly configure the camera bus. -.s_fmt() and .try_fmt() have to be implemented too. Sensor window and scaling -factors have to be maintained by camera drivers internally. According to the -V4L2 API all capture drivers must support the VIDIOC_CROPCAP ioctl, hence we -rely on camera drivers implementing .cropcap(). If the camera driver does not -support cropping, it may choose to not implement .s_crop(), but to enable -cropping support by the camera host driver at least the .g_crop method must be -implemented. - -User window geometry is kept in .user_width and .user_height fields in struct -soc_camera_device and used by the soc-camera core and host drivers. The core -updates these fields upon successful completion of a .s_fmt() call, but if these -fields change elsewhere, e.g. during .s_crop() processing, the host driver is -responsible for updating them. - -Format conversion ------------------ - -V4L2 distinguishes between pixel formats, as they are stored in memory, and as -they are transferred over a media bus. Soc-camera provides support to -conveniently manage these formats. A table of standard transformations is -maintained by soc-camera core, which describes, what FOURCC pixel format will -be obtained, if a media-bus pixel format is stored in memory according to -certain rules. E.g. if MEDIA_BUS_FMT_YUYV8_2X8 data is sampled with 8 bits per -sample and stored in memory in the little-endian order with no gaps between -bytes, data in memory will represent the V4L2_PIX_FMT_YUYV FOURCC format. These -standard transformations will be used by soc-camera or by camera host drivers to -configure camera drivers to produce the FOURCC format, requested by the user, -using the VIDIOC_S_FMT ioctl(). Apart from those standard format conversions, -host drivers can also provide their own conversion rules by implementing a -.get_formats and, if required, a .put_formats methods. diff --git a/drivers/staging/media/soc_camera/soc-camera.rst b/drivers/staging/media/soc_camera/soc-camera.rst new file mode 100644 index 000000000000..7c39711aebf8 --- /dev/null +++ b/drivers/staging/media/soc_camera/soc-camera.rst @@ -0,0 +1,171 @@ +.. SPDX-License-Identifier: GPL-2.0 + +The Soc-Camera Drivers +====================== + +Author: Guennadi Liakhovetski + +Terminology +----------- + +The following terms are used in this document: + - camera / camera device / camera sensor - a video-camera sensor chip, capable + of connecting to a variety of systems and interfaces, typically uses i2c for + control and configuration, and a parallel or a serial bus for data. + - camera host - an interface, to which a camera is connected. Typically a + specialised interface, present on many SoCs, e.g. PXA27x and PXA3xx, SuperH, + i.MX27, i.MX31. + - camera host bus - a connection between a camera host and a camera. Can be + parallel or serial, consists of data and control lines, e.g. clock, vertical + and horizontal synchronization signals. + +Purpose of the soc-camera subsystem +----------------------------------- + +The soc-camera subsystem initially provided a unified API between camera host +drivers and camera sensor drivers. Later the soc-camera sensor API has been +replaced with the V4L2 standard subdev API. This also made camera driver re-use +with non-soc-camera hosts possible. The camera host API to the soc-camera core +has been preserved. + +Soc-camera implements a V4L2 interface to the user, currently only the "mmap" +method is supported by host drivers. However, the soc-camera core also provides +support for the "read" method. + +The subsystem has been designed to support multiple camera host interfaces and +multiple cameras per interface, although most applications have only one camera +sensor. + +Existing drivers +---------------- + +As of 3.7 there are seven host drivers in the mainline: atmel-isi.c, +mx1_camera.c (broken, scheduled for removal), mx2_camera.c, mx3_camera.c, +omap1_camera.c, pxa_camera.c, sh_mobile_ceu_camera.c, and multiple sensor +drivers under drivers/media/i2c/soc_camera/. + +Camera host API +--------------- + +A host camera driver is registered using the + +.. code-block:: none + + soc_camera_host_register(struct soc_camera_host *); + +function. The host object can be initialized as follows: + +.. code-block:: none + + struct soc_camera_host *ici; + ici->drv_name = DRV_NAME; + ici->ops = &camera_host_ops; + ici->priv = pcdev; + ici->v4l2_dev.dev = &pdev->dev; + ici->nr = pdev->id; + +All camera host methods are passed in a struct soc_camera_host_ops: + +.. code-block:: none + + static struct soc_camera_host_ops camera_host_ops = { + .owner = THIS_MODULE, + .add = camera_add_device, + .remove = camera_remove_device, + .set_fmt = camera_set_fmt_cap, + .try_fmt = camera_try_fmt_cap, + .init_videobuf2 = camera_init_videobuf2, + .poll = camera_poll, + .querycap = camera_querycap, + .set_bus_param = camera_set_bus_param, + /* The rest of host operations are optional */ + }; + +.add and .remove methods are called when a sensor is attached to or detached +from the host. .set_bus_param is used to configure physical connection +parameters between the host and the sensor. .init_videobuf2 is called by +soc-camera core when a video-device is opened, the host driver would typically +call vb2_queue_init() in this method. Further video-buffer management is +implemented completely by the specific camera host driver. If the host driver +supports non-standard pixel format conversion, it should implement a +.get_formats and, possibly, a .put_formats operations. See below for more +details about format conversion. The rest of the methods are called from +respective V4L2 operations. + +Camera API +---------- + +Sensor drivers can use struct soc_camera_link, typically provided by the +platform, and used to specify to which camera host bus the sensor is connected, +and optionally provide platform .power and .reset methods for the camera. This +struct is provided to the camera driver via the I2C client device platform data +and can be obtained, using the soc_camera_i2c_to_link() macro. Care should be +taken, when using soc_camera_vdev_to_subdev() and when accessing struct +soc_camera_device, using v4l2_get_subdev_hostdata(): both only work, when +running on an soc-camera host. The actual camera driver operation is implemented +using the V4L2 subdev API. Additionally soc-camera camera drivers can use +auxiliary soc-camera helper functions like soc_camera_power_on() and +soc_camera_power_off(), which switch regulators, provided by the platform and call +board-specific power switching methods. soc_camera_apply_board_flags() takes +camera bus configuration capability flags and applies any board transformations, +e.g. signal polarity inversion. soc_mbus_get_fmtdesc() can be used to obtain a +pixel format descriptor, corresponding to a certain media-bus pixel format code. +soc_camera_limit_side() can be used to restrict beginning and length of a frame +side, based on camera capabilities. + +VIDIOC_S_CROP and VIDIOC_S_FMT behaviour +---------------------------------------- + +Above user ioctls modify image geometry as follows: + +VIDIOC_S_CROP: sets location and sizes of the sensor window. Unit is one sensor +pixel. Changing sensor window sizes preserves any scaling factors, therefore +user window sizes change as well. + +VIDIOC_S_FMT: sets user window. Should preserve previously set sensor window as +much as possible by modifying scaling factors. If the sensor window cannot be +preserved precisely, it may be changed too. + +In soc-camera there are two locations, where scaling and cropping can take +place: in the camera driver and in the host driver. User ioctls are first passed +to the host driver, which then generally passes them down to the camera driver. +It is more efficient to perform scaling and cropping in the camera driver to +save camera bus bandwidth and maximise the framerate. However, if the camera +driver failed to set the required parameters with sufficient precision, the host +driver may decide to also use its own scaling and cropping to fulfill the user's +request. + +Camera drivers are interfaced to the soc-camera core and to host drivers over +the v4l2-subdev API, which is completely functional, it doesn't pass any data. +Therefore all camera drivers shall reply to .g_fmt() requests with their current +output geometry. This is necessary to correctly configure the camera bus. +.s_fmt() and .try_fmt() have to be implemented too. Sensor window and scaling +factors have to be maintained by camera drivers internally. According to the +V4L2 API all capture drivers must support the VIDIOC_CROPCAP ioctl, hence we +rely on camera drivers implementing .cropcap(). If the camera driver does not +support cropping, it may choose to not implement .s_crop(), but to enable +cropping support by the camera host driver at least the .g_crop method must be +implemented. + +User window geometry is kept in .user_width and .user_height fields in struct +soc_camera_device and used by the soc-camera core and host drivers. The core +updates these fields upon successful completion of a .s_fmt() call, but if these +fields change elsewhere, e.g. during .s_crop() processing, the host driver is +responsible for updating them. + +Format conversion +----------------- + +V4L2 distinguishes between pixel formats, as they are stored in memory, and as +they are transferred over a media bus. Soc-camera provides support to +conveniently manage these formats. A table of standard transformations is +maintained by soc-camera core, which describes, what FOURCC pixel format will +be obtained, if a media-bus pixel format is stored in memory according to +certain rules. E.g. if MEDIA_BUS_FMT_YUYV8_2X8 data is sampled with 8 bits per +sample and stored in memory in the little-endian order with no gaps between +bytes, data in memory will represent the V4L2_PIX_FMT_YUYV FOURCC format. These +standard transformations will be used by soc-camera or by camera host drivers to +configure camera drivers to produce the FOURCC format, requested by the user, +using the VIDIOC_S_FMT ioctl(). Apart from those standard format conversions, +host drivers can also provide their own conversion rules by implementing a +.get_formats and, if required, a .put_formats methods. -- cgit v1.2.3 From 64a881836a91304cc1ff8d108b12366609a27510 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 4 Mar 2020 16:15:25 +0100 Subject: media: docs: split cpia2.rst on two files In order to be able to better organize the subsystem, split the cpia2 information on two files: one user-facing and another one from Kernel development PoV. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/v4l-drivers/cpia2.rst | 46 -------------------- Documentation/media/v4l-drivers/cpia2_devel.rst | 56 +++++++++++++++++++++++++ Documentation/media/v4l-drivers/index.rst | 2 + 3 files changed, 58 insertions(+), 46 deletions(-) create mode 100644 Documentation/media/v4l-drivers/cpia2_devel.rst (limited to 'Documentation') diff --git a/Documentation/media/v4l-drivers/cpia2.rst b/Documentation/media/v4l-drivers/cpia2.rst index a86baa1c83f1..6f4258aebbfe 100644 --- a/Documentation/media/v4l-drivers/cpia2.rst +++ b/Documentation/media/v4l-drivers/cpia2.rst @@ -147,49 +147,3 @@ We are providing a modified gqcam application to view the output. In order to avoid confusion, here it is called mview. There is also the qx5view program which can also control the lights on the qx5 microscope. MJPEG Tools (http://mjpeg.sourceforge.net) can also be used to record from the camera. - -Notes to developers -~~~~~~~~~~~~~~~~~~~ - - - This is a driver version stripped of the 2.4 back compatibility - and old MJPEG ioctl API. See cpia2.sf.net for 2.4 support. - -Programmer's overview of cpia2 driver -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Cpia2 is the second generation video coprocessor from VLSI Vision Ltd (now a -division of ST Microelectronics). There are two versions. The first is the -STV0672, which is capable of up to 30 frames per second (fps) in frame sizes -up to CIF, and 15 fps for VGA frames. The STV0676 is an improved version, -which can handle up to 30 fps VGA. Both coprocessors can be attached to two -CMOS sensors - the vvl6410 CIF sensor and the vvl6500 VGA sensor. These will -be referred to as the 410 and the 500 sensors, or the CIF and VGA sensors. - -The two chipsets operate almost identically. The core is an 8051 processor, -running two different versions of firmware. The 672 runs the VP4 video -processor code, the 676 runs VP5. There are a few differences in register -mappings for the two chips. In these cases, the symbols defined in the -header files are marked with VP4 or VP5 as part of the symbol name. - -The cameras appear externally as three sets of registers. Setting register -values is the only way to control the camera. Some settings are -interdependant, such as the sequence required to power up the camera. I will -try to make note of all of these cases. - -The register sets are called blocks. Block 0 is the system block. This -section is always powered on when the camera is plugged in. It contains -registers that control housekeeping functions such as powering up the video -processor. The video processor is the VP block. These registers control -how the video from the sensor is processed. Examples are timing registers, -user mode (vga, qvga), scaling, cropping, framerates, and so on. The last -block is the video compressor (VC). The video stream sent from the camera is -compressed as Motion JPEG (JPEGA). The VC controls all of the compression -parameters. Looking at the file cpia2_registers.h, you can get a full view -of these registers and the possible values for most of them. - -One or more registers can be set or read by sending a usb control message to -the camera. There are three modes for this. Block mode requests a number -of contiguous registers. Random mode reads or writes random registers with -a tuple structure containing address/value pairs. The repeat mode is only -used by VP4 to load a firmware patch. It contains a starting address and -a sequence of bytes to be written into a gpio port. diff --git a/Documentation/media/v4l-drivers/cpia2_devel.rst b/Documentation/media/v4l-drivers/cpia2_devel.rst new file mode 100644 index 000000000000..decaa4768c78 --- /dev/null +++ b/Documentation/media/v4l-drivers/cpia2_devel.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GPL-2.0 + +The cpia2 driver +================ + +Authors: Peter Pregler , +Scott J. Bertin , and +Jarl Totland for the original cpia driver, which +this one was modelled from. + + +Notes to developers +~~~~~~~~~~~~~~~~~~~ + + - This is a driver version stripped of the 2.4 back compatibility + and old MJPEG ioctl API. See cpia2.sf.net for 2.4 support. + +Programmer's overview of cpia2 driver +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Cpia2 is the second generation video coprocessor from VLSI Vision Ltd (now a +division of ST Microelectronics). There are two versions. The first is the +STV0672, which is capable of up to 30 frames per second (fps) in frame sizes +up to CIF, and 15 fps for VGA frames. The STV0676 is an improved version, +which can handle up to 30 fps VGA. Both coprocessors can be attached to two +CMOS sensors - the vvl6410 CIF sensor and the vvl6500 VGA sensor. These will +be referred to as the 410 and the 500 sensors, or the CIF and VGA sensors. + +The two chipsets operate almost identically. The core is an 8051 processor, +running two different versions of firmware. The 672 runs the VP4 video +processor code, the 676 runs VP5. There are a few differences in register +mappings for the two chips. In these cases, the symbols defined in the +header files are marked with VP4 or VP5 as part of the symbol name. + +The cameras appear externally as three sets of registers. Setting register +values is the only way to control the camera. Some settings are +interdependant, such as the sequence required to power up the camera. I will +try to make note of all of these cases. + +The register sets are called blocks. Block 0 is the system block. This +section is always powered on when the camera is plugged in. It contains +registers that control housekeeping functions such as powering up the video +processor. The video processor is the VP block. These registers control +how the video from the sensor is processed. Examples are timing registers, +user mode (vga, qvga), scaling, cropping, framerates, and so on. The last +block is the video compressor (VC). The video stream sent from the camera is +compressed as Motion JPEG (JPEGA). The VC controls all of the compression +parameters. Looking at the file cpia2_registers.h, you can get a full view +of these registers and the possible values for most of them. + +One or more registers can be set or read by sending a usb control message to +the camera. There are three modes for this. Block mode requests a number +of contiguous registers. Random mode reads or writes random registers with +a tuple structure containing address/value pairs. The repeat mode is only +used by VP4 to load a firmware patch. It contains a starting address and +a sequence of bytes to be written into a gpio port. diff --git a/Documentation/media/v4l-drivers/index.rst b/Documentation/media/v4l-drivers/index.rst index eca22b82de94..72fbb394f6a2 100644 --- a/Documentation/media/v4l-drivers/index.rst +++ b/Documentation/media/v4l-drivers/index.rst @@ -65,3 +65,5 @@ For more details see the file COPYING in the source distribution of Linux. vimc vivid zr364xx + + cpia2_devel -- cgit v1.2.3 From f40b814a3d5ad5275580bba3d005e442d7e3f361 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 4 Mar 2020 14:31:12 +0100 Subject: media: docs: split ci.rst into uAPI and user guide docs The ci.rst file contains two parts: the first one describing how to use the CA high level interface; the second one with uAPI internals. Split this on two separate files, adding the uAPI bits to the DVB ca.rst configuration. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/dvb-drivers/ci.rst | 160 +------------------------ Documentation/media/uapi/dvb/ca.rst | 1 + Documentation/media/uapi/dvb/ca_high_level.rst | 157 ++++++++++++++++++++++++ 3 files changed, 161 insertions(+), 157 deletions(-) create mode 100644 Documentation/media/uapi/dvb/ca_high_level.rst (limited to 'Documentation') diff --git a/Documentation/media/dvb-drivers/ci.rst b/Documentation/media/dvb-drivers/ci.rst index 35f33f1f9e2a..ded4d8fbbf92 100644 --- a/Documentation/media/dvb-drivers/ci.rst +++ b/Documentation/media/dvb-drivers/ci.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0 -Digital TV Conditional Access Interface (CI API) -================================================ +Digital TV Conditional Access Interface +======================================= .. note:: @@ -15,7 +15,7 @@ existing low level CI API. .. note:: For the Twinhan/Twinhan clones, the dst_ca module handles the CI - hardware handling.This module is loaded automatically if a CI + hardware handling. This module is loaded automatically if a CI (Common Interface, that holds the CAM (Conditional Access Module) is detected. @@ -75,157 +75,3 @@ Modules that have been tested by this driver at present are (1) Irdeto 1 and 2 from SCM (2) Viaccess from SCM (3) Dragoncam - -The High level CI API -~~~~~~~~~~~~~~~~~~~~~ - -For the programmer -^^^^^^^^^^^^^^^^^^ - -With the High Level CI approach any new card with almost any random -architecture can be implemented with this style, the definitions -inside the switch statement can be easily adapted for any card, thereby -eliminating the need for any additional ioctls. - -The disadvantage is that the driver/hardware has to manage the rest. For -the application programmer it would be as simple as sending/receiving an -array to/from the CI ioctls as defined in the Linux DVB API. No changes -have been made in the API to accommodate this feature. - - -Why the need for another CI interface? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This is one of the most commonly asked question. Well a nice question. -Strictly speaking this is not a new interface. - -The CI interface is defined in the DVB API in ca.h as: - -.. code-block:: c - - typedef struct ca_slot_info { - int num; /* slot number */ - - int type; /* CA interface this slot supports */ - #define CA_CI 1 /* CI high level interface */ - #define CA_CI_LINK 2 /* CI link layer level interface */ - #define CA_CI_PHYS 4 /* CI physical layer level interface */ - #define CA_DESCR 8 /* built-in descrambler */ - #define CA_SC 128 /* simple smart card interface */ - - unsigned int flags; - #define CA_CI_MODULE_PRESENT 1 /* module (or card) inserted */ - #define CA_CI_MODULE_READY 2 - } ca_slot_info_t; - -This CI interface follows the CI high level interface, which is not -implemented by most applications. Hence this area is revisited. - -This CI interface is quite different in the case that it tries to -accommodate all other CI based devices, that fall into the other categories. - -This means that this CI interface handles the EN50221 style tags in the -Application layer only and no session management is taken care of by the -application. The driver/hardware will take care of all that. - -This interface is purely an EN50221 interface exchanging APDU's. This -means that no session management, link layer or a transport layer do -exist in this case in the application to driver communication. It is -as simple as that. The driver/hardware has to take care of that. - -With this High Level CI interface, the interface can be defined with the -regular ioctls. - -All these ioctls are also valid for the High level CI interface - -#define CA_RESET _IO('o', 128) -#define CA_GET_CAP _IOR('o', 129, ca_caps_t) -#define CA_GET_SLOT_INFO _IOR('o', 130, ca_slot_info_t) -#define CA_GET_DESCR_INFO _IOR('o', 131, ca_descr_info_t) -#define CA_GET_MSG _IOR('o', 132, ca_msg_t) -#define CA_SEND_MSG _IOW('o', 133, ca_msg_t) -#define CA_SET_DESCR _IOW('o', 134, ca_descr_t) - - -On querying the device, the device yields information thus: - -.. code-block:: none - - CA_GET_SLOT_INFO - ---------------------------- - Command = [info] - APP: Number=[1] - APP: Type=[1] - APP: flags=[1] - APP: CI High level interface - APP: CA/CI Module Present - - CA_GET_CAP - ---------------------------- - Command = [caps] - APP: Slots=[1] - APP: Type=[1] - APP: Descrambler keys=[16] - APP: Type=[1] - - CA_SEND_MSG - ---------------------------- - Descriptors(Program Level)=[ 09 06 06 04 05 50 ff f1] - Found CA descriptor @ program level - - (20) ES type=[2] ES pid=[201] ES length =[0 (0x0)] - (25) ES type=[4] ES pid=[301] ES length =[0 (0x0)] - ca_message length is 25 (0x19) bytes - EN50221 CA MSG=[ 9f 80 32 19 03 01 2d d1 f0 08 01 09 06 06 04 05 50 ff f1 02 e0 c9 00 00 04 e1 2d 00 00] - - -Not all ioctl's are implemented in the driver from the API, the other -features of the hardware that cannot be implemented by the API are achieved -using the CA_GET_MSG and CA_SEND_MSG ioctls. An EN50221 style wrapper is -used to exchange the data to maintain compatibility with other hardware. - -.. code-block:: c - - /* a message to/from a CI-CAM */ - typedef struct ca_msg { - unsigned int index; - unsigned int type; - unsigned int length; - unsigned char msg[256]; - } ca_msg_t; - - -The flow of data can be described thus, - -.. code-block:: none - - App (User) - ----- - parse - | - | - v - en50221 APDU (package) - -------------------------------------- - | | | High Level CI driver - | | | - | v | - | en50221 APDU (unpackage) | - | | | - | | | - | v | - | sanity checks | - | | | - | | | - | v | - | do (H/W dep) | - -------------------------------------- - | Hardware - | - v - - - - -The High Level CI interface uses the EN50221 DVB standard, following a -standard ensures futureproofness. diff --git a/Documentation/media/uapi/dvb/ca.rst b/Documentation/media/uapi/dvb/ca.rst index 8796512c1378..c6ee624b1234 100644 --- a/Documentation/media/uapi/dvb/ca.rst +++ b/Documentation/media/uapi/dvb/ca.rst @@ -29,3 +29,4 @@ application. ca_data_types ca_function_calls + ca_high_level diff --git a/Documentation/media/uapi/dvb/ca_high_level.rst b/Documentation/media/uapi/dvb/ca_high_level.rst new file mode 100644 index 000000000000..a73f3691c31f --- /dev/null +++ b/Documentation/media/uapi/dvb/ca_high_level.rst @@ -0,0 +1,157 @@ +.. SPDX-License-Identifier: GPL-2.0 + +The High level CI API +===================== + +.. note:: + + This documentation is outdated. + +This document describes the high level CI API as in accordance to the +Linux DVB API. + + +With the High Level CI approach any new card with almost any random +architecture can be implemented with this style, the definitions +inside the switch statement can be easily adapted for any card, thereby +eliminating the need for any additional ioctls. + +The disadvantage is that the driver/hardware has to manage the rest. For +the application programmer it would be as simple as sending/receiving an +array to/from the CI ioctls as defined in the Linux DVB API. No changes +have been made in the API to accommodate this feature. + + +Why the need for another CI interface? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is one of the most commonly asked question. Well a nice question. +Strictly speaking this is not a new interface. + +The CI interface is defined in the DVB API in ca.h as: + +.. code-block:: c + + typedef struct ca_slot_info { + int num; /* slot number */ + + int type; /* CA interface this slot supports */ + #define CA_CI 1 /* CI high level interface */ + #define CA_CI_LINK 2 /* CI link layer level interface */ + #define CA_CI_PHYS 4 /* CI physical layer level interface */ + #define CA_DESCR 8 /* built-in descrambler */ + #define CA_SC 128 /* simple smart card interface */ + + unsigned int flags; + #define CA_CI_MODULE_PRESENT 1 /* module (or card) inserted */ + #define CA_CI_MODULE_READY 2 + } ca_slot_info_t; + +This CI interface follows the CI high level interface, which is not +implemented by most applications. Hence this area is revisited. + +This CI interface is quite different in the case that it tries to +accommodate all other CI based devices, that fall into the other categories. + +This means that this CI interface handles the EN50221 style tags in the +Application layer only and no session management is taken care of by the +application. The driver/hardware will take care of all that. + +This interface is purely an EN50221 interface exchanging APDU's. This +means that no session management, link layer or a transport layer do +exist in this case in the application to driver communication. It is +as simple as that. The driver/hardware has to take care of that. + +With this High Level CI interface, the interface can be defined with the +regular ioctls. + +All these ioctls are also valid for the High level CI interface + +#define CA_RESET _IO('o', 128) +#define CA_GET_CAP _IOR('o', 129, ca_caps_t) +#define CA_GET_SLOT_INFO _IOR('o', 130, ca_slot_info_t) +#define CA_GET_DESCR_INFO _IOR('o', 131, ca_descr_info_t) +#define CA_GET_MSG _IOR('o', 132, ca_msg_t) +#define CA_SEND_MSG _IOW('o', 133, ca_msg_t) +#define CA_SET_DESCR _IOW('o', 134, ca_descr_t) + + +On querying the device, the device yields information thus: + +.. code-block:: none + + CA_GET_SLOT_INFO + ---------------------------- + Command = [info] + APP: Number=[1] + APP: Type=[1] + APP: flags=[1] + APP: CI High level interface + APP: CA/CI Module Present + + CA_GET_CAP + ---------------------------- + Command = [caps] + APP: Slots=[1] + APP: Type=[1] + APP: Descrambler keys=[16] + APP: Type=[1] + + CA_SEND_MSG + ---------------------------- + Descriptors(Program Level)=[ 09 06 06 04 05 50 ff f1] + Found CA descriptor @ program level + + (20) ES type=[2] ES pid=[201] ES length =[0 (0x0)] + (25) ES type=[4] ES pid=[301] ES length =[0 (0x0)] + ca_message length is 25 (0x19) bytes + EN50221 CA MSG=[ 9f 80 32 19 03 01 2d d1 f0 08 01 09 06 06 04 05 50 ff f1 02 e0 c9 00 00 04 e1 2d 00 00] + + +Not all ioctl's are implemented in the driver from the API, the other +features of the hardware that cannot be implemented by the API are achieved +using the CA_GET_MSG and CA_SEND_MSG ioctls. An EN50221 style wrapper is +used to exchange the data to maintain compatibility with other hardware. + +.. code-block:: c + + /* a message to/from a CI-CAM */ + typedef struct ca_msg { + unsigned int index; + unsigned int type; + unsigned int length; + unsigned char msg[256]; + } ca_msg_t; + + +The flow of data can be described thus, + +.. code-block:: none + + App (User) + ----- + parse + | + | + v + en50221 APDU (package) + -------------------------------------- + | | | High Level CI driver + | | | + | v | + | en50221 APDU (unpackage) | + | | | + | | | + | v | + | sanity checks | + | | | + | | | + | v | + | do (H/W dep) | + -------------------------------------- + | Hardware + | + v + +The High Level CI interface uses the EN50221 DVB standard, following a +standard ensures futureproofness. -- cgit v1.2.3 From a6c5ac5ca76041b1f86e24a799fd0505aa0dd9b1 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 4 Mar 2020 16:24:52 +0100 Subject: media: docs: split meye.rst into admin and uAPI docs Instead of placing both info from admin PoV and uAPI at the same place, split into two separate documents. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/v4l-drivers/index.rst | 1 + Documentation/media/v4l-drivers/meye-uapi.rst | 53 +++++++++++++++++++++++++++ Documentation/media/v4l-drivers/meye.rst | 41 --------------------- 3 files changed, 54 insertions(+), 41 deletions(-) create mode 100644 Documentation/media/v4l-drivers/meye-uapi.rst (limited to 'Documentation') diff --git a/Documentation/media/v4l-drivers/index.rst b/Documentation/media/v4l-drivers/index.rst index 72fbb394f6a2..5a87bd1da9bd 100644 --- a/Documentation/media/v4l-drivers/index.rst +++ b/Documentation/media/v4l-drivers/index.rst @@ -67,3 +67,4 @@ For more details see the file COPYING in the source distribution of Linux. zr364xx cpia2_devel + meye-uapi diff --git a/Documentation/media/v4l-drivers/meye-uapi.rst b/Documentation/media/v4l-drivers/meye-uapi.rst new file mode 100644 index 000000000000..66b1c142f920 --- /dev/null +++ b/Documentation/media/v4l-drivers/meye-uapi.rst @@ -0,0 +1,53 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: + +Vaio Picturebook Motion Eye Camera Driver +========================================= + +Copyright |copy| 2001-2004 Stelian Pop + +Copyright |copy| 2001-2002 Alcôve + +Copyright |copy| 2000 Andrew Tridgell + +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/meye.rst b/Documentation/media/v4l-drivers/meye.rst index dc57a6a91b43..9098a1e65f8b 100644 --- a/Documentation/media/v4l-drivers/meye.rst +++ b/Documentation/media/v4l-drivers/meye.rst @@ -87,47 +87,6 @@ Usage: motioneye () for getting ppm or jpg snapshots, mjpeg video -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. - Bugs / Todo ----------- -- cgit v1.2.3 From 8d562a0038da9977b6c2b83c2f1be499734f1253 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 4 Mar 2020 17:10:12 +0100 Subject: media: docs: split vimc.rst into devel and admin parts The vimc driver has some kerneldoc markups, plus admin info. Split it into two files. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/v4l-drivers/index.rst | 2 ++ Documentation/media/v4l-drivers/vimc-devel.rst | 15 +++++++++++++++ Documentation/media/v4l-drivers/vimc.rst | 11 ----------- 3 files changed, 17 insertions(+), 11 deletions(-) create mode 100644 Documentation/media/v4l-drivers/vimc-devel.rst (limited to 'Documentation') diff --git a/Documentation/media/v4l-drivers/index.rst b/Documentation/media/v4l-drivers/index.rst index 5a87bd1da9bd..2b8e2cbfff23 100644 --- a/Documentation/media/v4l-drivers/index.rst +++ b/Documentation/media/v4l-drivers/index.rst @@ -67,4 +67,6 @@ For more details see the file COPYING in the source distribution of Linux. zr364xx cpia2_devel + vimc-devel + meye-uapi diff --git a/Documentation/media/v4l-drivers/vimc-devel.rst b/Documentation/media/v4l-drivers/vimc-devel.rst new file mode 100644 index 000000000000..b2aa2ee79205 --- /dev/null +++ b/Documentation/media/v4l-drivers/vimc-devel.rst @@ -0,0 +1,15 @@ +.. SPDX-License-Identifier: GPL-2.0 + +The Virtual Media Controller Driver (vimc) +========================================== + +Source code documentation +------------------------- + +vimc-streamer +~~~~~~~~~~~~~ + +.. kernel-doc:: drivers/media/platform/vimc/vimc-streamer.h + :internal: + +.. kernel-doc:: drivers/media/platform/vimc/vimc-streamer.c diff --git a/Documentation/media/v4l-drivers/vimc.rst b/Documentation/media/v4l-drivers/vimc.rst index 8f5d7f8d83bb..211cc8972410 100644 --- a/Documentation/media/v4l-drivers/vimc.rst +++ b/Documentation/media/v4l-drivers/vimc.rst @@ -88,14 +88,3 @@ Vimc has a module parameter to configure the driver. height, so the image size will be ``sca_mult^2`` bigger than the original one. Currently, only supports scaling up (the default value is 3). - -Source code documentation -------------------------- - -vimc-streamer -~~~~~~~~~~~~~ - -.. kernel-doc:: drivers/media/platform/vimc/vimc-streamer.h - :internal: - -.. kernel-doc:: drivers/media/platform/vimc/vimc-streamer.c -- cgit v1.2.3 From 481025598f214eea371a2aa9cf2464ed786b7555 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 5 Mar 2020 07:24:17 +0100 Subject: media: docs: split development info from bttv.rst This file contains both admin and development stuff. Split on two, as they're usually read by different audiences. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/v4l-drivers/bttv-devel.rst | 123 +++++++++++++++++++++++++ Documentation/media/v4l-drivers/bttv.rst | 120 ------------------------ Documentation/media/v4l-drivers/index.rst | 1 + 3 files changed, 124 insertions(+), 120 deletions(-) create mode 100644 Documentation/media/v4l-drivers/bttv-devel.rst (limited to 'Documentation') diff --git a/Documentation/media/v4l-drivers/bttv-devel.rst b/Documentation/media/v4l-drivers/bttv-devel.rst new file mode 100644 index 000000000000..396fad572c93 --- /dev/null +++ b/Documentation/media/v4l-drivers/bttv-devel.rst @@ -0,0 +1,123 @@ +.. SPDX-License-Identifier: GPL-2.0 + +The bttv driver +=============== + +bttv and sound mini howto +------------------------- + +There are a lot of different bt848/849/878/879 based boards available. +Making video work often is not a big deal, because this is handled +completely by the bt8xx chip, which is common on all boards. But +sound is handled in slightly different ways on each board. + +To handle the grabber boards correctly, there is a array tvcards[] in +bttv-cards.c, which holds the information required for each board. +Sound will work only, if the correct entry is used (for video it often +makes no difference). The bttv driver prints a line to the kernel +log, telling which card type is used. Like this one: + +.. code-block:: none + + bttv0: model: BT848(Hauppauge old) [autodetected] + +You should verify this is correct. If it isn't, you have to pass the +correct board type as insmod argument, "insmod bttv card=2" for +example. The file CARDLIST has a list of valid arguments for card. +If your card isn't listed there, you might check the source code for +new entries which are not listed yet. If there isn't one for your +card, you can check if one of the existing entries does work for you +(just trial and error...). + +Some boards have an extra processor for sound to do stereo decoding +and other nice features. The msp34xx chips are used by Hauppauge for +example. If your board has one, you might have to load a helper +module like msp3400.o to make sound work. If there isn't one for the +chip used on your board: Bad luck. Start writing a new one. Well, +you might want to check the video4linux mailing list archive first... + +Of course you need a correctly installed soundcard unless you have the +speakers connected directly to the grabber board. Hint: check the +mixer settings too. ALSA for example has everything muted by default. + + +How sound works in detail +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Still doesn't work? Looks like some driver hacking is required. +Below is a do-it-yourself description for you. + +The bt8xx chips have 32 general purpose pins, and registers to control +these pins. One register is the output enable register +(BT848_GPIO_OUT_EN), it says which pins are actively driven by the +bt848 chip. Another one is the data register (BT848_GPIO_DATA), where +you can get/set the status if these pins. They can be used for input +and output. + +Most grabber board vendors use these pins to control an external chip +which does the sound routing. But every board is a little different. +These pins are also used by some companies to drive remote control +receiver chips. Some boards use the i2c bus instead of the gpio pins +to connect the mux chip. + +As mentioned above, there is a array which holds the required +information for each known board. You basically have to create a new +line for your board. The important fields are these two: + +.. code-block:: c + + struct tvcard + { + [ ... ] + u32 gpiomask; + u32 audiomux[6]; /* Tuner, Radio, external, internal, mute, stereo */ + }; + +gpiomask specifies which pins are used to control the audio mux chip. +The corresponding bits in the output enable register +(BT848_GPIO_OUT_EN) will be set as these pins must be driven by the +bt848 chip. + +The audiomux\[\] array holds the data values for the different inputs +(i.e. which pins must be high/low for tuner/mute/...). This will be +written to the data register (BT848_GPIO_DATA) to switch the audio +mux. + + +What you have to do is figure out the correct values for gpiomask and +the audiomux array. If you have Windows and the drivers four your +card installed, you might to check out if you can read these registers +values used by the windows driver. A tool to do this is available +from ftp://telepresence.dmem.strath.ac.uk/pub/bt848/winutil, but it +doesn't work with bt878 boards according to some reports I received. +Another one with bt878 support is available from +http://btwincap.sourceforge.net/Files/btspy2.00.zip + +You might also dig around in the \*.ini files of the Windows applications. +You can have a look at the board to see which of the gpio pins are +connected at all and then start trial-and-error ... + + +Starting with release 0.7.41 bttv has a number of insmod options to +make the gpio debugging easier: + +.. code-block:: none + + bttv_gpio=0/1 enable/disable gpio debug messages + gpiomask=n set the gpiomask value + audiomux=i,j,... set the values of the audiomux array + audioall=a set the values of the audiomux array (one + value for all array elements, useful to check + out which effect the particular value has). + +The messages printed with bttv_gpio=1 look like this: + +.. code-block:: none + + bttv0: gpio: en=00000027, out=00000024 in=00ffffd8 [audio: off] + + en = output _en_able register (BT848_GPIO_OUT_EN) + out = _out_put bits of the data register (BT848_GPIO_DATA), + i.e. BT848_GPIO_DATA & BT848_GPIO_OUT_EN + in = _in_put bits of the data register, + i.e. BT848_GPIO_DATA & ~BT848_GPIO_OUT_EN diff --git a/Documentation/media/v4l-drivers/bttv.rst b/Documentation/media/v4l-drivers/bttv.rst index f956ee264099..9b15a0cba283 100644 --- a/Documentation/media/v4l-drivers/bttv.rst +++ b/Documentation/media/v4l-drivers/bttv.rst @@ -438,126 +438,6 @@ parking, thus lowering arbitration performance. The Bt879 drivers must query for these non-compliant devices, and set the EN_VSFX bit only if required. -bttv and sound mini howto -------------------------- - -There are a lot of different bt848/849/878/879 based boards available. -Making video work often is not a big deal, because this is handled -completely by the bt8xx chip, which is common on all boards. But -sound is handled in slightly different ways on each board. - -To handle the grabber boards correctly, there is a array tvcards[] in -bttv-cards.c, which holds the information required for each board. -Sound will work only, if the correct entry is used (for video it often -makes no difference). The bttv driver prints a line to the kernel -log, telling which card type is used. Like this one: - -.. code-block:: none - - bttv0: model: BT848(Hauppauge old) [autodetected] - -You should verify this is correct. If it isn't, you have to pass the -correct board type as insmod argument, "insmod bttv card=2" for -example. The file CARDLIST has a list of valid arguments for card. -If your card isn't listed there, you might check the source code for -new entries which are not listed yet. If there isn't one for your -card, you can check if one of the existing entries does work for you -(just trial and error...). - -Some boards have an extra processor for sound to do stereo decoding -and other nice features. The msp34xx chips are used by Hauppauge for -example. If your board has one, you might have to load a helper -module like msp3400.o to make sound work. If there isn't one for the -chip used on your board: Bad luck. Start writing a new one. Well, -you might want to check the video4linux mailing list archive first... - -Of course you need a correctly installed soundcard unless you have the -speakers connected directly to the grabber board. Hint: check the -mixer settings too. ALSA for example has everything muted by default. - - -How sound works in detail -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Still doesn't work? Looks like some driver hacking is required. -Below is a do-it-yourself description for you. - -The bt8xx chips have 32 general purpose pins, and registers to control -these pins. One register is the output enable register -(BT848_GPIO_OUT_EN), it says which pins are actively driven by the -bt848 chip. Another one is the data register (BT848_GPIO_DATA), where -you can get/set the status if these pins. They can be used for input -and output. - -Most grabber board vendors use these pins to control an external chip -which does the sound routing. But every board is a little different. -These pins are also used by some companies to drive remote control -receiver chips. Some boards use the i2c bus instead of the gpio pins -to connect the mux chip. - -As mentioned above, there is a array which holds the required -information for each known board. You basically have to create a new -line for your board. The important fields are these two: - -.. code-block:: c - - struct tvcard - { - [ ... ] - u32 gpiomask; - u32 audiomux[6]; /* Tuner, Radio, external, internal, mute, stereo */ - }; - -gpiomask specifies which pins are used to control the audio mux chip. -The corresponding bits in the output enable register -(BT848_GPIO_OUT_EN) will be set as these pins must be driven by the -bt848 chip. - -The audiomux\[\] array holds the data values for the different inputs -(i.e. which pins must be high/low for tuner/mute/...). This will be -written to the data register (BT848_GPIO_DATA) to switch the audio -mux. - - -What you have to do is figure out the correct values for gpiomask and -the audiomux array. If you have Windows and the drivers four your -card installed, you might to check out if you can read these registers -values used by the windows driver. A tool to do this is available -from ftp://telepresence.dmem.strath.ac.uk/pub/bt848/winutil, but it -doesn't work with bt878 boards according to some reports I received. -Another one with bt878 support is available from -http://btwincap.sourceforge.net/Files/btspy2.00.zip - -You might also dig around in the \*.ini files of the Windows applications. -You can have a look at the board to see which of the gpio pins are -connected at all and then start trial-and-error ... - - -Starting with release 0.7.41 bttv has a number of insmod options to -make the gpio debugging easier: - -.. code-block:: none - - bttv_gpio=0/1 enable/disable gpio debug messages - gpiomask=n set the gpiomask value - audiomux=i,j,... set the values of the audiomux array - audioall=a set the values of the audiomux array (one - value for all array elements, useful to check - out which effect the particular value has). - -The messages printed with bttv_gpio=1 look like this: - -.. code-block:: none - - bttv0: gpio: en=00000027, out=00000024 in=00ffffd8 [audio: off] - - en = output _en_able register (BT848_GPIO_OUT_EN) - out = _out_put bits of the data register (BT848_GPIO_DATA), - i.e. BT848_GPIO_DATA & BT848_GPIO_OUT_EN - in = _in_put bits of the data register, - i.e. BT848_GPIO_DATA & ~BT848_GPIO_OUT_EN - - Other elements of the tvcards array ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/media/v4l-drivers/index.rst b/Documentation/media/v4l-drivers/index.rst index 2b8e2cbfff23..52d7c8d14ee7 100644 --- a/Documentation/media/v4l-drivers/index.rst +++ b/Documentation/media/v4l-drivers/index.rst @@ -66,6 +66,7 @@ For more details see the file COPYING in the source distribution of Linux. vivid zr364xx + bttv-devel cpia2_devel vimc-devel -- cgit v1.2.3 From 51df01acc193084430543db71c69f19827191752 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 5 Mar 2020 07:25:55 +0100 Subject: media: docs: split development info from cx88.rst This file contains both admin and development stuff. Split on two, as they're usually read by different audiences. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/v4l-drivers/cx88-devel.rst | 113 +++++++++++++++++++++++++ Documentation/media/v4l-drivers/cx88.rst | 107 ----------------------- Documentation/media/v4l-drivers/index.rst | 1 + 3 files changed, 114 insertions(+), 107 deletions(-) create mode 100644 Documentation/media/v4l-drivers/cx88-devel.rst (limited to 'Documentation') diff --git a/Documentation/media/v4l-drivers/cx88-devel.rst b/Documentation/media/v4l-drivers/cx88-devel.rst new file mode 100644 index 000000000000..cfe7c03f4930 --- /dev/null +++ b/Documentation/media/v4l-drivers/cx88-devel.rst @@ -0,0 +1,113 @@ +.. SPDX-License-Identifier: GPL-2.0 + +The cx88 driver +=============== + +Author: Gerd Hoffmann + +Documentation missing at the cx88 datasheet +------------------------------------------- + +MO_OUTPUT_FORMAT (0x310164) + +.. code-block:: none + + Previous default from DScaler: 0x1c1f0008 + Digit 8: 31-28 + 28: PREVREMOD = 1 + + Digit 7: 27-24 (0xc = 12 = b1100 ) + 27: COMBALT = 1 + 26: PAL_INV_PHASE + (DScaler apparently set this to 1, resulted in sucky picture) + + Digits 6,5: 23-16 + 25-16: COMB_RANGE = 0x1f [default] (9 bits -> max 512) + + Digit 4: 15-12 + 15: DISIFX = 0 + 14: INVCBF = 0 + 13: DISADAPT = 0 + 12: NARROWADAPT = 0 + + Digit 3: 11-8 + 11: FORCE2H + 10: FORCEREMD + 9: NCHROMAEN + 8: NREMODEN + + Digit 2: 7-4 + 7-6: YCORE + 5-4: CCORE + + Digit 1: 3-0 + 3: RANGE = 1 + 2: HACTEXT + 1: HSFMT + +0x47 is the sync byte for MPEG-2 transport stream packets. +Datasheet incorrectly states to use 47 decimal. 188 is the length. +All DVB compliant frontends output packets with this start code. + +Hauppauge WinTV cx88 IR information +----------------------------------- + +The controls for the mux are GPIO [0,1] for source, and GPIO 2 for muting. + +====== ======== ================================================= +GPIO0 GPIO1 +====== ======== ================================================= + 0 0 TV Audio + 1 0 FM radio + 0 1 Line-In + 1 1 Mono tuner bypass or CD passthru (tuner specific) +====== ======== ================================================= + +GPIO 16(I believe) is tied to the IR port (if present). + + +From the data sheet: + +- Register 24'h20004 PCI Interrupt Status + + - bit [18] IR_SMP_INT Set when 32 input samples have been collected over + - gpio[16] pin into GP_SAMPLE register. + +What's missing from the data sheet: + +- Setup 4KHz sampling rate (roughly 2x oversampled; good enough for our RC5 + compat remote) +- set register 0x35C050 to 0xa80a80 +- enable sampling +- set register 0x35C054 to 0x5 +- enable the IRQ bit 18 in the interrupt mask register (and + provide for a handler) + +GP_SAMPLE register is at 0x35C058 + +Bits are then right shifted into the GP_SAMPLE register at the specified +rate; you get an interrupt when a full DWORD is received. +You need to recover the actual RC5 bits out of the (oversampled) IR sensor +bits. (Hint: look for the 0/1and 1/0 crossings of the RC5 bi-phase data) An +actual raw RC5 code will span 2-3 DWORDS, depending on the actual alignment. + +I'm pretty sure when no IR signal is present the receiver is always in a +marking state(1); but stray light, etc can cause intermittent noise values +as well. Remember, this is a free running sample of the IR receiver state +over time, so don't assume any sample starts at any particular place. + +Additional info +~~~~~~~~~~~~~~~ + +This data sheet (google search) seems to have a lovely description of the +RC5 basics: +http://www.atmel.com/dyn/resources/prod_documents/doc2817.pdf + +This document has more data: +http://www.nenya.be/beor/electronics/rc5.htm + +This document has a how to decode a bi-phase data stream: +http://www.ee.washington.edu/circuit_archive/text/ir_decode.txt + +This document has still more info: +http://www.xs4all.nl/~sbp/knowledge/ir/rc5.htm diff --git a/Documentation/media/v4l-drivers/cx88.rst b/Documentation/media/v4l-drivers/cx88.rst index 698c73ea2e36..e4badb18199d 100644 --- a/Documentation/media/v4l-drivers/cx88.rst +++ b/Documentation/media/v4l-drivers/cx88.rst @@ -56,110 +56,3 @@ the driver. What to do then? trial-and-error using the tuner= insmod option. If you know which one the card has you can also have a look at the list in CARDLIST.tuner - -Documentation missing at the cx88 datasheet -------------------------------------------- - -MO_OUTPUT_FORMAT (0x310164) - -.. code-block:: none - - Previous default from DScaler: 0x1c1f0008 - Digit 8: 31-28 - 28: PREVREMOD = 1 - - Digit 7: 27-24 (0xc = 12 = b1100 ) - 27: COMBALT = 1 - 26: PAL_INV_PHASE - (DScaler apparently set this to 1, resulted in sucky picture) - - Digits 6,5: 23-16 - 25-16: COMB_RANGE = 0x1f [default] (9 bits -> max 512) - - Digit 4: 15-12 - 15: DISIFX = 0 - 14: INVCBF = 0 - 13: DISADAPT = 0 - 12: NARROWADAPT = 0 - - Digit 3: 11-8 - 11: FORCE2H - 10: FORCEREMD - 9: NCHROMAEN - 8: NREMODEN - - Digit 2: 7-4 - 7-6: YCORE - 5-4: CCORE - - Digit 1: 3-0 - 3: RANGE = 1 - 2: HACTEXT - 1: HSFMT - -0x47 is the sync byte for MPEG-2 transport stream packets. -Datasheet incorrectly states to use 47 decimal. 188 is the length. -All DVB compliant frontends output packets with this start code. - -Hauppauge WinTV cx88 IR information ------------------------------------ - -The controls for the mux are GPIO [0,1] for source, and GPIO 2 for muting. - -====== ======== ================================================= -GPIO0 GPIO1 -====== ======== ================================================= - 0 0 TV Audio - 1 0 FM radio - 0 1 Line-In - 1 1 Mono tuner bypass or CD passthru (tuner specific) -====== ======== ================================================= - -GPIO 16(I believe) is tied to the IR port (if present). - - -From the data sheet: - -- Register 24'h20004 PCI Interrupt Status - - - bit [18] IR_SMP_INT Set when 32 input samples have been collected over - - gpio[16] pin into GP_SAMPLE register. - -What's missing from the data sheet: - -- Setup 4KHz sampling rate (roughly 2x oversampled; good enough for our RC5 - compat remote) -- set register 0x35C050 to 0xa80a80 -- enable sampling -- set register 0x35C054 to 0x5 -- enable the IRQ bit 18 in the interrupt mask register (and - provide for a handler) - -GP_SAMPLE register is at 0x35C058 - -Bits are then right shifted into the GP_SAMPLE register at the specified -rate; you get an interrupt when a full DWORD is received. -You need to recover the actual RC5 bits out of the (oversampled) IR sensor -bits. (Hint: look for the 0/1and 1/0 crossings of the RC5 bi-phase data) An -actual raw RC5 code will span 2-3 DWORDS, depending on the actual alignment. - -I'm pretty sure when no IR signal is present the receiver is always in a -marking state(1); but stray light, etc can cause intermittent noise values -as well. Remember, this is a free running sample of the IR receiver state -over time, so don't assume any sample starts at any particular place. - -Additional info -~~~~~~~~~~~~~~~ - -This data sheet (google search) seems to have a lovely description of the -RC5 basics: -http://www.atmel.com/dyn/resources/prod_documents/doc2817.pdf - -This document has more data: -http://www.nenya.be/beor/electronics/rc5.htm - -This document has a how to decode a bi-phase data stream: -http://www.ee.washington.edu/circuit_archive/text/ir_decode.txt - -This document has still more info: -http://www.xs4all.nl/~sbp/knowledge/ir/rc5.htm diff --git a/Documentation/media/v4l-drivers/index.rst b/Documentation/media/v4l-drivers/index.rst index 52d7c8d14ee7..dfc878c050da 100644 --- a/Documentation/media/v4l-drivers/index.rst +++ b/Documentation/media/v4l-drivers/index.rst @@ -68,6 +68,7 @@ For more details see the file COPYING in the source distribution of Linux. bttv-devel cpia2_devel + cx88-devel vimc-devel meye-uapi -- cgit v1.2.3 From aeb9b21ab44953ae183c685ae46f84ff44a96bd4 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 5 Mar 2020 07:30:50 +0100 Subject: media: docs: split cx2341x.rst into different audiences This file contains both driver develompent documentation (basically, firmware documentation) and IVTV-specific documentation about VBI and raw formats, focused on uAPI development. Split on two, as they're usually read by different audiences. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/v4l-drivers/cx2341x-devel.rst | 3685 ++++++++++++++++++++ Documentation/media/v4l-drivers/cx2341x-uapi.rst | 179 + Documentation/media/v4l-drivers/cx2341x.rst | 3860 --------------------- Documentation/media/v4l-drivers/index.rst | 3 +- 4 files changed, 3866 insertions(+), 3861 deletions(-) create mode 100644 Documentation/media/v4l-drivers/cx2341x-devel.rst create mode 100644 Documentation/media/v4l-drivers/cx2341x-uapi.rst delete mode 100644 Documentation/media/v4l-drivers/cx2341x.rst (limited to 'Documentation') diff --git a/Documentation/media/v4l-drivers/cx2341x-devel.rst b/Documentation/media/v4l-drivers/cx2341x-devel.rst new file mode 100644 index 000000000000..97699df6ea2e --- /dev/null +++ b/Documentation/media/v4l-drivers/cx2341x-devel.rst @@ -0,0 +1,3685 @@ +.. SPDX-License-Identifier: GPL-2.0 + +The cx2341x driver +================== + +Memory at cx2341x chips +----------------------- + +This section describes the cx2341x memory map and documents some of the +register space. + +.. note:: the memory long words are little-endian ('intel format'). + +.. warning:: + + This information was figured out from searching through the memory + and registers, this information may not be correct and is certainly + not complete, and was not derived from anything more than searching + through the memory space with commands like: + + .. code-block:: none + + ivtvctl -O min=0x02000000,max=0x020000ff + + So take this as is, I'm always searching for more stuff, it's a large + register space :-). + +Memory Map +~~~~~~~~~~ + +The cx2341x exposes its entire 64M memory space to the PCI host via the PCI BAR0 +(Base Address Register 0). The addresses here are offsets relative to the +address held in BAR0. + +.. code-block:: none + + 0x00000000-0x00ffffff Encoder memory space + 0x00000000-0x0003ffff Encode.rom + ???-??? MPEG buffer(s) + ???-??? Raw video capture buffer(s) + ???-??? Raw audio capture buffer(s) + ???-??? Display buffers (6 or 9) + + 0x01000000-0x01ffffff Decoder memory space + 0x01000000-0x0103ffff Decode.rom + ???-??? MPEG buffers(s) + 0x0114b000-0x0115afff Audio.rom (deprecated?) + + 0x02000000-0x0200ffff Register Space + +Registers +~~~~~~~~~ + +The registers occupy the 64k space starting at the 0x02000000 offset from BAR0. +All of these registers are 32 bits wide. + +.. code-block:: none + + DMA Registers 0x000-0xff: + + 0x00 - Control: + 0=reset/cancel, 1=read, 2=write, 4=stop + 0x04 - DMA status: + 1=read busy, 2=write busy, 4=read error, 8=write error, 16=link list error + 0x08 - pci DMA pointer for read link list + 0x0c - pci DMA pointer for write link list + 0x10 - read/write DMA enable: + 1=read enable, 2=write enable + 0x14 - always 0xffffffff, if set any lower instability occurs, 0x00 crashes + 0x18 - ?? + 0x1c - always 0x20 or 32, smaller values slow down DMA transactions + 0x20 - always value of 0x780a010a + 0x24-0x3c - usually just random values??? + 0x40 - Interrupt status + 0x44 - Write a bit here and shows up in Interrupt status 0x40 + 0x48 - Interrupt Mask + 0x4C - always value of 0xfffdffff, + if changed to 0xffffffff DMA write interrupts break. + 0x50 - always 0xffffffff + 0x54 - always 0xffffffff (0x4c, 0x50, 0x54 seem like interrupt masks, are + 3 processors on chip, Java ones, VPU, SPU, APU, maybe these are the + interrupt masks???). + 0x60-0x7C - random values + 0x80 - first write linked list reg, for Encoder Memory addr + 0x84 - first write linked list reg, for pci memory addr + 0x88 - first write linked list reg, for length of buffer in memory addr + (|0x80000000 or this for last link) + 0x8c-0xdc - rest of write linked list reg, 8 sets of 3 total, DMA goes here + from linked list addr in reg 0x0c, firmware must push through or + something. + 0xe0 - first (and only) read linked list reg, for pci memory addr + 0xe4 - first (and only) read linked list reg, for Decoder memory addr + 0xe8 - first (and only) read linked list reg, for length of buffer + 0xec-0xff - Nothing seems to be in these registers, 0xec-f4 are 0x00000000. + +Memory locations for Encoder Buffers 0x700-0x7ff: + +These registers show offsets of memory locations pertaining to each +buffer area used for encoding, have to shift them by <<1 first. + +- 0x07F8: Encoder SDRAM refresh +- 0x07FC: Encoder SDRAM pre-charge + +Memory locations for Decoder Buffers 0x800-0x8ff: + +These registers show offsets of memory locations pertaining to each +buffer area used for decoding, have to shift them by <<1 first. + +- 0x08F8: Decoder SDRAM refresh +- 0x08FC: Decoder SDRAM pre-charge + +Other memory locations: + +- 0x2800: Video Display Module control +- 0x2D00: AO (audio output?) control +- 0x2D24: Bytes Flushed +- 0x7000: LSB I2C write clock bit (inverted) +- 0x7004: LSB I2C write data bit (inverted) +- 0x7008: LSB I2C read clock bit +- 0x700c: LSB I2C read data bit +- 0x9008: GPIO get input state +- 0x900c: GPIO set output state +- 0x9020: GPIO direction (Bit7 (GPIO 0..7) - 0:input, 1:output) +- 0x9050: SPU control +- 0x9054: Reset HW blocks +- 0x9058: VPU control +- 0xA018: Bit6: interrupt pending? +- 0xA064: APU command + + +Interrupt Status Register +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The definition of the bits in the interrupt status register 0x0040, and the +interrupt mask 0x0048. If a bit is cleared in the mask, then we want our ISR to +execute. + +- bit 31 Encoder Start Capture +- bit 30 Encoder EOS +- bit 29 Encoder VBI capture +- bit 28 Encoder Video Input Module reset event +- bit 27 Encoder DMA complete +- bit 24 Decoder audio mode change detection event (through event notification) +- bit 22 Decoder data request +- bit 20 Decoder DMA complete +- bit 19 Decoder VBI re-insertion +- bit 18 Decoder DMA err (linked-list bad) + +Missing documentation +--------------------- + +- Encoder API post(?) +- Decoder API post(?) +- Decoder VTRACE event + + +The cx2341x firmware upload +--------------------------- + +This document describes how to upload the cx2341x firmware to the card. + +How to find +~~~~~~~~~~~ + +See the web pages of the various projects that uses this chip for information +on how to obtain the firmware. + +The firmware stored in a Windows driver can be detected as follows: + +- Each firmware image is 256k bytes. +- The 1st 32-bit word of the Encoder image is 0x0000da7 +- The 1st 32-bit word of the Decoder image is 0x00003a7 +- The 2nd 32-bit word of both images is 0xaa55bb66 + +How to load +~~~~~~~~~~~ + +- Issue the FWapi command to stop the encoder if it is running. Wait for the + command to complete. +- Issue the FWapi command to stop the decoder if it is running. Wait for the + command to complete. +- Issue the I2C command to the digitizer to stop emitting VSYNC events. +- Issue the FWapi command to halt the encoder's firmware. +- Sleep for 10ms. +- Issue the FWapi command to halt the decoder's firmware. +- Sleep for 10ms. +- Write 0x00000000 to register 0x2800 to stop the Video Display Module. +- Write 0x00000005 to register 0x2D00 to stop the AO (audio output?). +- Write 0x00000000 to register 0xA064 to ping? the APU. +- Write 0xFFFFFFFE to register 0x9058 to stop the VPU. +- Write 0xFFFFFFFF to register 0x9054 to reset the HW blocks. +- Write 0x00000001 to register 0x9050 to stop the SPU. +- Sleep for 10ms. +- Write 0x0000001A to register 0x07FC to init the Encoder SDRAM's pre-charge. +- Write 0x80000640 to register 0x07F8 to init the Encoder SDRAM's refresh to 1us. +- Write 0x0000001A to register 0x08FC to init the Decoder SDRAM's pre-charge. +- Write 0x80000640 to register 0x08F8 to init the Decoder SDRAM's refresh to 1us. +- Sleep for 512ms. (600ms is recommended) +- Transfer the encoder's firmware image to offset 0 in Encoder memory space. +- Transfer the decoder's firmware image to offset 0 in Decoder memory space. +- Use a read-modify-write operation to Clear bit 0 of register 0x9050 to + re-enable the SPU. +- Sleep for 1 second. +- Use a read-modify-write operation to Clear bits 3 and 0 of register 0x9058 + to re-enable the VPU. +- Sleep for 1 second. +- Issue status API commands to both firmware images to verify. + + +How to call the firmware API +---------------------------- + +The preferred calling convention is known as the firmware mailbox. The +mailboxes are basically a fixed length array that serves as the call-stack. + +Firmware mailboxes can be located by searching the encoder and decoder memory +for a 16 byte signature. That signature will be located on a 256-byte boundary. + +Signature: + +.. code-block:: none + + 0x78, 0x56, 0x34, 0x12, 0x12, 0x78, 0x56, 0x34, + 0x34, 0x12, 0x78, 0x56, 0x56, 0x34, 0x12, 0x78 + +The firmware implements 20 mailboxes of 20 32-bit words. The first 10 are +reserved for API calls. The second 10 are used by the firmware for event +notification. + + ====== ================= + Index Name + ====== ================= + 0 Flags + 1 Command + 2 Return value + 3 Timeout + 4-19 Parameter/Result + ====== ================= + + +The flags are defined in the following table. The direction is from the +perspective of the firmware. + + ==== ========== ============================================ + Bit Direction Purpose + ==== ========== ============================================ + 2 O Firmware has processed the command. + 1 I Driver has finished setting the parameters. + 0 I Driver is using this mailbox. + ==== ========== ============================================ + +The command is a 32-bit enumerator. The API specifics may be found in this +chapter. + +The return value is a 32-bit enumerator. Only two values are currently defined: + +- 0=success +- -1=command undefined. + +There are 16 parameters/results 32-bit fields. The driver populates these fields +with values for all the parameters required by the call. The driver overwrites +these fields with result values returned by the call. + +The timeout value protects the card from a hung driver thread. If the driver +doesn't handle the completed call within the timeout specified, the firmware +will reset that mailbox. + +To make an API call, the driver iterates over each mailbox looking for the +first one available (bit 0 has been cleared). The driver sets that bit, fills +in the command enumerator, the timeout value and any required parameters. The +driver then sets the parameter ready bit (bit 1). The firmware scans the +mailboxes for pending commands, processes them, sets the result code, populates +the result value array with that call's return values and sets the call +complete bit (bit 2). Once bit 2 is set, the driver should retrieve the results +and clear all the flags. If the driver does not perform this task within the +time set in the timeout register, the firmware will reset that mailbox. + +Event notifications are sent from the firmware to the host. The host tells the +firmware which events it is interested in via an API call. That call tells the +firmware which notification mailbox to use. The firmware signals the host via +an interrupt. Only the 16 Results fields are used, the Flags, Command, Return +value and Timeout words are not used. + + +OSD firmware API description +---------------------------- + +.. note:: this API is part of the decoder firmware, so it's cx23415 only. + + + +CX2341X_OSD_GET_FRAMEBUFFER +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 65/0x41 + +Description +^^^^^^^^^^^ + +Return base and length of contiguous OSD memory. + +Result[0] +^^^^^^^^^ + +OSD base address + +Result[1] +^^^^^^^^^ + +OSD length + + + +CX2341X_OSD_GET_PIXEL_FORMAT +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 66/0x42 + +Description +^^^^^^^^^^^ + +Query OSD format + +Result[0] +^^^^^^^^^ + +0=8bit index +1=16bit RGB 5:6:5 +2=16bit ARGB 1:5:5:5 +3=16bit ARGB 1:4:4:4 +4=32bit ARGB 8:8:8:8 + + + +CX2341X_OSD_SET_PIXEL_FORMAT +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 67/0x43 + +Description +^^^^^^^^^^^ + +Assign pixel format + +Param[0] +^^^^^^^^ + +- 0=8bit index +- 1=16bit RGB 5:6:5 +- 2=16bit ARGB 1:5:5:5 +- 3=16bit ARGB 1:4:4:4 +- 4=32bit ARGB 8:8:8:8 + + + +CX2341X_OSD_GET_STATE +~~~~~~~~~~~~~~~~~~~~~ + +Enum: 68/0x44 + +Description +^^^^^^^^^^^ + +Query OSD state + +Result[0] +^^^^^^^^^ + +- Bit 0 0=off, 1=on +- Bits 1:2 alpha control +- Bits 3:5 pixel format + + + +CX2341X_OSD_SET_STATE +~~~~~~~~~~~~~~~~~~~~~ + +Enum: 69/0x45 + +Description +^^^^^^^^^^^ + +OSD switch + +Param[0] +^^^^^^^^ + +0=off, 1=on + + + +CX2341X_OSD_GET_OSD_COORDS +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 70/0x46 + +Description +^^^^^^^^^^^ + +Retrieve coordinates of OSD area blended with video + +Result[0] +^^^^^^^^^ + +OSD buffer address + +Result[1] +^^^^^^^^^ + +Stride in pixels + +Result[2] +^^^^^^^^^ + +Lines in OSD buffer + +Result[3] +^^^^^^^^^ + +Horizontal offset in buffer + +Result[4] +^^^^^^^^^ + +Vertical offset in buffer + + + +CX2341X_OSD_SET_OSD_COORDS +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 71/0x47 + +Description +^^^^^^^^^^^ + +Assign the coordinates of the OSD area to blend with video + +Param[0] +^^^^^^^^ + +buffer address + +Param[1] +^^^^^^^^ + +buffer stride in pixels + +Param[2] +^^^^^^^^ + +lines in buffer + +Param[3] +^^^^^^^^ + +horizontal offset + +Param[4] +^^^^^^^^ + +vertical offset + + + +CX2341X_OSD_GET_SCREEN_COORDS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 72/0x48 + +Description +^^^^^^^^^^^ + +Retrieve OSD screen area coordinates + +Result[0] +^^^^^^^^^ + +top left horizontal offset + +Result[1] +^^^^^^^^^ + +top left vertical offset + +Result[2] +^^^^^^^^^ + +bottom right horizontal offset + +Result[3] +^^^^^^^^^ + +bottom right vertical offset + + + +CX2341X_OSD_SET_SCREEN_COORDS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 73/0x49 + +Description +^^^^^^^^^^^ + +Assign the coordinates of the screen area to blend with video + +Param[0] +^^^^^^^^ + +top left horizontal offset + +Param[1] +^^^^^^^^ + +top left vertical offset + +Param[2] +^^^^^^^^ + +bottom left horizontal offset + +Param[3] +^^^^^^^^ + +bottom left vertical offset + + + +CX2341X_OSD_GET_GLOBAL_ALPHA +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 74/0x4A + +Description +^^^^^^^^^^^ + +Retrieve OSD global alpha + +Result[0] +^^^^^^^^^ + +global alpha: 0=off, 1=on + +Result[1] +^^^^^^^^^ + +bits 0:7 global alpha + + + +CX2341X_OSD_SET_GLOBAL_ALPHA +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 75/0x4B + +Description +^^^^^^^^^^^ + +Update global alpha + +Param[0] +^^^^^^^^ + +global alpha: 0=off, 1=on + +Param[1] +^^^^^^^^ + +global alpha (8 bits) + +Param[2] +^^^^^^^^ + +local alpha: 0=on, 1=off + + + +CX2341X_OSD_SET_BLEND_COORDS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 78/0x4C + +Description +^^^^^^^^^^^ + +Move start of blending area within display buffer + +Param[0] +^^^^^^^^ + +horizontal offset in buffer + +Param[1] +^^^^^^^^ + +vertical offset in buffer + + + +CX2341X_OSD_GET_FLICKER_STATE +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 79/0x4F + +Description +^^^^^^^^^^^ + +Retrieve flicker reduction module state + +Result[0] +^^^^^^^^^ + +flicker state: 0=off, 1=on + + + +CX2341X_OSD_SET_FLICKER_STATE +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 80/0x50 + +Description +^^^^^^^^^^^ + +Set flicker reduction module state + +Param[0] +^^^^^^^^ + +State: 0=off, 1=on + + + +CX2341X_OSD_BLT_COPY +~~~~~~~~~~~~~~~~~~~~ + +Enum: 82/0x52 + +Description +^^^^^^^^^^^ + +BLT copy + +Param[0] +^^^^^^^^ + +.. code-block:: none + + '0000' zero + '0001' ~destination AND ~source + '0010' ~destination AND source + '0011' ~destination + '0100' destination AND ~source + '0101' ~source + '0110' destination XOR source + '0111' ~destination OR ~source + '1000' ~destination AND ~source + '1001' destination XNOR source + '1010' source + '1011' ~destination OR source + '1100' destination + '1101' destination OR ~source + '1110' destination OR source + '1111' one + + +Param[1] +^^^^^^^^ + +Resulting alpha blending + +- '01' source_alpha +- '10' destination_alpha +- '11' source_alpha*destination_alpha+1 + (zero if both source and destination alpha are zero) + +Param[2] +^^^^^^^^ + +.. code-block:: none + + '00' output_pixel = source_pixel + + '01' if source_alpha=0: + output_pixel = destination_pixel + if 256 > source_alpha > 1: + output_pixel = ((source_alpha + 1)*source_pixel + + (255 - source_alpha)*destination_pixel)/256 + + '10' if destination_alpha=0: + output_pixel = source_pixel + if 255 > destination_alpha > 0: + output_pixel = ((255 - destination_alpha)*source_pixel + + (destination_alpha + 1)*destination_pixel)/256 + + '11' if source_alpha=0: + source_temp = 0 + if source_alpha=255: + source_temp = source_pixel*256 + if 255 > source_alpha > 0: + source_temp = source_pixel*(source_alpha + 1) + if destination_alpha=0: + destination_temp = 0 + if destination_alpha=255: + destination_temp = destination_pixel*256 + if 255 > destination_alpha > 0: + destination_temp = destination_pixel*(destination_alpha + 1) + output_pixel = (source_temp + destination_temp)/256 + +Param[3] +^^^^^^^^ + +width + +Param[4] +^^^^^^^^ + +height + +Param[5] +^^^^^^^^ + +destination pixel mask + +Param[6] +^^^^^^^^ + +destination rectangle start address + +Param[7] +^^^^^^^^ + +destination stride in dwords + +Param[8] +^^^^^^^^ + +source stride in dwords + +Param[9] +^^^^^^^^ + +source rectangle start address + + + +CX2341X_OSD_BLT_FILL +~~~~~~~~~~~~~~~~~~~~ + +Enum: 83/0x53 + +Description +^^^^^^^^^^^ + +BLT fill color + +Param[0] +^^^^^^^^ + +Same as Param[0] on API 0x52 + +Param[1] +^^^^^^^^ + +Same as Param[1] on API 0x52 + +Param[2] +^^^^^^^^ + +Same as Param[2] on API 0x52 + +Param[3] +^^^^^^^^ + +width + +Param[4] +^^^^^^^^ + +height + +Param[5] +^^^^^^^^ + +destination pixel mask + +Param[6] +^^^^^^^^ + +destination rectangle start address + +Param[7] +^^^^^^^^ + +destination stride in dwords + +Param[8] +^^^^^^^^ + +color fill value + + + +CX2341X_OSD_BLT_TEXT +~~~~~~~~~~~~~~~~~~~~ + +Enum: 84/0x54 + +Description +^^^^^^^^^^^ + +BLT for 8 bit alpha text source + +Param[0] +^^^^^^^^ + +Same as Param[0] on API 0x52 + +Param[1] +^^^^^^^^ + +Same as Param[1] on API 0x52 + +Param[2] +^^^^^^^^ + +Same as Param[2] on API 0x52 + +Param[3] +^^^^^^^^ + +width + +Param[4] +^^^^^^^^ + +height + +Param[5] +^^^^^^^^ + +destination pixel mask + +Param[6] +^^^^^^^^ + +destination rectangle start address + +Param[7] +^^^^^^^^ + +destination stride in dwords + +Param[8] +^^^^^^^^ + +source stride in dwords + +Param[9] +^^^^^^^^ + +source rectangle start address + +Param[10] +^^^^^^^^^ + +color fill value + + + +CX2341X_OSD_SET_FRAMEBUFFER_WINDOW +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 86/0x56 + +Description +^^^^^^^^^^^ + +Positions the main output window on the screen. The coordinates must be +such that the entire window fits on the screen. + +Param[0] +^^^^^^^^ + +window width + +Param[1] +^^^^^^^^ + +window height + +Param[2] +^^^^^^^^ + +top left window corner horizontal offset + +Param[3] +^^^^^^^^ + +top left window corner vertical offset + + + +CX2341X_OSD_SET_CHROMA_KEY +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 96/0x60 + +Description +^^^^^^^^^^^ + +Chroma key switch and color + +Param[0] +^^^^^^^^ + +state: 0=off, 1=on + +Param[1] +^^^^^^^^ + +color + + + +CX2341X_OSD_GET_ALPHA_CONTENT_INDEX +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 97/0x61 + +Description +^^^^^^^^^^^ + +Retrieve alpha content index + +Result[0] +^^^^^^^^^ + +alpha content index, Range 0:15 + + + +CX2341X_OSD_SET_ALPHA_CONTENT_INDEX +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 98/0x62 + +Description +^^^^^^^^^^^ + +Assign alpha content index + +Param[0] +^^^^^^^^ + +alpha content index, range 0:15 + + +Encoder firmware API description +-------------------------------- + +CX2341X_ENC_PING_FW +~~~~~~~~~~~~~~~~~~~ + +Enum: 128/0x80 + +Description +^^^^^^^^^^^ + +Does nothing. Can be used to check if the firmware is responding. + + + +CX2341X_ENC_START_CAPTURE +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 129/0x81 + +Description +^^^^^^^^^^^ + +Commences the capture of video, audio and/or VBI data. All encoding +parameters must be initialized prior to this API call. Captures frames +continuously or until a predefined number of frames have been captured. + +Param[0] +^^^^^^^^ + +Capture stream type: + + - 0=MPEG + - 1=Raw + - 2=Raw passthrough + - 3=VBI + + +Param[1] +^^^^^^^^ + +Bitmask: + + - Bit 0 when set, captures YUV + - Bit 1 when set, captures PCM audio + - Bit 2 when set, captures VBI (same as param[0]=3) + - Bit 3 when set, the capture destination is the decoder + (same as param[0]=2) + - Bit 4 when set, the capture destination is the host + +.. note:: this parameter is only meaningful for RAW capture type. + + + +CX2341X_ENC_STOP_CAPTURE +~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 130/0x82 + +Description +^^^^^^^^^^^ + +Ends a capture in progress + +Param[0] +^^^^^^^^ + +- 0=stop at end of GOP (generates IRQ) +- 1=stop immediate (no IRQ) + +Param[1] +^^^^^^^^ + +Stream type to stop, see param[0] of API 0x81 + +Param[2] +^^^^^^^^ + +Subtype, see param[1] of API 0x81 + + + +CX2341X_ENC_SET_AUDIO_ID +~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 137/0x89 + +Description +^^^^^^^^^^^ + +Assigns the transport stream ID of the encoded audio stream + +Param[0] +^^^^^^^^ + +Audio Stream ID + + + +CX2341X_ENC_SET_VIDEO_ID +~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 139/0x8B + +Description +^^^^^^^^^^^ + +Set video transport stream ID + +Param[0] +^^^^^^^^ + +Video stream ID + + + +CX2341X_ENC_SET_PCR_ID +~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 141/0x8D + +Description +^^^^^^^^^^^ + +Assigns the transport stream ID for PCR packets + +Param[0] +^^^^^^^^ + +PCR Stream ID + + + +CX2341X_ENC_SET_FRAME_RATE +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 143/0x8F + +Description +^^^^^^^^^^^ + +Set video frames per second. Change occurs at start of new GOP. + +Param[0] +^^^^^^^^ + +- 0=30fps +- 1=25fps + + + +CX2341X_ENC_SET_FRAME_SIZE +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 145/0x91 + +Description +^^^^^^^^^^^ + +Select video stream encoding resolution. + +Param[0] +^^^^^^^^ + +Height in lines. Default 480 + +Param[1] +^^^^^^^^ + +Width in pixels. Default 720 + + + +CX2341X_ENC_SET_BIT_RATE +~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 149/0x95 + +Description +^^^^^^^^^^^ + +Assign average video stream bitrate. + +Param[0] +^^^^^^^^ + +0=variable bitrate, 1=constant bitrate + +Param[1] +^^^^^^^^ + +bitrate in bits per second + +Param[2] +^^^^^^^^ + +peak bitrate in bits per second, divided by 400 + +Param[3] +^^^^^^^^ + +Mux bitrate in bits per second, divided by 400. May be 0 (default). + +Param[4] +^^^^^^^^ + +Rate Control VBR Padding + +Param[5] +^^^^^^^^ + +VBV Buffer used by encoder + +.. note:: + + #) Param\[3\] and Param\[4\] seem to be always 0 + #) Param\[5\] doesn't seem to be used. + + + +CX2341X_ENC_SET_GOP_PROPERTIES +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 151/0x97 + +Description +^^^^^^^^^^^ + +Setup the GOP structure + +Param[0] +^^^^^^^^ + +GOP size (maximum is 34) + +Param[1] +^^^^^^^^ + +Number of B frames between the I and P frame, plus 1. +For example: IBBPBBPBBPBB --> GOP size: 12, number of B frames: 2+1 = 3 + +.. note:: + + GOP size must be a multiple of (B-frames + 1). + + + +CX2341X_ENC_SET_ASPECT_RATIO +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 153/0x99 + +Description +^^^^^^^^^^^ + +Sets the encoding aspect ratio. Changes in the aspect ratio take effect +at the start of the next GOP. + +Param[0] +^^^^^^^^ + +- '0000' forbidden +- '0001' 1:1 square +- '0010' 4:3 +- '0011' 16:9 +- '0100' 2.21:1 +- '0101' to '1111' reserved + + + +CX2341X_ENC_SET_DNR_FILTER_MODE +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 155/0x9B + +Description +^^^^^^^^^^^ + +Assign Dynamic Noise Reduction operating mode + +Param[0] +^^^^^^^^ + +Bit0: Spatial filter, set=auto, clear=manual +Bit1: Temporal filter, set=auto, clear=manual + +Param[1] +^^^^^^^^ + +Median filter: + +- 0=Disabled +- 1=Horizontal +- 2=Vertical +- 3=Horiz/Vert +- 4=Diagonal + + + +CX2341X_ENC_SET_DNR_FILTER_PROPS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 157/0x9D + +Description +^^^^^^^^^^^ + +These Dynamic Noise Reduction filter values are only meaningful when +the respective filter is set to "manual" (See API 0x9B) + +Param[0] +^^^^^^^^ + +Spatial filter: default 0, range 0:15 + +Param[1] +^^^^^^^^ + +Temporal filter: default 0, range 0:31 + + + +CX2341X_ENC_SET_CORING_LEVELS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 159/0x9F + +Description +^^^^^^^^^^^ + +Assign Dynamic Noise Reduction median filter properties. + +Param[0] +^^^^^^^^ + +Threshold above which the luminance median filter is enabled. +Default: 0, range 0:255 + +Param[1] +^^^^^^^^ + +Threshold below which the luminance median filter is enabled. +Default: 255, range 0:255 + +Param[2] +^^^^^^^^ + +Threshold above which the chrominance median filter is enabled. +Default: 0, range 0:255 + +Param[3] +^^^^^^^^ + +Threshold below which the chrominance median filter is enabled. +Default: 255, range 0:255 + + + +CX2341X_ENC_SET_SPATIAL_FILTER_TYPE +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 161/0xA1 + +Description +^^^^^^^^^^^ + +Assign spatial prefilter parameters + +Param[0] +^^^^^^^^ + +Luminance filter + +- 0=Off +- 1=1D Horizontal +- 2=1D Vertical +- 3=2D H/V Separable (default) +- 4=2D Symmetric non-separable + +Param[1] +^^^^^^^^ + +Chrominance filter + +- 0=Off +- 1=1D Horizontal (default) + + + +CX2341X_ENC_SET_VBI_LINE +~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 183/0xB7 + +Description +^^^^^^^^^^^ + +Selects VBI line number. + +Param[0] +^^^^^^^^ + +- Bits 0:4 line number +- Bit 31 0=top_field, 1=bottom_field +- Bits 0:31 all set specifies "all lines" + +Param[1] +^^^^^^^^ + +VBI line information features: 0=disabled, 1=enabled + +Param[2] +^^^^^^^^ + +Slicing: 0=None, 1=Closed Caption +Almost certainly not implemented. Set to 0. + +Param[3] +^^^^^^^^ + +Luminance samples in this line. +Almost certainly not implemented. Set to 0. + +Param[4] +^^^^^^^^ + +Chrominance samples in this line +Almost certainly not implemented. Set to 0. + + + +CX2341X_ENC_SET_STREAM_TYPE +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 185/0xB9 + +Description +^^^^^^^^^^^ + +Assign stream type + +.. note:: + + Transport stream is not working in recent firmwares. + And in older firmwares the timestamps in the TS seem to be + unreliable. + +Param[0] +^^^^^^^^ + +- 0=Program stream +- 1=Transport stream +- 2=MPEG1 stream +- 3=PES A/V stream +- 5=PES Video stream +- 7=PES Audio stream +- 10=DVD stream +- 11=VCD stream +- 12=SVCD stream +- 13=DVD_S1 stream +- 14=DVD_S2 stream + + + +CX2341X_ENC_SET_OUTPUT_PORT +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 187/0xBB + +Description +^^^^^^^^^^^ + +Assign stream output port. Normally 0 when the data is copied through +the PCI bus (DMA), and 1 when the data is streamed to another chip +(pvrusb and cx88-blackbird). + +Param[0] +^^^^^^^^ + +- 0=Memory (default) +- 1=Streaming +- 2=Serial + +Param[1] +^^^^^^^^ + +Unknown, but leaving this to 0 seems to work best. Indications are that +this might have to do with USB support, although passing anything but 0 +only breaks things. + + + +CX2341X_ENC_SET_AUDIO_PROPERTIES +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 189/0xBD + +Description +^^^^^^^^^^^ + +Set audio stream properties, may be called while encoding is in progress. + +.. note:: + + All bitfields are consistent with ISO11172 documentation except + bits 2:3 which ISO docs define as: + + - '11' Layer I + - '10' Layer II + - '01' Layer III + - '00' Undefined + + This discrepancy may indicate a possible error in the documentation. + Testing indicated that only Layer II is actually working, and that + the minimum bitrate should be 192 kbps. + +Param[0] +^^^^^^^^ + +Bitmask: + +.. code-block:: none + + 0:1 '00' 44.1Khz + '01' 48Khz + '10' 32Khz + '11' reserved + + 2:3 '01'=Layer I + '10'=Layer II + + 4:7 Bitrate: + Index | Layer I | Layer II + ------+-------------+------------ + '0000' | free format | free format + '0001' | 32 kbit/s | 32 kbit/s + '0010' | 64 kbit/s | 48 kbit/s + '0011' | 96 kbit/s | 56 kbit/s + '0100' | 128 kbit/s | 64 kbit/s + '0101' | 160 kbit/s | 80 kbit/s + '0110' | 192 kbit/s | 96 kbit/s + '0111' | 224 kbit/s | 112 kbit/s + '1000' | 256 kbit/s | 128 kbit/s + '1001' | 288 kbit/s | 160 kbit/s + '1010' | 320 kbit/s | 192 kbit/s + '1011' | 352 kbit/s | 224 kbit/s + '1100' | 384 kbit/s | 256 kbit/s + '1101' | 416 kbit/s | 320 kbit/s + '1110' | 448 kbit/s | 384 kbit/s + + .. note:: + + For Layer II, not all combinations of total bitrate + and mode are allowed. See ISO11172-3 3-Annex B, + Table 3-B.2 + + 8:9 '00'=Stereo + '01'=JointStereo + '10'=Dual + '11'=Mono + + .. note:: + + The cx23415 cannot decode Joint Stereo properly. + + 10:11 Mode Extension used in joint_stereo mode. + In Layer I and II they indicate which subbands are in + intensity_stereo. All other subbands are coded in stereo. + '00' subbands 4-31 in intensity_stereo, bound==4 + '01' subbands 8-31 in intensity_stereo, bound==8 + '10' subbands 12-31 in intensity_stereo, bound==12 + '11' subbands 16-31 in intensity_stereo, bound==16 + + 12:13 Emphasis: + '00' None + '01' 50/15uS + '10' reserved + '11' CCITT J.17 + + 14 CRC: + '0' off + '1' on + + 15 Copyright: + '0' off + '1' on + + 16 Generation: + '0' copy + '1' original + + + +CX2341X_ENC_HALT_FW +~~~~~~~~~~~~~~~~~~~ + +Enum: 195/0xC3 + +Description +^^^^^^^^^^^ + +The firmware is halted and no further API calls are serviced until the +firmware is uploaded again. + + + +CX2341X_ENC_GET_VERSION +~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 196/0xC4 + +Description +^^^^^^^^^^^ + +Returns the version of the encoder firmware. + +Result[0] +^^^^^^^^^ + +Version bitmask: +- Bits 0:15 build +- Bits 16:23 minor +- Bits 24:31 major + + + +CX2341X_ENC_SET_GOP_CLOSURE +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 197/0xC5 + +Description +^^^^^^^^^^^ + +Assigns the GOP open/close property. + +Param[0] +^^^^^^^^ + +- 0=Open +- 1=Closed + + + +CX2341X_ENC_GET_SEQ_END +~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 198/0xC6 + +Description +^^^^^^^^^^^ + +Obtains the sequence end code of the encoder's buffer. When a capture +is started a number of interrupts are still generated, the last of +which will have Result[0] set to 1 and Result[1] will contain the size +of the buffer. + +Result[0] +^^^^^^^^^ + +State of the transfer (1 if last buffer) + +Result[1] +^^^^^^^^^ + +If Result[0] is 1, this contains the size of the last buffer, undefined +otherwise. + + + +CX2341X_ENC_SET_PGM_INDEX_INFO +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 199/0xC7 + +Description +^^^^^^^^^^^ + +Sets the Program Index Information. +The information is stored as follows: + +.. code-block:: c + + struct info { + u32 length; // Length of this frame + u32 offset_low; // Offset in the file of the + u32 offset_high; // start of this frame + u32 mask1; // Bits 0-2 are the type mask: + // 1=I, 2=P, 4=B + // 0=End of Program Index, other fields + // are invalid. + u32 pts; // The PTS of the frame + u32 mask2; // Bit 0 is bit 32 of the pts. + }; + u32 table_ptr; + struct info index[400]; + +The table_ptr is the encoder memory address in the table were +*new* entries will be written. + +.. note:: This is a ringbuffer, so the table_ptr will wraparound. + +Param[0] +^^^^^^^^ + +Picture Mask: +- 0=No index capture +- 1=I frames +- 3=I,P frames +- 7=I,P,B frames + +(Seems to be ignored, it always indexes I, P and B frames) + +Param[1] +^^^^^^^^ + +Elements requested (up to 400) + +Result[0] +^^^^^^^^^ + +Offset in the encoder memory of the start of the table. + +Result[1] +^^^^^^^^^ + +Number of allocated elements up to a maximum of Param[1] + + + +CX2341X_ENC_SET_VBI_CONFIG +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 200/0xC8 + +Description +^^^^^^^^^^^ + +Configure VBI settings + +Param[0] +^^^^^^^^ + +Bitmap: + +.. code-block:: none + + 0 Mode '0' Sliced, '1' Raw + 1:3 Insertion: + '000' insert in extension & user data + '001' insert in private packets + '010' separate stream and user data + '111' separate stream and private data + 8:15 Stream ID (normally 0xBD) + +Param[1] +^^^^^^^^ + +Frames per interrupt (max 8). Only valid in raw mode. + +Param[2] +^^^^^^^^ + +Total raw VBI frames. Only valid in raw mode. + +Param[3] +^^^^^^^^ + +Start codes + +Param[4] +^^^^^^^^ + +Stop codes + +Param[5] +^^^^^^^^ + +Lines per frame + +Param[6] +^^^^^^^^ + +Byte per line + +Result[0] +^^^^^^^^^ + +Observed frames per interrupt in raw mode only. Rage 1 to Param[1] + +Result[1] +^^^^^^^^^ + +Observed number of frames in raw mode. Range 1 to Param[2] + +Result[2] +^^^^^^^^^ + +Memory offset to start or raw VBI data + + + +CX2341X_ENC_SET_DMA_BLOCK_SIZE +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 201/0xC9 + +Description +^^^^^^^^^^^ + +Set DMA transfer block size + +Param[0] +^^^^^^^^ + +DMA transfer block size in bytes or frames. When unit is bytes, +supported block sizes are 2^7, 2^8 and 2^9 bytes. + +Param[1] +^^^^^^^^ + +Unit: 0=bytes, 1=frames + + + +CX2341X_ENC_GET_PREV_DMA_INFO_MB_10 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 202/0xCA + +Description +^^^^^^^^^^^ + +Returns information on the previous DMA transfer in conjunction with +bit 27 of the interrupt mask. Uses mailbox 10. + +Result[0] +^^^^^^^^^ + +Type of stream + +Result[1] +^^^^^^^^^ + +Address Offset + +Result[2] +^^^^^^^^^ + +Maximum size of transfer + + + +CX2341X_ENC_GET_PREV_DMA_INFO_MB_9 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 203/0xCB + +Description +^^^^^^^^^^^ + +Returns information on the previous DMA transfer in conjunction with +bit 27 or 18 of the interrupt mask. Uses mailbox 9. + +Result[0] +^^^^^^^^^ + +Status bits: +- 0 read completed +- 1 write completed +- 2 DMA read error +- 3 DMA write error +- 4 Scatter-Gather array error + +Result[1] +^^^^^^^^^ + +DMA type + +Result[2] +^^^^^^^^^ + +Presentation Time Stamp bits 0..31 + +Result[3] +^^^^^^^^^ + +Presentation Time Stamp bit 32 + + + +CX2341X_ENC_SCHED_DMA_TO_HOST +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 204/0xCC + +Description +^^^^^^^^^^^ + +Setup DMA to host operation + +Param[0] +^^^^^^^^ + +Memory address of link list + +Param[1] +^^^^^^^^ + +Length of link list (wtf: what units ???) + +Param[2] +^^^^^^^^ + +DMA type (0=MPEG) + + + +CX2341X_ENC_INITIALIZE_INPUT +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 205/0xCD + +Description +^^^^^^^^^^^ + +Initializes the video input + + + +CX2341X_ENC_SET_FRAME_DROP_RATE +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 208/0xD0 + +Description +^^^^^^^^^^^ + +For each frame captured, skip specified number of frames. + +Param[0] +^^^^^^^^ + +Number of frames to skip + + + +CX2341X_ENC_PAUSE_ENCODER +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 210/0xD2 + +Description +^^^^^^^^^^^ + +During a pause condition, all frames are dropped instead of being encoded. + +Param[0] +^^^^^^^^ + +- 0=Pause encoding +- 1=Continue encoding + + + +CX2341X_ENC_REFRESH_INPUT +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 211/0xD3 + +Description +^^^^^^^^^^^ + +Refreshes the video input + + + +CX2341X_ENC_SET_COPYRIGHT +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 212/0xD4 + +Description +^^^^^^^^^^^ + +Sets stream copyright property + +Param[0] +^^^^^^^^ + + +- 0=Stream is not copyrighted +- 1=Stream is copyrighted + + + +CX2341X_ENC_SET_EVENT_NOTIFICATION +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 213/0xD5 + +Description +^^^^^^^^^^^ + +Setup firmware to notify the host about a particular event. Host must +unmask the interrupt bit. + +Param[0] +^^^^^^^^ + +Event (0=refresh encoder input) + +Param[1] +^^^^^^^^ + +Notification 0=disabled 1=enabled + +Param[2] +^^^^^^^^ + +Interrupt bit + +Param[3] +^^^^^^^^ + +Mailbox slot, -1 if no mailbox required. + + + +CX2341X_ENC_SET_NUM_VSYNC_LINES +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 214/0xD6 + +Description +^^^^^^^^^^^ + +Depending on the analog video decoder used, this assigns the number +of lines for field 1 and 2. + +Param[0] +^^^^^^^^ + +Field 1 number of lines: +- 0x00EF for SAA7114 +- 0x00F0 for SAA7115 +- 0x0105 for Micronas + +Param[1] +^^^^^^^^ + +Field 2 number of lines: +- 0x00EF for SAA7114 +- 0x00F0 for SAA7115 +- 0x0106 for Micronas + + + +CX2341X_ENC_SET_PLACEHOLDER +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 215/0xD7 + +Description +^^^^^^^^^^^ + +Provides a mechanism of inserting custom user data in the MPEG stream. + +Param[0] +^^^^^^^^ + +- 0=extension & user data +- 1=private packet with stream ID 0xBD + +Param[1] +^^^^^^^^ + +Rate at which to insert data, in units of frames (for private packet) +or GOPs (for ext. & user data) + +Param[2] +^^^^^^^^ + +Number of data DWORDs (below) to insert + +Param[3] +^^^^^^^^ + +Custom data 0 + +Param[4] +^^^^^^^^ + +Custom data 1 + +Param[5] +^^^^^^^^ + +Custom data 2 + +Param[6] +^^^^^^^^ + +Custom data 3 + +Param[7] +^^^^^^^^ + +Custom data 4 + +Param[8] +^^^^^^^^ + +Custom data 5 + +Param[9] +^^^^^^^^ + +Custom data 6 + +Param[10] +^^^^^^^^^ + +Custom data 7 + +Param[11] +^^^^^^^^^ + +Custom data 8 + + + +CX2341X_ENC_MUTE_VIDEO +~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 217/0xD9 + +Description +^^^^^^^^^^^ + +Video muting + +Param[0] +^^^^^^^^ + +Bit usage: + +.. code-block:: none + + 0 '0'=video not muted + '1'=video muted, creates frames with the YUV color defined below + 1:7 Unused + 8:15 V chrominance information + 16:23 U chrominance information + 24:31 Y luminance information + + + +CX2341X_ENC_MUTE_AUDIO +~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 218/0xDA + +Description +^^^^^^^^^^^ + +Audio muting + +Param[0] +^^^^^^^^ + +- 0=audio not muted +- 1=audio muted (produces silent mpeg audio stream) + + + +CX2341X_ENC_SET_VERT_CROP_LINE +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 219/0xDB + +Description +^^^^^^^^^^^ + +Something to do with 'Vertical Crop Line' + +Param[0] +^^^^^^^^ + +If saa7114 and raw VBI capture and 60 Hz, then set to 10001. +Else 0. + + + +CX2341X_ENC_MISC +~~~~~~~~~~~~~~~~ + +Enum: 220/0xDC + +Description +^^^^^^^^^^^ + +Miscellaneous actions. Not known for 100% what it does. It's really a +sort of ioctl call. The first parameter is a command number, the second +the value. + +Param[0] +^^^^^^^^ + +Command number: + +.. code-block:: none + + 1=set initial SCR value when starting encoding (works). + 2=set quality mode (apparently some test setting). + 3=setup advanced VIM protection handling. + Always 1 for the cx23416 and 0 for cx23415. + 4=generate DVD compatible PTS timestamps + 5=USB flush mode + 6=something to do with the quantization matrix + 7=set navigation pack insertion for DVD: adds 0xbf (private stream 2) + packets to the MPEG. The size of these packets is 2048 bytes (including + the header of 6 bytes: 0x000001bf + length). The payload is zeroed and + it is up to the application to fill them in. These packets are apparently + inserted every four frames. + 8=enable scene change detection (seems to be a failure) + 9=set history parameters of the video input module + 10=set input field order of VIM + 11=set quantization matrix + 12=reset audio interface after channel change or input switch (has no argument). + Needed for the cx2584x, not needed for the mspx4xx, but it doesn't seem to + do any harm calling it regardless. + 13=set audio volume delay + 14=set audio delay + + +Param[1] +^^^^^^^^ + +Command value. + +Decoder firmware API description +-------------------------------- + +.. note:: this API is part of the decoder firmware, so it's cx23415 only. + + + +CX2341X_DEC_PING_FW +~~~~~~~~~~~~~~~~~~~ + +Enum: 0/0x00 + +Description +^^^^^^^^^^^ + +This API call does nothing. It may be used to check if the firmware +is responding. + + + +CX2341X_DEC_START_PLAYBACK +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 1/0x01 + +Description +^^^^^^^^^^^ + +Begin or resume playback. + +Param[0] +^^^^^^^^ + +0 based frame number in GOP to begin playback from. + +Param[1] +^^^^^^^^ + +Specifies the number of muted audio frames to play before normal +audio resumes. (This is not implemented in the firmware, leave at 0) + + + +CX2341X_DEC_STOP_PLAYBACK +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 2/0x02 + +Description +^^^^^^^^^^^ + +Ends playback and clears all decoder buffers. If PTS is not zero, +playback stops at specified PTS. + +Param[0] +^^^^^^^^ + +Display 0=last frame, 1=black + +.. note:: + + this takes effect immediately, so if you want to wait for a PTS, + then use '0', otherwise the screen goes to black at once. + You can call this later (even if there is no playback) with a 1 value + to set the screen to black. + +Param[1] +^^^^^^^^ + +PTS low + +Param[2] +^^^^^^^^ + +PTS high + + + +CX2341X_DEC_SET_PLAYBACK_SPEED +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 3/0x03 + +Description +^^^^^^^^^^^ + +Playback stream at speed other than normal. There are two modes of +operation: + + - Smooth: host transfers entire stream and firmware drops unused + frames. + - Coarse: host drops frames based on indexing as required to achieve + desired speed. + +Param[0] +^^^^^^^^ + +.. code-block:: none + + Bitmap: + 0:7 0 normal + 1 fast only "1.5 times" + n nX fast, 1/nX slow + 30 Framedrop: + '0' during 1.5 times play, every other B frame is dropped + '1' during 1.5 times play, stream is unchanged (bitrate + must not exceed 8mbps) + 31 Speed: + '0' slow + '1' fast + +.. note:: + + n is limited to 2. Anything higher does not result in + faster playback. Instead the host should start dropping frames. + +Param[1] +^^^^^^^^ + +Direction: 0=forward, 1=reverse + +.. note:: + + to make reverse playback work you have to write full GOPs in + reverse order. + +Param[2] +^^^^^^^^ + +.. code-block:: none + + Picture mask: + 1=I frames + 3=I, P frames + 7=I, P, B frames + +Param[3] +^^^^^^^^ + +B frames per GOP (for reverse play only) + +.. note:: + + for reverse playback the Picture Mask should be set to I or I, P. + Adding B frames to the mask will result in corrupt video. This field + has to be set to the correct value in order to keep the timing correct. + +Param[4] +^^^^^^^^ + +Mute audio: 0=disable, 1=enable + +Param[5] +^^^^^^^^ + +Display 0=frame, 1=field + +Param[6] +^^^^^^^^ + +Specifies the number of muted audio frames to play before normal audio +resumes. (Not implemented in the firmware, leave at 0) + + + +CX2341X_DEC_STEP_VIDEO +~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 5/0x05 + +Description +^^^^^^^^^^^ + +Each call to this API steps the playback to the next unit defined below +in the current playback direction. + +Param[0] +^^^^^^^^ + +0=frame, 1=top field, 2=bottom field + + + +CX2341X_DEC_SET_DMA_BLOCK_SIZE +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 8/0x08 + +Description +^^^^^^^^^^^ + +Set DMA transfer block size. Counterpart to API 0xC9 + +Param[0] +^^^^^^^^ + +DMA transfer block size in bytes. A different size may be specified +when issuing the DMA transfer command. + + + +CX2341X_DEC_GET_XFER_INFO +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 9/0x09 + +Description +^^^^^^^^^^^ + +This API call may be used to detect an end of stream condition. + +Result[0] +^^^^^^^^^ + +Stream type + +Result[1] +^^^^^^^^^ + +Address offset + +Result[2] +^^^^^^^^^ + +Maximum bytes to transfer + +Result[3] +^^^^^^^^^ + +Buffer fullness + + + +CX2341X_DEC_GET_DMA_STATUS +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 10/0x0A + +Description +^^^^^^^^^^^ + +Status of the last DMA transfer + +Result[0] +^^^^^^^^^ + +Bit 1 set means transfer complete +Bit 2 set means DMA error +Bit 3 set means linked list error + +Result[1] +^^^^^^^^^ + +DMA type: 0=MPEG, 1=OSD, 2=YUV + + + +CX2341X_DEC_SCHED_DMA_FROM_HOST +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 11/0x0B + +Description +^^^^^^^^^^^ + +Setup DMA from host operation. Counterpart to API 0xCC + +Param[0] +^^^^^^^^ + +Memory address of link list + +Param[1] +^^^^^^^^ + +Total # of bytes to transfer + +Param[2] +^^^^^^^^ + +DMA type (0=MPEG, 1=OSD, 2=YUV) + + + +CX2341X_DEC_PAUSE_PLAYBACK +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 13/0x0D + +Description +^^^^^^^^^^^ + +Freeze playback immediately. In this mode, when internal buffers are +full, no more data will be accepted and data request IRQs will be +masked. + +Param[0] +^^^^^^^^ + +Display: 0=last frame, 1=black + + + +CX2341X_DEC_HALT_FW +~~~~~~~~~~~~~~~~~~~ + +Enum: 14/0x0E + +Description +^^^^^^^^^^^ + +The firmware is halted and no further API calls are serviced until +the firmware is uploaded again. + + + +CX2341X_DEC_SET_STANDARD +~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 16/0x10 + +Description +^^^^^^^^^^^ + +Selects display standard + +Param[0] +^^^^^^^^ + +0=NTSC, 1=PAL + + + +CX2341X_DEC_GET_VERSION +~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 17/0x11 + +Description +^^^^^^^^^^^ + +Returns decoder firmware version information + +Result[0] +^^^^^^^^^ + +Version bitmask: + - Bits 0:15 build + - Bits 16:23 minor + - Bits 24:31 major + + + +CX2341X_DEC_SET_STREAM_INPUT +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 20/0x14 + +Description +^^^^^^^^^^^ + +Select decoder stream input port + +Param[0] +^^^^^^^^ + +0=memory (default), 1=streaming + + + +CX2341X_DEC_GET_TIMING_INFO +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 21/0x15 + +Description +^^^^^^^^^^^ + +Returns timing information from start of playback + +Result[0] +^^^^^^^^^ + +Frame count by decode order + +Result[1] +^^^^^^^^^ + +Video PTS bits 0:31 by display order + +Result[2] +^^^^^^^^^ + +Video PTS bit 32 by display order + +Result[3] +^^^^^^^^^ + +SCR bits 0:31 by display order + +Result[4] +^^^^^^^^^ + +SCR bit 32 by display order + + + +CX2341X_DEC_SET_AUDIO_MODE +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 22/0x16 + +Description +^^^^^^^^^^^ + +Select audio mode + +Param[0] +^^^^^^^^ + +Dual mono mode action + 0=Stereo, 1=Left, 2=Right, 3=Mono, 4=Swap, -1=Unchanged + +Param[1] +^^^^^^^^ + +Stereo mode action: + 0=Stereo, 1=Left, 2=Right, 3=Mono, 4=Swap, -1=Unchanged + + + +CX2341X_DEC_SET_EVENT_NOTIFICATION +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 23/0x17 + +Description +^^^^^^^^^^^ + +Setup firmware to notify the host about a particular event. +Counterpart to API 0xD5 + +Param[0] +^^^^^^^^ + +Event: + - 0=Audio mode change between mono, (joint) stereo and dual channel. + - 3=Decoder started + - 4=Unknown: goes off 10-15 times per second while decoding. + - 5=Some sync event: goes off once per frame. + +Param[1] +^^^^^^^^ + +Notification 0=disabled, 1=enabled + +Param[2] +^^^^^^^^ + +Interrupt bit + +Param[3] +^^^^^^^^ + +Mailbox slot, -1 if no mailbox required. + + + +CX2341X_DEC_SET_DISPLAY_BUFFERS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 24/0x18 + +Description +^^^^^^^^^^^ + +Number of display buffers. To decode all frames in reverse playback you +must use nine buffers. + +Param[0] +^^^^^^^^ + +0=six buffers, 1=nine buffers + + + +CX2341X_DEC_EXTRACT_VBI +~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 25/0x19 + +Description +^^^^^^^^^^^ + +Extracts VBI data + +Param[0] +^^^^^^^^ + +0=extract from extension & user data, 1=extract from private packets + +Result[0] +^^^^^^^^^ + +VBI table location + +Result[1] +^^^^^^^^^ + +VBI table size + + + +CX2341X_DEC_SET_DECODER_SOURCE +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 26/0x1A + +Description +^^^^^^^^^^^ + +Selects decoder source. Ensure that the parameters passed to this +API match the encoder settings. + +Param[0] +^^^^^^^^ + +Mode: 0=MPEG from host, 1=YUV from encoder, 2=YUV from host + +Param[1] +^^^^^^^^ + +YUV picture width + +Param[2] +^^^^^^^^ + +YUV picture height + +Param[3] +^^^^^^^^ + +Bitmap: see Param[0] of API 0xBD + + + +CX2341X_DEC_SET_PREBUFFERING +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum: 30/0x1E + +Description +^^^^^^^^^^^ + +Decoder prebuffering, when enabled up to 128KB are buffered for +streams <8mpbs or 640KB for streams >8mbps + +Param[0] +^^^^^^^^ + +0=off, 1=on + +PVR350 Video decoder registers 0x02002800 -> 0x02002B00 +------------------------------------------------------- + +Author: Ian Armstrong + +Version: v0.4 + +Date: 12 March 2007 + + +This list has been worked out through trial and error. There will be mistakes +and omissions. Some registers have no obvious effect so it's hard to say what +they do, while others interact with each other, or require a certain load +sequence. Horizontal filter setup is one example, with six registers working +in unison and requiring a certain load sequence to correctly configure. The +indexed colour palette is much easier to set at just two registers, but again +it requires a certain load sequence. + +Some registers are fussy about what they are set to. Load in a bad value & the +decoder will fail. A firmware reload will often recover, but sometimes a reset +is required. For registers containing size information, setting them to 0 is +generally a bad idea. For other control registers i.e. 2878, you'll only find +out what values are bad when it hangs. + +.. code-block:: none + + -------------------------------------------------------------------------------- + 2800 + bit 0 + Decoder enable + 0 = disable + 1 = enable + -------------------------------------------------------------------------------- + 2804 + bits 0:31 + Decoder horizontal Y alias register 1 + --------------- + 2808 + bits 0:31 + Decoder horizontal Y alias register 2 + --------------- + 280C + bits 0:31 + Decoder horizontal Y alias register 3 + --------------- + 2810 + bits 0:31 + Decoder horizontal Y alias register 4 + --------------- + 2814 + bits 0:31 + Decoder horizontal Y alias register 5 + --------------- + 2818 + bits 0:31 + Decoder horizontal Y alias trigger + + These six registers control the horizontal aliasing filter for the Y plane. + The first five registers must all be loaded before accessing the trigger + (2818), as this register actually clocks the data through for the first + five. + + To correctly program set the filter, this whole procedure must be done 16 + times. The actual register contents are copied from a lookup-table in the + firmware which contains 4 different filter settings. + + -------------------------------------------------------------------------------- + 281C + bits 0:31 + Decoder horizontal UV alias register 1 + --------------- + 2820 + bits 0:31 + Decoder horizontal UV alias register 2 + --------------- + 2824 + bits 0:31 + Decoder horizontal UV alias register 3 + --------------- + 2828 + bits 0:31 + Decoder horizontal UV alias register 4 + --------------- + 282C + bits 0:31 + Decoder horizontal UV alias register 5 + --------------- + 2830 + bits 0:31 + Decoder horizontal UV alias trigger + + These six registers control the horizontal aliasing for the UV plane. + Operation is the same as the Y filter, with 2830 being the trigger + register. + + -------------------------------------------------------------------------------- + 2834 + bits 0:15 + Decoder Y source width in pixels + + bits 16:31 + Decoder Y destination width in pixels + --------------- + 2838 + bits 0:15 + Decoder UV source width in pixels + + bits 16:31 + Decoder UV destination width in pixels + + NOTE: For both registers, the resulting image must be fully visible on + screen. If the image exceeds the right edge both the source and destination + size must be adjusted to reflect the visible portion. For the source width, + you must take into account the scaling when calculating the new value. + -------------------------------------------------------------------------------- + + 283C + bits 0:31 + Decoder Y horizontal scaling + Normally = Reg 2854 >> 2 + --------------- + 2840 + bits 0:31 + Decoder ?? unknown - horizontal scaling + Usually 0x00080514 + --------------- + 2844 + bits 0:31 + Decoder UV horizontal scaling + Normally = Reg 2854 >> 2 + --------------- + 2848 + bits 0:31 + Decoder ?? unknown - horizontal scaling + Usually 0x00100514 + --------------- + 284C + bits 0:31 + Decoder ?? unknown - Y plane + Usually 0x00200020 + --------------- + 2850 + bits 0:31 + Decoder ?? unknown - UV plane + Usually 0x00200020 + --------------- + 2854 + bits 0:31 + Decoder 'master' value for horizontal scaling + --------------- + 2858 + bits 0:31 + Decoder ?? unknown + Usually 0 + --------------- + 285C + bits 0:31 + Decoder ?? unknown + Normally = Reg 2854 >> 1 + --------------- + 2860 + bits 0:31 + Decoder ?? unknown + Usually 0 + --------------- + 2864 + bits 0:31 + Decoder ?? unknown + Normally = Reg 2854 >> 1 + --------------- + 2868 + bits 0:31 + Decoder ?? unknown + Usually 0 + + Most of these registers either control horizontal scaling, or appear linked + to it in some way. Register 2854 contains the 'master' value & the other + registers can be calculated from that one. You must also remember to + correctly set the divider in Reg 2874. + + To enlarge: + Reg 2854 = (source_width * 0x00200000) / destination_width + Reg 2874 = No divide + + To reduce from full size down to half size: + Reg 2854 = (source_width/2 * 0x00200000) / destination width + Reg 2874 = Divide by 2 + + To reduce from half size down to quarter size: + Reg 2854 = (source_width/4 * 0x00200000) / destination width + Reg 2874 = Divide by 4 + + The result is always rounded up. + + -------------------------------------------------------------------------------- + 286C + bits 0:15 + Decoder horizontal Y buffer offset + + bits 15:31 + Decoder horizontal UV buffer offset + + Offset into the video image buffer. If the offset is gradually incremented, + the on screen image will move left & wrap around higher up on the right. + + -------------------------------------------------------------------------------- + 2870 + bits 0:15 + Decoder horizontal Y output offset + + bits 16:31 + Decoder horizontal UV output offset + + Offsets the actual video output. Controls output alignment of the Y & UV + planes. The higher the value, the greater the shift to the left. Use + reg 2890 to move the image right. + + -------------------------------------------------------------------------------- + 2874 + bits 0:1 + Decoder horizontal Y output size divider + 00 = No divide + 01 = Divide by 2 + 10 = Divide by 3 + + bits 4:5 + Decoder horizontal UV output size divider + 00 = No divide + 01 = Divide by 2 + 10 = Divide by 3 + + bit 8 + Decoder ?? unknown + 0 = Normal + 1 = Affects video output levels + + bit 16 + Decoder ?? unknown + 0 = Normal + 1 = Disable horizontal filter + + -------------------------------------------------------------------------------- + 2878 + bit 0 + ?? unknown + + bit 1 + osd on/off + 0 = osd off + 1 = osd on + + bit 2 + Decoder + osd video timing + 0 = NTSC + 1 = PAL + + bits 3:4 + ?? unknown + + bit 5 + Decoder + osd + Swaps upper & lower fields + + -------------------------------------------------------------------------------- + 287C + bits 0:10 + Decoder & osd ?? unknown + Moves entire screen horizontally. Starts at 0x005 with the screen + shifted heavily to the right. Incrementing in steps of 0x004 will + gradually shift the screen to the left. + + bits 11:31 + ?? unknown + + Normally contents are 0x00101111 (NTSC) or 0x1010111d (PAL) + + -------------------------------------------------------------------------------- + 2880 -------- ?? unknown + 2884 -------- ?? unknown + -------------------------------------------------------------------------------- + 2888 + bit 0 + Decoder + osd ?? unknown + 0 = Normal + 1 = Misaligned fields (Correctable through 289C & 28A4) + + bit 4 + ?? unknown + + bit 8 + ?? unknown + + Warning: Bad values will require a firmware reload to recover. + Known to be bad are 0x000,0x011,0x100,0x111 + -------------------------------------------------------------------------------- + 288C + bits 0:15 + osd ?? unknown + Appears to affect the osd position stability. The higher the value the + more unstable it becomes. Decoder output remains stable. + + bits 16:31 + osd ?? unknown + Same as bits 0:15 + + -------------------------------------------------------------------------------- + 2890 + bits 0:11 + Decoder output horizontal offset. + + Horizontal offset moves the video image right. A small left shift is + possible, but it's better to use reg 2870 for that due to its greater + range. + + NOTE: Video corruption will occur if video window is shifted off the right + edge. To avoid this read the notes for 2834 & 2838. + -------------------------------------------------------------------------------- + 2894 + bits 0:23 + Decoder output video surround colour. + + Contains the colour (in yuv) used to fill the screen when the video is + running in a window. + -------------------------------------------------------------------------------- + 2898 + bits 0:23 + Decoder video window colour + Contains the colour (in yuv) used to fill the video window when the + video is turned off. + + bit 24 + Decoder video output + 0 = Video on + 1 = Video off + + bit 28 + Decoder plane order + 0 = Y,UV + 1 = UV,Y + + bit 29 + Decoder second plane byte order + 0 = Normal (UV) + 1 = Swapped (VU) + + In normal usage, the first plane is Y & the second plane is UV. Though the + order of the planes can be swapped, only the byte order of the second plane + can be swapped. This isn't much use for the Y plane, but can be useful for + the UV plane. + + -------------------------------------------------------------------------------- + 289C + bits 0:15 + Decoder vertical field offset 1 + + bits 16:31 + Decoder vertical field offset 2 + + Controls field output vertical alignment. The higher the number, the lower + the image on screen. Known starting values are 0x011E0017 (NTSC) & + 0x01500017 (PAL) + -------------------------------------------------------------------------------- + 28A0 + bits 0:15 + Decoder & osd width in pixels + + bits 16:31 + Decoder & osd height in pixels + + All output from the decoder & osd are disabled beyond this area. Decoder + output will simply go black outside of this region. If the osd tries to + exceed this area it will become corrupt. + -------------------------------------------------------------------------------- + 28A4 + bits 0:11 + osd left shift. + + Has a range of 0x770->0x7FF. With the exception of 0, any value outside of + this range corrupts the osd. + -------------------------------------------------------------------------------- + 28A8 + bits 0:15 + osd vertical field offset 1 + + bits 16:31 + osd vertical field offset 2 + + Controls field output vertical alignment. The higher the number, the lower + the image on screen. Known starting values are 0x011E0017 (NTSC) & + 0x01500017 (PAL) + -------------------------------------------------------------------------------- + 28AC -------- ?? unknown + | + V + 28BC -------- ?? unknown + -------------------------------------------------------------------------------- + 28C0 + bit 0 + Current output field + 0 = first field + 1 = second field + + bits 16:31 + Current scanline + The scanline counts from the top line of the first field + through to the last line of the second field. + -------------------------------------------------------------------------------- + 28C4 -------- ?? unknown + | + V + 28F8 -------- ?? unknown + -------------------------------------------------------------------------------- + 28FC + bit 0 + ?? unknown + 0 = Normal + 1 = Breaks decoder & osd output + -------------------------------------------------------------------------------- + 2900 + bits 0:31 + Decoder vertical Y alias register 1 + --------------- + 2904 + bits 0:31 + Decoder vertical Y alias register 2 + --------------- + 2908 + bits 0:31 + Decoder vertical Y alias trigger + + These three registers control the vertical aliasing filter for the Y plane. + Operation is similar to the horizontal Y filter (2804). The only real + difference is that there are only two registers to set before accessing + the trigger register (2908). As for the horizontal filter, the values are + taken from a lookup table in the firmware, and the procedure must be + repeated 16 times to fully program the filter. + -------------------------------------------------------------------------------- + 290C + bits 0:31 + Decoder vertical UV alias register 1 + --------------- + 2910 + bits 0:31 + Decoder vertical UV alias register 2 + --------------- + 2914 + bits 0:31 + Decoder vertical UV alias trigger + + These three registers control the vertical aliasing filter for the UV + plane. Operation is the same as the Y filter, with 2914 being the trigger. + -------------------------------------------------------------------------------- + 2918 + bits 0:15 + Decoder Y source height in pixels + + bits 16:31 + Decoder Y destination height in pixels + --------------- + 291C + bits 0:15 + Decoder UV source height in pixels divided by 2 + + bits 16:31 + Decoder UV destination height in pixels + + NOTE: For both registers, the resulting image must be fully visible on + screen. If the image exceeds the bottom edge both the source and + destination size must be adjusted to reflect the visible portion. For the + source height, you must take into account the scaling when calculating the + new value. + -------------------------------------------------------------------------------- + 2920 + bits 0:31 + Decoder Y vertical scaling + Normally = Reg 2930 >> 2 + --------------- + 2924 + bits 0:31 + Decoder Y vertical scaling + Normally = Reg 2920 + 0x514 + --------------- + 2928 + bits 0:31 + Decoder UV vertical scaling + When enlarging = Reg 2930 >> 2 + When reducing = Reg 2930 >> 3 + --------------- + 292C + bits 0:31 + Decoder UV vertical scaling + Normally = Reg 2928 + 0x514 + --------------- + 2930 + bits 0:31 + Decoder 'master' value for vertical scaling + --------------- + 2934 + bits 0:31 + Decoder ?? unknown - Y vertical scaling + --------------- + 2938 + bits 0:31 + Decoder Y vertical scaling + Normally = Reg 2930 + --------------- + 293C + bits 0:31 + Decoder ?? unknown - Y vertical scaling + --------------- + 2940 + bits 0:31 + Decoder UV vertical scaling + When enlarging = Reg 2930 >> 1 + When reducing = Reg 2930 + --------------- + 2944 + bits 0:31 + Decoder ?? unknown - UV vertical scaling + --------------- + 2948 + bits 0:31 + Decoder UV vertical scaling + Normally = Reg 2940 + --------------- + 294C + bits 0:31 + Decoder ?? unknown - UV vertical scaling + + Most of these registers either control vertical scaling, or appear linked + to it in some way. Register 2930 contains the 'master' value & all other + registers can be calculated from that one. You must also remember to + correctly set the divider in Reg 296C + + To enlarge: + Reg 2930 = (source_height * 0x00200000) / destination_height + Reg 296C = No divide + + To reduce from full size down to half size: + Reg 2930 = (source_height/2 * 0x00200000) / destination height + Reg 296C = Divide by 2 + + To reduce from half down to quarter. + Reg 2930 = (source_height/4 * 0x00200000) / destination height + Reg 296C = Divide by 4 + + -------------------------------------------------------------------------------- + 2950 + bits 0:15 + Decoder Y line index into display buffer, first field + + bits 16:31 + Decoder Y vertical line skip, first field + -------------------------------------------------------------------------------- + 2954 + bits 0:15 + Decoder Y line index into display buffer, second field + + bits 16:31 + Decoder Y vertical line skip, second field + -------------------------------------------------------------------------------- + 2958 + bits 0:15 + Decoder UV line index into display buffer, first field + + bits 16:31 + Decoder UV vertical line skip, first field + -------------------------------------------------------------------------------- + 295C + bits 0:15 + Decoder UV line index into display buffer, second field + + bits 16:31 + Decoder UV vertical line skip, second field + -------------------------------------------------------------------------------- + 2960 + bits 0:15 + Decoder destination height minus 1 + + bits 16:31 + Decoder destination height divided by 2 + -------------------------------------------------------------------------------- + 2964 + bits 0:15 + Decoder Y vertical offset, second field + + bits 16:31 + Decoder Y vertical offset, first field + + These two registers shift the Y plane up. The higher the number, the + greater the shift. + -------------------------------------------------------------------------------- + 2968 + bits 0:15 + Decoder UV vertical offset, second field + + bits 16:31 + Decoder UV vertical offset, first field + + These two registers shift the UV plane up. The higher the number, the + greater the shift. + -------------------------------------------------------------------------------- + 296C + bits 0:1 + Decoder vertical Y output size divider + 00 = No divide + 01 = Divide by 2 + 10 = Divide by 4 + + bits 8:9 + Decoder vertical UV output size divider + 00 = No divide + 01 = Divide by 2 + 10 = Divide by 4 + -------------------------------------------------------------------------------- + 2970 + bit 0 + Decoder ?? unknown + 0 = Normal + 1 = Affect video output levels + + bit 16 + Decoder ?? unknown + 0 = Normal + 1 = Disable vertical filter + + -------------------------------------------------------------------------------- + 2974 -------- ?? unknown + | + V + 29EF -------- ?? unknown + -------------------------------------------------------------------------------- + 2A00 + bits 0:2 + osd colour mode + 000 = 8 bit indexed + 001 = 16 bit (565) + 010 = 15 bit (555) + 011 = 12 bit (444) + 100 = 32 bit (8888) + + bits 4:5 + osd display bpp + 01 = 8 bit + 10 = 16 bit + 11 = 32 bit + + bit 8 + osd global alpha + 0 = Off + 1 = On + + bit 9 + osd local alpha + 0 = Off + 1 = On + + bit 10 + osd colour key + 0 = Off + 1 = On + + bit 11 + osd ?? unknown + Must be 1 + + bit 13 + osd colour space + 0 = ARGB + 1 = AYVU + + bits 16:31 + osd ?? unknown + Must be 0x001B (some kind of buffer pointer ?) + + When the bits-per-pixel is set to 8, the colour mode is ignored and + assumed to be 8 bit indexed. For 16 & 32 bits-per-pixel the colour depth + is honoured, and when using a colour depth that requires fewer bytes than + allocated the extra bytes are used as padding. So for a 32 bpp with 8 bit + index colour, there are 3 padding bytes per pixel. It's also possible to + select 16bpp with a 32 bit colour mode. This results in the pixel width + being doubled, but the color key will not work as expected in this mode. + + Colour key is as it suggests. You designate a colour which will become + completely transparent. When using 565, 555 or 444 colour modes, the + colour key is always 16 bits wide. The colour to key on is set in Reg 2A18. + + Local alpha works differently depending on the colour mode. For 32bpp & 8 + bit indexed, local alpha is a per-pixel 256 step transparency, with 0 being + transparent and 255 being solid. For the 16bpp modes 555 & 444, the unused + bit(s) act as a simple transparency switch, with 0 being solid & 1 being + fully transparent. There is no local alpha support for 16bit 565. + + Global alpha is a 256 step transparency that applies to the entire osd, + with 0 being transparent & 255 being solid. + + It's possible to combine colour key, local alpha & global alpha. + -------------------------------------------------------------------------------- + 2A04 + bits 0:15 + osd x coord for left edge + + bits 16:31 + osd y coord for top edge + --------------- + 2A08 + bits 0:15 + osd x coord for right edge + + bits 16:31 + osd y coord for bottom edge + + For both registers, (0,0) = top left corner of the display area. These + registers do not control the osd size, only where it's positioned & how + much is visible. The visible osd area cannot exceed the right edge of the + display, otherwise the osd will become corrupt. See reg 2A10 for + setting osd width. + -------------------------------------------------------------------------------- + 2A0C + bits 0:31 + osd buffer index + + An index into the osd buffer. Slowly incrementing this moves the osd left, + wrapping around onto the right edge + -------------------------------------------------------------------------------- + 2A10 + bits 0:11 + osd buffer 32 bit word width + + Contains the width of the osd measured in 32 bit words. This means that all + colour modes are restricted to a byte width which is divisible by 4. + -------------------------------------------------------------------------------- + 2A14 + bits 0:15 + osd height in pixels + + bits 16:32 + osd line index into buffer + osd will start displaying from this line. + -------------------------------------------------------------------------------- + 2A18 + bits 0:31 + osd colour key + + Contains the colour value which will be transparent. + -------------------------------------------------------------------------------- + 2A1C + bits 0:7 + osd global alpha + + Contains the global alpha value (equiv ivtvfbctl --alpha XX) + -------------------------------------------------------------------------------- + 2A20 -------- ?? unknown + | + V + 2A2C -------- ?? unknown + -------------------------------------------------------------------------------- + 2A30 + bits 0:7 + osd colour to change in indexed palette + --------------- + 2A34 + bits 0:31 + osd colour for indexed palette + + To set the new palette, first load the index of the colour to change into + 2A30, then load the new colour into 2A34. The full palette is 256 colours, + so the index range is 0x00-0xFF + -------------------------------------------------------------------------------- + 2A38 -------- ?? unknown + 2A3C -------- ?? unknown + -------------------------------------------------------------------------------- + 2A40 + bits 0:31 + osd ?? unknown + + Affects overall brightness, wrapping around to black + -------------------------------------------------------------------------------- + 2A44 + bits 0:31 + osd ?? unknown + + Green tint + -------------------------------------------------------------------------------- + 2A48 + bits 0:31 + osd ?? unknown + + Red tint + -------------------------------------------------------------------------------- + 2A4C + bits 0:31 + osd ?? unknown + + Affects overall brightness, wrapping around to black + -------------------------------------------------------------------------------- + 2A50 + bits 0:31 + osd ?? unknown + + Colour shift + -------------------------------------------------------------------------------- + 2A54 + bits 0:31 + osd ?? unknown + + Colour shift + -------------------------------------------------------------------------------- + 2A58 -------- ?? unknown + | + V + 2AFC -------- ?? unknown + -------------------------------------------------------------------------------- + 2B00 + bit 0 + osd filter control + 0 = filter off + 1 = filter on + + bits 1:4 + osd ?? unknown + + -------------------------------------------------------------------------------- + +The cx231xx DMA engine +---------------------- + + +This page describes the structures and procedures used by the cx2341x DMA +engine. + +Introduction +~~~~~~~~~~~~ + +The cx2341x PCI interface is busmaster capable. This means it has a DMA +engine to efficiently transfer large volumes of data between the card and main +memory without requiring help from a CPU. Like most hardware, it must operate +on contiguous physical memory. This is difficult to come by in large quantities +on virtual memory machines. + +Therefore, it also supports a technique called "scatter-gather". The card can +transfer multiple buffers in one operation. Instead of allocating one large +contiguous buffer, the driver can allocate several smaller buffers. + +In practice, I've seen the average transfer to be roughly 80K, but transfers +above 128K were not uncommon, particularly at startup. The 128K figure is +important, because that is the largest block that the kernel can normally +allocate. Even still, 128K blocks are hard to come by, so the driver writer is +urged to choose a smaller block size and learn the scatter-gather technique. + +Mailbox #10 is reserved for DMA transfer information. + +Note: the hardware expects little-endian data ('intel format'). + +Flow +~~~~ + +This section describes, in general, the order of events when handling DMA +transfers. Detailed information follows this section. + +- The card raises the Encoder interrupt. +- The driver reads the transfer type, offset and size from Mailbox #10. +- The driver constructs the scatter-gather array from enough free dma buffers + to cover the size. +- The driver schedules the DMA transfer via the ScheduleDMAtoHost API call. +- The card raises the DMA Complete interrupt. +- The driver checks the DMA status register for any errors. +- The driver post-processes the newly transferred buffers. + +NOTE! It is possible that the Encoder and DMA Complete interrupts get raised +simultaneously. (End of the last, start of the next, etc.) + +Mailbox #10 +~~~~~~~~~~~ + +The Flags, Command, Return Value and Timeout fields are ignored. + +- Name: Mailbox #10 +- Results[0]: Type: 0: MPEG. +- Results[1]: Offset: The position relative to the card's memory space. +- Results[2]: Size: The exact number of bytes to transfer. + +My speculation is that since the StartCapture API has a capture type of "RAW" +available, that the type field will have other values that correspond to YUV +and PCM data. + +Scatter-Gather Array +~~~~~~~~~~~~~~~~~~~~ + +The scatter-gather array is a contiguously allocated block of memory that +tells the card the source and destination of each data-block to transfer. +Card "addresses" are derived from the offset supplied by Mailbox #10. Host +addresses are the physical memory location of the target DMA buffer. + +Each S-G array element is a struct of three 32-bit words. The first word is +the source address, the second is the destination address. Both take up the +entire 32 bits. The lowest 18 bits of the third word is the transfer byte +count. The high-bit of the third word is the "last" flag. The last-flag tells +the card to raise the DMA_DONE interrupt. From hard personal experience, if +you forget to set this bit, the card will still "work" but the stream will +most likely get corrupted. + +The transfer count must be a multiple of 256. Therefore, the driver will need +to track how much data in the target buffer is valid and deal with it +accordingly. + +Array Element: + +- 32-bit Source Address +- 32-bit Destination Address +- 14-bit reserved (high bit is the last flag) +- 18-bit byte count + +DMA Transfer Status +~~~~~~~~~~~~~~~~~~~ + +Register 0x0004 holds the DMA Transfer Status: + +- bit 0: read completed +- bit 1: write completed +- bit 2: DMA read error +- bit 3: DMA write error +- bit 4: Scatter-Gather array error diff --git a/Documentation/media/v4l-drivers/cx2341x-uapi.rst b/Documentation/media/v4l-drivers/cx2341x-uapi.rst new file mode 100644 index 000000000000..8a7977af79d5 --- /dev/null +++ b/Documentation/media/v4l-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 + #include + #include + + 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 + + +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/cx2341x.rst b/Documentation/media/v4l-drivers/cx2341x.rst deleted file mode 100644 index 8ca37deb56b6..000000000000 --- a/Documentation/media/v4l-drivers/cx2341x.rst +++ /dev/null @@ -1,3860 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -The cx2341x driver -================== - -Memory at cx2341x chips ------------------------ - -This section describes the cx2341x memory map and documents some of the -register space. - -.. note:: the memory long words are little-endian ('intel format'). - -.. warning:: - - This information was figured out from searching through the memory - and registers, this information may not be correct and is certainly - not complete, and was not derived from anything more than searching - through the memory space with commands like: - - .. code-block:: none - - ivtvctl -O min=0x02000000,max=0x020000ff - - So take this as is, I'm always searching for more stuff, it's a large - register space :-). - -Memory Map -~~~~~~~~~~ - -The cx2341x exposes its entire 64M memory space to the PCI host via the PCI BAR0 -(Base Address Register 0). The addresses here are offsets relative to the -address held in BAR0. - -.. code-block:: none - - 0x00000000-0x00ffffff Encoder memory space - 0x00000000-0x0003ffff Encode.rom - ???-??? MPEG buffer(s) - ???-??? Raw video capture buffer(s) - ???-??? Raw audio capture buffer(s) - ???-??? Display buffers (6 or 9) - - 0x01000000-0x01ffffff Decoder memory space - 0x01000000-0x0103ffff Decode.rom - ???-??? MPEG buffers(s) - 0x0114b000-0x0115afff Audio.rom (deprecated?) - - 0x02000000-0x0200ffff Register Space - -Registers -~~~~~~~~~ - -The registers occupy the 64k space starting at the 0x02000000 offset from BAR0. -All of these registers are 32 bits wide. - -.. code-block:: none - - DMA Registers 0x000-0xff: - - 0x00 - Control: - 0=reset/cancel, 1=read, 2=write, 4=stop - 0x04 - DMA status: - 1=read busy, 2=write busy, 4=read error, 8=write error, 16=link list error - 0x08 - pci DMA pointer for read link list - 0x0c - pci DMA pointer for write link list - 0x10 - read/write DMA enable: - 1=read enable, 2=write enable - 0x14 - always 0xffffffff, if set any lower instability occurs, 0x00 crashes - 0x18 - ?? - 0x1c - always 0x20 or 32, smaller values slow down DMA transactions - 0x20 - always value of 0x780a010a - 0x24-0x3c - usually just random values??? - 0x40 - Interrupt status - 0x44 - Write a bit here and shows up in Interrupt status 0x40 - 0x48 - Interrupt Mask - 0x4C - always value of 0xfffdffff, - if changed to 0xffffffff DMA write interrupts break. - 0x50 - always 0xffffffff - 0x54 - always 0xffffffff (0x4c, 0x50, 0x54 seem like interrupt masks, are - 3 processors on chip, Java ones, VPU, SPU, APU, maybe these are the - interrupt masks???). - 0x60-0x7C - random values - 0x80 - first write linked list reg, for Encoder Memory addr - 0x84 - first write linked list reg, for pci memory addr - 0x88 - first write linked list reg, for length of buffer in memory addr - (|0x80000000 or this for last link) - 0x8c-0xdc - rest of write linked list reg, 8 sets of 3 total, DMA goes here - from linked list addr in reg 0x0c, firmware must push through or - something. - 0xe0 - first (and only) read linked list reg, for pci memory addr - 0xe4 - first (and only) read linked list reg, for Decoder memory addr - 0xe8 - first (and only) read linked list reg, for length of buffer - 0xec-0xff - Nothing seems to be in these registers, 0xec-f4 are 0x00000000. - -Memory locations for Encoder Buffers 0x700-0x7ff: - -These registers show offsets of memory locations pertaining to each -buffer area used for encoding, have to shift them by <<1 first. - -- 0x07F8: Encoder SDRAM refresh -- 0x07FC: Encoder SDRAM pre-charge - -Memory locations for Decoder Buffers 0x800-0x8ff: - -These registers show offsets of memory locations pertaining to each -buffer area used for decoding, have to shift them by <<1 first. - -- 0x08F8: Decoder SDRAM refresh -- 0x08FC: Decoder SDRAM pre-charge - -Other memory locations: - -- 0x2800: Video Display Module control -- 0x2D00: AO (audio output?) control -- 0x2D24: Bytes Flushed -- 0x7000: LSB I2C write clock bit (inverted) -- 0x7004: LSB I2C write data bit (inverted) -- 0x7008: LSB I2C read clock bit -- 0x700c: LSB I2C read data bit -- 0x9008: GPIO get input state -- 0x900c: GPIO set output state -- 0x9020: GPIO direction (Bit7 (GPIO 0..7) - 0:input, 1:output) -- 0x9050: SPU control -- 0x9054: Reset HW blocks -- 0x9058: VPU control -- 0xA018: Bit6: interrupt pending? -- 0xA064: APU command - - -Interrupt Status Register -~~~~~~~~~~~~~~~~~~~~~~~~~ - -The definition of the bits in the interrupt status register 0x0040, and the -interrupt mask 0x0048. If a bit is cleared in the mask, then we want our ISR to -execute. - -- bit 31 Encoder Start Capture -- bit 30 Encoder EOS -- bit 29 Encoder VBI capture -- bit 28 Encoder Video Input Module reset event -- bit 27 Encoder DMA complete -- bit 24 Decoder audio mode change detection event (through event notification) -- bit 22 Decoder data request -- bit 20 Decoder DMA complete -- bit 19 Decoder VBI re-insertion -- bit 18 Decoder DMA err (linked-list bad) - -Missing documentation ---------------------- - -- Encoder API post(?) -- Decoder API post(?) -- Decoder VTRACE event - - -The cx2341x firmware upload ---------------------------- - -This document describes how to upload the cx2341x firmware to the card. - -How to find -~~~~~~~~~~~ - -See the web pages of the various projects that uses this chip for information -on how to obtain the firmware. - -The firmware stored in a Windows driver can be detected as follows: - -- Each firmware image is 256k bytes. -- The 1st 32-bit word of the Encoder image is 0x0000da7 -- The 1st 32-bit word of the Decoder image is 0x00003a7 -- The 2nd 32-bit word of both images is 0xaa55bb66 - -How to load -~~~~~~~~~~~ - -- Issue the FWapi command to stop the encoder if it is running. Wait for the - command to complete. -- Issue the FWapi command to stop the decoder if it is running. Wait for the - command to complete. -- Issue the I2C command to the digitizer to stop emitting VSYNC events. -- Issue the FWapi command to halt the encoder's firmware. -- Sleep for 10ms. -- Issue the FWapi command to halt the decoder's firmware. -- Sleep for 10ms. -- Write 0x00000000 to register 0x2800 to stop the Video Display Module. -- Write 0x00000005 to register 0x2D00 to stop the AO (audio output?). -- Write 0x00000000 to register 0xA064 to ping? the APU. -- Write 0xFFFFFFFE to register 0x9058 to stop the VPU. -- Write 0xFFFFFFFF to register 0x9054 to reset the HW blocks. -- Write 0x00000001 to register 0x9050 to stop the SPU. -- Sleep for 10ms. -- Write 0x0000001A to register 0x07FC to init the Encoder SDRAM's pre-charge. -- Write 0x80000640 to register 0x07F8 to init the Encoder SDRAM's refresh to 1us. -- Write 0x0000001A to register 0x08FC to init the Decoder SDRAM's pre-charge. -- Write 0x80000640 to register 0x08F8 to init the Decoder SDRAM's refresh to 1us. -- Sleep for 512ms. (600ms is recommended) -- Transfer the encoder's firmware image to offset 0 in Encoder memory space. -- Transfer the decoder's firmware image to offset 0 in Decoder memory space. -- Use a read-modify-write operation to Clear bit 0 of register 0x9050 to - re-enable the SPU. -- Sleep for 1 second. -- Use a read-modify-write operation to Clear bits 3 and 0 of register 0x9058 - to re-enable the VPU. -- Sleep for 1 second. -- Issue status API commands to both firmware images to verify. - - -How to call the firmware API ----------------------------- - -The preferred calling convention is known as the firmware mailbox. The -mailboxes are basically a fixed length array that serves as the call-stack. - -Firmware mailboxes can be located by searching the encoder and decoder memory -for a 16 byte signature. That signature will be located on a 256-byte boundary. - -Signature: - -.. code-block:: none - - 0x78, 0x56, 0x34, 0x12, 0x12, 0x78, 0x56, 0x34, - 0x34, 0x12, 0x78, 0x56, 0x56, 0x34, 0x12, 0x78 - -The firmware implements 20 mailboxes of 20 32-bit words. The first 10 are -reserved for API calls. The second 10 are used by the firmware for event -notification. - - ====== ================= - Index Name - ====== ================= - 0 Flags - 1 Command - 2 Return value - 3 Timeout - 4-19 Parameter/Result - ====== ================= - - -The flags are defined in the following table. The direction is from the -perspective of the firmware. - - ==== ========== ============================================ - Bit Direction Purpose - ==== ========== ============================================ - 2 O Firmware has processed the command. - 1 I Driver has finished setting the parameters. - 0 I Driver is using this mailbox. - ==== ========== ============================================ - -The command is a 32-bit enumerator. The API specifics may be found in this -chapter. - -The return value is a 32-bit enumerator. Only two values are currently defined: - -- 0=success -- -1=command undefined. - -There are 16 parameters/results 32-bit fields. The driver populates these fields -with values for all the parameters required by the call. The driver overwrites -these fields with result values returned by the call. - -The timeout value protects the card from a hung driver thread. If the driver -doesn't handle the completed call within the timeout specified, the firmware -will reset that mailbox. - -To make an API call, the driver iterates over each mailbox looking for the -first one available (bit 0 has been cleared). The driver sets that bit, fills -in the command enumerator, the timeout value and any required parameters. The -driver then sets the parameter ready bit (bit 1). The firmware scans the -mailboxes for pending commands, processes them, sets the result code, populates -the result value array with that call's return values and sets the call -complete bit (bit 2). Once bit 2 is set, the driver should retrieve the results -and clear all the flags. If the driver does not perform this task within the -time set in the timeout register, the firmware will reset that mailbox. - -Event notifications are sent from the firmware to the host. The host tells the -firmware which events it is interested in via an API call. That call tells the -firmware which notification mailbox to use. The firmware signals the host via -an interrupt. Only the 16 Results fields are used, the Flags, Command, Return -value and Timeout words are not used. - - -OSD firmware API description ----------------------------- - -.. note:: this API is part of the decoder firmware, so it's cx23415 only. - - - -CX2341X_OSD_GET_FRAMEBUFFER -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 65/0x41 - -Description -^^^^^^^^^^^ - -Return base and length of contiguous OSD memory. - -Result[0] -^^^^^^^^^ - -OSD base address - -Result[1] -^^^^^^^^^ - -OSD length - - - -CX2341X_OSD_GET_PIXEL_FORMAT -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 66/0x42 - -Description -^^^^^^^^^^^ - -Query OSD format - -Result[0] -^^^^^^^^^ - -0=8bit index -1=16bit RGB 5:6:5 -2=16bit ARGB 1:5:5:5 -3=16bit ARGB 1:4:4:4 -4=32bit ARGB 8:8:8:8 - - - -CX2341X_OSD_SET_PIXEL_FORMAT -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 67/0x43 - -Description -^^^^^^^^^^^ - -Assign pixel format - -Param[0] -^^^^^^^^ - -- 0=8bit index -- 1=16bit RGB 5:6:5 -- 2=16bit ARGB 1:5:5:5 -- 3=16bit ARGB 1:4:4:4 -- 4=32bit ARGB 8:8:8:8 - - - -CX2341X_OSD_GET_STATE -~~~~~~~~~~~~~~~~~~~~~ - -Enum: 68/0x44 - -Description -^^^^^^^^^^^ - -Query OSD state - -Result[0] -^^^^^^^^^ - -- Bit 0 0=off, 1=on -- Bits 1:2 alpha control -- Bits 3:5 pixel format - - - -CX2341X_OSD_SET_STATE -~~~~~~~~~~~~~~~~~~~~~ - -Enum: 69/0x45 - -Description -^^^^^^^^^^^ - -OSD switch - -Param[0] -^^^^^^^^ - -0=off, 1=on - - - -CX2341X_OSD_GET_OSD_COORDS -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 70/0x46 - -Description -^^^^^^^^^^^ - -Retrieve coordinates of OSD area blended with video - -Result[0] -^^^^^^^^^ - -OSD buffer address - -Result[1] -^^^^^^^^^ - -Stride in pixels - -Result[2] -^^^^^^^^^ - -Lines in OSD buffer - -Result[3] -^^^^^^^^^ - -Horizontal offset in buffer - -Result[4] -^^^^^^^^^ - -Vertical offset in buffer - - - -CX2341X_OSD_SET_OSD_COORDS -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 71/0x47 - -Description -^^^^^^^^^^^ - -Assign the coordinates of the OSD area to blend with video - -Param[0] -^^^^^^^^ - -buffer address - -Param[1] -^^^^^^^^ - -buffer stride in pixels - -Param[2] -^^^^^^^^ - -lines in buffer - -Param[3] -^^^^^^^^ - -horizontal offset - -Param[4] -^^^^^^^^ - -vertical offset - - - -CX2341X_OSD_GET_SCREEN_COORDS -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 72/0x48 - -Description -^^^^^^^^^^^ - -Retrieve OSD screen area coordinates - -Result[0] -^^^^^^^^^ - -top left horizontal offset - -Result[1] -^^^^^^^^^ - -top left vertical offset - -Result[2] -^^^^^^^^^ - -bottom right horizontal offset - -Result[3] -^^^^^^^^^ - -bottom right vertical offset - - - -CX2341X_OSD_SET_SCREEN_COORDS -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 73/0x49 - -Description -^^^^^^^^^^^ - -Assign the coordinates of the screen area to blend with video - -Param[0] -^^^^^^^^ - -top left horizontal offset - -Param[1] -^^^^^^^^ - -top left vertical offset - -Param[2] -^^^^^^^^ - -bottom left horizontal offset - -Param[3] -^^^^^^^^ - -bottom left vertical offset - - - -CX2341X_OSD_GET_GLOBAL_ALPHA -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 74/0x4A - -Description -^^^^^^^^^^^ - -Retrieve OSD global alpha - -Result[0] -^^^^^^^^^ - -global alpha: 0=off, 1=on - -Result[1] -^^^^^^^^^ - -bits 0:7 global alpha - - - -CX2341X_OSD_SET_GLOBAL_ALPHA -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 75/0x4B - -Description -^^^^^^^^^^^ - -Update global alpha - -Param[0] -^^^^^^^^ - -global alpha: 0=off, 1=on - -Param[1] -^^^^^^^^ - -global alpha (8 bits) - -Param[2] -^^^^^^^^ - -local alpha: 0=on, 1=off - - - -CX2341X_OSD_SET_BLEND_COORDS -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 78/0x4C - -Description -^^^^^^^^^^^ - -Move start of blending area within display buffer - -Param[0] -^^^^^^^^ - -horizontal offset in buffer - -Param[1] -^^^^^^^^ - -vertical offset in buffer - - - -CX2341X_OSD_GET_FLICKER_STATE -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 79/0x4F - -Description -^^^^^^^^^^^ - -Retrieve flicker reduction module state - -Result[0] -^^^^^^^^^ - -flicker state: 0=off, 1=on - - - -CX2341X_OSD_SET_FLICKER_STATE -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 80/0x50 - -Description -^^^^^^^^^^^ - -Set flicker reduction module state - -Param[0] -^^^^^^^^ - -State: 0=off, 1=on - - - -CX2341X_OSD_BLT_COPY -~~~~~~~~~~~~~~~~~~~~ - -Enum: 82/0x52 - -Description -^^^^^^^^^^^ - -BLT copy - -Param[0] -^^^^^^^^ - -.. code-block:: none - - '0000' zero - '0001' ~destination AND ~source - '0010' ~destination AND source - '0011' ~destination - '0100' destination AND ~source - '0101' ~source - '0110' destination XOR source - '0111' ~destination OR ~source - '1000' ~destination AND ~source - '1001' destination XNOR source - '1010' source - '1011' ~destination OR source - '1100' destination - '1101' destination OR ~source - '1110' destination OR source - '1111' one - - -Param[1] -^^^^^^^^ - -Resulting alpha blending - -- '01' source_alpha -- '10' destination_alpha -- '11' source_alpha*destination_alpha+1 - (zero if both source and destination alpha are zero) - -Param[2] -^^^^^^^^ - -.. code-block:: none - - '00' output_pixel = source_pixel - - '01' if source_alpha=0: - output_pixel = destination_pixel - if 256 > source_alpha > 1: - output_pixel = ((source_alpha + 1)*source_pixel + - (255 - source_alpha)*destination_pixel)/256 - - '10' if destination_alpha=0: - output_pixel = source_pixel - if 255 > destination_alpha > 0: - output_pixel = ((255 - destination_alpha)*source_pixel + - (destination_alpha + 1)*destination_pixel)/256 - - '11' if source_alpha=0: - source_temp = 0 - if source_alpha=255: - source_temp = source_pixel*256 - if 255 > source_alpha > 0: - source_temp = source_pixel*(source_alpha + 1) - if destination_alpha=0: - destination_temp = 0 - if destination_alpha=255: - destination_temp = destination_pixel*256 - if 255 > destination_alpha > 0: - destination_temp = destination_pixel*(destination_alpha + 1) - output_pixel = (source_temp + destination_temp)/256 - -Param[3] -^^^^^^^^ - -width - -Param[4] -^^^^^^^^ - -height - -Param[5] -^^^^^^^^ - -destination pixel mask - -Param[6] -^^^^^^^^ - -destination rectangle start address - -Param[7] -^^^^^^^^ - -destination stride in dwords - -Param[8] -^^^^^^^^ - -source stride in dwords - -Param[9] -^^^^^^^^ - -source rectangle start address - - - -CX2341X_OSD_BLT_FILL -~~~~~~~~~~~~~~~~~~~~ - -Enum: 83/0x53 - -Description -^^^^^^^^^^^ - -BLT fill color - -Param[0] -^^^^^^^^ - -Same as Param[0] on API 0x52 - -Param[1] -^^^^^^^^ - -Same as Param[1] on API 0x52 - -Param[2] -^^^^^^^^ - -Same as Param[2] on API 0x52 - -Param[3] -^^^^^^^^ - -width - -Param[4] -^^^^^^^^ - -height - -Param[5] -^^^^^^^^ - -destination pixel mask - -Param[6] -^^^^^^^^ - -destination rectangle start address - -Param[7] -^^^^^^^^ - -destination stride in dwords - -Param[8] -^^^^^^^^ - -color fill value - - - -CX2341X_OSD_BLT_TEXT -~~~~~~~~~~~~~~~~~~~~ - -Enum: 84/0x54 - -Description -^^^^^^^^^^^ - -BLT for 8 bit alpha text source - -Param[0] -^^^^^^^^ - -Same as Param[0] on API 0x52 - -Param[1] -^^^^^^^^ - -Same as Param[1] on API 0x52 - -Param[2] -^^^^^^^^ - -Same as Param[2] on API 0x52 - -Param[3] -^^^^^^^^ - -width - -Param[4] -^^^^^^^^ - -height - -Param[5] -^^^^^^^^ - -destination pixel mask - -Param[6] -^^^^^^^^ - -destination rectangle start address - -Param[7] -^^^^^^^^ - -destination stride in dwords - -Param[8] -^^^^^^^^ - -source stride in dwords - -Param[9] -^^^^^^^^ - -source rectangle start address - -Param[10] -^^^^^^^^^ - -color fill value - - - -CX2341X_OSD_SET_FRAMEBUFFER_WINDOW -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 86/0x56 - -Description -^^^^^^^^^^^ - -Positions the main output window on the screen. The coordinates must be -such that the entire window fits on the screen. - -Param[0] -^^^^^^^^ - -window width - -Param[1] -^^^^^^^^ - -window height - -Param[2] -^^^^^^^^ - -top left window corner horizontal offset - -Param[3] -^^^^^^^^ - -top left window corner vertical offset - - - -CX2341X_OSD_SET_CHROMA_KEY -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 96/0x60 - -Description -^^^^^^^^^^^ - -Chroma key switch and color - -Param[0] -^^^^^^^^ - -state: 0=off, 1=on - -Param[1] -^^^^^^^^ - -color - - - -CX2341X_OSD_GET_ALPHA_CONTENT_INDEX -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 97/0x61 - -Description -^^^^^^^^^^^ - -Retrieve alpha content index - -Result[0] -^^^^^^^^^ - -alpha content index, Range 0:15 - - - -CX2341X_OSD_SET_ALPHA_CONTENT_INDEX -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 98/0x62 - -Description -^^^^^^^^^^^ - -Assign alpha content index - -Param[0] -^^^^^^^^ - -alpha content index, range 0:15 - - -Encoder firmware API description --------------------------------- - -CX2341X_ENC_PING_FW -~~~~~~~~~~~~~~~~~~~ - -Enum: 128/0x80 - -Description -^^^^^^^^^^^ - -Does nothing. Can be used to check if the firmware is responding. - - - -CX2341X_ENC_START_CAPTURE -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 129/0x81 - -Description -^^^^^^^^^^^ - -Commences the capture of video, audio and/or VBI data. All encoding -parameters must be initialized prior to this API call. Captures frames -continuously or until a predefined number of frames have been captured. - -Param[0] -^^^^^^^^ - -Capture stream type: - - - 0=MPEG - - 1=Raw - - 2=Raw passthrough - - 3=VBI - - -Param[1] -^^^^^^^^ - -Bitmask: - - - Bit 0 when set, captures YUV - - Bit 1 when set, captures PCM audio - - Bit 2 when set, captures VBI (same as param[0]=3) - - Bit 3 when set, the capture destination is the decoder - (same as param[0]=2) - - Bit 4 when set, the capture destination is the host - -.. note:: this parameter is only meaningful for RAW capture type. - - - -CX2341X_ENC_STOP_CAPTURE -~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 130/0x82 - -Description -^^^^^^^^^^^ - -Ends a capture in progress - -Param[0] -^^^^^^^^ - -- 0=stop at end of GOP (generates IRQ) -- 1=stop immediate (no IRQ) - -Param[1] -^^^^^^^^ - -Stream type to stop, see param[0] of API 0x81 - -Param[2] -^^^^^^^^ - -Subtype, see param[1] of API 0x81 - - - -CX2341X_ENC_SET_AUDIO_ID -~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 137/0x89 - -Description -^^^^^^^^^^^ - -Assigns the transport stream ID of the encoded audio stream - -Param[0] -^^^^^^^^ - -Audio Stream ID - - - -CX2341X_ENC_SET_VIDEO_ID -~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 139/0x8B - -Description -^^^^^^^^^^^ - -Set video transport stream ID - -Param[0] -^^^^^^^^ - -Video stream ID - - - -CX2341X_ENC_SET_PCR_ID -~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 141/0x8D - -Description -^^^^^^^^^^^ - -Assigns the transport stream ID for PCR packets - -Param[0] -^^^^^^^^ - -PCR Stream ID - - - -CX2341X_ENC_SET_FRAME_RATE -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 143/0x8F - -Description -^^^^^^^^^^^ - -Set video frames per second. Change occurs at start of new GOP. - -Param[0] -^^^^^^^^ - -- 0=30fps -- 1=25fps - - - -CX2341X_ENC_SET_FRAME_SIZE -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 145/0x91 - -Description -^^^^^^^^^^^ - -Select video stream encoding resolution. - -Param[0] -^^^^^^^^ - -Height in lines. Default 480 - -Param[1] -^^^^^^^^ - -Width in pixels. Default 720 - - - -CX2341X_ENC_SET_BIT_RATE -~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 149/0x95 - -Description -^^^^^^^^^^^ - -Assign average video stream bitrate. - -Param[0] -^^^^^^^^ - -0=variable bitrate, 1=constant bitrate - -Param[1] -^^^^^^^^ - -bitrate in bits per second - -Param[2] -^^^^^^^^ - -peak bitrate in bits per second, divided by 400 - -Param[3] -^^^^^^^^ - -Mux bitrate in bits per second, divided by 400. May be 0 (default). - -Param[4] -^^^^^^^^ - -Rate Control VBR Padding - -Param[5] -^^^^^^^^ - -VBV Buffer used by encoder - -.. note:: - - #) Param\[3\] and Param\[4\] seem to be always 0 - #) Param\[5\] doesn't seem to be used. - - - -CX2341X_ENC_SET_GOP_PROPERTIES -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 151/0x97 - -Description -^^^^^^^^^^^ - -Setup the GOP structure - -Param[0] -^^^^^^^^ - -GOP size (maximum is 34) - -Param[1] -^^^^^^^^ - -Number of B frames between the I and P frame, plus 1. -For example: IBBPBBPBBPBB --> GOP size: 12, number of B frames: 2+1 = 3 - -.. note:: - - GOP size must be a multiple of (B-frames + 1). - - - -CX2341X_ENC_SET_ASPECT_RATIO -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 153/0x99 - -Description -^^^^^^^^^^^ - -Sets the encoding aspect ratio. Changes in the aspect ratio take effect -at the start of the next GOP. - -Param[0] -^^^^^^^^ - -- '0000' forbidden -- '0001' 1:1 square -- '0010' 4:3 -- '0011' 16:9 -- '0100' 2.21:1 -- '0101' to '1111' reserved - - - -CX2341X_ENC_SET_DNR_FILTER_MODE -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 155/0x9B - -Description -^^^^^^^^^^^ - -Assign Dynamic Noise Reduction operating mode - -Param[0] -^^^^^^^^ - -Bit0: Spatial filter, set=auto, clear=manual -Bit1: Temporal filter, set=auto, clear=manual - -Param[1] -^^^^^^^^ - -Median filter: - -- 0=Disabled -- 1=Horizontal -- 2=Vertical -- 3=Horiz/Vert -- 4=Diagonal - - - -CX2341X_ENC_SET_DNR_FILTER_PROPS -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 157/0x9D - -Description -^^^^^^^^^^^ - -These Dynamic Noise Reduction filter values are only meaningful when -the respective filter is set to "manual" (See API 0x9B) - -Param[0] -^^^^^^^^ - -Spatial filter: default 0, range 0:15 - -Param[1] -^^^^^^^^ - -Temporal filter: default 0, range 0:31 - - - -CX2341X_ENC_SET_CORING_LEVELS -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 159/0x9F - -Description -^^^^^^^^^^^ - -Assign Dynamic Noise Reduction median filter properties. - -Param[0] -^^^^^^^^ - -Threshold above which the luminance median filter is enabled. -Default: 0, range 0:255 - -Param[1] -^^^^^^^^ - -Threshold below which the luminance median filter is enabled. -Default: 255, range 0:255 - -Param[2] -^^^^^^^^ - -Threshold above which the chrominance median filter is enabled. -Default: 0, range 0:255 - -Param[3] -^^^^^^^^ - -Threshold below which the chrominance median filter is enabled. -Default: 255, range 0:255 - - - -CX2341X_ENC_SET_SPATIAL_FILTER_TYPE -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 161/0xA1 - -Description -^^^^^^^^^^^ - -Assign spatial prefilter parameters - -Param[0] -^^^^^^^^ - -Luminance filter - -- 0=Off -- 1=1D Horizontal -- 2=1D Vertical -- 3=2D H/V Separable (default) -- 4=2D Symmetric non-separable - -Param[1] -^^^^^^^^ - -Chrominance filter - -- 0=Off -- 1=1D Horizontal (default) - - - -CX2341X_ENC_SET_VBI_LINE -~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 183/0xB7 - -Description -^^^^^^^^^^^ - -Selects VBI line number. - -Param[0] -^^^^^^^^ - -- Bits 0:4 line number -- Bit 31 0=top_field, 1=bottom_field -- Bits 0:31 all set specifies "all lines" - -Param[1] -^^^^^^^^ - -VBI line information features: 0=disabled, 1=enabled - -Param[2] -^^^^^^^^ - -Slicing: 0=None, 1=Closed Caption -Almost certainly not implemented. Set to 0. - -Param[3] -^^^^^^^^ - -Luminance samples in this line. -Almost certainly not implemented. Set to 0. - -Param[4] -^^^^^^^^ - -Chrominance samples in this line -Almost certainly not implemented. Set to 0. - - - -CX2341X_ENC_SET_STREAM_TYPE -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 185/0xB9 - -Description -^^^^^^^^^^^ - -Assign stream type - -.. note:: - - Transport stream is not working in recent firmwares. - And in older firmwares the timestamps in the TS seem to be - unreliable. - -Param[0] -^^^^^^^^ - -- 0=Program stream -- 1=Transport stream -- 2=MPEG1 stream -- 3=PES A/V stream -- 5=PES Video stream -- 7=PES Audio stream -- 10=DVD stream -- 11=VCD stream -- 12=SVCD stream -- 13=DVD_S1 stream -- 14=DVD_S2 stream - - - -CX2341X_ENC_SET_OUTPUT_PORT -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 187/0xBB - -Description -^^^^^^^^^^^ - -Assign stream output port. Normally 0 when the data is copied through -the PCI bus (DMA), and 1 when the data is streamed to another chip -(pvrusb and cx88-blackbird). - -Param[0] -^^^^^^^^ - -- 0=Memory (default) -- 1=Streaming -- 2=Serial - -Param[1] -^^^^^^^^ - -Unknown, but leaving this to 0 seems to work best. Indications are that -this might have to do with USB support, although passing anything but 0 -only breaks things. - - - -CX2341X_ENC_SET_AUDIO_PROPERTIES -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 189/0xBD - -Description -^^^^^^^^^^^ - -Set audio stream properties, may be called while encoding is in progress. - -.. note:: - - All bitfields are consistent with ISO11172 documentation except - bits 2:3 which ISO docs define as: - - - '11' Layer I - - '10' Layer II - - '01' Layer III - - '00' Undefined - - This discrepancy may indicate a possible error in the documentation. - Testing indicated that only Layer II is actually working, and that - the minimum bitrate should be 192 kbps. - -Param[0] -^^^^^^^^ - -Bitmask: - -.. code-block:: none - - 0:1 '00' 44.1Khz - '01' 48Khz - '10' 32Khz - '11' reserved - - 2:3 '01'=Layer I - '10'=Layer II - - 4:7 Bitrate: - Index | Layer I | Layer II - ------+-------------+------------ - '0000' | free format | free format - '0001' | 32 kbit/s | 32 kbit/s - '0010' | 64 kbit/s | 48 kbit/s - '0011' | 96 kbit/s | 56 kbit/s - '0100' | 128 kbit/s | 64 kbit/s - '0101' | 160 kbit/s | 80 kbit/s - '0110' | 192 kbit/s | 96 kbit/s - '0111' | 224 kbit/s | 112 kbit/s - '1000' | 256 kbit/s | 128 kbit/s - '1001' | 288 kbit/s | 160 kbit/s - '1010' | 320 kbit/s | 192 kbit/s - '1011' | 352 kbit/s | 224 kbit/s - '1100' | 384 kbit/s | 256 kbit/s - '1101' | 416 kbit/s | 320 kbit/s - '1110' | 448 kbit/s | 384 kbit/s - - .. note:: - - For Layer II, not all combinations of total bitrate - and mode are allowed. See ISO11172-3 3-Annex B, - Table 3-B.2 - - 8:9 '00'=Stereo - '01'=JointStereo - '10'=Dual - '11'=Mono - - .. note:: - - The cx23415 cannot decode Joint Stereo properly. - - 10:11 Mode Extension used in joint_stereo mode. - In Layer I and II they indicate which subbands are in - intensity_stereo. All other subbands are coded in stereo. - '00' subbands 4-31 in intensity_stereo, bound==4 - '01' subbands 8-31 in intensity_stereo, bound==8 - '10' subbands 12-31 in intensity_stereo, bound==12 - '11' subbands 16-31 in intensity_stereo, bound==16 - - 12:13 Emphasis: - '00' None - '01' 50/15uS - '10' reserved - '11' CCITT J.17 - - 14 CRC: - '0' off - '1' on - - 15 Copyright: - '0' off - '1' on - - 16 Generation: - '0' copy - '1' original - - - -CX2341X_ENC_HALT_FW -~~~~~~~~~~~~~~~~~~~ - -Enum: 195/0xC3 - -Description -^^^^^^^^^^^ - -The firmware is halted and no further API calls are serviced until the -firmware is uploaded again. - - - -CX2341X_ENC_GET_VERSION -~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 196/0xC4 - -Description -^^^^^^^^^^^ - -Returns the version of the encoder firmware. - -Result[0] -^^^^^^^^^ - -Version bitmask: -- Bits 0:15 build -- Bits 16:23 minor -- Bits 24:31 major - - - -CX2341X_ENC_SET_GOP_CLOSURE -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 197/0xC5 - -Description -^^^^^^^^^^^ - -Assigns the GOP open/close property. - -Param[0] -^^^^^^^^ - -- 0=Open -- 1=Closed - - - -CX2341X_ENC_GET_SEQ_END -~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 198/0xC6 - -Description -^^^^^^^^^^^ - -Obtains the sequence end code of the encoder's buffer. When a capture -is started a number of interrupts are still generated, the last of -which will have Result[0] set to 1 and Result[1] will contain the size -of the buffer. - -Result[0] -^^^^^^^^^ - -State of the transfer (1 if last buffer) - -Result[1] -^^^^^^^^^ - -If Result[0] is 1, this contains the size of the last buffer, undefined -otherwise. - - - -CX2341X_ENC_SET_PGM_INDEX_INFO -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 199/0xC7 - -Description -^^^^^^^^^^^ - -Sets the Program Index Information. -The information is stored as follows: - -.. code-block:: c - - struct info { - u32 length; // Length of this frame - u32 offset_low; // Offset in the file of the - u32 offset_high; // start of this frame - u32 mask1; // Bits 0-2 are the type mask: - // 1=I, 2=P, 4=B - // 0=End of Program Index, other fields - // are invalid. - u32 pts; // The PTS of the frame - u32 mask2; // Bit 0 is bit 32 of the pts. - }; - u32 table_ptr; - struct info index[400]; - -The table_ptr is the encoder memory address in the table were -*new* entries will be written. - -.. note:: This is a ringbuffer, so the table_ptr will wraparound. - -Param[0] -^^^^^^^^ - -Picture Mask: -- 0=No index capture -- 1=I frames -- 3=I,P frames -- 7=I,P,B frames - -(Seems to be ignored, it always indexes I, P and B frames) - -Param[1] -^^^^^^^^ - -Elements requested (up to 400) - -Result[0] -^^^^^^^^^ - -Offset in the encoder memory of the start of the table. - -Result[1] -^^^^^^^^^ - -Number of allocated elements up to a maximum of Param[1] - - - -CX2341X_ENC_SET_VBI_CONFIG -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 200/0xC8 - -Description -^^^^^^^^^^^ - -Configure VBI settings - -Param[0] -^^^^^^^^ - -Bitmap: - -.. code-block:: none - - 0 Mode '0' Sliced, '1' Raw - 1:3 Insertion: - '000' insert in extension & user data - '001' insert in private packets - '010' separate stream and user data - '111' separate stream and private data - 8:15 Stream ID (normally 0xBD) - -Param[1] -^^^^^^^^ - -Frames per interrupt (max 8). Only valid in raw mode. - -Param[2] -^^^^^^^^ - -Total raw VBI frames. Only valid in raw mode. - -Param[3] -^^^^^^^^ - -Start codes - -Param[4] -^^^^^^^^ - -Stop codes - -Param[5] -^^^^^^^^ - -Lines per frame - -Param[6] -^^^^^^^^ - -Byte per line - -Result[0] -^^^^^^^^^ - -Observed frames per interrupt in raw mode only. Rage 1 to Param[1] - -Result[1] -^^^^^^^^^ - -Observed number of frames in raw mode. Range 1 to Param[2] - -Result[2] -^^^^^^^^^ - -Memory offset to start or raw VBI data - - - -CX2341X_ENC_SET_DMA_BLOCK_SIZE -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 201/0xC9 - -Description -^^^^^^^^^^^ - -Set DMA transfer block size - -Param[0] -^^^^^^^^ - -DMA transfer block size in bytes or frames. When unit is bytes, -supported block sizes are 2^7, 2^8 and 2^9 bytes. - -Param[1] -^^^^^^^^ - -Unit: 0=bytes, 1=frames - - - -CX2341X_ENC_GET_PREV_DMA_INFO_MB_10 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 202/0xCA - -Description -^^^^^^^^^^^ - -Returns information on the previous DMA transfer in conjunction with -bit 27 of the interrupt mask. Uses mailbox 10. - -Result[0] -^^^^^^^^^ - -Type of stream - -Result[1] -^^^^^^^^^ - -Address Offset - -Result[2] -^^^^^^^^^ - -Maximum size of transfer - - - -CX2341X_ENC_GET_PREV_DMA_INFO_MB_9 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 203/0xCB - -Description -^^^^^^^^^^^ - -Returns information on the previous DMA transfer in conjunction with -bit 27 or 18 of the interrupt mask. Uses mailbox 9. - -Result[0] -^^^^^^^^^ - -Status bits: -- 0 read completed -- 1 write completed -- 2 DMA read error -- 3 DMA write error -- 4 Scatter-Gather array error - -Result[1] -^^^^^^^^^ - -DMA type - -Result[2] -^^^^^^^^^ - -Presentation Time Stamp bits 0..31 - -Result[3] -^^^^^^^^^ - -Presentation Time Stamp bit 32 - - - -CX2341X_ENC_SCHED_DMA_TO_HOST -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 204/0xCC - -Description -^^^^^^^^^^^ - -Setup DMA to host operation - -Param[0] -^^^^^^^^ - -Memory address of link list - -Param[1] -^^^^^^^^ - -Length of link list (wtf: what units ???) - -Param[2] -^^^^^^^^ - -DMA type (0=MPEG) - - - -CX2341X_ENC_INITIALIZE_INPUT -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 205/0xCD - -Description -^^^^^^^^^^^ - -Initializes the video input - - - -CX2341X_ENC_SET_FRAME_DROP_RATE -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 208/0xD0 - -Description -^^^^^^^^^^^ - -For each frame captured, skip specified number of frames. - -Param[0] -^^^^^^^^ - -Number of frames to skip - - - -CX2341X_ENC_PAUSE_ENCODER -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 210/0xD2 - -Description -^^^^^^^^^^^ - -During a pause condition, all frames are dropped instead of being encoded. - -Param[0] -^^^^^^^^ - -- 0=Pause encoding -- 1=Continue encoding - - - -CX2341X_ENC_REFRESH_INPUT -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 211/0xD3 - -Description -^^^^^^^^^^^ - -Refreshes the video input - - - -CX2341X_ENC_SET_COPYRIGHT -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 212/0xD4 - -Description -^^^^^^^^^^^ - -Sets stream copyright property - -Param[0] -^^^^^^^^ - - -- 0=Stream is not copyrighted -- 1=Stream is copyrighted - - - -CX2341X_ENC_SET_EVENT_NOTIFICATION -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 213/0xD5 - -Description -^^^^^^^^^^^ - -Setup firmware to notify the host about a particular event. Host must -unmask the interrupt bit. - -Param[0] -^^^^^^^^ - -Event (0=refresh encoder input) - -Param[1] -^^^^^^^^ - -Notification 0=disabled 1=enabled - -Param[2] -^^^^^^^^ - -Interrupt bit - -Param[3] -^^^^^^^^ - -Mailbox slot, -1 if no mailbox required. - - - -CX2341X_ENC_SET_NUM_VSYNC_LINES -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 214/0xD6 - -Description -^^^^^^^^^^^ - -Depending on the analog video decoder used, this assigns the number -of lines for field 1 and 2. - -Param[0] -^^^^^^^^ - -Field 1 number of lines: -- 0x00EF for SAA7114 -- 0x00F0 for SAA7115 -- 0x0105 for Micronas - -Param[1] -^^^^^^^^ - -Field 2 number of lines: -- 0x00EF for SAA7114 -- 0x00F0 for SAA7115 -- 0x0106 for Micronas - - - -CX2341X_ENC_SET_PLACEHOLDER -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 215/0xD7 - -Description -^^^^^^^^^^^ - -Provides a mechanism of inserting custom user data in the MPEG stream. - -Param[0] -^^^^^^^^ - -- 0=extension & user data -- 1=private packet with stream ID 0xBD - -Param[1] -^^^^^^^^ - -Rate at which to insert data, in units of frames (for private packet) -or GOPs (for ext. & user data) - -Param[2] -^^^^^^^^ - -Number of data DWORDs (below) to insert - -Param[3] -^^^^^^^^ - -Custom data 0 - -Param[4] -^^^^^^^^ - -Custom data 1 - -Param[5] -^^^^^^^^ - -Custom data 2 - -Param[6] -^^^^^^^^ - -Custom data 3 - -Param[7] -^^^^^^^^ - -Custom data 4 - -Param[8] -^^^^^^^^ - -Custom data 5 - -Param[9] -^^^^^^^^ - -Custom data 6 - -Param[10] -^^^^^^^^^ - -Custom data 7 - -Param[11] -^^^^^^^^^ - -Custom data 8 - - - -CX2341X_ENC_MUTE_VIDEO -~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 217/0xD9 - -Description -^^^^^^^^^^^ - -Video muting - -Param[0] -^^^^^^^^ - -Bit usage: - -.. code-block:: none - - 0 '0'=video not muted - '1'=video muted, creates frames with the YUV color defined below - 1:7 Unused - 8:15 V chrominance information - 16:23 U chrominance information - 24:31 Y luminance information - - - -CX2341X_ENC_MUTE_AUDIO -~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 218/0xDA - -Description -^^^^^^^^^^^ - -Audio muting - -Param[0] -^^^^^^^^ - -- 0=audio not muted -- 1=audio muted (produces silent mpeg audio stream) - - - -CX2341X_ENC_SET_VERT_CROP_LINE -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 219/0xDB - -Description -^^^^^^^^^^^ - -Something to do with 'Vertical Crop Line' - -Param[0] -^^^^^^^^ - -If saa7114 and raw VBI capture and 60 Hz, then set to 10001. -Else 0. - - - -CX2341X_ENC_MISC -~~~~~~~~~~~~~~~~ - -Enum: 220/0xDC - -Description -^^^^^^^^^^^ - -Miscellaneous actions. Not known for 100% what it does. It's really a -sort of ioctl call. The first parameter is a command number, the second -the value. - -Param[0] -^^^^^^^^ - -Command number: - -.. code-block:: none - - 1=set initial SCR value when starting encoding (works). - 2=set quality mode (apparently some test setting). - 3=setup advanced VIM protection handling. - Always 1 for the cx23416 and 0 for cx23415. - 4=generate DVD compatible PTS timestamps - 5=USB flush mode - 6=something to do with the quantization matrix - 7=set navigation pack insertion for DVD: adds 0xbf (private stream 2) - packets to the MPEG. The size of these packets is 2048 bytes (including - the header of 6 bytes: 0x000001bf + length). The payload is zeroed and - it is up to the application to fill them in. These packets are apparently - inserted every four frames. - 8=enable scene change detection (seems to be a failure) - 9=set history parameters of the video input module - 10=set input field order of VIM - 11=set quantization matrix - 12=reset audio interface after channel change or input switch (has no argument). - Needed for the cx2584x, not needed for the mspx4xx, but it doesn't seem to - do any harm calling it regardless. - 13=set audio volume delay - 14=set audio delay - - -Param[1] -^^^^^^^^ - -Command value. - -Decoder firmware API description --------------------------------- - -.. note:: this API is part of the decoder firmware, so it's cx23415 only. - - - -CX2341X_DEC_PING_FW -~~~~~~~~~~~~~~~~~~~ - -Enum: 0/0x00 - -Description -^^^^^^^^^^^ - -This API call does nothing. It may be used to check if the firmware -is responding. - - - -CX2341X_DEC_START_PLAYBACK -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 1/0x01 - -Description -^^^^^^^^^^^ - -Begin or resume playback. - -Param[0] -^^^^^^^^ - -0 based frame number in GOP to begin playback from. - -Param[1] -^^^^^^^^ - -Specifies the number of muted audio frames to play before normal -audio resumes. (This is not implemented in the firmware, leave at 0) - - - -CX2341X_DEC_STOP_PLAYBACK -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 2/0x02 - -Description -^^^^^^^^^^^ - -Ends playback and clears all decoder buffers. If PTS is not zero, -playback stops at specified PTS. - -Param[0] -^^^^^^^^ - -Display 0=last frame, 1=black - -.. note:: - - this takes effect immediately, so if you want to wait for a PTS, - then use '0', otherwise the screen goes to black at once. - You can call this later (even if there is no playback) with a 1 value - to set the screen to black. - -Param[1] -^^^^^^^^ - -PTS low - -Param[2] -^^^^^^^^ - -PTS high - - - -CX2341X_DEC_SET_PLAYBACK_SPEED -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 3/0x03 - -Description -^^^^^^^^^^^ - -Playback stream at speed other than normal. There are two modes of -operation: - - - Smooth: host transfers entire stream and firmware drops unused - frames. - - Coarse: host drops frames based on indexing as required to achieve - desired speed. - -Param[0] -^^^^^^^^ - -.. code-block:: none - - Bitmap: - 0:7 0 normal - 1 fast only "1.5 times" - n nX fast, 1/nX slow - 30 Framedrop: - '0' during 1.5 times play, every other B frame is dropped - '1' during 1.5 times play, stream is unchanged (bitrate - must not exceed 8mbps) - 31 Speed: - '0' slow - '1' fast - -.. note:: - - n is limited to 2. Anything higher does not result in - faster playback. Instead the host should start dropping frames. - -Param[1] -^^^^^^^^ - -Direction: 0=forward, 1=reverse - -.. note:: - - to make reverse playback work you have to write full GOPs in - reverse order. - -Param[2] -^^^^^^^^ - -.. code-block:: none - - Picture mask: - 1=I frames - 3=I, P frames - 7=I, P, B frames - -Param[3] -^^^^^^^^ - -B frames per GOP (for reverse play only) - -.. note:: - - for reverse playback the Picture Mask should be set to I or I, P. - Adding B frames to the mask will result in corrupt video. This field - has to be set to the correct value in order to keep the timing correct. - -Param[4] -^^^^^^^^ - -Mute audio: 0=disable, 1=enable - -Param[5] -^^^^^^^^ - -Display 0=frame, 1=field - -Param[6] -^^^^^^^^ - -Specifies the number of muted audio frames to play before normal audio -resumes. (Not implemented in the firmware, leave at 0) - - - -CX2341X_DEC_STEP_VIDEO -~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 5/0x05 - -Description -^^^^^^^^^^^ - -Each call to this API steps the playback to the next unit defined below -in the current playback direction. - -Param[0] -^^^^^^^^ - -0=frame, 1=top field, 2=bottom field - - - -CX2341X_DEC_SET_DMA_BLOCK_SIZE -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 8/0x08 - -Description -^^^^^^^^^^^ - -Set DMA transfer block size. Counterpart to API 0xC9 - -Param[0] -^^^^^^^^ - -DMA transfer block size in bytes. A different size may be specified -when issuing the DMA transfer command. - - - -CX2341X_DEC_GET_XFER_INFO -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 9/0x09 - -Description -^^^^^^^^^^^ - -This API call may be used to detect an end of stream condition. - -Result[0] -^^^^^^^^^ - -Stream type - -Result[1] -^^^^^^^^^ - -Address offset - -Result[2] -^^^^^^^^^ - -Maximum bytes to transfer - -Result[3] -^^^^^^^^^ - -Buffer fullness - - - -CX2341X_DEC_GET_DMA_STATUS -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 10/0x0A - -Description -^^^^^^^^^^^ - -Status of the last DMA transfer - -Result[0] -^^^^^^^^^ - -Bit 1 set means transfer complete -Bit 2 set means DMA error -Bit 3 set means linked list error - -Result[1] -^^^^^^^^^ - -DMA type: 0=MPEG, 1=OSD, 2=YUV - - - -CX2341X_DEC_SCHED_DMA_FROM_HOST -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 11/0x0B - -Description -^^^^^^^^^^^ - -Setup DMA from host operation. Counterpart to API 0xCC - -Param[0] -^^^^^^^^ - -Memory address of link list - -Param[1] -^^^^^^^^ - -Total # of bytes to transfer - -Param[2] -^^^^^^^^ - -DMA type (0=MPEG, 1=OSD, 2=YUV) - - - -CX2341X_DEC_PAUSE_PLAYBACK -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 13/0x0D - -Description -^^^^^^^^^^^ - -Freeze playback immediately. In this mode, when internal buffers are -full, no more data will be accepted and data request IRQs will be -masked. - -Param[0] -^^^^^^^^ - -Display: 0=last frame, 1=black - - - -CX2341X_DEC_HALT_FW -~~~~~~~~~~~~~~~~~~~ - -Enum: 14/0x0E - -Description -^^^^^^^^^^^ - -The firmware is halted and no further API calls are serviced until -the firmware is uploaded again. - - - -CX2341X_DEC_SET_STANDARD -~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 16/0x10 - -Description -^^^^^^^^^^^ - -Selects display standard - -Param[0] -^^^^^^^^ - -0=NTSC, 1=PAL - - - -CX2341X_DEC_GET_VERSION -~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 17/0x11 - -Description -^^^^^^^^^^^ - -Returns decoder firmware version information - -Result[0] -^^^^^^^^^ - -Version bitmask: - - Bits 0:15 build - - Bits 16:23 minor - - Bits 24:31 major - - - -CX2341X_DEC_SET_STREAM_INPUT -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 20/0x14 - -Description -^^^^^^^^^^^ - -Select decoder stream input port - -Param[0] -^^^^^^^^ - -0=memory (default), 1=streaming - - - -CX2341X_DEC_GET_TIMING_INFO -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 21/0x15 - -Description -^^^^^^^^^^^ - -Returns timing information from start of playback - -Result[0] -^^^^^^^^^ - -Frame count by decode order - -Result[1] -^^^^^^^^^ - -Video PTS bits 0:31 by display order - -Result[2] -^^^^^^^^^ - -Video PTS bit 32 by display order - -Result[3] -^^^^^^^^^ - -SCR bits 0:31 by display order - -Result[4] -^^^^^^^^^ - -SCR bit 32 by display order - - - -CX2341X_DEC_SET_AUDIO_MODE -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 22/0x16 - -Description -^^^^^^^^^^^ - -Select audio mode - -Param[0] -^^^^^^^^ - -Dual mono mode action - 0=Stereo, 1=Left, 2=Right, 3=Mono, 4=Swap, -1=Unchanged - -Param[1] -^^^^^^^^ - -Stereo mode action: - 0=Stereo, 1=Left, 2=Right, 3=Mono, 4=Swap, -1=Unchanged - - - -CX2341X_DEC_SET_EVENT_NOTIFICATION -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 23/0x17 - -Description -^^^^^^^^^^^ - -Setup firmware to notify the host about a particular event. -Counterpart to API 0xD5 - -Param[0] -^^^^^^^^ - -Event: - - 0=Audio mode change between mono, (joint) stereo and dual channel. - - 3=Decoder started - - 4=Unknown: goes off 10-15 times per second while decoding. - - 5=Some sync event: goes off once per frame. - -Param[1] -^^^^^^^^ - -Notification 0=disabled, 1=enabled - -Param[2] -^^^^^^^^ - -Interrupt bit - -Param[3] -^^^^^^^^ - -Mailbox slot, -1 if no mailbox required. - - - -CX2341X_DEC_SET_DISPLAY_BUFFERS -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 24/0x18 - -Description -^^^^^^^^^^^ - -Number of display buffers. To decode all frames in reverse playback you -must use nine buffers. - -Param[0] -^^^^^^^^ - -0=six buffers, 1=nine buffers - - - -CX2341X_DEC_EXTRACT_VBI -~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 25/0x19 - -Description -^^^^^^^^^^^ - -Extracts VBI data - -Param[0] -^^^^^^^^ - -0=extract from extension & user data, 1=extract from private packets - -Result[0] -^^^^^^^^^ - -VBI table location - -Result[1] -^^^^^^^^^ - -VBI table size - - - -CX2341X_DEC_SET_DECODER_SOURCE -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 26/0x1A - -Description -^^^^^^^^^^^ - -Selects decoder source. Ensure that the parameters passed to this -API match the encoder settings. - -Param[0] -^^^^^^^^ - -Mode: 0=MPEG from host, 1=YUV from encoder, 2=YUV from host - -Param[1] -^^^^^^^^ - -YUV picture width - -Param[2] -^^^^^^^^ - -YUV picture height - -Param[3] -^^^^^^^^ - -Bitmap: see Param[0] of API 0xBD - - - -CX2341X_DEC_SET_PREBUFFERING -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enum: 30/0x1E - -Description -^^^^^^^^^^^ - -Decoder prebuffering, when enabled up to 128KB are buffered for -streams <8mpbs or 640KB for streams >8mbps - -Param[0] -^^^^^^^^ - -0=off, 1=on - -PVR350 Video decoder registers 0x02002800 -> 0x02002B00 -------------------------------------------------------- - -Author: Ian Armstrong - -Version: v0.4 - -Date: 12 March 2007 - - -This list has been worked out through trial and error. There will be mistakes -and omissions. Some registers have no obvious effect so it's hard to say what -they do, while others interact with each other, or require a certain load -sequence. Horizontal filter setup is one example, with six registers working -in unison and requiring a certain load sequence to correctly configure. The -indexed colour palette is much easier to set at just two registers, but again -it requires a certain load sequence. - -Some registers are fussy about what they are set to. Load in a bad value & the -decoder will fail. A firmware reload will often recover, but sometimes a reset -is required. For registers containing size information, setting them to 0 is -generally a bad idea. For other control registers i.e. 2878, you'll only find -out what values are bad when it hangs. - -.. code-block:: none - - -------------------------------------------------------------------------------- - 2800 - bit 0 - Decoder enable - 0 = disable - 1 = enable - -------------------------------------------------------------------------------- - 2804 - bits 0:31 - Decoder horizontal Y alias register 1 - --------------- - 2808 - bits 0:31 - Decoder horizontal Y alias register 2 - --------------- - 280C - bits 0:31 - Decoder horizontal Y alias register 3 - --------------- - 2810 - bits 0:31 - Decoder horizontal Y alias register 4 - --------------- - 2814 - bits 0:31 - Decoder horizontal Y alias register 5 - --------------- - 2818 - bits 0:31 - Decoder horizontal Y alias trigger - - These six registers control the horizontal aliasing filter for the Y plane. - The first five registers must all be loaded before accessing the trigger - (2818), as this register actually clocks the data through for the first - five. - - To correctly program set the filter, this whole procedure must be done 16 - times. The actual register contents are copied from a lookup-table in the - firmware which contains 4 different filter settings. - - -------------------------------------------------------------------------------- - 281C - bits 0:31 - Decoder horizontal UV alias register 1 - --------------- - 2820 - bits 0:31 - Decoder horizontal UV alias register 2 - --------------- - 2824 - bits 0:31 - Decoder horizontal UV alias register 3 - --------------- - 2828 - bits 0:31 - Decoder horizontal UV alias register 4 - --------------- - 282C - bits 0:31 - Decoder horizontal UV alias register 5 - --------------- - 2830 - bits 0:31 - Decoder horizontal UV alias trigger - - These six registers control the horizontal aliasing for the UV plane. - Operation is the same as the Y filter, with 2830 being the trigger - register. - - -------------------------------------------------------------------------------- - 2834 - bits 0:15 - Decoder Y source width in pixels - - bits 16:31 - Decoder Y destination width in pixels - --------------- - 2838 - bits 0:15 - Decoder UV source width in pixels - - bits 16:31 - Decoder UV destination width in pixels - - NOTE: For both registers, the resulting image must be fully visible on - screen. If the image exceeds the right edge both the source and destination - size must be adjusted to reflect the visible portion. For the source width, - you must take into account the scaling when calculating the new value. - -------------------------------------------------------------------------------- - - 283C - bits 0:31 - Decoder Y horizontal scaling - Normally = Reg 2854 >> 2 - --------------- - 2840 - bits 0:31 - Decoder ?? unknown - horizontal scaling - Usually 0x00080514 - --------------- - 2844 - bits 0:31 - Decoder UV horizontal scaling - Normally = Reg 2854 >> 2 - --------------- - 2848 - bits 0:31 - Decoder ?? unknown - horizontal scaling - Usually 0x00100514 - --------------- - 284C - bits 0:31 - Decoder ?? unknown - Y plane - Usually 0x00200020 - --------------- - 2850 - bits 0:31 - Decoder ?? unknown - UV plane - Usually 0x00200020 - --------------- - 2854 - bits 0:31 - Decoder 'master' value for horizontal scaling - --------------- - 2858 - bits 0:31 - Decoder ?? unknown - Usually 0 - --------------- - 285C - bits 0:31 - Decoder ?? unknown - Normally = Reg 2854 >> 1 - --------------- - 2860 - bits 0:31 - Decoder ?? unknown - Usually 0 - --------------- - 2864 - bits 0:31 - Decoder ?? unknown - Normally = Reg 2854 >> 1 - --------------- - 2868 - bits 0:31 - Decoder ?? unknown - Usually 0 - - Most of these registers either control horizontal scaling, or appear linked - to it in some way. Register 2854 contains the 'master' value & the other - registers can be calculated from that one. You must also remember to - correctly set the divider in Reg 2874. - - To enlarge: - Reg 2854 = (source_width * 0x00200000) / destination_width - Reg 2874 = No divide - - To reduce from full size down to half size: - Reg 2854 = (source_width/2 * 0x00200000) / destination width - Reg 2874 = Divide by 2 - - To reduce from half size down to quarter size: - Reg 2854 = (source_width/4 * 0x00200000) / destination width - Reg 2874 = Divide by 4 - - The result is always rounded up. - - -------------------------------------------------------------------------------- - 286C - bits 0:15 - Decoder horizontal Y buffer offset - - bits 15:31 - Decoder horizontal UV buffer offset - - Offset into the video image buffer. If the offset is gradually incremented, - the on screen image will move left & wrap around higher up on the right. - - -------------------------------------------------------------------------------- - 2870 - bits 0:15 - Decoder horizontal Y output offset - - bits 16:31 - Decoder horizontal UV output offset - - Offsets the actual video output. Controls output alignment of the Y & UV - planes. The higher the value, the greater the shift to the left. Use - reg 2890 to move the image right. - - -------------------------------------------------------------------------------- - 2874 - bits 0:1 - Decoder horizontal Y output size divider - 00 = No divide - 01 = Divide by 2 - 10 = Divide by 3 - - bits 4:5 - Decoder horizontal UV output size divider - 00 = No divide - 01 = Divide by 2 - 10 = Divide by 3 - - bit 8 - Decoder ?? unknown - 0 = Normal - 1 = Affects video output levels - - bit 16 - Decoder ?? unknown - 0 = Normal - 1 = Disable horizontal filter - - -------------------------------------------------------------------------------- - 2878 - bit 0 - ?? unknown - - bit 1 - osd on/off - 0 = osd off - 1 = osd on - - bit 2 - Decoder + osd video timing - 0 = NTSC - 1 = PAL - - bits 3:4 - ?? unknown - - bit 5 - Decoder + osd - Swaps upper & lower fields - - -------------------------------------------------------------------------------- - 287C - bits 0:10 - Decoder & osd ?? unknown - Moves entire screen horizontally. Starts at 0x005 with the screen - shifted heavily to the right. Incrementing in steps of 0x004 will - gradually shift the screen to the left. - - bits 11:31 - ?? unknown - - Normally contents are 0x00101111 (NTSC) or 0x1010111d (PAL) - - -------------------------------------------------------------------------------- - 2880 -------- ?? unknown - 2884 -------- ?? unknown - -------------------------------------------------------------------------------- - 2888 - bit 0 - Decoder + osd ?? unknown - 0 = Normal - 1 = Misaligned fields (Correctable through 289C & 28A4) - - bit 4 - ?? unknown - - bit 8 - ?? unknown - - Warning: Bad values will require a firmware reload to recover. - Known to be bad are 0x000,0x011,0x100,0x111 - -------------------------------------------------------------------------------- - 288C - bits 0:15 - osd ?? unknown - Appears to affect the osd position stability. The higher the value the - more unstable it becomes. Decoder output remains stable. - - bits 16:31 - osd ?? unknown - Same as bits 0:15 - - -------------------------------------------------------------------------------- - 2890 - bits 0:11 - Decoder output horizontal offset. - - Horizontal offset moves the video image right. A small left shift is - possible, but it's better to use reg 2870 for that due to its greater - range. - - NOTE: Video corruption will occur if video window is shifted off the right - edge. To avoid this read the notes for 2834 & 2838. - -------------------------------------------------------------------------------- - 2894 - bits 0:23 - Decoder output video surround colour. - - Contains the colour (in yuv) used to fill the screen when the video is - running in a window. - -------------------------------------------------------------------------------- - 2898 - bits 0:23 - Decoder video window colour - Contains the colour (in yuv) used to fill the video window when the - video is turned off. - - bit 24 - Decoder video output - 0 = Video on - 1 = Video off - - bit 28 - Decoder plane order - 0 = Y,UV - 1 = UV,Y - - bit 29 - Decoder second plane byte order - 0 = Normal (UV) - 1 = Swapped (VU) - - In normal usage, the first plane is Y & the second plane is UV. Though the - order of the planes can be swapped, only the byte order of the second plane - can be swapped. This isn't much use for the Y plane, but can be useful for - the UV plane. - - -------------------------------------------------------------------------------- - 289C - bits 0:15 - Decoder vertical field offset 1 - - bits 16:31 - Decoder vertical field offset 2 - - Controls field output vertical alignment. The higher the number, the lower - the image on screen. Known starting values are 0x011E0017 (NTSC) & - 0x01500017 (PAL) - -------------------------------------------------------------------------------- - 28A0 - bits 0:15 - Decoder & osd width in pixels - - bits 16:31 - Decoder & osd height in pixels - - All output from the decoder & osd are disabled beyond this area. Decoder - output will simply go black outside of this region. If the osd tries to - exceed this area it will become corrupt. - -------------------------------------------------------------------------------- - 28A4 - bits 0:11 - osd left shift. - - Has a range of 0x770->0x7FF. With the exception of 0, any value outside of - this range corrupts the osd. - -------------------------------------------------------------------------------- - 28A8 - bits 0:15 - osd vertical field offset 1 - - bits 16:31 - osd vertical field offset 2 - - Controls field output vertical alignment. The higher the number, the lower - the image on screen. Known starting values are 0x011E0017 (NTSC) & - 0x01500017 (PAL) - -------------------------------------------------------------------------------- - 28AC -------- ?? unknown - | - V - 28BC -------- ?? unknown - -------------------------------------------------------------------------------- - 28C0 - bit 0 - Current output field - 0 = first field - 1 = second field - - bits 16:31 - Current scanline - The scanline counts from the top line of the first field - through to the last line of the second field. - -------------------------------------------------------------------------------- - 28C4 -------- ?? unknown - | - V - 28F8 -------- ?? unknown - -------------------------------------------------------------------------------- - 28FC - bit 0 - ?? unknown - 0 = Normal - 1 = Breaks decoder & osd output - -------------------------------------------------------------------------------- - 2900 - bits 0:31 - Decoder vertical Y alias register 1 - --------------- - 2904 - bits 0:31 - Decoder vertical Y alias register 2 - --------------- - 2908 - bits 0:31 - Decoder vertical Y alias trigger - - These three registers control the vertical aliasing filter for the Y plane. - Operation is similar to the horizontal Y filter (2804). The only real - difference is that there are only two registers to set before accessing - the trigger register (2908). As for the horizontal filter, the values are - taken from a lookup table in the firmware, and the procedure must be - repeated 16 times to fully program the filter. - -------------------------------------------------------------------------------- - 290C - bits 0:31 - Decoder vertical UV alias register 1 - --------------- - 2910 - bits 0:31 - Decoder vertical UV alias register 2 - --------------- - 2914 - bits 0:31 - Decoder vertical UV alias trigger - - These three registers control the vertical aliasing filter for the UV - plane. Operation is the same as the Y filter, with 2914 being the trigger. - -------------------------------------------------------------------------------- - 2918 - bits 0:15 - Decoder Y source height in pixels - - bits 16:31 - Decoder Y destination height in pixels - --------------- - 291C - bits 0:15 - Decoder UV source height in pixels divided by 2 - - bits 16:31 - Decoder UV destination height in pixels - - NOTE: For both registers, the resulting image must be fully visible on - screen. If the image exceeds the bottom edge both the source and - destination size must be adjusted to reflect the visible portion. For the - source height, you must take into account the scaling when calculating the - new value. - -------------------------------------------------------------------------------- - 2920 - bits 0:31 - Decoder Y vertical scaling - Normally = Reg 2930 >> 2 - --------------- - 2924 - bits 0:31 - Decoder Y vertical scaling - Normally = Reg 2920 + 0x514 - --------------- - 2928 - bits 0:31 - Decoder UV vertical scaling - When enlarging = Reg 2930 >> 2 - When reducing = Reg 2930 >> 3 - --------------- - 292C - bits 0:31 - Decoder UV vertical scaling - Normally = Reg 2928 + 0x514 - --------------- - 2930 - bits 0:31 - Decoder 'master' value for vertical scaling - --------------- - 2934 - bits 0:31 - Decoder ?? unknown - Y vertical scaling - --------------- - 2938 - bits 0:31 - Decoder Y vertical scaling - Normally = Reg 2930 - --------------- - 293C - bits 0:31 - Decoder ?? unknown - Y vertical scaling - --------------- - 2940 - bits 0:31 - Decoder UV vertical scaling - When enlarging = Reg 2930 >> 1 - When reducing = Reg 2930 - --------------- - 2944 - bits 0:31 - Decoder ?? unknown - UV vertical scaling - --------------- - 2948 - bits 0:31 - Decoder UV vertical scaling - Normally = Reg 2940 - --------------- - 294C - bits 0:31 - Decoder ?? unknown - UV vertical scaling - - Most of these registers either control vertical scaling, or appear linked - to it in some way. Register 2930 contains the 'master' value & all other - registers can be calculated from that one. You must also remember to - correctly set the divider in Reg 296C - - To enlarge: - Reg 2930 = (source_height * 0x00200000) / destination_height - Reg 296C = No divide - - To reduce from full size down to half size: - Reg 2930 = (source_height/2 * 0x00200000) / destination height - Reg 296C = Divide by 2 - - To reduce from half down to quarter. - Reg 2930 = (source_height/4 * 0x00200000) / destination height - Reg 296C = Divide by 4 - - -------------------------------------------------------------------------------- - 2950 - bits 0:15 - Decoder Y line index into display buffer, first field - - bits 16:31 - Decoder Y vertical line skip, first field - -------------------------------------------------------------------------------- - 2954 - bits 0:15 - Decoder Y line index into display buffer, second field - - bits 16:31 - Decoder Y vertical line skip, second field - -------------------------------------------------------------------------------- - 2958 - bits 0:15 - Decoder UV line index into display buffer, first field - - bits 16:31 - Decoder UV vertical line skip, first field - -------------------------------------------------------------------------------- - 295C - bits 0:15 - Decoder UV line index into display buffer, second field - - bits 16:31 - Decoder UV vertical line skip, second field - -------------------------------------------------------------------------------- - 2960 - bits 0:15 - Decoder destination height minus 1 - - bits 16:31 - Decoder destination height divided by 2 - -------------------------------------------------------------------------------- - 2964 - bits 0:15 - Decoder Y vertical offset, second field - - bits 16:31 - Decoder Y vertical offset, first field - - These two registers shift the Y plane up. The higher the number, the - greater the shift. - -------------------------------------------------------------------------------- - 2968 - bits 0:15 - Decoder UV vertical offset, second field - - bits 16:31 - Decoder UV vertical offset, first field - - These two registers shift the UV plane up. The higher the number, the - greater the shift. - -------------------------------------------------------------------------------- - 296C - bits 0:1 - Decoder vertical Y output size divider - 00 = No divide - 01 = Divide by 2 - 10 = Divide by 4 - - bits 8:9 - Decoder vertical UV output size divider - 00 = No divide - 01 = Divide by 2 - 10 = Divide by 4 - -------------------------------------------------------------------------------- - 2970 - bit 0 - Decoder ?? unknown - 0 = Normal - 1 = Affect video output levels - - bit 16 - Decoder ?? unknown - 0 = Normal - 1 = Disable vertical filter - - -------------------------------------------------------------------------------- - 2974 -------- ?? unknown - | - V - 29EF -------- ?? unknown - -------------------------------------------------------------------------------- - 2A00 - bits 0:2 - osd colour mode - 000 = 8 bit indexed - 001 = 16 bit (565) - 010 = 15 bit (555) - 011 = 12 bit (444) - 100 = 32 bit (8888) - - bits 4:5 - osd display bpp - 01 = 8 bit - 10 = 16 bit - 11 = 32 bit - - bit 8 - osd global alpha - 0 = Off - 1 = On - - bit 9 - osd local alpha - 0 = Off - 1 = On - - bit 10 - osd colour key - 0 = Off - 1 = On - - bit 11 - osd ?? unknown - Must be 1 - - bit 13 - osd colour space - 0 = ARGB - 1 = AYVU - - bits 16:31 - osd ?? unknown - Must be 0x001B (some kind of buffer pointer ?) - - When the bits-per-pixel is set to 8, the colour mode is ignored and - assumed to be 8 bit indexed. For 16 & 32 bits-per-pixel the colour depth - is honoured, and when using a colour depth that requires fewer bytes than - allocated the extra bytes are used as padding. So for a 32 bpp with 8 bit - index colour, there are 3 padding bytes per pixel. It's also possible to - select 16bpp with a 32 bit colour mode. This results in the pixel width - being doubled, but the color key will not work as expected in this mode. - - Colour key is as it suggests. You designate a colour which will become - completely transparent. When using 565, 555 or 444 colour modes, the - colour key is always 16 bits wide. The colour to key on is set in Reg 2A18. - - Local alpha works differently depending on the colour mode. For 32bpp & 8 - bit indexed, local alpha is a per-pixel 256 step transparency, with 0 being - transparent and 255 being solid. For the 16bpp modes 555 & 444, the unused - bit(s) act as a simple transparency switch, with 0 being solid & 1 being - fully transparent. There is no local alpha support for 16bit 565. - - Global alpha is a 256 step transparency that applies to the entire osd, - with 0 being transparent & 255 being solid. - - It's possible to combine colour key, local alpha & global alpha. - -------------------------------------------------------------------------------- - 2A04 - bits 0:15 - osd x coord for left edge - - bits 16:31 - osd y coord for top edge - --------------- - 2A08 - bits 0:15 - osd x coord for right edge - - bits 16:31 - osd y coord for bottom edge - - For both registers, (0,0) = top left corner of the display area. These - registers do not control the osd size, only where it's positioned & how - much is visible. The visible osd area cannot exceed the right edge of the - display, otherwise the osd will become corrupt. See reg 2A10 for - setting osd width. - -------------------------------------------------------------------------------- - 2A0C - bits 0:31 - osd buffer index - - An index into the osd buffer. Slowly incrementing this moves the osd left, - wrapping around onto the right edge - -------------------------------------------------------------------------------- - 2A10 - bits 0:11 - osd buffer 32 bit word width - - Contains the width of the osd measured in 32 bit words. This means that all - colour modes are restricted to a byte width which is divisible by 4. - -------------------------------------------------------------------------------- - 2A14 - bits 0:15 - osd height in pixels - - bits 16:32 - osd line index into buffer - osd will start displaying from this line. - -------------------------------------------------------------------------------- - 2A18 - bits 0:31 - osd colour key - - Contains the colour value which will be transparent. - -------------------------------------------------------------------------------- - 2A1C - bits 0:7 - osd global alpha - - Contains the global alpha value (equiv ivtvfbctl --alpha XX) - -------------------------------------------------------------------------------- - 2A20 -------- ?? unknown - | - V - 2A2C -------- ?? unknown - -------------------------------------------------------------------------------- - 2A30 - bits 0:7 - osd colour to change in indexed palette - --------------- - 2A34 - bits 0:31 - osd colour for indexed palette - - To set the new palette, first load the index of the colour to change into - 2A30, then load the new colour into 2A34. The full palette is 256 colours, - so the index range is 0x00-0xFF - -------------------------------------------------------------------------------- - 2A38 -------- ?? unknown - 2A3C -------- ?? unknown - -------------------------------------------------------------------------------- - 2A40 - bits 0:31 - osd ?? unknown - - Affects overall brightness, wrapping around to black - -------------------------------------------------------------------------------- - 2A44 - bits 0:31 - osd ?? unknown - - Green tint - -------------------------------------------------------------------------------- - 2A48 - bits 0:31 - osd ?? unknown - - Red tint - -------------------------------------------------------------------------------- - 2A4C - bits 0:31 - osd ?? unknown - - Affects overall brightness, wrapping around to black - -------------------------------------------------------------------------------- - 2A50 - bits 0:31 - osd ?? unknown - - Colour shift - -------------------------------------------------------------------------------- - 2A54 - bits 0:31 - osd ?? unknown - - Colour shift - -------------------------------------------------------------------------------- - 2A58 -------- ?? unknown - | - V - 2AFC -------- ?? unknown - -------------------------------------------------------------------------------- - 2B00 - bit 0 - osd filter control - 0 = filter off - 1 = filter on - - bits 1:4 - osd ?? unknown - - -------------------------------------------------------------------------------- - -The cx231xx DMA engine ----------------------- - - -This page describes the structures and procedures used by the cx2341x DMA -engine. - -Introduction -~~~~~~~~~~~~ - -The cx2341x PCI interface is busmaster capable. This means it has a DMA -engine to efficiently transfer large volumes of data between the card and main -memory without requiring help from a CPU. Like most hardware, it must operate -on contiguous physical memory. This is difficult to come by in large quantities -on virtual memory machines. - -Therefore, it also supports a technique called "scatter-gather". The card can -transfer multiple buffers in one operation. Instead of allocating one large -contiguous buffer, the driver can allocate several smaller buffers. - -In practice, I've seen the average transfer to be roughly 80K, but transfers -above 128K were not uncommon, particularly at startup. The 128K figure is -important, because that is the largest block that the kernel can normally -allocate. Even still, 128K blocks are hard to come by, so the driver writer is -urged to choose a smaller block size and learn the scatter-gather technique. - -Mailbox #10 is reserved for DMA transfer information. - -Note: the hardware expects little-endian data ('intel format'). - -Flow -~~~~ - -This section describes, in general, the order of events when handling DMA -transfers. Detailed information follows this section. - -- The card raises the Encoder interrupt. -- The driver reads the transfer type, offset and size from Mailbox #10. -- The driver constructs the scatter-gather array from enough free dma buffers - to cover the size. -- The driver schedules the DMA transfer via the ScheduleDMAtoHost API call. -- The card raises the DMA Complete interrupt. -- The driver checks the DMA status register for any errors. -- The driver post-processes the newly transferred buffers. - -NOTE! It is possible that the Encoder and DMA Complete interrupts get raised -simultaneously. (End of the last, start of the next, etc.) - -Mailbox #10 -~~~~~~~~~~~ - -The Flags, Command, Return Value and Timeout fields are ignored. - -- Name: Mailbox #10 -- Results[0]: Type: 0: MPEG. -- Results[1]: Offset: The position relative to the card's memory space. -- Results[2]: Size: The exact number of bytes to transfer. - -My speculation is that since the StartCapture API has a capture type of "RAW" -available, that the type field will have other values that correspond to YUV -and PCM data. - -Scatter-Gather Array -~~~~~~~~~~~~~~~~~~~~ - -The scatter-gather array is a contiguously allocated block of memory that -tells the card the source and destination of each data-block to transfer. -Card "addresses" are derived from the offset supplied by Mailbox #10. Host -addresses are the physical memory location of the target DMA buffer. - -Each S-G array element is a struct of three 32-bit words. The first word is -the source address, the second is the destination address. Both take up the -entire 32 bits. The lowest 18 bits of the third word is the transfer byte -count. The high-bit of the third word is the "last" flag. The last-flag tells -the card to raise the DMA_DONE interrupt. From hard personal experience, if -you forget to set this bit, the card will still "work" but the stream will -most likely get corrupted. - -The transfer count must be a multiple of 256. Therefore, the driver will need -to track how much data in the target buffer is valid and deal with it -accordingly. - -Array Element: - -- 32-bit Source Address -- 32-bit Destination Address -- 14-bit reserved (high bit is the last flag) -- 18-bit byte count - -DMA Transfer Status -~~~~~~~~~~~~~~~~~~~ - -Register 0x0004 holds the DMA Transfer Status: - -- bit 0: read completed -- bit 1: write completed -- bit 2: DMA read error -- bit 3: DMA write error -- bit 4: Scatter-Gather array error - -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 - #include - #include - - 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 - - -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/index.rst b/Documentation/media/v4l-drivers/index.rst index dfc878c050da..f3e34ccaf365 100644 --- a/Documentation/media/v4l-drivers/index.rst +++ b/Documentation/media/v4l-drivers/index.rst @@ -38,7 +38,6 @@ For more details see the file COPYING in the source distribution of Linux. bttv cafe_ccic cpia2 - cx2341x cx88 davinci-vpbe fimc @@ -68,7 +67,9 @@ For more details see the file COPYING in the source distribution of Linux. bttv-devel cpia2_devel + cx2341x-devel cx88-devel vimc-devel + cx2341x-uapi meye-uapi -- cgit v1.2.3 From d81c969b95d4096344714c9131a0843b4193750c Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 5 Mar 2020 07:36:13 +0100 Subject: media: docs: split uAPI info from davinci-vpbe.rst This file contains both driver develompent documentation and userspace API. Split on two, as they're usually read by different audiences. Signed-off-by: Mauro Carvalho Chehab --- .../media/v4l-drivers/davinci-vpbe-devel.rst | 39 ++++++++++++++++++++ Documentation/media/v4l-drivers/davinci-vpbe.rst | 42 +++------------------- Documentation/media/v4l-drivers/index.rst | 1 + 3 files changed, 45 insertions(+), 37 deletions(-) create mode 100644 Documentation/media/v4l-drivers/davinci-vpbe-devel.rst (limited to 'Documentation') diff --git a/Documentation/media/v4l-drivers/davinci-vpbe-devel.rst b/Documentation/media/v4l-drivers/davinci-vpbe-devel.rst new file mode 100644 index 000000000000..f0961672e6a3 --- /dev/null +++ b/Documentation/media/v4l-drivers/davinci-vpbe-devel.rst @@ -0,0 +1,39 @@ +.. SPDX-License-Identifier: GPL-2.0 + +The VPBE V4L2 driver design +=========================== + +File partitioning +----------------- + + V4L2 display device driver + drivers/media/platform/davinci/vpbe_display.c + drivers/media/platform/davinci/vpbe_display.h + + VPBE display controller + drivers/media/platform/davinci/vpbe.c + drivers/media/platform/davinci/vpbe.h + + VPBE venc sub device driver + drivers/media/platform/davinci/vpbe_venc.c + drivers/media/platform/davinci/vpbe_venc.h + drivers/media/platform/davinci/vpbe_venc_regs.h + + VPBE osd driver + drivers/media/platform/davinci/vpbe_osd.c + drivers/media/platform/davinci/vpbe_osd.h + drivers/media/platform/davinci/vpbe_osd_regs.h + +To be done +---------- + +vpbe display controller + - Add support for external encoders. + - add support for selecting external encoder as default at probe time. + +vpbe venc sub device + - add timings for supporting ths8200 + - add support for LogicPD LCD. + +FB drivers + - Add support for fbdev drivers.- Ready and part of subsequent patches. diff --git a/Documentation/media/v4l-drivers/davinci-vpbe.rst b/Documentation/media/v4l-drivers/davinci-vpbe.rst index 0fde433e5c71..9e6360fd02db 100644 --- a/Documentation/media/v4l-drivers/davinci-vpbe.rst +++ b/Documentation/media/v4l-drivers/davinci-vpbe.rst @@ -3,38 +3,18 @@ The VPBE V4L2 driver design =========================== -File partitioning ------------------ - - V4L2 display device driver - drivers/media/platform/davinci/vpbe_display.c - drivers/media/platform/davinci/vpbe_display.h - - VPBE display controller - drivers/media/platform/davinci/vpbe.c - drivers/media/platform/davinci/vpbe.h - - VPBE venc sub device driver - drivers/media/platform/davinci/vpbe_venc.c - drivers/media/platform/davinci/vpbe_venc.h - drivers/media/platform/davinci/vpbe_venc_regs.h - - VPBE osd driver - drivers/media/platform/davinci/vpbe_osd.c - drivers/media/platform/davinci/vpbe_osd.h - drivers/media/platform/davinci/vpbe_osd_regs.h - Functional partitioning ----------------------- -Consists of the following (in the same order as the list under file -partitioning): +Consists of the following: 1. V4L2 display driver + Implements creation of video2 and video3 device nodes and provides v4l2 device interface to manage VID0 and VID1 layers. 2. Display controller + Loads up VENC, OSD and external encoders such as ths8200. It provides a set of API calls to V4L2 drivers to set the output/standards in the VENC or external sub devices. It also provides @@ -54,6 +34,7 @@ partitioning): encoders is not present, and would be a part of the next patch series. 3. VENC subdevice module + Responsible for setting outputs provided through internal DACs and also setting timings at LCD controller port when external encoders are connected at the port or LCD panel timings required. When external encoder/LCD panel @@ -72,6 +53,7 @@ partitioning): patch series. 4. OSD module + OSD module implements all OSD layer management and hardware specific features. The VPBE module interacts with the OSD for enabling and disabling appropriate features of the OSD. @@ -81,17 +63,3 @@ Current status A fully functional working version of the V4L2 driver is available. This driver has been tested with NTSC and PAL standards and buffer streaming. - -To be done ----------- - -vpbe display controller - - Add support for external encoders. - - add support for selecting external encoder as default at probe time. - -vpbe venc sub device - - add timings for supporting ths8200 - - add support for LogicPD LCD. - -FB drivers - - Add support for fbdev drivers.- Ready and part of subsequent patches. diff --git a/Documentation/media/v4l-drivers/index.rst b/Documentation/media/v4l-drivers/index.rst index f3e34ccaf365..2d782a40a7b6 100644 --- a/Documentation/media/v4l-drivers/index.rst +++ b/Documentation/media/v4l-drivers/index.rst @@ -69,6 +69,7 @@ For more details see the file COPYING in the source distribution of Linux. cpia2_devel cx2341x-devel cx88-devel + davinci-vpbe-devel vimc-devel cx2341x-uapi -- cgit v1.2.3 From b4a5f46cdee4beda24ce22cb55d116120271af3e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 5 Mar 2020 07:38:55 +0100 Subject: media: docs: split uAPI info from fimc.rst This file contains both driver develompent documentation and userspace API. Split on two, as they're usually read by different audiences. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/v4l-drivers/fimc-devel.rst | 33 ++++++++++++++++++++++++++ Documentation/media/v4l-drivers/fimc.rst | 22 ++--------------- Documentation/media/v4l-drivers/index.rst | 1 + 3 files changed, 36 insertions(+), 20 deletions(-) create mode 100644 Documentation/media/v4l-drivers/fimc-devel.rst (limited to 'Documentation') diff --git a/Documentation/media/v4l-drivers/fimc-devel.rst b/Documentation/media/v4l-drivers/fimc-devel.rst new file mode 100644 index 000000000000..956e3a9901f8 --- /dev/null +++ b/Documentation/media/v4l-drivers/fimc-devel.rst @@ -0,0 +1,33 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: + +The Samsung S5P/EXYNOS4 FIMC driver +=================================== + +Copyright |copy| 2012 - 2013 Samsung Electronics Co., Ltd. + +Files partitioning +------------------ + +- media device driver + + drivers/media/platform/exynos4-is/media-dev.[ch] + +- camera capture video device driver + + drivers/media/platform/exynos4-is/fimc-capture.c + +- MIPI-CSI2 receiver subdev + + drivers/media/platform/exynos4-is/mipi-csis.[ch] + +- video post-processor (mem-to-mem) + + drivers/media/platform/exynos4-is/fimc-core.c + +- common files + + drivers/media/platform/exynos4-is/fimc-core.h + drivers/media/platform/exynos4-is/fimc-reg.h + drivers/media/platform/exynos4-is/regs-fimc.h diff --git a/Documentation/media/v4l-drivers/fimc.rst b/Documentation/media/v4l-drivers/fimc.rst index 74585ba48b7f..0b8ddc4a3008 100644 --- a/Documentation/media/v4l-drivers/fimc.rst +++ b/Documentation/media/v4l-drivers/fimc.rst @@ -38,26 +38,6 @@ Not currently supported - LCD writeback input - per frame clock gating (mem-to-mem) -Files partitioning ------------------- - -- media device driver - drivers/media/platform/exynos4-is/media-dev.[ch] - -- camera capture video device driver - drivers/media/platform/exynos4-is/fimc-capture.c - -- MIPI-CSI2 receiver subdev - drivers/media/platform/exynos4-is/mipi-csis.[ch] - -- video post-processor (mem-to-mem) - drivers/media/platform/exynos4-is/fimc-core.c - -- common files - drivers/media/platform/exynos4-is/fimc-core.h - drivers/media/platform/exynos4-is/fimc-reg.h - drivers/media/platform/exynos4-is/regs-fimc.h - User space interfaces --------------------- @@ -74,6 +54,7 @@ connections of the MIPI-CSIS device(s) to the FIMC entities. The media device interface allows to configure the SoC for capturing image data from the sensor through more than one FIMC instance (e.g. for simultaneous viewfinder and still capture setup). + Reconfiguration is done by enabling/disabling media links created by the driver during initialization. The internal device topology can be easily discovered through media entity and links enumeration. @@ -116,6 +97,7 @@ sensor subdev -> mipi-csi subdev -> fimc subdev -> video node When we configure these devices through sub-device API at user space, the configuration flow must be from left to right, and the video node is configured as last one. + When we don't use sub-device user space API the whole configuration of all devices belonging to the pipeline is done at the video node driver. The sysfs entry allows to instruct the capture node driver not to configure diff --git a/Documentation/media/v4l-drivers/index.rst b/Documentation/media/v4l-drivers/index.rst index 2d782a40a7b6..adf72937b119 100644 --- a/Documentation/media/v4l-drivers/index.rst +++ b/Documentation/media/v4l-drivers/index.rst @@ -70,6 +70,7 @@ For more details see the file COPYING in the source distribution of Linux. cx2341x-devel cx88-devel davinci-vpbe-devel + fimc-devel vimc-devel cx2341x-uapi -- cgit v1.2.3 From f8dd7a257dcef6c4c208b7d8b0e2a7229131cf8d Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 5 Mar 2020 07:48:35 +0100 Subject: media: docs: split uAPI info from saa7134-devel.rst This file contains both driver develompent documentation and userspace API. Split on two, as they're usually read by different audiences. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/v4l-drivers/index.rst | 1 + Documentation/media/v4l-drivers/saa7134-devel.rst | 67 +++++++++++++++++++++++ Documentation/media/v4l-drivers/saa7134.rst | 54 ------------------ 3 files changed, 68 insertions(+), 54 deletions(-) create mode 100644 Documentation/media/v4l-drivers/saa7134-devel.rst (limited to 'Documentation') diff --git a/Documentation/media/v4l-drivers/index.rst b/Documentation/media/v4l-drivers/index.rst index adf72937b119..6fdfd9a41913 100644 --- a/Documentation/media/v4l-drivers/index.rst +++ b/Documentation/media/v4l-drivers/index.rst @@ -71,6 +71,7 @@ For more details see the file COPYING in the source distribution of Linux. cx88-devel davinci-vpbe-devel fimc-devel + saa7134-devel vimc-devel cx2341x-uapi diff --git a/Documentation/media/v4l-drivers/saa7134-devel.rst b/Documentation/media/v4l-drivers/saa7134-devel.rst new file mode 100644 index 000000000000..167fd729bc8c --- /dev/null +++ b/Documentation/media/v4l-drivers/saa7134-devel.rst @@ -0,0 +1,67 @@ +.. SPDX-License-Identifier: GPL-2.0 + +The saa7134 driver +================== + +Author Gerd Hoffmann + + +Card Variations: +---------------- + +Cards can use either of these two crystals (xtal): + +- 32.11 MHz -> .audio_clock=0x187de7 +- 24.576MHz -> .audio_clock=0x200000 (xtal * .audio_clock = 51539600) + +Some details about 30/34/35: + +- saa7130 - low-price chip, doesn't have mute, that is why all those + cards should have .mute field defined in their tuner structure. + +- saa7134 - usual chip + +- saa7133/35 - saa7135 is probably a marketing decision, since all those + chips identifies itself as 33 on pci. + +LifeView GPIOs +-------------- + +This section was authored by: Peter Missel + +- LifeView FlyTV Platinum FM (LR214WF) + + - GP27 MDT2005 PB4 pin 10 + - GP26 MDT2005 PB3 pin 9 + - GP25 MDT2005 PB2 pin 8 + - GP23 MDT2005 PB1 pin 7 + - GP22 MDT2005 PB0 pin 6 + - GP21 MDT2005 PB5 pin 11 + - GP20 MDT2005 PB6 pin 12 + - GP19 MDT2005 PB7 pin 13 + - nc MDT2005 PA3 pin 2 + - Remote MDT2005 PA2 pin 1 + - GP18 MDT2005 PA1 pin 18 + - nc MDT2005 PA0 pin 17 strap low + - GP17 Strap "GP7"=High + - GP16 Strap "GP6"=High + + - 0=Radio 1=TV + - Drives SA630D ENCH1 and HEF4052 A1 pinsto do FM radio through + SIF input + + - GP15 nc + - GP14 nc + - GP13 nc + - GP12 Strap "GP5" = High + - GP11 Strap "GP4" = High + - GP10 Strap "GP3" = High + - GP09 Strap "GP2" = Low + - GP08 Strap "GP1" = Low + - GP07.00 nc + +Credits +------- + +andrew.stevens@philips.com + werner.leeb@philips.com for providing +saa7134 hardware specs and sample board. diff --git a/Documentation/media/v4l-drivers/saa7134.rst b/Documentation/media/v4l-drivers/saa7134.rst index 15d06facdbc1..c84246dd81c0 100644 --- a/Documentation/media/v4l-drivers/saa7134.rst +++ b/Documentation/media/v4l-drivers/saa7134.rst @@ -54,60 +54,6 @@ Known Problems default might not work for you depending on which version you have. There is a tuner= insmod option to override the driver's default. -Card Variations: ----------------- - -Cards can use either of these two crystals (xtal): - -- 32.11 MHz -> .audio_clock=0x187de7 -- 24.576MHz -> .audio_clock=0x200000 (xtal * .audio_clock = 51539600) - -Some details about 30/34/35: - -- saa7130 - low-price chip, doesn't have mute, that is why all those - cards should have .mute field defined in their tuner structure. - -- saa7134 - usual chip - -- saa7133/35 - saa7135 is probably a marketing decision, since all those - chips identifies itself as 33 on pci. - -LifeView GPIOs --------------- - -This section was authored by: Peter Missel - -- LifeView FlyTV Platinum FM (LR214WF) - - - GP27 MDT2005 PB4 pin 10 - - GP26 MDT2005 PB3 pin 9 - - GP25 MDT2005 PB2 pin 8 - - GP23 MDT2005 PB1 pin 7 - - GP22 MDT2005 PB0 pin 6 - - GP21 MDT2005 PB5 pin 11 - - GP20 MDT2005 PB6 pin 12 - - GP19 MDT2005 PB7 pin 13 - - nc MDT2005 PA3 pin 2 - - Remote MDT2005 PA2 pin 1 - - GP18 MDT2005 PA1 pin 18 - - nc MDT2005 PA0 pin 17 strap low - - GP17 Strap "GP7"=High - - GP16 Strap "GP6"=High - - - 0=Radio 1=TV - - Drives SA630D ENCH1 and HEF4052 A1 pinsto do FM radio through - SIF input - - - GP15 nc - - GP14 nc - - GP13 nc - - GP12 Strap "GP5" = High - - GP11 Strap "GP4" = High - - GP10 Strap "GP3" = High - - GP09 Strap "GP2" = Low - - GP08 Strap "GP1" = Low - - GP07.00 nc - Credits ------- -- cgit v1.2.3 From 889a500ed5fef83ffd8ffc962b73df02750caaed Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 5 Mar 2020 07:59:19 +0100 Subject: media: docs: split uAPI info from omap3isp.rst This file contains both driver develompent documentation and userspace API. Split on two, as they're usually read by different audiences. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/v4l-drivers/index.rst | 1 + Documentation/media/v4l-drivers/omap3isp-uapi.rst | 208 ++++++++++++++++++++++ Documentation/media/v4l-drivers/omap3isp.rst | 196 +------------------- 3 files changed, 211 insertions(+), 194 deletions(-) create mode 100644 Documentation/media/v4l-drivers/omap3isp-uapi.rst (limited to 'Documentation') diff --git a/Documentation/media/v4l-drivers/index.rst b/Documentation/media/v4l-drivers/index.rst index 6fdfd9a41913..364c65ea86fb 100644 --- a/Documentation/media/v4l-drivers/index.rst +++ b/Documentation/media/v4l-drivers/index.rst @@ -76,3 +76,4 @@ For more details see the file COPYING in the source distribution of Linux. cx2341x-uapi meye-uapi + omap3isp-uapi diff --git a/Documentation/media/v4l-drivers/omap3isp-uapi.rst b/Documentation/media/v4l-drivers/omap3isp-uapi.rst new file mode 100644 index 000000000000..5f966a874a3c --- /dev/null +++ b/Documentation/media/v4l-drivers/omap3isp-uapi.rst @@ -0,0 +1,208 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: + +OMAP 3 Image Signal Processor (ISP) driver +========================================== + +Copyright |copy| 2010 Nokia Corporation + +Copyright |copy| 2009 Texas Instruments, Inc. + +Contacts: Laurent Pinchart , +Sakari Ailus , David Cohen + + +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/omap3isp.rst b/Documentation/media/v4l-drivers/omap3isp.rst index 8974c444e3a1..bc447bbec7ce 100644 --- a/Documentation/media/v4l-drivers/omap3isp.rst +++ b/Documentation/media/v4l-drivers/omap3isp.rst @@ -49,7 +49,7 @@ interface to userspace. - OMAP3 ISP histogram Each possible link in the ISP is modelled by a link in the Media controller -interface. For an example program see [#f2]_. +interface. For an example program see [#]_. Controlling the OMAP 3 ISP @@ -68,196 +68,6 @@ Autoidle does have issues with some ISP blocks on the 3430, at least. Autoidle is only enabled on 3630 when the omap3isp module parameter autoidle is non-zero. - -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 [#f1]_. - -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. - - Technical reference manuals (TRMs) and other documentation ---------------------------------------------------------- @@ -279,6 +89,4 @@ DM 3730 TRM: References ---------- -.. [#f1] include/linux/omap3isp.h - -.. [#f2] http://git.ideasonboard.org/?p=media-ctl.git;a=summary +.. [#] http://git.ideasonboard.org/?p=media-ctl.git;a=summary -- cgit v1.2.3 From 5dfb8db56b273740a76e8687ee7efb4b2c0ec83b Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 5 Mar 2020 08:33:37 +0100 Subject: media: docs: split uAPI info from imx.rst This file contains both driver develompent documentation and userspace API. Split on two, as they're usually read by different audiences. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/v4l-drivers/imx-uapi.rst | 125 +++++++++++++++++++++++++++ Documentation/media/v4l-drivers/imx.rst | 88 +------------------ Documentation/media/v4l-drivers/index.rst | 1 + 3 files changed, 128 insertions(+), 86 deletions(-) create mode 100644 Documentation/media/v4l-drivers/imx-uapi.rst (limited to 'Documentation') diff --git a/Documentation/media/v4l-drivers/imx-uapi.rst b/Documentation/media/v4l-drivers/imx-uapi.rst new file mode 100644 index 000000000000..8d47712dea9f --- /dev/null +++ b/Documentation/media/v4l-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 +- Philipp Zabel +- Russell King + +Copyright (C) 2012-2017 Mentor Graphics Inc. diff --git a/Documentation/media/v4l-drivers/imx.rst b/Documentation/media/v4l-drivers/imx.rst index 1246573c1019..3182951c7651 100644 --- a/Documentation/media/v4l-drivers/imx.rst +++ b/Documentation/media/v4l-drivers/imx.rst @@ -191,14 +191,7 @@ or unqualified interlaced). The capture interface will enforce the same field order as the source pad field order (interlaced-bt if source pad is seq-bt, interlaced-tb if source pad is seq-tb). -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). +For events produced by ipuX_csiY, see ref:`imx_api_ipuX_csiY`. Cropping in ipuX_csiY --------------------- @@ -247,84 +240,7 @@ rate by half at the IDMAC output source pad: 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. - +See ref:`imx_api_FIM`. ipuX_vdic --------- diff --git a/Documentation/media/v4l-drivers/index.rst b/Documentation/media/v4l-drivers/index.rst index 364c65ea86fb..67665a8abe02 100644 --- a/Documentation/media/v4l-drivers/index.rst +++ b/Documentation/media/v4l-drivers/index.rst @@ -75,5 +75,6 @@ For more details see the file COPYING in the source distribution of Linux. vimc-devel cx2341x-uapi + imx-uapi meye-uapi omap3isp-uapi -- cgit v1.2.3 From 54f38fcae536ea202ce7d6a359521492fba30c1f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 4 Mar 2020 10:21:39 +0100 Subject: media: docs: move uAPI book to userspace-api/media Since 2017, there is an space reserved for userspace API, created by changeset 1d596dee3862 ("docs: Create a user-space API guide"). As the media subsystem was one of the first subsystems to use Sphinx, until this patch, we were keeping things on a separate place. Let's just use the new location, as having all uAPI altogether will likely make things easier for developers. Signed-off-by: Mauro Carvalho Chehab --- Documentation/ABI/testing/debugfs-cec-error-inj | 2 +- Documentation/Makefile | 10 +- Documentation/doc-guide/parse-headers.rst | 2 +- Documentation/fb/api.rst | 4 +- Documentation/media/Makefile | 69 - Documentation/media/audio.h.rst.exceptions | 19 - Documentation/media/ca.h.rst.exceptions | 25 - Documentation/media/cec.h.rst.exceptions | 575 -- Documentation/media/conf_nitpick.py | 111 - Documentation/media/dmx.h.rst.exceptions | 66 - Documentation/media/frontend.h.rst.exceptions | 214 - Documentation/media/index.rst | 2 +- Documentation/media/intro.rst | 46 - Documentation/media/lirc.h.rst.exceptions | 80 - Documentation/media/media.h.rst.exceptions | 32 - Documentation/media/media_uapi.rst | 33 - Documentation/media/net.h.rst.exceptions | 13 - Documentation/media/typical_media_device.svg | 116 - Documentation/media/uapi/cec/cec-api.rst | 54 - Documentation/media/uapi/cec/cec-func-close.rst | 54 - Documentation/media/uapi/cec/cec-func-ioctl.rst | 73 - Documentation/media/uapi/cec/cec-func-open.rst | 85 - Documentation/media/uapi/cec/cec-func-poll.rst | 85 - Documentation/media/uapi/cec/cec-funcs.rst | 30 - Documentation/media/uapi/cec/cec-header.rst | 17 - Documentation/media/uapi/cec/cec-intro.rst | 49 - .../media/uapi/cec/cec-ioc-adap-g-caps.rst | 150 - .../media/uapi/cec/cec-ioc-adap-g-conn-info.rst | 105 - .../media/uapi/cec/cec-ioc-adap-g-log-addrs.rst | 378 - .../media/uapi/cec/cec-ioc-adap-g-phys-addr.rst | 100 - Documentation/media/uapi/cec/cec-ioc-dqevent.rst | 257 - Documentation/media/uapi/cec/cec-ioc-g-mode.rst | 301 - Documentation/media/uapi/cec/cec-ioc-receive.rst | 391 - Documentation/media/uapi/cec/cec-pin-error-inj.rst | 334 - .../uapi/dvb/audio-bilingual-channel-select.rst | 66 - .../media/uapi/dvb/audio-channel-select.rst | 66 - .../media/uapi/dvb/audio-clear-buffer.rst | 55 - Documentation/media/uapi/dvb/audio-continue.rst | 56 - Documentation/media/uapi/dvb/audio-fclose.rst | 63 - Documentation/media/uapi/dvb/audio-fopen.rst | 115 - Documentation/media/uapi/dvb/audio-fwrite.rst | 91 - .../media/uapi/dvb/audio-get-capabilities.rst | 63 - Documentation/media/uapi/dvb/audio-get-status.rst | 63 - Documentation/media/uapi/dvb/audio-pause.rst | 57 - Documentation/media/uapi/dvb/audio-play.rst | 56 - .../media/uapi/dvb/audio-select-source.rst | 65 - Documentation/media/uapi/dvb/audio-set-av-sync.rst | 67 - .../media/uapi/dvb/audio-set-bypass-mode.rst | 70 - Documentation/media/uapi/dvb/audio-set-id.rst | 67 - Documentation/media/uapi/dvb/audio-set-mixer.rst | 61 - Documentation/media/uapi/dvb/audio-set-mute.rst | 71 - .../media/uapi/dvb/audio-set-streamtype.rst | 77 - Documentation/media/uapi/dvb/audio-stop.rst | 56 - Documentation/media/uapi/dvb/audio.rst | 34 - Documentation/media/uapi/dvb/audio_data_types.rst | 123 - .../media/uapi/dvb/audio_function_calls.rst | 37 - Documentation/media/uapi/dvb/ca-fclose.rst | 50 - Documentation/media/uapi/dvb/ca-fopen.rst | 84 - Documentation/media/uapi/dvb/ca-get-cap.rst | 53 - Documentation/media/uapi/dvb/ca-get-descr-info.rst | 49 - Documentation/media/uapi/dvb/ca-get-msg.rst | 59 - Documentation/media/uapi/dvb/ca-get-slot-info.rst | 64 - Documentation/media/uapi/dvb/ca-reset.rst | 51 - Documentation/media/uapi/dvb/ca-send-msg.rst | 58 - Documentation/media/uapi/dvb/ca-set-descr.rst | 53 - Documentation/media/uapi/dvb/ca.rst | 32 - Documentation/media/uapi/dvb/ca_data_types.rst | 16 - Documentation/media/uapi/dvb/ca_function_calls.rst | 27 - Documentation/media/uapi/dvb/ca_high_level.rst | 157 - Documentation/media/uapi/dvb/demux.rst | 30 - Documentation/media/uapi/dvb/dmx-add-pid.rst | 56 - Documentation/media/uapi/dvb/dmx-expbuf.rst | 97 - Documentation/media/uapi/dvb/dmx-fclose.rst | 52 - Documentation/media/uapi/dvb/dmx-fopen.rst | 98 - Documentation/media/uapi/dvb/dmx-fread.rst | 87 - Documentation/media/uapi/dvb/dmx-fwrite.rst | 79 - Documentation/media/uapi/dvb/dmx-get-pes-pids.rst | 71 - Documentation/media/uapi/dvb/dmx-get-stc.rst | 73 - Documentation/media/uapi/dvb/dmx-mmap.rst | 125 - Documentation/media/uapi/dvb/dmx-munmap.rst | 63 - Documentation/media/uapi/dvb/dmx-qbuf.rst | 93 - Documentation/media/uapi/dvb/dmx-querybuf.rst | 72 - Documentation/media/uapi/dvb/dmx-remove-pid.rst | 57 - Documentation/media/uapi/dvb/dmx-reqbufs.rst | 83 - .../media/uapi/dvb/dmx-set-buffer-size.rst | 57 - Documentation/media/uapi/dvb/dmx-set-filter.rst | 64 - .../media/uapi/dvb/dmx-set-pes-filter.rst | 76 - Documentation/media/uapi/dvb/dmx-start.rst | 75 - Documentation/media/uapi/dvb/dmx-stop.rst | 52 - Documentation/media/uapi/dvb/dmx_fcalls.rst | 37 - Documentation/media/uapi/dvb/dmx_types.rst | 16 - .../media/uapi/dvb/dvb-fe-read-status.rst | 32 - .../media/uapi/dvb/dvb-frontend-event.rst | 22 - .../media/uapi/dvb/dvb-frontend-parameters.rst | 126 - Documentation/media/uapi/dvb/dvbapi.rst | 126 - Documentation/media/uapi/dvb/dvbproperty.rst | 133 - Documentation/media/uapi/dvb/dvbstb.svg | 43 - Documentation/media/uapi/dvb/examples.rst | 23 - Documentation/media/uapi/dvb/fe-bandwidth-t.rst | 81 - .../media/uapi/dvb/fe-diseqc-recv-slave-reply.rst | 55 - .../media/uapi/dvb/fe-diseqc-reset-overload.rst | 53 - .../media/uapi/dvb/fe-diseqc-send-burst.rst | 59 - .../media/uapi/dvb/fe-diseqc-send-master-cmd.rst | 56 - .../uapi/dvb/fe-dishnetwork-send-legacy-cmd.rst | 62 - .../media/uapi/dvb/fe-enable-high-lnb-voltage.rst | 61 - Documentation/media/uapi/dvb/fe-get-event.rst | 78 - Documentation/media/uapi/dvb/fe-get-frontend.rst | 69 - Documentation/media/uapi/dvb/fe-get-info.rst | 70 - Documentation/media/uapi/dvb/fe-get-property.rst | 83 - Documentation/media/uapi/dvb/fe-read-ber.rst | 57 - .../media/uapi/dvb/fe-read-signal-strength.rst | 57 - Documentation/media/uapi/dvb/fe-read-snr.rst | 57 - Documentation/media/uapi/dvb/fe-read-status.rst | 72 - .../media/uapi/dvb/fe-read-uncorrected-blocks.rst | 59 - .../media/uapi/dvb/fe-set-frontend-tune-mode.rst | 64 - Documentation/media/uapi/dvb/fe-set-frontend.rst | 78 - Documentation/media/uapi/dvb/fe-set-tone.rst | 65 - Documentation/media/uapi/dvb/fe-set-voltage.rst | 69 - Documentation/media/uapi/dvb/fe-type-t.rst | 98 - .../media/uapi/dvb/fe_property_parameters.rst | 1014 --- Documentation/media/uapi/dvb/frontend-header.rst | 13 - .../uapi/dvb/frontend-property-cable-systems.rst | 82 - .../dvb/frontend-property-satellite-systems.rst | 112 - .../dvb/frontend-property-terrestrial-systems.rst | 301 - .../media/uapi/dvb/frontend-stat-properties.rst | 252 - Documentation/media/uapi/dvb/frontend.rst | 63 - Documentation/media/uapi/dvb/frontend_f_close.rst | 57 - Documentation/media/uapi/dvb/frontend_f_open.rst | 117 - Documentation/media/uapi/dvb/frontend_fcalls.rst | 31 - .../media/uapi/dvb/frontend_legacy_api.rst | 45 - .../media/uapi/dvb/frontend_legacy_dvbv3_api.rst | 25 - Documentation/media/uapi/dvb/headers.rst | 30 - Documentation/media/uapi/dvb/intro.rst | 190 - Documentation/media/uapi/dvb/legacy_dvb_apis.rst | 39 - Documentation/media/uapi/dvb/net-add-if.rst | 60 - Documentation/media/uapi/dvb/net-get-if.rst | 59 - Documentation/media/uapi/dvb/net-remove-if.rst | 55 - Documentation/media/uapi/dvb/net-types.rst | 16 - Documentation/media/uapi/dvb/net.rst | 48 - .../media/uapi/dvb/query-dvb-frontend-info.rst | 20 - .../media/uapi/dvb/video-clear-buffer.rst | 63 - Documentation/media/uapi/dvb/video-command.rst | 105 - Documentation/media/uapi/dvb/video-continue.rst | 66 - .../media/uapi/dvb/video-fast-forward.rst | 83 - Documentation/media/uapi/dvb/video-fclose.rst | 62 - Documentation/media/uapi/dvb/video-fopen.rst | 122 - Documentation/media/uapi/dvb/video-freeze.rst | 70 - Documentation/media/uapi/dvb/video-fwrite.rst | 90 - .../media/uapi/dvb/video-get-capabilities.rst | 70 - Documentation/media/uapi/dvb/video-get-event.rst | 114 - .../media/uapi/dvb/video-get-frame-count.rst | 74 - Documentation/media/uapi/dvb/video-get-pts.rst | 78 - Documentation/media/uapi/dvb/video-get-size.rst | 78 - Documentation/media/uapi/dvb/video-get-status.rst | 80 - Documentation/media/uapi/dvb/video-play.rst | 66 - .../media/uapi/dvb/video-select-source.rst | 84 - Documentation/media/uapi/dvb/video-set-blank.rst | 73 - .../media/uapi/dvb/video-set-display-format.rst | 69 - Documentation/media/uapi/dvb/video-set-format.rst | 92 - .../media/uapi/dvb/video-set-streamtype.rst | 70 - Documentation/media/uapi/dvb/video-slowmotion.rst | 83 - .../media/uapi/dvb/video-stillpicture.rst | 70 - Documentation/media/uapi/dvb/video-stop.rst | 83 - Documentation/media/uapi/dvb/video-try-command.rst | 75 - Documentation/media/uapi/dvb/video.rst | 43 - .../media/uapi/dvb/video_function_calls.rst | 42 - Documentation/media/uapi/dvb/video_types.rst | 255 - Documentation/media/uapi/fdl-appendix.rst | 478 -- Documentation/media/uapi/gen-errors.rst | 103 - .../media/uapi/mediactl/media-controller-intro.rst | 40 - .../media/uapi/mediactl/media-controller-model.rst | 42 - .../media/uapi/mediactl/media-controller.rst | 62 - .../media/uapi/mediactl/media-func-close.rst | 54 - .../media/uapi/mediactl/media-func-ioctl.rst | 74 - .../media/uapi/mediactl/media-func-open.rst | 76 - Documentation/media/uapi/mediactl/media-funcs.rst | 33 - Documentation/media/uapi/mediactl/media-header.rst | 17 - .../media/uapi/mediactl/media-ioc-device-info.rst | 118 - .../uapi/mediactl/media-ioc-enum-entities.rst | 156 - .../media/uapi/mediactl/media-ioc-enum-links.rst | 157 - .../media/uapi/mediactl/media-ioc-g-topology.rst | 307 - .../uapi/mediactl/media-ioc-request-alloc.rst | 90 - .../media/uapi/mediactl/media-ioc-setup-link.rst | 74 - .../uapi/mediactl/media-request-ioc-queue.rst | 102 - .../uapi/mediactl/media-request-ioc-reinit.rst | 75 - Documentation/media/uapi/mediactl/media-types.rst | 425 -- Documentation/media/uapi/mediactl/request-api.rst | 276 - .../media/uapi/mediactl/request-func-close.rst | 73 - .../media/uapi/mediactl/request-func-ioctl.rst | 91 - .../media/uapi/mediactl/request-func-poll.rst | 101 - Documentation/media/uapi/rc/keytable.c.rst | 183 - Documentation/media/uapi/rc/lirc-dev-intro.rst | 171 - Documentation/media/uapi/rc/lirc-dev.rst | 21 - Documentation/media/uapi/rc/lirc-func.rst | 34 - Documentation/media/uapi/rc/lirc-get-features.rst | 200 - Documentation/media/uapi/rc/lirc-get-rec-mode.rst | 74 - .../media/uapi/rc/lirc-get-rec-resolution.rst | 54 - Documentation/media/uapi/rc/lirc-get-send-mode.rst | 78 - Documentation/media/uapi/rc/lirc-get-timeout.rst | 63 - Documentation/media/uapi/rc/lirc-header.rst | 17 - Documentation/media/uapi/rc/lirc-read.rst | 76 - .../uapi/rc/lirc-set-measure-carrier-mode.rst | 53 - .../media/uapi/rc/lirc-set-rec-carrier-range.rst | 54 - .../media/uapi/rc/lirc-set-rec-carrier.rst | 53 - .../media/uapi/rc/lirc-set-rec-timeout-reports.rst | 56 - .../media/uapi/rc/lirc-set-rec-timeout.rst | 61 - .../media/uapi/rc/lirc-set-send-carrier.rst | 48 - .../media/uapi/rc/lirc-set-send-duty-cycle.rst | 54 - .../media/uapi/rc/lirc-set-transmitter-mask.rst | 58 - .../media/uapi/rc/lirc-set-wideband-receiver.rst | 63 - Documentation/media/uapi/rc/lirc-write.rst | 82 - Documentation/media/uapi/rc/rc-intro.rst | 31 - Documentation/media/uapi/rc/rc-protos.rst | 456 -- Documentation/media/uapi/rc/rc-sysfs-nodes.rst | 151 - Documentation/media/uapi/rc/rc-table-change.rst | 25 - Documentation/media/uapi/rc/rc-tables.rst | 766 -- Documentation/media/uapi/rc/remote_controllers.rst | 59 - Documentation/media/uapi/v4l/app-pri.rst | 37 - Documentation/media/uapi/v4l/async.rst | 16 - Documentation/media/uapi/v4l/audio.rst | 104 - Documentation/media/uapi/v4l/bayer.svg | 56 - Documentation/media/uapi/v4l/biblio.rst | 416 -- Documentation/media/uapi/v4l/buffer.rst | 817 -- Documentation/media/uapi/v4l/capture-example.rst | 20 - Documentation/media/uapi/v4l/capture.c.rst | 671 -- Documentation/media/uapi/v4l/colorspaces-defs.rst | 183 - .../media/uapi/v4l/colorspaces-details.rst | 813 -- Documentation/media/uapi/v4l/colorspaces.rst | 170 - Documentation/media/uapi/v4l/common-defs.rst | 20 - Documentation/media/uapi/v4l/common.rst | 64 - Documentation/media/uapi/v4l/compat.rst | 25 - Documentation/media/uapi/v4l/constraints.svg | 37 - Documentation/media/uapi/v4l/control.rst | 512 -- Documentation/media/uapi/v4l/crop.rst | 324 - Documentation/media/uapi/v4l/crop.svg | 290 - Documentation/media/uapi/v4l/depth-formats.rst | 24 - Documentation/media/uapi/v4l/dev-capture.rst | 111 - Documentation/media/uapi/v4l/dev-decoder.rst | 1101 --- Documentation/media/uapi/v4l/dev-event.rst | 54 - Documentation/media/uapi/v4l/dev-mem2mem.rst | 49 - Documentation/media/uapi/v4l/dev-meta.rst | 74 - Documentation/media/uapi/v4l/dev-osd.rst | 157 - Documentation/media/uapi/v4l/dev-output.rst | 108 - Documentation/media/uapi/v4l/dev-overlay.rst | 328 - Documentation/media/uapi/v4l/dev-radio.rst | 59 - Documentation/media/uapi/v4l/dev-raw-vbi.rst | 306 - Documentation/media/uapi/v4l/dev-rds.rst | 191 - Documentation/media/uapi/v4l/dev-sdr.rst | 114 - Documentation/media/uapi/v4l/dev-sliced-vbi.rst | 669 -- .../media/uapi/v4l/dev-stateless-decoder.rst | 424 -- Documentation/media/uapi/v4l/dev-subdev.rst | 503 -- Documentation/media/uapi/v4l/dev-touch.rst | 63 - Documentation/media/uapi/v4l/devices.rst | 33 - Documentation/media/uapi/v4l/diff-v4l.rst | 693 -- Documentation/media/uapi/v4l/dmabuf.rst | 169 - Documentation/media/uapi/v4l/dv-timings.rst | 45 - Documentation/media/uapi/v4l/ext-ctrls-camera.rst | 515 -- Documentation/media/uapi/v4l/ext-ctrls-codec.rst | 4264 ----------- Documentation/media/uapi/v4l/ext-ctrls-detect.rst | 71 - Documentation/media/uapi/v4l/ext-ctrls-dv.rst | 166 - Documentation/media/uapi/v4l/ext-ctrls-flash.rst | 192 - Documentation/media/uapi/v4l/ext-ctrls-fm-rx.rst | 95 - Documentation/media/uapi/v4l/ext-ctrls-fm-tx.rst | 188 - .../media/uapi/v4l/ext-ctrls-image-process.rst | 63 - .../media/uapi/v4l/ext-ctrls-image-source.rst | 67 - Documentation/media/uapi/v4l/ext-ctrls-jpeg.rst | 113 - .../media/uapi/v4l/ext-ctrls-rf-tuner.rst | 96 - Documentation/media/uapi/v4l/extended-controls.rst | 180 - Documentation/media/uapi/v4l/field-order.rst | 172 - Documentation/media/uapi/v4l/fieldseq_bt.svg | 2621 ------- Documentation/media/uapi/v4l/fieldseq_tb.svg | 2618 ------- Documentation/media/uapi/v4l/format.rst | 99 - Documentation/media/uapi/v4l/func-close.rst | 56 - Documentation/media/uapi/v4l/func-ioctl.rst | 69 - Documentation/media/uapi/v4l/func-mmap.rst | 148 - Documentation/media/uapi/v4l/func-munmap.rst | 65 - Documentation/media/uapi/v4l/func-open.rst | 90 - Documentation/media/uapi/v4l/func-poll.rst | 124 - Documentation/media/uapi/v4l/func-read.rst | 140 - Documentation/media/uapi/v4l/func-select.rst | 127 - Documentation/media/uapi/v4l/func-write.rst | 91 - Documentation/media/uapi/v4l/hist-v4l2.rst | 1374 ---- Documentation/media/uapi/v4l/hsv-formats.rst | 26 - Documentation/media/uapi/v4l/io.rst | 58 - .../media/uapi/v4l/libv4l-introduction.rst | 191 - Documentation/media/uapi/v4l/libv4l.rst | 20 - Documentation/media/uapi/v4l/meta-formats.rst | 27 - Documentation/media/uapi/v4l/mmap.rst | 292 - Documentation/media/uapi/v4l/nv12mt.svg | 477 -- Documentation/media/uapi/v4l/nv12mt_example.svg | 1616 ---- Documentation/media/uapi/v4l/open.rst | 165 - Documentation/media/uapi/v4l/pipeline.dot | 14 - Documentation/media/uapi/v4l/pixfmt-bayer.rst | 39 - Documentation/media/uapi/v4l/pixfmt-cnf4.rst | 31 - Documentation/media/uapi/v4l/pixfmt-compressed.rst | 232 - Documentation/media/uapi/v4l/pixfmt-grey.rst | 51 - Documentation/media/uapi/v4l/pixfmt-indexed.rst | 54 - Documentation/media/uapi/v4l/pixfmt-intro.rst | 58 - Documentation/media/uapi/v4l/pixfmt-inzi.rst | 89 - Documentation/media/uapi/v4l/pixfmt-m420.rst | 133 - Documentation/media/uapi/v4l/pixfmt-meta-d4xx.rst | 220 - .../media/uapi/v4l/pixfmt-meta-intel-ipu3.rst | 104 - Documentation/media/uapi/v4l/pixfmt-meta-uvc.rst | 58 - Documentation/media/uapi/v4l/pixfmt-meta-vivid.rst | 60 - .../media/uapi/v4l/pixfmt-meta-vsp1-hgo.rst | 175 - .../media/uapi/v4l/pixfmt-meta-vsp1-hgt.rst | 136 - Documentation/media/uapi/v4l/pixfmt-nv12.rst | 136 - Documentation/media/uapi/v4l/pixfmt-nv12m.rst | 151 - Documentation/media/uapi/v4l/pixfmt-nv12mt.rst | 67 - Documentation/media/uapi/v4l/pixfmt-nv16.rst | 160 - Documentation/media/uapi/v4l/pixfmt-nv16m.rst | 164 - Documentation/media/uapi/v4l/pixfmt-nv24.rst | 102 - Documentation/media/uapi/v4l/pixfmt-packed-hsv.rst | 164 - Documentation/media/uapi/v4l/pixfmt-packed-yuv.rst | 380 - Documentation/media/uapi/v4l/pixfmt-reserved.rst | 282 - Documentation/media/uapi/v4l/pixfmt-rgb.rst | 1304 ---- Documentation/media/uapi/v4l/pixfmt-sdr-cs08.rst | 37 - Documentation/media/uapi/v4l/pixfmt-sdr-cs14le.rst | 41 - Documentation/media/uapi/v4l/pixfmt-sdr-cu08.rst | 37 - Documentation/media/uapi/v4l/pixfmt-sdr-cu16le.rst | 41 - .../media/uapi/v4l/pixfmt-sdr-pcu16be.rst | 62 - .../media/uapi/v4l/pixfmt-sdr-pcu18be.rst | 62 - .../media/uapi/v4l/pixfmt-sdr-pcu20be.rst | 62 - Documentation/media/uapi/v4l/pixfmt-sdr-ru12le.rst | 39 - .../media/uapi/v4l/pixfmt-srggb10-ipu3.rst | 342 - Documentation/media/uapi/v4l/pixfmt-srggb10.rst | 83 - .../media/uapi/v4l/pixfmt-srggb10alaw8.rst | 31 - .../media/uapi/v4l/pixfmt-srggb10dpcm8.rst | 35 - Documentation/media/uapi/v4l/pixfmt-srggb10p.rst | 81 - Documentation/media/uapi/v4l/pixfmt-srggb12.rst | 84 - Documentation/media/uapi/v4l/pixfmt-srggb12p.rst | 94 - Documentation/media/uapi/v4l/pixfmt-srggb14.rst | 82 - Documentation/media/uapi/v4l/pixfmt-srggb14p.rst | 152 - Documentation/media/uapi/v4l/pixfmt-srggb16.rst | 76 - Documentation/media/uapi/v4l/pixfmt-srggb8.rst | 61 - Documentation/media/uapi/v4l/pixfmt-tch-td08.rst | 59 - Documentation/media/uapi/v4l/pixfmt-tch-td16.rst | 74 - Documentation/media/uapi/v4l/pixfmt-tch-tu08.rst | 57 - Documentation/media/uapi/v4l/pixfmt-tch-tu16.rst | 73 - Documentation/media/uapi/v4l/pixfmt-uv8.rst | 54 - Documentation/media/uapi/v4l/pixfmt-uyvy.rst | 117 - .../media/uapi/v4l/pixfmt-v4l2-mplane.rst | 138 - Documentation/media/uapi/v4l/pixfmt-v4l2.rst | 171 - Documentation/media/uapi/v4l/pixfmt-vyuy.rst | 115 - Documentation/media/uapi/v4l/pixfmt-y10.rst | 72 - Documentation/media/uapi/v4l/pixfmt-y10b.rst | 40 - Documentation/media/uapi/v4l/pixfmt-y10p.rst | 50 - Documentation/media/uapi/v4l/pixfmt-y12.rst | 72 - Documentation/media/uapi/v4l/pixfmt-y12i.rst | 43 - Documentation/media/uapi/v4l/pixfmt-y14.rst | 72 - Documentation/media/uapi/v4l/pixfmt-y16-be.rst | 76 - Documentation/media/uapi/v4l/pixfmt-y16.rst | 76 - Documentation/media/uapi/v4l/pixfmt-y41p.rst | 158 - Documentation/media/uapi/v4l/pixfmt-y8i.rst | 73 - Documentation/media/uapi/v4l/pixfmt-yuv410.rst | 134 - Documentation/media/uapi/v4l/pixfmt-yuv411p.rst | 122 - Documentation/media/uapi/v4l/pixfmt-yuv420.rst | 150 - Documentation/media/uapi/v4l/pixfmt-yuv420m.rst | 159 - Documentation/media/uapi/v4l/pixfmt-yuv422m.rst | 148 - Documentation/media/uapi/v4l/pixfmt-yuv422p.rst | 136 - Documentation/media/uapi/v4l/pixfmt-yuv444m.rst | 148 - Documentation/media/uapi/v4l/pixfmt-yuyv.rst | 125 - Documentation/media/uapi/v4l/pixfmt-yvyu.rst | 115 - Documentation/media/uapi/v4l/pixfmt-z16.rst | 73 - Documentation/media/uapi/v4l/pixfmt.rst | 45 - Documentation/media/uapi/v4l/planar-apis.rst | 68 - Documentation/media/uapi/v4l/querycap.rst | 41 - Documentation/media/uapi/v4l/rw.rst | 54 - Documentation/media/uapi/v4l/sdr-formats.rst | 29 - .../media/uapi/v4l/selection-api-configuration.rst | 144 - .../media/uapi/v4l/selection-api-examples.rst | 91 - .../media/uapi/v4l/selection-api-intro.rst | 35 - .../media/uapi/v4l/selection-api-targets.rst | 27 - .../media/uapi/v4l/selection-api-vs-crop-api.rst | 46 - Documentation/media/uapi/v4l/selection-api.rst | 23 - Documentation/media/uapi/v4l/selection.svg | 1178 --- Documentation/media/uapi/v4l/selections-common.rst | 30 - Documentation/media/uapi/v4l/standard.rst | 192 - Documentation/media/uapi/v4l/streaming-par.rst | 40 - Documentation/media/uapi/v4l/subdev-formats.rst | 7833 -------------------- .../uapi/v4l/subdev-image-processing-crop.svg | 312 - .../uapi/v4l/subdev-image-processing-full.svg | 752 -- ...ubdev-image-processing-scaling-multi-source.svg | 550 -- Documentation/media/uapi/v4l/tch-formats.rst | 25 - Documentation/media/uapi/v4l/tuner.rst | 92 - Documentation/media/uapi/v4l/user-func.rst | 88 - Documentation/media/uapi/v4l/userp.rst | 128 - .../media/uapi/v4l/v4l2-selection-flags.rst | 51 - .../media/uapi/v4l/v4l2-selection-targets.rst | 78 - Documentation/media/uapi/v4l/v4l2.rst | 423 -- Documentation/media/uapi/v4l/v4l2grab-example.rst | 24 - Documentation/media/uapi/v4l/v4l2grab.c.rst | 176 - Documentation/media/uapi/v4l/vbi_525.svg | 821 -- Documentation/media/uapi/v4l/vbi_625.svg | 870 --- Documentation/media/uapi/v4l/vbi_hsync.svg | 321 - Documentation/media/uapi/v4l/video.rst | 75 - Documentation/media/uapi/v4l/videodev.rst | 16 - .../media/uapi/v4l/vidioc-create-bufs.rst | 141 - Documentation/media/uapi/v4l/vidioc-cropcap.rst | 143 - .../media/uapi/v4l/vidioc-dbg-g-chip-info.rst | 167 - .../media/uapi/v4l/vidioc-dbg-g-register.rst | 171 - .../media/uapi/v4l/vidioc-decoder-cmd.rst | 226 - Documentation/media/uapi/v4l/vidioc-dqevent.rst | 391 - .../media/uapi/v4l/vidioc-dv-timings-cap.rst | 169 - .../media/uapi/v4l/vidioc-encoder-cmd.rst | 168 - .../media/uapi/v4l/vidioc-enum-dv-timings.rst | 114 - Documentation/media/uapi/v4l/vidioc-enum-fmt.rst | 159 - .../media/uapi/v4l/vidioc-enum-frameintervals.rst | 203 - .../media/uapi/v4l/vidioc-enum-framesizes.rst | 213 - .../media/uapi/v4l/vidioc-enum-freq-bands.rst | 150 - Documentation/media/uapi/v4l/vidioc-enumaudio.rst | 62 - .../media/uapi/v4l/vidioc-enumaudioout.rst | 67 - Documentation/media/uapi/v4l/vidioc-enuminput.rst | 242 - Documentation/media/uapi/v4l/vidioc-enumoutput.rst | 165 - Documentation/media/uapi/v4l/vidioc-enumstd.rst | 367 - Documentation/media/uapi/v4l/vidioc-expbuf.rst | 175 - Documentation/media/uapi/v4l/vidioc-g-audio.rst | 135 - Documentation/media/uapi/v4l/vidioc-g-audioout.rst | 108 - Documentation/media/uapi/v4l/vidioc-g-crop.rst | 119 - Documentation/media/uapi/v4l/vidioc-g-ctrl.rst | 106 - .../media/uapi/v4l/vidioc-g-dv-timings.rst | 312 - Documentation/media/uapi/v4l/vidioc-g-edid.rst | 154 - .../media/uapi/v4l/vidioc-g-enc-index.rst | 156 - .../media/uapi/v4l/vidioc-g-ext-ctrls.rst | 416 -- Documentation/media/uapi/v4l/vidioc-g-fbuf.rst | 362 - Documentation/media/uapi/v4l/vidioc-g-fmt.rst | 161 - .../media/uapi/v4l/vidioc-g-frequency.rst | 112 - Documentation/media/uapi/v4l/vidioc-g-input.rst | 71 - Documentation/media/uapi/v4l/vidioc-g-jpegcomp.rst | 134 - .../media/uapi/v4l/vidioc-g-modulator.rst | 202 - Documentation/media/uapi/v4l/vidioc-g-output.rst | 73 - Documentation/media/uapi/v4l/vidioc-g-parm.rst | 270 - Documentation/media/uapi/v4l/vidioc-g-priority.rst | 100 - .../media/uapi/v4l/vidioc-g-selection.rst | 200 - .../media/uapi/v4l/vidioc-g-sliced-vbi-cap.rst | 202 - Documentation/media/uapi/v4l/vidioc-g-std.rst | 81 - Documentation/media/uapi/v4l/vidioc-g-tuner.rst | 476 -- Documentation/media/uapi/v4l/vidioc-log-status.rst | 56 - Documentation/media/uapi/v4l/vidioc-overlay.rst | 61 - .../media/uapi/v4l/vidioc-prepare-buf.rst | 65 - Documentation/media/uapi/v4l/vidioc-qbuf.rst | 205 - .../media/uapi/v4l/vidioc-query-dv-timings.rst | 94 - Documentation/media/uapi/v4l/vidioc-querybuf.rst | 87 - Documentation/media/uapi/v4l/vidioc-querycap.rst | 284 - Documentation/media/uapi/v4l/vidioc-queryctrl.rst | 616 -- Documentation/media/uapi/v4l/vidioc-querystd.rst | 77 - Documentation/media/uapi/v4l/vidioc-reqbufs.rst | 169 - .../media/uapi/v4l/vidioc-s-hw-freq-seek.rst | 147 - Documentation/media/uapi/v4l/vidioc-streamon.rst | 113 - .../uapi/v4l/vidioc-subdev-enum-frame-interval.rst | 120 - .../uapi/v4l/vidioc-subdev-enum-frame-size.rst | 125 - .../uapi/v4l/vidioc-subdev-enum-mbus-code.rst | 98 - .../media/uapi/v4l/vidioc-subdev-g-crop.rst | 125 - .../media/uapi/v4l/vidioc-subdev-g-fmt.rst | 154 - .../uapi/v4l/vidioc-subdev-g-frame-interval.rst | 120 - .../media/uapi/v4l/vidioc-subdev-g-selection.rst | 125 - .../media/uapi/v4l/vidioc-subscribe-event.rst | 123 - Documentation/media/uapi/v4l/yuv-formats.rst | 64 - Documentation/media/video.h.rst.exceptions | 39 - Documentation/media/videodev2.h.rst.exceptions | 572 -- .../translations/it_IT/doc-guide/parse-headers.rst | 2 +- Documentation/userspace-api/media/Makefile | 69 + .../userspace-api/media/audio.h.rst.exceptions | 19 + .../userspace-api/media/ca.h.rst.exceptions | 25 + .../userspace-api/media/cec.h.rst.exceptions | 575 ++ Documentation/userspace-api/media/cec/cec-api.rst | 54 + .../userspace-api/media/cec/cec-func-close.rst | 54 + .../userspace-api/media/cec/cec-func-ioctl.rst | 73 + .../userspace-api/media/cec/cec-func-open.rst | 85 + .../userspace-api/media/cec/cec-func-poll.rst | 85 + .../userspace-api/media/cec/cec-funcs.rst | 30 + .../userspace-api/media/cec/cec-header.rst | 17 + .../userspace-api/media/cec/cec-intro.rst | 49 + .../media/cec/cec-ioc-adap-g-caps.rst | 150 + .../media/cec/cec-ioc-adap-g-conn-info.rst | 105 + .../media/cec/cec-ioc-adap-g-log-addrs.rst | 378 + .../media/cec/cec-ioc-adap-g-phys-addr.rst | 100 + .../userspace-api/media/cec/cec-ioc-dqevent.rst | 257 + .../userspace-api/media/cec/cec-ioc-g-mode.rst | 301 + .../userspace-api/media/cec/cec-ioc-receive.rst | 391 + .../userspace-api/media/cec/cec-pin-error-inj.rst | 334 + Documentation/userspace-api/media/conf_nitpick.py | 111 + .../userspace-api/media/dmx.h.rst.exceptions | 66 + .../media/dvb/audio-bilingual-channel-select.rst | 66 + .../media/dvb/audio-channel-select.rst | 66 + .../userspace-api/media/dvb/audio-clear-buffer.rst | 55 + .../userspace-api/media/dvb/audio-continue.rst | 56 + .../userspace-api/media/dvb/audio-fclose.rst | 63 + .../userspace-api/media/dvb/audio-fopen.rst | 115 + .../userspace-api/media/dvb/audio-fwrite.rst | 91 + .../media/dvb/audio-get-capabilities.rst | 63 + .../userspace-api/media/dvb/audio-get-status.rst | 63 + .../userspace-api/media/dvb/audio-pause.rst | 57 + .../userspace-api/media/dvb/audio-play.rst | 56 + .../media/dvb/audio-select-source.rst | 65 + .../userspace-api/media/dvb/audio-set-av-sync.rst | 67 + .../media/dvb/audio-set-bypass-mode.rst | 70 + .../userspace-api/media/dvb/audio-set-id.rst | 67 + .../userspace-api/media/dvb/audio-set-mixer.rst | 61 + .../userspace-api/media/dvb/audio-set-mute.rst | 71 + .../media/dvb/audio-set-streamtype.rst | 77 + .../userspace-api/media/dvb/audio-stop.rst | 56 + Documentation/userspace-api/media/dvb/audio.rst | 34 + .../userspace-api/media/dvb/audio_data_types.rst | 123 + .../media/dvb/audio_function_calls.rst | 37 + .../userspace-api/media/dvb/ca-fclose.rst | 50 + Documentation/userspace-api/media/dvb/ca-fopen.rst | 84 + .../userspace-api/media/dvb/ca-get-cap.rst | 53 + .../userspace-api/media/dvb/ca-get-descr-info.rst | 49 + .../userspace-api/media/dvb/ca-get-msg.rst | 59 + .../userspace-api/media/dvb/ca-get-slot-info.rst | 64 + Documentation/userspace-api/media/dvb/ca-reset.rst | 51 + .../userspace-api/media/dvb/ca-send-msg.rst | 58 + .../userspace-api/media/dvb/ca-set-descr.rst | 53 + Documentation/userspace-api/media/dvb/ca.rst | 32 + .../userspace-api/media/dvb/ca_data_types.rst | 16 + .../userspace-api/media/dvb/ca_function_calls.rst | 27 + .../userspace-api/media/dvb/ca_high_level.rst | 157 + Documentation/userspace-api/media/dvb/demux.rst | 30 + .../userspace-api/media/dvb/dmx-add-pid.rst | 56 + .../userspace-api/media/dvb/dmx-expbuf.rst | 97 + .../userspace-api/media/dvb/dmx-fclose.rst | 52 + .../userspace-api/media/dvb/dmx-fopen.rst | 98 + .../userspace-api/media/dvb/dmx-fread.rst | 87 + .../userspace-api/media/dvb/dmx-fwrite.rst | 79 + .../userspace-api/media/dvb/dmx-get-pes-pids.rst | 71 + .../userspace-api/media/dvb/dmx-get-stc.rst | 73 + Documentation/userspace-api/media/dvb/dmx-mmap.rst | 125 + .../userspace-api/media/dvb/dmx-munmap.rst | 63 + Documentation/userspace-api/media/dvb/dmx-qbuf.rst | 93 + .../userspace-api/media/dvb/dmx-querybuf.rst | 72 + .../userspace-api/media/dvb/dmx-remove-pid.rst | 57 + .../userspace-api/media/dvb/dmx-reqbufs.rst | 83 + .../media/dvb/dmx-set-buffer-size.rst | 57 + .../userspace-api/media/dvb/dmx-set-filter.rst | 64 + .../userspace-api/media/dvb/dmx-set-pes-filter.rst | 76 + .../userspace-api/media/dvb/dmx-start.rst | 75 + Documentation/userspace-api/media/dvb/dmx-stop.rst | 52 + .../userspace-api/media/dvb/dmx_fcalls.rst | 37 + .../userspace-api/media/dvb/dmx_types.rst | 16 + .../userspace-api/media/dvb/dvb-fe-read-status.rst | 32 + .../userspace-api/media/dvb/dvb-frontend-event.rst | 22 + .../media/dvb/dvb-frontend-parameters.rst | 126 + Documentation/userspace-api/media/dvb/dvbapi.rst | 126 + .../userspace-api/media/dvb/dvbproperty.rst | 133 + Documentation/userspace-api/media/dvb/dvbstb.svg | 43 + Documentation/userspace-api/media/dvb/examples.rst | 23 + .../userspace-api/media/dvb/fe-bandwidth-t.rst | 81 + .../media/dvb/fe-diseqc-recv-slave-reply.rst | 55 + .../media/dvb/fe-diseqc-reset-overload.rst | 53 + .../media/dvb/fe-diseqc-send-burst.rst | 59 + .../media/dvb/fe-diseqc-send-master-cmd.rst | 56 + .../media/dvb/fe-dishnetwork-send-legacy-cmd.rst | 62 + .../media/dvb/fe-enable-high-lnb-voltage.rst | 61 + .../userspace-api/media/dvb/fe-get-event.rst | 78 + .../userspace-api/media/dvb/fe-get-frontend.rst | 69 + .../userspace-api/media/dvb/fe-get-info.rst | 70 + .../userspace-api/media/dvb/fe-get-property.rst | 83 + .../userspace-api/media/dvb/fe-read-ber.rst | 57 + .../media/dvb/fe-read-signal-strength.rst | 57 + .../userspace-api/media/dvb/fe-read-snr.rst | 57 + .../userspace-api/media/dvb/fe-read-status.rst | 72 + .../media/dvb/fe-read-uncorrected-blocks.rst | 59 + .../media/dvb/fe-set-frontend-tune-mode.rst | 64 + .../userspace-api/media/dvb/fe-set-frontend.rst | 78 + .../userspace-api/media/dvb/fe-set-tone.rst | 65 + .../userspace-api/media/dvb/fe-set-voltage.rst | 69 + .../userspace-api/media/dvb/fe-type-t.rst | 98 + .../media/dvb/fe_property_parameters.rst | 1014 +++ .../userspace-api/media/dvb/frontend-header.rst | 13 + .../media/dvb/frontend-property-cable-systems.rst | 82 + .../dvb/frontend-property-satellite-systems.rst | 112 + .../dvb/frontend-property-terrestrial-systems.rst | 301 + .../media/dvb/frontend-stat-properties.rst | 252 + Documentation/userspace-api/media/dvb/frontend.rst | 63 + .../userspace-api/media/dvb/frontend_f_close.rst | 57 + .../userspace-api/media/dvb/frontend_f_open.rst | 117 + .../userspace-api/media/dvb/frontend_fcalls.rst | 31 + .../media/dvb/frontend_legacy_api.rst | 45 + .../media/dvb/frontend_legacy_dvbv3_api.rst | 25 + Documentation/userspace-api/media/dvb/headers.rst | 30 + Documentation/userspace-api/media/dvb/intro.rst | 190 + .../userspace-api/media/dvb/legacy_dvb_apis.rst | 39 + .../userspace-api/media/dvb/net-add-if.rst | 60 + .../userspace-api/media/dvb/net-get-if.rst | 59 + .../userspace-api/media/dvb/net-remove-if.rst | 55 + .../userspace-api/media/dvb/net-types.rst | 16 + Documentation/userspace-api/media/dvb/net.rst | 48 + .../media/dvb/query-dvb-frontend-info.rst | 20 + .../userspace-api/media/dvb/video-clear-buffer.rst | 63 + .../userspace-api/media/dvb/video-command.rst | 105 + .../userspace-api/media/dvb/video-continue.rst | 66 + .../userspace-api/media/dvb/video-fast-forward.rst | 83 + .../userspace-api/media/dvb/video-fclose.rst | 62 + .../userspace-api/media/dvb/video-fopen.rst | 122 + .../userspace-api/media/dvb/video-freeze.rst | 70 + .../userspace-api/media/dvb/video-fwrite.rst | 90 + .../media/dvb/video-get-capabilities.rst | 70 + .../userspace-api/media/dvb/video-get-event.rst | 114 + .../media/dvb/video-get-frame-count.rst | 74 + .../userspace-api/media/dvb/video-get-pts.rst | 78 + .../userspace-api/media/dvb/video-get-size.rst | 78 + .../userspace-api/media/dvb/video-get-status.rst | 80 + .../userspace-api/media/dvb/video-play.rst | 66 + .../media/dvb/video-select-source.rst | 84 + .../userspace-api/media/dvb/video-set-blank.rst | 73 + .../media/dvb/video-set-display-format.rst | 69 + .../userspace-api/media/dvb/video-set-format.rst | 92 + .../media/dvb/video-set-streamtype.rst | 70 + .../userspace-api/media/dvb/video-slowmotion.rst | 83 + .../userspace-api/media/dvb/video-stillpicture.rst | 70 + .../userspace-api/media/dvb/video-stop.rst | 83 + .../userspace-api/media/dvb/video-try-command.rst | 75 + Documentation/userspace-api/media/dvb/video.rst | 43 + .../media/dvb/video_function_calls.rst | 42 + .../userspace-api/media/dvb/video_types.rst | 255 + Documentation/userspace-api/media/fdl-appendix.rst | 478 ++ .../userspace-api/media/frontend.h.rst.exceptions | 214 + Documentation/userspace-api/media/gen-errors.rst | 103 + Documentation/userspace-api/media/index.rst | 33 + Documentation/userspace-api/media/intro.rst | 46 + .../userspace-api/media/lirc.h.rst.exceptions | 80 + .../userspace-api/media/media.h.rst.exceptions | 32 + .../media/mediactl/media-controller-intro.rst | 40 + .../media/mediactl/media-controller-model.rst | 42 + .../media/mediactl/media-controller.rst | 62 + .../media/mediactl/media-func-close.rst | 54 + .../media/mediactl/media-func-ioctl.rst | 74 + .../media/mediactl/media-func-open.rst | 76 + .../userspace-api/media/mediactl/media-funcs.rst | 33 + .../userspace-api/media/mediactl/media-header.rst | 17 + .../media/mediactl/media-ioc-device-info.rst | 118 + .../media/mediactl/media-ioc-enum-entities.rst | 156 + .../media/mediactl/media-ioc-enum-links.rst | 157 + .../media/mediactl/media-ioc-g-topology.rst | 307 + .../media/mediactl/media-ioc-request-alloc.rst | 90 + .../media/mediactl/media-ioc-setup-link.rst | 74 + .../media/mediactl/media-request-ioc-queue.rst | 102 + .../media/mediactl/media-request-ioc-reinit.rst | 75 + .../userspace-api/media/mediactl/media-types.rst | 425 ++ .../userspace-api/media/mediactl/request-api.rst | 276 + .../media/mediactl/request-func-close.rst | 73 + .../media/mediactl/request-func-ioctl.rst | 91 + .../media/mediactl/request-func-poll.rst | 101 + .../userspace-api/media/net.h.rst.exceptions | 13 + .../userspace-api/media/rc/keytable.c.rst | 183 + .../userspace-api/media/rc/lirc-dev-intro.rst | 171 + Documentation/userspace-api/media/rc/lirc-dev.rst | 21 + Documentation/userspace-api/media/rc/lirc-func.rst | 34 + .../userspace-api/media/rc/lirc-get-features.rst | 200 + .../userspace-api/media/rc/lirc-get-rec-mode.rst | 74 + .../media/rc/lirc-get-rec-resolution.rst | 54 + .../userspace-api/media/rc/lirc-get-send-mode.rst | 78 + .../userspace-api/media/rc/lirc-get-timeout.rst | 63 + .../userspace-api/media/rc/lirc-header.rst | 17 + Documentation/userspace-api/media/rc/lirc-read.rst | 76 + .../media/rc/lirc-set-measure-carrier-mode.rst | 53 + .../media/rc/lirc-set-rec-carrier-range.rst | 54 + .../media/rc/lirc-set-rec-carrier.rst | 53 + .../media/rc/lirc-set-rec-timeout-reports.rst | 56 + .../media/rc/lirc-set-rec-timeout.rst | 61 + .../media/rc/lirc-set-send-carrier.rst | 48 + .../media/rc/lirc-set-send-duty-cycle.rst | 54 + .../media/rc/lirc-set-transmitter-mask.rst | 58 + .../media/rc/lirc-set-wideband-receiver.rst | 63 + .../userspace-api/media/rc/lirc-write.rst | 82 + Documentation/userspace-api/media/rc/rc-intro.rst | 31 + Documentation/userspace-api/media/rc/rc-protos.rst | 456 ++ .../userspace-api/media/rc/rc-sysfs-nodes.rst | 151 + .../userspace-api/media/rc/rc-table-change.rst | 25 + Documentation/userspace-api/media/rc/rc-tables.rst | 766 ++ .../userspace-api/media/rc/remote_controllers.rst | 59 + .../userspace-api/media/typical_media_device.svg | 116 + Documentation/userspace-api/media/v4l/app-pri.rst | 37 + Documentation/userspace-api/media/v4l/async.rst | 16 + Documentation/userspace-api/media/v4l/audio.rst | 104 + Documentation/userspace-api/media/v4l/bayer.svg | 56 + Documentation/userspace-api/media/v4l/biblio.rst | 416 ++ Documentation/userspace-api/media/v4l/buffer.rst | 817 ++ .../userspace-api/media/v4l/capture-example.rst | 20 + .../userspace-api/media/v4l/capture.c.rst | 671 ++ .../userspace-api/media/v4l/colorspaces-defs.rst | 183 + .../media/v4l/colorspaces-details.rst | 813 ++ .../userspace-api/media/v4l/colorspaces.rst | 170 + .../userspace-api/media/v4l/common-defs.rst | 20 + Documentation/userspace-api/media/v4l/common.rst | 64 + Documentation/userspace-api/media/v4l/compat.rst | 25 + .../userspace-api/media/v4l/constraints.svg | 37 + Documentation/userspace-api/media/v4l/control.rst | 512 ++ Documentation/userspace-api/media/v4l/crop.rst | 324 + Documentation/userspace-api/media/v4l/crop.svg | 290 + .../userspace-api/media/v4l/depth-formats.rst | 24 + .../userspace-api/media/v4l/dev-capture.rst | 111 + .../userspace-api/media/v4l/dev-decoder.rst | 1101 +++ .../userspace-api/media/v4l/dev-event.rst | 54 + .../userspace-api/media/v4l/dev-mem2mem.rst | 49 + Documentation/userspace-api/media/v4l/dev-meta.rst | 74 + Documentation/userspace-api/media/v4l/dev-osd.rst | 157 + .../userspace-api/media/v4l/dev-output.rst | 108 + .../userspace-api/media/v4l/dev-overlay.rst | 328 + .../userspace-api/media/v4l/dev-radio.rst | 59 + .../userspace-api/media/v4l/dev-raw-vbi.rst | 306 + Documentation/userspace-api/media/v4l/dev-rds.rst | 191 + Documentation/userspace-api/media/v4l/dev-sdr.rst | 114 + .../userspace-api/media/v4l/dev-sliced-vbi.rst | 669 ++ .../media/v4l/dev-stateless-decoder.rst | 424 ++ .../userspace-api/media/v4l/dev-subdev.rst | 503 ++ .../userspace-api/media/v4l/dev-touch.rst | 63 + Documentation/userspace-api/media/v4l/devices.rst | 33 + Documentation/userspace-api/media/v4l/diff-v4l.rst | 693 ++ Documentation/userspace-api/media/v4l/dmabuf.rst | 169 + .../userspace-api/media/v4l/dv-timings.rst | 45 + .../userspace-api/media/v4l/ext-ctrls-camera.rst | 515 ++ .../userspace-api/media/v4l/ext-ctrls-codec.rst | 4264 +++++++++++ .../userspace-api/media/v4l/ext-ctrls-detect.rst | 71 + .../userspace-api/media/v4l/ext-ctrls-dv.rst | 166 + .../userspace-api/media/v4l/ext-ctrls-flash.rst | 192 + .../userspace-api/media/v4l/ext-ctrls-fm-rx.rst | 95 + .../userspace-api/media/v4l/ext-ctrls-fm-tx.rst | 188 + .../media/v4l/ext-ctrls-image-process.rst | 63 + .../media/v4l/ext-ctrls-image-source.rst | 67 + .../userspace-api/media/v4l/ext-ctrls-jpeg.rst | 113 + .../userspace-api/media/v4l/ext-ctrls-rf-tuner.rst | 96 + .../userspace-api/media/v4l/extended-controls.rst | 180 + .../userspace-api/media/v4l/field-order.rst | 172 + .../userspace-api/media/v4l/fieldseq_bt.svg | 2621 +++++++ .../userspace-api/media/v4l/fieldseq_tb.svg | 2618 +++++++ Documentation/userspace-api/media/v4l/format.rst | 99 + .../userspace-api/media/v4l/func-close.rst | 56 + .../userspace-api/media/v4l/func-ioctl.rst | 69 + .../userspace-api/media/v4l/func-mmap.rst | 148 + .../userspace-api/media/v4l/func-munmap.rst | 65 + .../userspace-api/media/v4l/func-open.rst | 90 + .../userspace-api/media/v4l/func-poll.rst | 124 + .../userspace-api/media/v4l/func-read.rst | 140 + .../userspace-api/media/v4l/func-select.rst | 127 + .../userspace-api/media/v4l/func-write.rst | 91 + .../userspace-api/media/v4l/hist-v4l2.rst | 1374 ++++ .../userspace-api/media/v4l/hsv-formats.rst | 26 + Documentation/userspace-api/media/v4l/io.rst | 58 + .../media/v4l/libv4l-introduction.rst | 191 + Documentation/userspace-api/media/v4l/libv4l.rst | 20 + .../userspace-api/media/v4l/meta-formats.rst | 27 + Documentation/userspace-api/media/v4l/mmap.rst | 292 + Documentation/userspace-api/media/v4l/nv12mt.svg | 477 ++ .../userspace-api/media/v4l/nv12mt_example.svg | 1616 ++++ Documentation/userspace-api/media/v4l/open.rst | 165 + Documentation/userspace-api/media/v4l/pipeline.dot | 14 + .../userspace-api/media/v4l/pixfmt-bayer.rst | 39 + .../userspace-api/media/v4l/pixfmt-cnf4.rst | 31 + .../userspace-api/media/v4l/pixfmt-compressed.rst | 232 + .../userspace-api/media/v4l/pixfmt-grey.rst | 51 + .../userspace-api/media/v4l/pixfmt-indexed.rst | 54 + .../userspace-api/media/v4l/pixfmt-intro.rst | 58 + .../userspace-api/media/v4l/pixfmt-inzi.rst | 89 + .../userspace-api/media/v4l/pixfmt-m420.rst | 133 + .../userspace-api/media/v4l/pixfmt-meta-d4xx.rst | 220 + .../media/v4l/pixfmt-meta-intel-ipu3.rst | 104 + .../userspace-api/media/v4l/pixfmt-meta-uvc.rst | 58 + .../userspace-api/media/v4l/pixfmt-meta-vivid.rst | 60 + .../media/v4l/pixfmt-meta-vsp1-hgo.rst | 175 + .../media/v4l/pixfmt-meta-vsp1-hgt.rst | 136 + .../userspace-api/media/v4l/pixfmt-nv12.rst | 136 + .../userspace-api/media/v4l/pixfmt-nv12m.rst | 151 + .../userspace-api/media/v4l/pixfmt-nv12mt.rst | 67 + .../userspace-api/media/v4l/pixfmt-nv16.rst | 160 + .../userspace-api/media/v4l/pixfmt-nv16m.rst | 164 + .../userspace-api/media/v4l/pixfmt-nv24.rst | 102 + .../userspace-api/media/v4l/pixfmt-packed-hsv.rst | 164 + .../userspace-api/media/v4l/pixfmt-packed-yuv.rst | 380 + .../userspace-api/media/v4l/pixfmt-reserved.rst | 282 + .../userspace-api/media/v4l/pixfmt-rgb.rst | 1304 ++++ .../userspace-api/media/v4l/pixfmt-sdr-cs08.rst | 37 + .../userspace-api/media/v4l/pixfmt-sdr-cs14le.rst | 41 + .../userspace-api/media/v4l/pixfmt-sdr-cu08.rst | 37 + .../userspace-api/media/v4l/pixfmt-sdr-cu16le.rst | 41 + .../userspace-api/media/v4l/pixfmt-sdr-pcu16be.rst | 62 + .../userspace-api/media/v4l/pixfmt-sdr-pcu18be.rst | 62 + .../userspace-api/media/v4l/pixfmt-sdr-pcu20be.rst | 62 + .../userspace-api/media/v4l/pixfmt-sdr-ru12le.rst | 39 + .../media/v4l/pixfmt-srggb10-ipu3.rst | 342 + .../userspace-api/media/v4l/pixfmt-srggb10.rst | 83 + .../media/v4l/pixfmt-srggb10alaw8.rst | 31 + .../media/v4l/pixfmt-srggb10dpcm8.rst | 35 + .../userspace-api/media/v4l/pixfmt-srggb10p.rst | 81 + .../userspace-api/media/v4l/pixfmt-srggb12.rst | 84 + .../userspace-api/media/v4l/pixfmt-srggb12p.rst | 94 + .../userspace-api/media/v4l/pixfmt-srggb14.rst | 82 + .../userspace-api/media/v4l/pixfmt-srggb14p.rst | 152 + .../userspace-api/media/v4l/pixfmt-srggb16.rst | 76 + .../userspace-api/media/v4l/pixfmt-srggb8.rst | 61 + .../userspace-api/media/v4l/pixfmt-tch-td08.rst | 59 + .../userspace-api/media/v4l/pixfmt-tch-td16.rst | 74 + .../userspace-api/media/v4l/pixfmt-tch-tu08.rst | 57 + .../userspace-api/media/v4l/pixfmt-tch-tu16.rst | 73 + .../userspace-api/media/v4l/pixfmt-uv8.rst | 54 + .../userspace-api/media/v4l/pixfmt-uyvy.rst | 117 + .../userspace-api/media/v4l/pixfmt-v4l2-mplane.rst | 138 + .../userspace-api/media/v4l/pixfmt-v4l2.rst | 171 + .../userspace-api/media/v4l/pixfmt-vyuy.rst | 115 + .../userspace-api/media/v4l/pixfmt-y10.rst | 72 + .../userspace-api/media/v4l/pixfmt-y10b.rst | 40 + .../userspace-api/media/v4l/pixfmt-y10p.rst | 50 + .../userspace-api/media/v4l/pixfmt-y12.rst | 72 + .../userspace-api/media/v4l/pixfmt-y12i.rst | 43 + .../userspace-api/media/v4l/pixfmt-y14.rst | 72 + .../userspace-api/media/v4l/pixfmt-y16-be.rst | 76 + .../userspace-api/media/v4l/pixfmt-y16.rst | 76 + .../userspace-api/media/v4l/pixfmt-y41p.rst | 158 + .../userspace-api/media/v4l/pixfmt-y8i.rst | 73 + .../userspace-api/media/v4l/pixfmt-yuv410.rst | 134 + .../userspace-api/media/v4l/pixfmt-yuv411p.rst | 122 + .../userspace-api/media/v4l/pixfmt-yuv420.rst | 150 + .../userspace-api/media/v4l/pixfmt-yuv420m.rst | 159 + .../userspace-api/media/v4l/pixfmt-yuv422m.rst | 148 + .../userspace-api/media/v4l/pixfmt-yuv422p.rst | 136 + .../userspace-api/media/v4l/pixfmt-yuv444m.rst | 148 + .../userspace-api/media/v4l/pixfmt-yuyv.rst | 125 + .../userspace-api/media/v4l/pixfmt-yvyu.rst | 115 + .../userspace-api/media/v4l/pixfmt-z16.rst | 73 + Documentation/userspace-api/media/v4l/pixfmt.rst | 45 + .../userspace-api/media/v4l/planar-apis.rst | 68 + Documentation/userspace-api/media/v4l/querycap.rst | 41 + Documentation/userspace-api/media/v4l/rw.rst | 54 + .../userspace-api/media/v4l/sdr-formats.rst | 29 + .../media/v4l/selection-api-configuration.rst | 144 + .../media/v4l/selection-api-examples.rst | 91 + .../media/v4l/selection-api-intro.rst | 35 + .../media/v4l/selection-api-targets.rst | 27 + .../media/v4l/selection-api-vs-crop-api.rst | 46 + .../userspace-api/media/v4l/selection-api.rst | 23 + .../userspace-api/media/v4l/selection.svg | 1178 +++ .../userspace-api/media/v4l/selections-common.rst | 30 + Documentation/userspace-api/media/v4l/standard.rst | 192 + .../userspace-api/media/v4l/streaming-par.rst | 40 + .../userspace-api/media/v4l/subdev-formats.rst | 7833 ++++++++++++++++++++ .../media/v4l/subdev-image-processing-crop.svg | 312 + .../media/v4l/subdev-image-processing-full.svg | 752 ++ ...ubdev-image-processing-scaling-multi-source.svg | 550 ++ .../userspace-api/media/v4l/tch-formats.rst | 25 + Documentation/userspace-api/media/v4l/tuner.rst | 92 + .../userspace-api/media/v4l/user-func.rst | 88 + Documentation/userspace-api/media/v4l/userp.rst | 128 + .../media/v4l/v4l2-selection-flags.rst | 51 + .../media/v4l/v4l2-selection-targets.rst | 78 + Documentation/userspace-api/media/v4l/v4l2.rst | 423 ++ .../userspace-api/media/v4l/v4l2grab-example.rst | 24 + .../userspace-api/media/v4l/v4l2grab.c.rst | 176 + Documentation/userspace-api/media/v4l/vbi_525.svg | 821 ++ Documentation/userspace-api/media/v4l/vbi_625.svg | 870 +++ .../userspace-api/media/v4l/vbi_hsync.svg | 321 + Documentation/userspace-api/media/v4l/video.rst | 75 + Documentation/userspace-api/media/v4l/videodev.rst | 16 + .../userspace-api/media/v4l/vidioc-create-bufs.rst | 141 + .../userspace-api/media/v4l/vidioc-cropcap.rst | 143 + .../media/v4l/vidioc-dbg-g-chip-info.rst | 167 + .../media/v4l/vidioc-dbg-g-register.rst | 171 + .../userspace-api/media/v4l/vidioc-decoder-cmd.rst | 226 + .../userspace-api/media/v4l/vidioc-dqevent.rst | 391 + .../media/v4l/vidioc-dv-timings-cap.rst | 169 + .../userspace-api/media/v4l/vidioc-encoder-cmd.rst | 168 + .../media/v4l/vidioc-enum-dv-timings.rst | 114 + .../userspace-api/media/v4l/vidioc-enum-fmt.rst | 159 + .../media/v4l/vidioc-enum-frameintervals.rst | 203 + .../media/v4l/vidioc-enum-framesizes.rst | 213 + .../media/v4l/vidioc-enum-freq-bands.rst | 150 + .../userspace-api/media/v4l/vidioc-enumaudio.rst | 62 + .../media/v4l/vidioc-enumaudioout.rst | 67 + .../userspace-api/media/v4l/vidioc-enuminput.rst | 242 + .../userspace-api/media/v4l/vidioc-enumoutput.rst | 165 + .../userspace-api/media/v4l/vidioc-enumstd.rst | 367 + .../userspace-api/media/v4l/vidioc-expbuf.rst | 175 + .../userspace-api/media/v4l/vidioc-g-audio.rst | 135 + .../userspace-api/media/v4l/vidioc-g-audioout.rst | 108 + .../userspace-api/media/v4l/vidioc-g-crop.rst | 119 + .../userspace-api/media/v4l/vidioc-g-ctrl.rst | 106 + .../media/v4l/vidioc-g-dv-timings.rst | 312 + .../userspace-api/media/v4l/vidioc-g-edid.rst | 154 + .../userspace-api/media/v4l/vidioc-g-enc-index.rst | 156 + .../userspace-api/media/v4l/vidioc-g-ext-ctrls.rst | 416 ++ .../userspace-api/media/v4l/vidioc-g-fbuf.rst | 362 + .../userspace-api/media/v4l/vidioc-g-fmt.rst | 161 + .../userspace-api/media/v4l/vidioc-g-frequency.rst | 112 + .../userspace-api/media/v4l/vidioc-g-input.rst | 71 + .../userspace-api/media/v4l/vidioc-g-jpegcomp.rst | 134 + .../userspace-api/media/v4l/vidioc-g-modulator.rst | 202 + .../userspace-api/media/v4l/vidioc-g-output.rst | 73 + .../userspace-api/media/v4l/vidioc-g-parm.rst | 270 + .../userspace-api/media/v4l/vidioc-g-priority.rst | 100 + .../userspace-api/media/v4l/vidioc-g-selection.rst | 200 + .../media/v4l/vidioc-g-sliced-vbi-cap.rst | 202 + .../userspace-api/media/v4l/vidioc-g-std.rst | 81 + .../userspace-api/media/v4l/vidioc-g-tuner.rst | 476 ++ .../userspace-api/media/v4l/vidioc-log-status.rst | 56 + .../userspace-api/media/v4l/vidioc-overlay.rst | 61 + .../userspace-api/media/v4l/vidioc-prepare-buf.rst | 65 + .../userspace-api/media/v4l/vidioc-qbuf.rst | 205 + .../media/v4l/vidioc-query-dv-timings.rst | 94 + .../userspace-api/media/v4l/vidioc-querybuf.rst | 87 + .../userspace-api/media/v4l/vidioc-querycap.rst | 284 + .../userspace-api/media/v4l/vidioc-queryctrl.rst | 616 ++ .../userspace-api/media/v4l/vidioc-querystd.rst | 77 + .../userspace-api/media/v4l/vidioc-reqbufs.rst | 169 + .../media/v4l/vidioc-s-hw-freq-seek.rst | 147 + .../userspace-api/media/v4l/vidioc-streamon.rst | 113 + .../v4l/vidioc-subdev-enum-frame-interval.rst | 120 + .../media/v4l/vidioc-subdev-enum-frame-size.rst | 125 + .../media/v4l/vidioc-subdev-enum-mbus-code.rst | 98 + .../media/v4l/vidioc-subdev-g-crop.rst | 125 + .../media/v4l/vidioc-subdev-g-fmt.rst | 154 + .../media/v4l/vidioc-subdev-g-frame-interval.rst | 120 + .../media/v4l/vidioc-subdev-g-selection.rst | 125 + .../media/v4l/vidioc-subscribe-event.rst | 123 + .../userspace-api/media/v4l/yuv-formats.rst | 64 + .../userspace-api/media/video.h.rst.exceptions | 39 + .../userspace-api/media/videodev2.h.rst.exceptions | 572 ++ MAINTAINERS | 8 +- drivers/media/radio/Kconfig | 10 +- drivers/media/radio/wl128x/Kconfig | 2 +- 919 files changed, 81543 insertions(+), 81541 deletions(-) delete mode 100644 Documentation/media/Makefile delete mode 100644 Documentation/media/audio.h.rst.exceptions delete mode 100644 Documentation/media/ca.h.rst.exceptions delete mode 100644 Documentation/media/cec.h.rst.exceptions delete mode 100644 Documentation/media/conf_nitpick.py delete mode 100644 Documentation/media/dmx.h.rst.exceptions delete mode 100644 Documentation/media/frontend.h.rst.exceptions delete mode 100644 Documentation/media/intro.rst delete mode 100644 Documentation/media/lirc.h.rst.exceptions delete mode 100644 Documentation/media/media.h.rst.exceptions delete mode 100644 Documentation/media/media_uapi.rst delete mode 100644 Documentation/media/net.h.rst.exceptions delete mode 100644 Documentation/media/typical_media_device.svg delete mode 100644 Documentation/media/uapi/cec/cec-api.rst delete mode 100644 Documentation/media/uapi/cec/cec-func-close.rst delete mode 100644 Documentation/media/uapi/cec/cec-func-ioctl.rst delete mode 100644 Documentation/media/uapi/cec/cec-func-open.rst delete mode 100644 Documentation/media/uapi/cec/cec-func-poll.rst delete mode 100644 Documentation/media/uapi/cec/cec-funcs.rst delete mode 100644 Documentation/media/uapi/cec/cec-header.rst delete mode 100644 Documentation/media/uapi/cec/cec-intro.rst delete mode 100644 Documentation/media/uapi/cec/cec-ioc-adap-g-caps.rst delete mode 100644 Documentation/media/uapi/cec/cec-ioc-adap-g-conn-info.rst delete mode 100644 Documentation/media/uapi/cec/cec-ioc-adap-g-log-addrs.rst delete mode 100644 Documentation/media/uapi/cec/cec-ioc-adap-g-phys-addr.rst delete mode 100644 Documentation/media/uapi/cec/cec-ioc-dqevent.rst delete mode 100644 Documentation/media/uapi/cec/cec-ioc-g-mode.rst delete mode 100644 Documentation/media/uapi/cec/cec-ioc-receive.rst delete mode 100644 Documentation/media/uapi/cec/cec-pin-error-inj.rst delete mode 100644 Documentation/media/uapi/dvb/audio-bilingual-channel-select.rst delete mode 100644 Documentation/media/uapi/dvb/audio-channel-select.rst delete mode 100644 Documentation/media/uapi/dvb/audio-clear-buffer.rst delete mode 100644 Documentation/media/uapi/dvb/audio-continue.rst delete mode 100644 Documentation/media/uapi/dvb/audio-fclose.rst delete mode 100644 Documentation/media/uapi/dvb/audio-fopen.rst delete mode 100644 Documentation/media/uapi/dvb/audio-fwrite.rst delete mode 100644 Documentation/media/uapi/dvb/audio-get-capabilities.rst delete mode 100644 Documentation/media/uapi/dvb/audio-get-status.rst delete mode 100644 Documentation/media/uapi/dvb/audio-pause.rst delete mode 100644 Documentation/media/uapi/dvb/audio-play.rst delete mode 100644 Documentation/media/uapi/dvb/audio-select-source.rst delete mode 100644 Documentation/media/uapi/dvb/audio-set-av-sync.rst delete mode 100644 Documentation/media/uapi/dvb/audio-set-bypass-mode.rst delete mode 100644 Documentation/media/uapi/dvb/audio-set-id.rst delete mode 100644 Documentation/media/uapi/dvb/audio-set-mixer.rst delete mode 100644 Documentation/media/uapi/dvb/audio-set-mute.rst delete mode 100644 Documentation/media/uapi/dvb/audio-set-streamtype.rst delete mode 100644 Documentation/media/uapi/dvb/audio-stop.rst delete mode 100644 Documentation/media/uapi/dvb/audio.rst delete mode 100644 Documentation/media/uapi/dvb/audio_data_types.rst delete mode 100644 Documentation/media/uapi/dvb/audio_function_calls.rst delete mode 100644 Documentation/media/uapi/dvb/ca-fclose.rst delete mode 100644 Documentation/media/uapi/dvb/ca-fopen.rst delete mode 100644 Documentation/media/uapi/dvb/ca-get-cap.rst delete mode 100644 Documentation/media/uapi/dvb/ca-get-descr-info.rst delete mode 100644 Documentation/media/uapi/dvb/ca-get-msg.rst delete mode 100644 Documentation/media/uapi/dvb/ca-get-slot-info.rst delete mode 100644 Documentation/media/uapi/dvb/ca-reset.rst delete mode 100644 Documentation/media/uapi/dvb/ca-send-msg.rst delete mode 100644 Documentation/media/uapi/dvb/ca-set-descr.rst delete mode 100644 Documentation/media/uapi/dvb/ca.rst delete mode 100644 Documentation/media/uapi/dvb/ca_data_types.rst delete mode 100644 Documentation/media/uapi/dvb/ca_function_calls.rst delete mode 100644 Documentation/media/uapi/dvb/ca_high_level.rst delete mode 100644 Documentation/media/uapi/dvb/demux.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-add-pid.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-expbuf.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-fclose.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-fopen.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-fread.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-fwrite.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-get-pes-pids.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-get-stc.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-mmap.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-munmap.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-qbuf.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-querybuf.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-remove-pid.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-reqbufs.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-set-buffer-size.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-set-filter.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-set-pes-filter.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-start.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-stop.rst delete mode 100644 Documentation/media/uapi/dvb/dmx_fcalls.rst delete mode 100644 Documentation/media/uapi/dvb/dmx_types.rst delete mode 100644 Documentation/media/uapi/dvb/dvb-fe-read-status.rst delete mode 100644 Documentation/media/uapi/dvb/dvb-frontend-event.rst delete mode 100644 Documentation/media/uapi/dvb/dvb-frontend-parameters.rst delete mode 100644 Documentation/media/uapi/dvb/dvbapi.rst delete mode 100644 Documentation/media/uapi/dvb/dvbproperty.rst delete mode 100644 Documentation/media/uapi/dvb/dvbstb.svg delete mode 100644 Documentation/media/uapi/dvb/examples.rst delete mode 100644 Documentation/media/uapi/dvb/fe-bandwidth-t.rst delete mode 100644 Documentation/media/uapi/dvb/fe-diseqc-recv-slave-reply.rst delete mode 100644 Documentation/media/uapi/dvb/fe-diseqc-reset-overload.rst delete mode 100644 Documentation/media/uapi/dvb/fe-diseqc-send-burst.rst delete mode 100644 Documentation/media/uapi/dvb/fe-diseqc-send-master-cmd.rst delete mode 100644 Documentation/media/uapi/dvb/fe-dishnetwork-send-legacy-cmd.rst delete mode 100644 Documentation/media/uapi/dvb/fe-enable-high-lnb-voltage.rst delete mode 100644 Documentation/media/uapi/dvb/fe-get-event.rst delete mode 100644 Documentation/media/uapi/dvb/fe-get-frontend.rst delete mode 100644 Documentation/media/uapi/dvb/fe-get-info.rst delete mode 100644 Documentation/media/uapi/dvb/fe-get-property.rst delete mode 100644 Documentation/media/uapi/dvb/fe-read-ber.rst delete mode 100644 Documentation/media/uapi/dvb/fe-read-signal-strength.rst delete mode 100644 Documentation/media/uapi/dvb/fe-read-snr.rst delete mode 100644 Documentation/media/uapi/dvb/fe-read-status.rst delete mode 100644 Documentation/media/uapi/dvb/fe-read-uncorrected-blocks.rst delete mode 100644 Documentation/media/uapi/dvb/fe-set-frontend-tune-mode.rst delete mode 100644 Documentation/media/uapi/dvb/fe-set-frontend.rst delete mode 100644 Documentation/media/uapi/dvb/fe-set-tone.rst delete mode 100644 Documentation/media/uapi/dvb/fe-set-voltage.rst delete mode 100644 Documentation/media/uapi/dvb/fe-type-t.rst delete mode 100644 Documentation/media/uapi/dvb/fe_property_parameters.rst delete mode 100644 Documentation/media/uapi/dvb/frontend-header.rst delete mode 100644 Documentation/media/uapi/dvb/frontend-property-cable-systems.rst delete mode 100644 Documentation/media/uapi/dvb/frontend-property-satellite-systems.rst delete mode 100644 Documentation/media/uapi/dvb/frontend-property-terrestrial-systems.rst delete mode 100644 Documentation/media/uapi/dvb/frontend-stat-properties.rst delete mode 100644 Documentation/media/uapi/dvb/frontend.rst delete mode 100644 Documentation/media/uapi/dvb/frontend_f_close.rst delete mode 100644 Documentation/media/uapi/dvb/frontend_f_open.rst delete mode 100644 Documentation/media/uapi/dvb/frontend_fcalls.rst delete mode 100644 Documentation/media/uapi/dvb/frontend_legacy_api.rst delete mode 100644 Documentation/media/uapi/dvb/frontend_legacy_dvbv3_api.rst delete mode 100644 Documentation/media/uapi/dvb/headers.rst delete mode 100644 Documentation/media/uapi/dvb/intro.rst delete mode 100644 Documentation/media/uapi/dvb/legacy_dvb_apis.rst delete mode 100644 Documentation/media/uapi/dvb/net-add-if.rst delete mode 100644 Documentation/media/uapi/dvb/net-get-if.rst delete mode 100644 Documentation/media/uapi/dvb/net-remove-if.rst delete mode 100644 Documentation/media/uapi/dvb/net-types.rst delete mode 100644 Documentation/media/uapi/dvb/net.rst delete mode 100644 Documentation/media/uapi/dvb/query-dvb-frontend-info.rst delete mode 100644 Documentation/media/uapi/dvb/video-clear-buffer.rst delete mode 100644 Documentation/media/uapi/dvb/video-command.rst delete mode 100644 Documentation/media/uapi/dvb/video-continue.rst delete mode 100644 Documentation/media/uapi/dvb/video-fast-forward.rst delete mode 100644 Documentation/media/uapi/dvb/video-fclose.rst delete mode 100644 Documentation/media/uapi/dvb/video-fopen.rst delete mode 100644 Documentation/media/uapi/dvb/video-freeze.rst delete mode 100644 Documentation/media/uapi/dvb/video-fwrite.rst delete mode 100644 Documentation/media/uapi/dvb/video-get-capabilities.rst delete mode 100644 Documentation/media/uapi/dvb/video-get-event.rst delete mode 100644 Documentation/media/uapi/dvb/video-get-frame-count.rst delete mode 100644 Documentation/media/uapi/dvb/video-get-pts.rst delete mode 100644 Documentation/media/uapi/dvb/video-get-size.rst delete mode 100644 Documentation/media/uapi/dvb/video-get-status.rst delete mode 100644 Documentation/media/uapi/dvb/video-play.rst delete mode 100644 Documentation/media/uapi/dvb/video-select-source.rst delete mode 100644 Documentation/media/uapi/dvb/video-set-blank.rst delete mode 100644 Documentation/media/uapi/dvb/video-set-display-format.rst delete mode 100644 Documentation/media/uapi/dvb/video-set-format.rst delete mode 100644 Documentation/media/uapi/dvb/video-set-streamtype.rst delete mode 100644 Documentation/media/uapi/dvb/video-slowmotion.rst delete mode 100644 Documentation/media/uapi/dvb/video-stillpicture.rst delete mode 100644 Documentation/media/uapi/dvb/video-stop.rst delete mode 100644 Documentation/media/uapi/dvb/video-try-command.rst delete mode 100644 Documentation/media/uapi/dvb/video.rst delete mode 100644 Documentation/media/uapi/dvb/video_function_calls.rst delete mode 100644 Documentation/media/uapi/dvb/video_types.rst delete mode 100644 Documentation/media/uapi/fdl-appendix.rst delete mode 100644 Documentation/media/uapi/gen-errors.rst delete mode 100644 Documentation/media/uapi/mediactl/media-controller-intro.rst delete mode 100644 Documentation/media/uapi/mediactl/media-controller-model.rst delete mode 100644 Documentation/media/uapi/mediactl/media-controller.rst delete mode 100644 Documentation/media/uapi/mediactl/media-func-close.rst delete mode 100644 Documentation/media/uapi/mediactl/media-func-ioctl.rst delete mode 100644 Documentation/media/uapi/mediactl/media-func-open.rst delete mode 100644 Documentation/media/uapi/mediactl/media-funcs.rst delete mode 100644 Documentation/media/uapi/mediactl/media-header.rst delete mode 100644 Documentation/media/uapi/mediactl/media-ioc-device-info.rst delete mode 100644 Documentation/media/uapi/mediactl/media-ioc-enum-entities.rst delete mode 100644 Documentation/media/uapi/mediactl/media-ioc-enum-links.rst delete mode 100644 Documentation/media/uapi/mediactl/media-ioc-g-topology.rst delete mode 100644 Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst delete mode 100644 Documentation/media/uapi/mediactl/media-ioc-setup-link.rst delete mode 100644 Documentation/media/uapi/mediactl/media-request-ioc-queue.rst delete mode 100644 Documentation/media/uapi/mediactl/media-request-ioc-reinit.rst delete mode 100644 Documentation/media/uapi/mediactl/media-types.rst delete mode 100644 Documentation/media/uapi/mediactl/request-api.rst delete mode 100644 Documentation/media/uapi/mediactl/request-func-close.rst delete mode 100644 Documentation/media/uapi/mediactl/request-func-ioctl.rst delete mode 100644 Documentation/media/uapi/mediactl/request-func-poll.rst delete mode 100644 Documentation/media/uapi/rc/keytable.c.rst delete mode 100644 Documentation/media/uapi/rc/lirc-dev-intro.rst delete mode 100644 Documentation/media/uapi/rc/lirc-dev.rst delete mode 100644 Documentation/media/uapi/rc/lirc-func.rst delete mode 100644 Documentation/media/uapi/rc/lirc-get-features.rst delete mode 100644 Documentation/media/uapi/rc/lirc-get-rec-mode.rst delete mode 100644 Documentation/media/uapi/rc/lirc-get-rec-resolution.rst delete mode 100644 Documentation/media/uapi/rc/lirc-get-send-mode.rst delete mode 100644 Documentation/media/uapi/rc/lirc-get-timeout.rst delete mode 100644 Documentation/media/uapi/rc/lirc-header.rst delete mode 100644 Documentation/media/uapi/rc/lirc-read.rst delete mode 100644 Documentation/media/uapi/rc/lirc-set-measure-carrier-mode.rst delete mode 100644 Documentation/media/uapi/rc/lirc-set-rec-carrier-range.rst delete mode 100644 Documentation/media/uapi/rc/lirc-set-rec-carrier.rst delete mode 100644 Documentation/media/uapi/rc/lirc-set-rec-timeout-reports.rst delete mode 100644 Documentation/media/uapi/rc/lirc-set-rec-timeout.rst delete mode 100644 Documentation/media/uapi/rc/lirc-set-send-carrier.rst delete mode 100644 Documentation/media/uapi/rc/lirc-set-send-duty-cycle.rst delete mode 100644 Documentation/media/uapi/rc/lirc-set-transmitter-mask.rst delete mode 100644 Documentation/media/uapi/rc/lirc-set-wideband-receiver.rst delete mode 100644 Documentation/media/uapi/rc/lirc-write.rst delete mode 100644 Documentation/media/uapi/rc/rc-intro.rst delete mode 100644 Documentation/media/uapi/rc/rc-protos.rst delete mode 100644 Documentation/media/uapi/rc/rc-sysfs-nodes.rst delete mode 100644 Documentation/media/uapi/rc/rc-table-change.rst delete mode 100644 Documentation/media/uapi/rc/rc-tables.rst delete mode 100644 Documentation/media/uapi/rc/remote_controllers.rst delete mode 100644 Documentation/media/uapi/v4l/app-pri.rst delete mode 100644 Documentation/media/uapi/v4l/async.rst delete mode 100644 Documentation/media/uapi/v4l/audio.rst delete mode 100644 Documentation/media/uapi/v4l/bayer.svg delete mode 100644 Documentation/media/uapi/v4l/biblio.rst delete mode 100644 Documentation/media/uapi/v4l/buffer.rst delete mode 100644 Documentation/media/uapi/v4l/capture-example.rst delete mode 100644 Documentation/media/uapi/v4l/capture.c.rst delete mode 100644 Documentation/media/uapi/v4l/colorspaces-defs.rst delete mode 100644 Documentation/media/uapi/v4l/colorspaces-details.rst delete mode 100644 Documentation/media/uapi/v4l/colorspaces.rst delete mode 100644 Documentation/media/uapi/v4l/common-defs.rst delete mode 100644 Documentation/media/uapi/v4l/common.rst delete mode 100644 Documentation/media/uapi/v4l/compat.rst delete mode 100644 Documentation/media/uapi/v4l/constraints.svg delete mode 100644 Documentation/media/uapi/v4l/control.rst delete mode 100644 Documentation/media/uapi/v4l/crop.rst delete mode 100644 Documentation/media/uapi/v4l/crop.svg delete mode 100644 Documentation/media/uapi/v4l/depth-formats.rst delete mode 100644 Documentation/media/uapi/v4l/dev-capture.rst delete mode 100644 Documentation/media/uapi/v4l/dev-decoder.rst delete mode 100644 Documentation/media/uapi/v4l/dev-event.rst delete mode 100644 Documentation/media/uapi/v4l/dev-mem2mem.rst delete mode 100644 Documentation/media/uapi/v4l/dev-meta.rst delete mode 100644 Documentation/media/uapi/v4l/dev-osd.rst delete mode 100644 Documentation/media/uapi/v4l/dev-output.rst delete mode 100644 Documentation/media/uapi/v4l/dev-overlay.rst delete mode 100644 Documentation/media/uapi/v4l/dev-radio.rst delete mode 100644 Documentation/media/uapi/v4l/dev-raw-vbi.rst delete mode 100644 Documentation/media/uapi/v4l/dev-rds.rst delete mode 100644 Documentation/media/uapi/v4l/dev-sdr.rst delete mode 100644 Documentation/media/uapi/v4l/dev-sliced-vbi.rst delete mode 100644 Documentation/media/uapi/v4l/dev-stateless-decoder.rst delete mode 100644 Documentation/media/uapi/v4l/dev-subdev.rst delete mode 100644 Documentation/media/uapi/v4l/dev-touch.rst delete mode 100644 Documentation/media/uapi/v4l/devices.rst delete mode 100644 Documentation/media/uapi/v4l/diff-v4l.rst delete mode 100644 Documentation/media/uapi/v4l/dmabuf.rst delete mode 100644 Documentation/media/uapi/v4l/dv-timings.rst delete mode 100644 Documentation/media/uapi/v4l/ext-ctrls-camera.rst delete mode 100644 Documentation/media/uapi/v4l/ext-ctrls-codec.rst delete mode 100644 Documentation/media/uapi/v4l/ext-ctrls-detect.rst delete mode 100644 Documentation/media/uapi/v4l/ext-ctrls-dv.rst delete mode 100644 Documentation/media/uapi/v4l/ext-ctrls-flash.rst delete mode 100644 Documentation/media/uapi/v4l/ext-ctrls-fm-rx.rst delete mode 100644 Documentation/media/uapi/v4l/ext-ctrls-fm-tx.rst delete mode 100644 Documentation/media/uapi/v4l/ext-ctrls-image-process.rst delete mode 100644 Documentation/media/uapi/v4l/ext-ctrls-image-source.rst delete mode 100644 Documentation/media/uapi/v4l/ext-ctrls-jpeg.rst delete mode 100644 Documentation/media/uapi/v4l/ext-ctrls-rf-tuner.rst delete mode 100644 Documentation/media/uapi/v4l/extended-controls.rst delete mode 100644 Documentation/media/uapi/v4l/field-order.rst delete mode 100644 Documentation/media/uapi/v4l/fieldseq_bt.svg delete mode 100644 Documentation/media/uapi/v4l/fieldseq_tb.svg delete mode 100644 Documentation/media/uapi/v4l/format.rst delete mode 100644 Documentation/media/uapi/v4l/func-close.rst delete mode 100644 Documentation/media/uapi/v4l/func-ioctl.rst delete mode 100644 Documentation/media/uapi/v4l/func-mmap.rst delete mode 100644 Documentation/media/uapi/v4l/func-munmap.rst delete mode 100644 Documentation/media/uapi/v4l/func-open.rst delete mode 100644 Documentation/media/uapi/v4l/func-poll.rst delete mode 100644 Documentation/media/uapi/v4l/func-read.rst delete mode 100644 Documentation/media/uapi/v4l/func-select.rst delete mode 100644 Documentation/media/uapi/v4l/func-write.rst delete mode 100644 Documentation/media/uapi/v4l/hist-v4l2.rst delete mode 100644 Documentation/media/uapi/v4l/hsv-formats.rst delete mode 100644 Documentation/media/uapi/v4l/io.rst delete mode 100644 Documentation/media/uapi/v4l/libv4l-introduction.rst delete mode 100644 Documentation/media/uapi/v4l/libv4l.rst delete mode 100644 Documentation/media/uapi/v4l/meta-formats.rst delete mode 100644 Documentation/media/uapi/v4l/mmap.rst delete mode 100644 Documentation/media/uapi/v4l/nv12mt.svg delete mode 100644 Documentation/media/uapi/v4l/nv12mt_example.svg delete mode 100644 Documentation/media/uapi/v4l/open.rst delete mode 100644 Documentation/media/uapi/v4l/pipeline.dot delete mode 100644 Documentation/media/uapi/v4l/pixfmt-bayer.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-cnf4.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-compressed.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-grey.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-indexed.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-intro.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-inzi.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-m420.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-meta-d4xx.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-meta-intel-ipu3.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-meta-uvc.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-meta-vivid.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgo.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgt.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-nv12.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-nv12m.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-nv12mt.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-nv16.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-nv16m.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-nv24.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-packed-hsv.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-packed-yuv.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-reserved.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-rgb.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-sdr-cs08.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-sdr-cs14le.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-sdr-cu08.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-sdr-cu16le.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-sdr-pcu16be.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-sdr-pcu18be.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-sdr-pcu20be.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-sdr-ru12le.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-srggb10-ipu3.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-srggb10.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-srggb10alaw8.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-srggb10dpcm8.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-srggb10p.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-srggb12.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-srggb12p.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-srggb14.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-srggb14p.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-srggb16.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-srggb8.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-tch-td08.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-tch-td16.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-tch-tu08.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-tch-tu16.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-uv8.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-uyvy.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-v4l2-mplane.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-v4l2.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-vyuy.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-y10.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-y10b.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-y10p.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-y12.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-y12i.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-y14.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-y16-be.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-y16.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-y41p.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-y8i.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-yuv410.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-yuv411p.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-yuv420.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-yuv420m.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-yuv422m.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-yuv422p.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-yuv444m.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-yuyv.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-yvyu.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-z16.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt.rst delete mode 100644 Documentation/media/uapi/v4l/planar-apis.rst delete mode 100644 Documentation/media/uapi/v4l/querycap.rst delete mode 100644 Documentation/media/uapi/v4l/rw.rst delete mode 100644 Documentation/media/uapi/v4l/sdr-formats.rst delete mode 100644 Documentation/media/uapi/v4l/selection-api-configuration.rst delete mode 100644 Documentation/media/uapi/v4l/selection-api-examples.rst delete mode 100644 Documentation/media/uapi/v4l/selection-api-intro.rst delete mode 100644 Documentation/media/uapi/v4l/selection-api-targets.rst delete mode 100644 Documentation/media/uapi/v4l/selection-api-vs-crop-api.rst delete mode 100644 Documentation/media/uapi/v4l/selection-api.rst delete mode 100644 Documentation/media/uapi/v4l/selection.svg delete mode 100644 Documentation/media/uapi/v4l/selections-common.rst delete mode 100644 Documentation/media/uapi/v4l/standard.rst delete mode 100644 Documentation/media/uapi/v4l/streaming-par.rst delete mode 100644 Documentation/media/uapi/v4l/subdev-formats.rst delete mode 100644 Documentation/media/uapi/v4l/subdev-image-processing-crop.svg delete mode 100644 Documentation/media/uapi/v4l/subdev-image-processing-full.svg delete mode 100644 Documentation/media/uapi/v4l/subdev-image-processing-scaling-multi-source.svg delete mode 100644 Documentation/media/uapi/v4l/tch-formats.rst delete mode 100644 Documentation/media/uapi/v4l/tuner.rst delete mode 100644 Documentation/media/uapi/v4l/user-func.rst delete mode 100644 Documentation/media/uapi/v4l/userp.rst delete mode 100644 Documentation/media/uapi/v4l/v4l2-selection-flags.rst delete mode 100644 Documentation/media/uapi/v4l/v4l2-selection-targets.rst delete mode 100644 Documentation/media/uapi/v4l/v4l2.rst delete mode 100644 Documentation/media/uapi/v4l/v4l2grab-example.rst delete mode 100644 Documentation/media/uapi/v4l/v4l2grab.c.rst delete mode 100644 Documentation/media/uapi/v4l/vbi_525.svg delete mode 100644 Documentation/media/uapi/v4l/vbi_625.svg delete mode 100644 Documentation/media/uapi/v4l/vbi_hsync.svg delete mode 100644 Documentation/media/uapi/v4l/video.rst delete mode 100644 Documentation/media/uapi/v4l/videodev.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-create-bufs.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-cropcap.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-dbg-g-chip-info.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-dbg-g-register.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-dqevent.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-dv-timings-cap.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-enum-dv-timings.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-enum-fmt.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-enum-frameintervals.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-enum-framesizes.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-enum-freq-bands.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-enumaudio.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-enumaudioout.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-enuminput.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-enumoutput.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-enumstd.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-expbuf.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-audio.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-audioout.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-crop.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-ctrl.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-edid.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-enc-index.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-ext-ctrls.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-fbuf.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-fmt.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-frequency.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-input.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-jpegcomp.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-modulator.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-output.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-parm.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-priority.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-selection.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-sliced-vbi-cap.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-std.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-tuner.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-log-status.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-overlay.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-prepare-buf.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-qbuf.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-query-dv-timings.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-querybuf.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-querycap.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-queryctrl.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-querystd.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-reqbufs.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-s-hw-freq-seek.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-streamon.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-subdev-enum-frame-interval.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-subdev-enum-frame-size.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-subdev-enum-mbus-code.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-subscribe-event.rst delete mode 100644 Documentation/media/uapi/v4l/yuv-formats.rst delete mode 100644 Documentation/media/video.h.rst.exceptions delete mode 100644 Documentation/media/videodev2.h.rst.exceptions create mode 100644 Documentation/userspace-api/media/Makefile create mode 100644 Documentation/userspace-api/media/audio.h.rst.exceptions create mode 100644 Documentation/userspace-api/media/ca.h.rst.exceptions create mode 100644 Documentation/userspace-api/media/cec.h.rst.exceptions create mode 100644 Documentation/userspace-api/media/cec/cec-api.rst create mode 100644 Documentation/userspace-api/media/cec/cec-func-close.rst create mode 100644 Documentation/userspace-api/media/cec/cec-func-ioctl.rst create mode 100644 Documentation/userspace-api/media/cec/cec-func-open.rst create mode 100644 Documentation/userspace-api/media/cec/cec-func-poll.rst create mode 100644 Documentation/userspace-api/media/cec/cec-funcs.rst create mode 100644 Documentation/userspace-api/media/cec/cec-header.rst create mode 100644 Documentation/userspace-api/media/cec/cec-intro.rst create mode 100644 Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst create mode 100644 Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst create mode 100644 Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst create mode 100644 Documentation/userspace-api/media/cec/cec-ioc-adap-g-phys-addr.rst create mode 100644 Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst create mode 100644 Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst create mode 100644 Documentation/userspace-api/media/cec/cec-ioc-receive.rst create mode 100644 Documentation/userspace-api/media/cec/cec-pin-error-inj.rst create mode 100644 Documentation/userspace-api/media/conf_nitpick.py create mode 100644 Documentation/userspace-api/media/dmx.h.rst.exceptions create mode 100644 Documentation/userspace-api/media/dvb/audio-bilingual-channel-select.rst create mode 100644 Documentation/userspace-api/media/dvb/audio-channel-select.rst create mode 100644 Documentation/userspace-api/media/dvb/audio-clear-buffer.rst create mode 100644 Documentation/userspace-api/media/dvb/audio-continue.rst create mode 100644 Documentation/userspace-api/media/dvb/audio-fclose.rst create mode 100644 Documentation/userspace-api/media/dvb/audio-fopen.rst create mode 100644 Documentation/userspace-api/media/dvb/audio-fwrite.rst create mode 100644 Documentation/userspace-api/media/dvb/audio-get-capabilities.rst create mode 100644 Documentation/userspace-api/media/dvb/audio-get-status.rst create mode 100644 Documentation/userspace-api/media/dvb/audio-pause.rst create mode 100644 Documentation/userspace-api/media/dvb/audio-play.rst create mode 100644 Documentation/userspace-api/media/dvb/audio-select-source.rst create mode 100644 Documentation/userspace-api/media/dvb/audio-set-av-sync.rst create mode 100644 Documentation/userspace-api/media/dvb/audio-set-bypass-mode.rst create mode 100644 Documentation/userspace-api/media/dvb/audio-set-id.rst create mode 100644 Documentation/userspace-api/media/dvb/audio-set-mixer.rst create mode 100644 Documentation/userspace-api/media/dvb/audio-set-mute.rst create mode 100644 Documentation/userspace-api/media/dvb/audio-set-streamtype.rst create mode 100644 Documentation/userspace-api/media/dvb/audio-stop.rst create mode 100644 Documentation/userspace-api/media/dvb/audio.rst create mode 100644 Documentation/userspace-api/media/dvb/audio_data_types.rst create mode 100644 Documentation/userspace-api/media/dvb/audio_function_calls.rst create mode 100644 Documentation/userspace-api/media/dvb/ca-fclose.rst create mode 100644 Documentation/userspace-api/media/dvb/ca-fopen.rst create mode 100644 Documentation/userspace-api/media/dvb/ca-get-cap.rst create mode 100644 Documentation/userspace-api/media/dvb/ca-get-descr-info.rst create mode 100644 Documentation/userspace-api/media/dvb/ca-get-msg.rst create mode 100644 Documentation/userspace-api/media/dvb/ca-get-slot-info.rst create mode 100644 Documentation/userspace-api/media/dvb/ca-reset.rst create mode 100644 Documentation/userspace-api/media/dvb/ca-send-msg.rst create mode 100644 Documentation/userspace-api/media/dvb/ca-set-descr.rst create mode 100644 Documentation/userspace-api/media/dvb/ca.rst create mode 100644 Documentation/userspace-api/media/dvb/ca_data_types.rst create mode 100644 Documentation/userspace-api/media/dvb/ca_function_calls.rst create mode 100644 Documentation/userspace-api/media/dvb/ca_high_level.rst create mode 100644 Documentation/userspace-api/media/dvb/demux.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-add-pid.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-expbuf.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-fclose.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-fopen.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-fread.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-fwrite.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-get-pes-pids.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-get-stc.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-mmap.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-munmap.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-qbuf.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-querybuf.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-remove-pid.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-reqbufs.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-set-buffer-size.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-set-filter.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-set-pes-filter.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-start.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-stop.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx_fcalls.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx_types.rst create mode 100644 Documentation/userspace-api/media/dvb/dvb-fe-read-status.rst create mode 100644 Documentation/userspace-api/media/dvb/dvb-frontend-event.rst create mode 100644 Documentation/userspace-api/media/dvb/dvb-frontend-parameters.rst create mode 100644 Documentation/userspace-api/media/dvb/dvbapi.rst create mode 100644 Documentation/userspace-api/media/dvb/dvbproperty.rst create mode 100644 Documentation/userspace-api/media/dvb/dvbstb.svg create mode 100644 Documentation/userspace-api/media/dvb/examples.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-bandwidth-t.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-diseqc-recv-slave-reply.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-diseqc-reset-overload.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-diseqc-send-burst.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-diseqc-send-master-cmd.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-dishnetwork-send-legacy-cmd.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-enable-high-lnb-voltage.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-get-event.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-get-frontend.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-get-info.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-get-property.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-read-ber.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-read-signal-strength.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-read-snr.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-read-status.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-read-uncorrected-blocks.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-set-frontend-tune-mode.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-set-frontend.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-set-tone.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-set-voltage.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-type-t.rst create mode 100644 Documentation/userspace-api/media/dvb/fe_property_parameters.rst create mode 100644 Documentation/userspace-api/media/dvb/frontend-header.rst create mode 100644 Documentation/userspace-api/media/dvb/frontend-property-cable-systems.rst create mode 100644 Documentation/userspace-api/media/dvb/frontend-property-satellite-systems.rst create mode 100644 Documentation/userspace-api/media/dvb/frontend-property-terrestrial-systems.rst create mode 100644 Documentation/userspace-api/media/dvb/frontend-stat-properties.rst create mode 100644 Documentation/userspace-api/media/dvb/frontend.rst create mode 100644 Documentation/userspace-api/media/dvb/frontend_f_close.rst create mode 100644 Documentation/userspace-api/media/dvb/frontend_f_open.rst create mode 100644 Documentation/userspace-api/media/dvb/frontend_fcalls.rst create mode 100644 Documentation/userspace-api/media/dvb/frontend_legacy_api.rst create mode 100644 Documentation/userspace-api/media/dvb/frontend_legacy_dvbv3_api.rst create mode 100644 Documentation/userspace-api/media/dvb/headers.rst create mode 100644 Documentation/userspace-api/media/dvb/intro.rst create mode 100644 Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst create mode 100644 Documentation/userspace-api/media/dvb/net-add-if.rst create mode 100644 Documentation/userspace-api/media/dvb/net-get-if.rst create mode 100644 Documentation/userspace-api/media/dvb/net-remove-if.rst create mode 100644 Documentation/userspace-api/media/dvb/net-types.rst create mode 100644 Documentation/userspace-api/media/dvb/net.rst create mode 100644 Documentation/userspace-api/media/dvb/query-dvb-frontend-info.rst create mode 100644 Documentation/userspace-api/media/dvb/video-clear-buffer.rst create mode 100644 Documentation/userspace-api/media/dvb/video-command.rst create mode 100644 Documentation/userspace-api/media/dvb/video-continue.rst create mode 100644 Documentation/userspace-api/media/dvb/video-fast-forward.rst create mode 100644 Documentation/userspace-api/media/dvb/video-fclose.rst create mode 100644 Documentation/userspace-api/media/dvb/video-fopen.rst create mode 100644 Documentation/userspace-api/media/dvb/video-freeze.rst create mode 100644 Documentation/userspace-api/media/dvb/video-fwrite.rst create mode 100644 Documentation/userspace-api/media/dvb/video-get-capabilities.rst create mode 100644 Documentation/userspace-api/media/dvb/video-get-event.rst create mode 100644 Documentation/userspace-api/media/dvb/video-get-frame-count.rst create mode 100644 Documentation/userspace-api/media/dvb/video-get-pts.rst create mode 100644 Documentation/userspace-api/media/dvb/video-get-size.rst create mode 100644 Documentation/userspace-api/media/dvb/video-get-status.rst create mode 100644 Documentation/userspace-api/media/dvb/video-play.rst create mode 100644 Documentation/userspace-api/media/dvb/video-select-source.rst create mode 100644 Documentation/userspace-api/media/dvb/video-set-blank.rst create mode 100644 Documentation/userspace-api/media/dvb/video-set-display-format.rst create mode 100644 Documentation/userspace-api/media/dvb/video-set-format.rst create mode 100644 Documentation/userspace-api/media/dvb/video-set-streamtype.rst create mode 100644 Documentation/userspace-api/media/dvb/video-slowmotion.rst create mode 100644 Documentation/userspace-api/media/dvb/video-stillpicture.rst create mode 100644 Documentation/userspace-api/media/dvb/video-stop.rst create mode 100644 Documentation/userspace-api/media/dvb/video-try-command.rst create mode 100644 Documentation/userspace-api/media/dvb/video.rst create mode 100644 Documentation/userspace-api/media/dvb/video_function_calls.rst create mode 100644 Documentation/userspace-api/media/dvb/video_types.rst create mode 100644 Documentation/userspace-api/media/fdl-appendix.rst create mode 100644 Documentation/userspace-api/media/frontend.h.rst.exceptions create mode 100644 Documentation/userspace-api/media/gen-errors.rst create mode 100644 Documentation/userspace-api/media/index.rst create mode 100644 Documentation/userspace-api/media/intro.rst create mode 100644 Documentation/userspace-api/media/lirc.h.rst.exceptions create mode 100644 Documentation/userspace-api/media/media.h.rst.exceptions create mode 100644 Documentation/userspace-api/media/mediactl/media-controller-intro.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-controller-model.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-controller.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-func-close.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-func-ioctl.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-func-open.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-funcs.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-header.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-ioc-request-alloc.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-ioc-setup-link.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-request-ioc-queue.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-request-ioc-reinit.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-types.rst create mode 100644 Documentation/userspace-api/media/mediactl/request-api.rst create mode 100644 Documentation/userspace-api/media/mediactl/request-func-close.rst create mode 100644 Documentation/userspace-api/media/mediactl/request-func-ioctl.rst create mode 100644 Documentation/userspace-api/media/mediactl/request-func-poll.rst create mode 100644 Documentation/userspace-api/media/net.h.rst.exceptions create mode 100644 Documentation/userspace-api/media/rc/keytable.c.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-dev-intro.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-dev.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-func.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-get-features.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-get-send-mode.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-get-timeout.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-header.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-read.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-set-rec-timeout-reports.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-write.rst create mode 100644 Documentation/userspace-api/media/rc/rc-intro.rst create mode 100644 Documentation/userspace-api/media/rc/rc-protos.rst create mode 100644 Documentation/userspace-api/media/rc/rc-sysfs-nodes.rst create mode 100644 Documentation/userspace-api/media/rc/rc-table-change.rst create mode 100644 Documentation/userspace-api/media/rc/rc-tables.rst create mode 100644 Documentation/userspace-api/media/rc/remote_controllers.rst create mode 100644 Documentation/userspace-api/media/typical_media_device.svg create mode 100644 Documentation/userspace-api/media/v4l/app-pri.rst create mode 100644 Documentation/userspace-api/media/v4l/async.rst create mode 100644 Documentation/userspace-api/media/v4l/audio.rst create mode 100644 Documentation/userspace-api/media/v4l/bayer.svg create mode 100644 Documentation/userspace-api/media/v4l/biblio.rst create mode 100644 Documentation/userspace-api/media/v4l/buffer.rst create mode 100644 Documentation/userspace-api/media/v4l/capture-example.rst create mode 100644 Documentation/userspace-api/media/v4l/capture.c.rst create mode 100644 Documentation/userspace-api/media/v4l/colorspaces-defs.rst create mode 100644 Documentation/userspace-api/media/v4l/colorspaces-details.rst create mode 100644 Documentation/userspace-api/media/v4l/colorspaces.rst create mode 100644 Documentation/userspace-api/media/v4l/common-defs.rst create mode 100644 Documentation/userspace-api/media/v4l/common.rst create mode 100644 Documentation/userspace-api/media/v4l/compat.rst create mode 100644 Documentation/userspace-api/media/v4l/constraints.svg create mode 100644 Documentation/userspace-api/media/v4l/control.rst create mode 100644 Documentation/userspace-api/media/v4l/crop.rst create mode 100644 Documentation/userspace-api/media/v4l/crop.svg create mode 100644 Documentation/userspace-api/media/v4l/depth-formats.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-capture.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-decoder.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-event.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-mem2mem.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-meta.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-osd.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-output.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-overlay.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-radio.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-raw-vbi.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-rds.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-sdr.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-stateless-decoder.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-subdev.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-touch.rst create mode 100644 Documentation/userspace-api/media/v4l/devices.rst create mode 100644 Documentation/userspace-api/media/v4l/diff-v4l.rst create mode 100644 Documentation/userspace-api/media/v4l/dmabuf.rst create mode 100644 Documentation/userspace-api/media/v4l/dv-timings.rst create mode 100644 Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst create mode 100644 Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst create mode 100644 Documentation/userspace-api/media/v4l/ext-ctrls-detect.rst create mode 100644 Documentation/userspace-api/media/v4l/ext-ctrls-dv.rst create mode 100644 Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst create mode 100644 Documentation/userspace-api/media/v4l/ext-ctrls-fm-rx.rst create mode 100644 Documentation/userspace-api/media/v4l/ext-ctrls-fm-tx.rst create mode 100644 Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst create mode 100644 Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst create mode 100644 Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst create mode 100644 Documentation/userspace-api/media/v4l/ext-ctrls-rf-tuner.rst create mode 100644 Documentation/userspace-api/media/v4l/extended-controls.rst create mode 100644 Documentation/userspace-api/media/v4l/field-order.rst create mode 100644 Documentation/userspace-api/media/v4l/fieldseq_bt.svg create mode 100644 Documentation/userspace-api/media/v4l/fieldseq_tb.svg create mode 100644 Documentation/userspace-api/media/v4l/format.rst create mode 100644 Documentation/userspace-api/media/v4l/func-close.rst create mode 100644 Documentation/userspace-api/media/v4l/func-ioctl.rst create mode 100644 Documentation/userspace-api/media/v4l/func-mmap.rst create mode 100644 Documentation/userspace-api/media/v4l/func-munmap.rst create mode 100644 Documentation/userspace-api/media/v4l/func-open.rst create mode 100644 Documentation/userspace-api/media/v4l/func-poll.rst create mode 100644 Documentation/userspace-api/media/v4l/func-read.rst create mode 100644 Documentation/userspace-api/media/v4l/func-select.rst create mode 100644 Documentation/userspace-api/media/v4l/func-write.rst create mode 100644 Documentation/userspace-api/media/v4l/hist-v4l2.rst create mode 100644 Documentation/userspace-api/media/v4l/hsv-formats.rst create mode 100644 Documentation/userspace-api/media/v4l/io.rst create mode 100644 Documentation/userspace-api/media/v4l/libv4l-introduction.rst create mode 100644 Documentation/userspace-api/media/v4l/libv4l.rst create mode 100644 Documentation/userspace-api/media/v4l/meta-formats.rst create mode 100644 Documentation/userspace-api/media/v4l/mmap.rst create mode 100644 Documentation/userspace-api/media/v4l/nv12mt.svg create mode 100644 Documentation/userspace-api/media/v4l/nv12mt_example.svg create mode 100644 Documentation/userspace-api/media/v4l/open.rst create mode 100644 Documentation/userspace-api/media/v4l/pipeline.dot create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-bayer.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-cnf4.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-compressed.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-grey.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-indexed.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-intro.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-inzi.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-m420.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-meta-intel-ipu3.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-meta-uvc.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-meta-vivid.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-meta-vsp1-hgo.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-meta-vsp1-hgt.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-nv12.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-nv12m.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-nv12mt.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-nv16.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-nv16m.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-nv24.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-packed-hsv.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-reserved.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-rgb.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-sdr-cs08.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-sdr-cs14le.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-sdr-cu08.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-sdr-cu16le.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu16be.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu18be.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu20be.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-sdr-ru12le.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-srggb10-ipu3.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-srggb10.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-srggb10alaw8.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-srggb10dpcm8.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-srggb10p.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-srggb12.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-srggb14.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-srggb16.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-srggb8.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-tch-td08.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-tch-td16.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-tch-tu08.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-tch-tu16.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-uv8.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-uyvy.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-v4l2-mplane.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-vyuy.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-y10.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-y10b.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-y10p.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-y12.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-y12i.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-y14.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-y16-be.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-y16.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-y41p.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-y8i.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-yuv410.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-yuv411p.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-yuv420.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-yuv420m.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-yuv422m.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-yuv422p.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-yuv444m.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-yuyv.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-yvyu.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-z16.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt.rst create mode 100644 Documentation/userspace-api/media/v4l/planar-apis.rst create mode 100644 Documentation/userspace-api/media/v4l/querycap.rst create mode 100644 Documentation/userspace-api/media/v4l/rw.rst create mode 100644 Documentation/userspace-api/media/v4l/sdr-formats.rst create mode 100644 Documentation/userspace-api/media/v4l/selection-api-configuration.rst create mode 100644 Documentation/userspace-api/media/v4l/selection-api-examples.rst create mode 100644 Documentation/userspace-api/media/v4l/selection-api-intro.rst create mode 100644 Documentation/userspace-api/media/v4l/selection-api-targets.rst create mode 100644 Documentation/userspace-api/media/v4l/selection-api-vs-crop-api.rst create mode 100644 Documentation/userspace-api/media/v4l/selection-api.rst create mode 100644 Documentation/userspace-api/media/v4l/selection.svg create mode 100644 Documentation/userspace-api/media/v4l/selections-common.rst create mode 100644 Documentation/userspace-api/media/v4l/standard.rst create mode 100644 Documentation/userspace-api/media/v4l/streaming-par.rst create mode 100644 Documentation/userspace-api/media/v4l/subdev-formats.rst create mode 100644 Documentation/userspace-api/media/v4l/subdev-image-processing-crop.svg create mode 100644 Documentation/userspace-api/media/v4l/subdev-image-processing-full.svg create mode 100644 Documentation/userspace-api/media/v4l/subdev-image-processing-scaling-multi-source.svg create mode 100644 Documentation/userspace-api/media/v4l/tch-formats.rst create mode 100644 Documentation/userspace-api/media/v4l/tuner.rst create mode 100644 Documentation/userspace-api/media/v4l/user-func.rst create mode 100644 Documentation/userspace-api/media/v4l/userp.rst create mode 100644 Documentation/userspace-api/media/v4l/v4l2-selection-flags.rst create mode 100644 Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst create mode 100644 Documentation/userspace-api/media/v4l/v4l2.rst create mode 100644 Documentation/userspace-api/media/v4l/v4l2grab-example.rst create mode 100644 Documentation/userspace-api/media/v4l/v4l2grab.c.rst create mode 100644 Documentation/userspace-api/media/v4l/vbi_525.svg create mode 100644 Documentation/userspace-api/media/v4l/vbi_625.svg create mode 100644 Documentation/userspace-api/media/v4l/vbi_hsync.svg create mode 100644 Documentation/userspace-api/media/v4l/video.rst create mode 100644 Documentation/userspace-api/media/v4l/videodev.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-cropcap.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-dbg-g-chip-info.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-dbg-g-register.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-dqevent.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-dv-timings-cap.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-enum-dv-timings.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-enum-frameintervals.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-enum-framesizes.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-enum-freq-bands.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-enumaudio.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-enumaudioout.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-enuminput.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-enumoutput.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-enumstd.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-expbuf.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-audio.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-audioout.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-crop.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-dv-timings.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-edid.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-enc-index.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-fmt.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-frequency.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-input.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-jpegcomp.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-modulator.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-output.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-parm.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-priority.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-selection.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-sliced-vbi-cap.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-std.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-tuner.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-log-status.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-overlay.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-prepare-buf.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-qbuf.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-query-dv-timings.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-querybuf.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-querycap.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-querystd.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-s-hw-freq-seek.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-streamon.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-interval.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst create mode 100644 Documentation/userspace-api/media/v4l/yuv-formats.rst create mode 100644 Documentation/userspace-api/media/video.h.rst.exceptions create mode 100644 Documentation/userspace-api/media/videodev2.h.rst.exceptions (limited to 'Documentation') diff --git a/Documentation/ABI/testing/debugfs-cec-error-inj b/Documentation/ABI/testing/debugfs-cec-error-inj index 4c3596c6d25b..5afcd78fbdb7 100644 --- a/Documentation/ABI/testing/debugfs-cec-error-inj +++ b/Documentation/ABI/testing/debugfs-cec-error-inj @@ -37,4 +37,4 @@ when changes are made. The following CEC error injection implementations exist: -- Documentation/media/uapi/cec/cec-pin-error-inj.rst +- Documentation/userspace-api/media/cec/cec-pin-error-inj.rst diff --git a/Documentation/Makefile b/Documentation/Makefile index cc786d11a028..7e12d10ca8e0 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -55,15 +55,15 @@ I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit; # $2 sphinx builder e.g. "html" -# $3 name of the build subfolder / e.g. "media", used as: +# $3 name of the build subfolder / e.g. "userspace-api/media", used as: # * dest folder relative to $(BUILDDIR) and # * cache folder relative to $(BUILDDIR)/.doctrees -# $4 dest subfolder e.g. "man" for man pages at media/man +# $4 dest subfolder e.g. "man" for man pages at userspace-api/media/man # $5 reST source folder relative to $(srctree)/$(src), -# e.g. "media" for the linux-tv book-set at ./Documentation/media +# e.g. "userspace-api/media" for the linux-tv book-set at ./Documentation/userspace-api/media quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) - cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media $2 && \ + cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media $2 && \ PYTHONDONTWRITEBYTECODE=1 \ BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \ $(PYTHON) $(srctree)/scripts/jobserver-exec \ @@ -120,7 +120,7 @@ refcheckdocs: cleandocs: $(Q)rm -rf $(BUILDDIR) - $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media clean + $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media clean dochelp: @echo ' Linux kernel internal documentation in different formats from ReST:' diff --git a/Documentation/doc-guide/parse-headers.rst b/Documentation/doc-guide/parse-headers.rst index 24cfaa15dd81..f7135b058246 100644 --- a/Documentation/doc-guide/parse-headers.rst +++ b/Documentation/doc-guide/parse-headers.rst @@ -10,7 +10,7 @@ if a symbol is not found at the documentation. That helps to keep the uAPI documentation in sync with the Kernel changes. The :ref:`parse_headers.pl ` provide a way to generate such cross-references. It has to be called via Makefile, while building the -documentation. Please see ``Documentation/media/Makefile`` for an example +documentation. Please see ``Documentation/userspace-api/media/Makefile`` for an example about how to use it inside the Kernel tree. .. _parse_headers: diff --git a/Documentation/fb/api.rst b/Documentation/fb/api.rst index 79ec33dded74..4f00e7196fef 100644 --- a/Documentation/fb/api.rst +++ b/Documentation/fb/api.rst @@ -290,12 +290,12 @@ the FB_CAP_FOURCC bit in the fb_fix_screeninfo capabilities field. FOURCC definitions are located in the linux/videodev2.h header. However, and despite starting with the V4L2_PIX_FMT_prefix, they are not restricted to V4L2 and don't require usage of the V4L2 subsystem. FOURCC documentation is -available in Documentation/media/uapi/v4l/pixfmt.rst. +available in Documentation/userspace-api/media/v4l/pixfmt.rst. To select a format, applications set the grayscale field to the desired FOURCC. For YUV formats, they should also select the appropriate colorspace by setting the colorspace field to one of the colorspaces listed in linux/videodev2.h and -documented in Documentation/media/uapi/v4l/colorspaces.rst. +documented in Documentation/userspace-api/media/v4l/colorspaces.rst. The red, green, blue and transp fields are not used with the FOURCC-based API. For forward compatibility reasons applications must zero those fields, and diff --git a/Documentation/media/Makefile b/Documentation/media/Makefile deleted file mode 100644 index d75d70f191bc..000000000000 --- a/Documentation/media/Makefile +++ /dev/null @@ -1,69 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 - -# Rules to convert a .h file to inline RST documentation - -SRC_DIR=$(srctree)/Documentation/media -PARSER = $(srctree)/Documentation/sphinx/parse-headers.pl -UAPI = $(srctree)/include/uapi/linux -KAPI = $(srctree)/include/linux - -FILES = audio.h.rst ca.h.rst dmx.h.rst frontend.h.rst net.h.rst video.h.rst \ - videodev2.h.rst media.h.rst cec.h.rst lirc.h.rst - -TARGETS := $(addprefix $(BUILDDIR)/, $(FILES)) - -gen_rst = \ - echo ${PARSER} $< $@ $(SRC_DIR)/$(notdir $@).exceptions; \ - ${PARSER} $< $@ $(SRC_DIR)/$(notdir $@).exceptions - -quiet_gen_rst = echo ' PARSE $(patsubst $(srctree)/%,%,$<)'; \ - ${PARSER} $< $@ $(SRC_DIR)/$(notdir $@).exceptions - -silent_gen_rst = ${gen_rst} - -$(BUILDDIR)/audio.h.rst: ${UAPI}/dvb/audio.h ${PARSER} $(SRC_DIR)/audio.h.rst.exceptions - @$($(quiet)gen_rst) - -$(BUILDDIR)/ca.h.rst: ${UAPI}/dvb/ca.h ${PARSER} $(SRC_DIR)/ca.h.rst.exceptions - @$($(quiet)gen_rst) - -$(BUILDDIR)/dmx.h.rst: ${UAPI}/dvb/dmx.h ${PARSER} $(SRC_DIR)/dmx.h.rst.exceptions - @$($(quiet)gen_rst) - -$(BUILDDIR)/frontend.h.rst: ${UAPI}/dvb/frontend.h ${PARSER} $(SRC_DIR)/frontend.h.rst.exceptions - @$($(quiet)gen_rst) - -$(BUILDDIR)/net.h.rst: ${UAPI}/dvb/net.h ${PARSER} $(SRC_DIR)/net.h.rst.exceptions - @$($(quiet)gen_rst) - -$(BUILDDIR)/video.h.rst: ${UAPI}/dvb/video.h ${PARSER} $(SRC_DIR)/video.h.rst.exceptions - @$($(quiet)gen_rst) - -$(BUILDDIR)/videodev2.h.rst: ${UAPI}/videodev2.h ${PARSER} $(SRC_DIR)/videodev2.h.rst.exceptions - @$($(quiet)gen_rst) - -$(BUILDDIR)/media.h.rst: ${UAPI}/media.h ${PARSER} $(SRC_DIR)/media.h.rst.exceptions - @$($(quiet)gen_rst) - -$(BUILDDIR)/cec.h.rst: ${UAPI}/cec.h ${PARSER} $(SRC_DIR)/cec.h.rst.exceptions - @$($(quiet)gen_rst) - -$(BUILDDIR)/lirc.h.rst: ${UAPI}/lirc.h ${PARSER} $(SRC_DIR)/lirc.h.rst.exceptions - @$($(quiet)gen_rst) - -# Media build rules - -.PHONY: all html epub xml latex - -all: $(IMGDOT) $(BUILDDIR) ${TARGETS} -html: all -epub: all -xml: all -latex: $(IMGPDF) all -linkcheck: - -clean: - -rm -f $(DOTTGT) $(IMGTGT) ${TARGETS} 2>/dev/null - -$(BUILDDIR): - $(Q)mkdir -p $@ diff --git a/Documentation/media/audio.h.rst.exceptions b/Documentation/media/audio.h.rst.exceptions deleted file mode 100644 index cf6620477f73..000000000000 --- a/Documentation/media/audio.h.rst.exceptions +++ /dev/null @@ -1,19 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 - -# Ignore header name -ignore define _DVBAUDIO_H_ - -# Undocumented audio caps, as this is a deprecated API anyway -ignore define AUDIO_CAP_DTS -ignore define AUDIO_CAP_LPCM -ignore define AUDIO_CAP_MP1 -ignore define AUDIO_CAP_MP2 -ignore define AUDIO_CAP_MP3 -ignore define AUDIO_CAP_AAC -ignore define AUDIO_CAP_OGG -ignore define AUDIO_CAP_SDDS -ignore define AUDIO_CAP_AC3 - -# some typedefs should point to struct/enums -replace typedef audio_mixer_t :c:type:`audio_mixer` -replace typedef audio_status_t :c:type:`audio_status` diff --git a/Documentation/media/ca.h.rst.exceptions b/Documentation/media/ca.h.rst.exceptions deleted file mode 100644 index f6828238eb48..000000000000 --- a/Documentation/media/ca.h.rst.exceptions +++ /dev/null @@ -1,25 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 - -# Ignore header name -ignore define _DVBCA_H_ - -# struct ca_slot_info defines -replace define CA_CI :c:type:`ca_slot_info` -replace define CA_CI_LINK :c:type:`ca_slot_info` -replace define CA_CI_PHYS :c:type:`ca_slot_info` -replace define CA_DESCR :c:type:`ca_slot_info` -replace define CA_SC :c:type:`ca_slot_info` -replace define CA_CI_MODULE_PRESENT :c:type:`ca_slot_info` -replace define CA_CI_MODULE_READY :c:type:`ca_slot_info` - -# struct ca_descr_info defines -replace define CA_ECD :c:type:`ca_descr_info` -replace define CA_NDS :c:type:`ca_descr_info` -replace define CA_DSS :c:type:`ca_descr_info` - -# some typedefs should point to struct/enums -replace typedef ca_slot_info_t :c:type:`ca_slot_info` -replace typedef ca_descr_info_t :c:type:`ca_descr_info` -replace typedef ca_caps_t :c:type:`ca_caps` -replace typedef ca_msg_t :c:type:`ca_msg` -replace typedef ca_descr_t :c:type:`ca_descr` diff --git a/Documentation/media/cec.h.rst.exceptions b/Documentation/media/cec.h.rst.exceptions deleted file mode 100644 index d83790ccac8e..000000000000 --- a/Documentation/media/cec.h.rst.exceptions +++ /dev/null @@ -1,575 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 - -# Ignore header name -ignore define _CEC_UAPI_H - -# define macros to ignore - -ignore define CEC_MAX_MSG_SIZE -ignore define CEC_MAX_LOG_ADDRS - -ignore define CEC_LOG_ADDR_MASK_TV -ignore define CEC_LOG_ADDR_MASK_RECORD -ignore define CEC_LOG_ADDR_MASK_TUNER -ignore define CEC_LOG_ADDR_MASK_PLAYBACK -ignore define CEC_LOG_ADDR_MASK_AUDIOSYSTEM -ignore define CEC_LOG_ADDR_MASK_BACKUP -ignore define CEC_LOG_ADDR_MASK_SPECIFIC -ignore define CEC_LOG_ADDR_MASK_UNREGISTERED - -# Shouldn't them be documented? -ignore define CEC_LOG_ADDR_INVALID -ignore define CEC_PHYS_ADDR_INVALID - -ignore define CEC_VENDOR_ID_NONE - -ignore define CEC_MODE_INITIATOR_MSK -ignore define CEC_MODE_FOLLOWER_MSK - -# Part of CEC 2.0 spec - shouldn't be documented too? -ignore define CEC_LOG_ADDR_TV -ignore define CEC_LOG_ADDR_RECORD_1 -ignore define CEC_LOG_ADDR_RECORD_2 -ignore define CEC_LOG_ADDR_TUNER_1 -ignore define CEC_LOG_ADDR_PLAYBACK_1 -ignore define CEC_LOG_ADDR_AUDIOSYSTEM -ignore define CEC_LOG_ADDR_TUNER_2 -ignore define CEC_LOG_ADDR_TUNER_3 -ignore define CEC_LOG_ADDR_PLAYBACK_2 -ignore define CEC_LOG_ADDR_RECORD_3 -ignore define CEC_LOG_ADDR_TUNER_4 -ignore define CEC_LOG_ADDR_PLAYBACK_3 -ignore define CEC_LOG_ADDR_BACKUP_1 -ignore define CEC_LOG_ADDR_BACKUP_2 -ignore define CEC_LOG_ADDR_SPECIFIC -ignore define CEC_LOG_ADDR_UNREGISTERED -ignore define CEC_LOG_ADDR_BROADCAST - -# IMHO, those should also be documented - -ignore define CEC_MSG_ACTIVE_SOURCE -ignore define CEC_MSG_IMAGE_VIEW_ON -ignore define CEC_MSG_TEXT_VIEW_ON - -ignore define CEC_MSG_INACTIVE_SOURCE -ignore define CEC_MSG_REQUEST_ACTIVE_SOURCE -ignore define CEC_MSG_ROUTING_CHANGE -ignore define CEC_MSG_ROUTING_INFORMATION -ignore define CEC_MSG_SET_STREAM_PATH - -ignore define CEC_MSG_STANDBY - -ignore define CEC_MSG_RECORD_OFF -ignore define CEC_MSG_RECORD_ON - -ignore define CEC_OP_RECORD_SRC_OWN -ignore define CEC_OP_RECORD_SRC_DIGITAL -ignore define CEC_OP_RECORD_SRC_ANALOG -ignore define CEC_OP_RECORD_SRC_EXT_PLUG -ignore define CEC_OP_RECORD_SRC_EXT_PHYS_ADDR - -ignore define CEC_OP_SERVICE_ID_METHOD_BY_DIG_ID -ignore define CEC_OP_SERVICE_ID_METHOD_BY_CHANNEL - -ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ARIB_GEN -ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ATSC_GEN -ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_DVB_GEN -ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ARIB_BS -ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ARIB_CS -ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ARIB_T -ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ATSC_CABLE -ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ATSC_SAT -ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ATSC_T -ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_DVB_C -ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_DVB_S -ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_DVB_S2 -ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_DVB_T - -ignore define CEC_OP_ANA_BCAST_TYPE_CABLE -ignore define CEC_OP_ANA_BCAST_TYPE_SATELLITE -ignore define CEC_OP_ANA_BCAST_TYPE_TERRESTRIAL - -ignore define CEC_OP_BCAST_SYSTEM_PAL_BG -ignore define CEC_OP_BCAST_SYSTEM_SECAM_LQ -ignore define CEC_OP_BCAST_SYSTEM_PAL_M -ignore define CEC_OP_BCAST_SYSTEM_NTSC_M -ignore define CEC_OP_BCAST_SYSTEM_PAL_I -ignore define CEC_OP_BCAST_SYSTEM_SECAM_DK -ignore define CEC_OP_BCAST_SYSTEM_SECAM_BG -ignore define CEC_OP_BCAST_SYSTEM_SECAM_L -ignore define CEC_OP_BCAST_SYSTEM_PAL_DK -ignore define CEC_OP_BCAST_SYSTEM_OTHER - -ignore define CEC_OP_CHANNEL_NUMBER_FMT_1_PART -ignore define CEC_OP_CHANNEL_NUMBER_FMT_2_PART - -ignore define CEC_MSG_RECORD_STATUS - -ignore define CEC_OP_RECORD_STATUS_CUR_SRC -ignore define CEC_OP_RECORD_STATUS_DIG_SERVICE -ignore define CEC_OP_RECORD_STATUS_ANA_SERVICE -ignore define CEC_OP_RECORD_STATUS_EXT_INPUT -ignore define CEC_OP_RECORD_STATUS_NO_DIG_SERVICE -ignore define CEC_OP_RECORD_STATUS_NO_ANA_SERVICE -ignore define CEC_OP_RECORD_STATUS_NO_SERVICE -ignore define CEC_OP_RECORD_STATUS_INVALID_EXT_PLUG -ignore define CEC_OP_RECORD_STATUS_INVALID_EXT_PHYS_ADDR -ignore define CEC_OP_RECORD_STATUS_UNSUP_CA -ignore define CEC_OP_RECORD_STATUS_NO_CA_ENTITLEMENTS -ignore define CEC_OP_RECORD_STATUS_CANT_COPY_SRC -ignore define CEC_OP_RECORD_STATUS_NO_MORE_COPIES -ignore define CEC_OP_RECORD_STATUS_NO_MEDIA -ignore define CEC_OP_RECORD_STATUS_PLAYING -ignore define CEC_OP_RECORD_STATUS_ALREADY_RECORDING -ignore define CEC_OP_RECORD_STATUS_MEDIA_PROT -ignore define CEC_OP_RECORD_STATUS_NO_SIGNAL -ignore define CEC_OP_RECORD_STATUS_MEDIA_PROBLEM -ignore define CEC_OP_RECORD_STATUS_NO_SPACE -ignore define CEC_OP_RECORD_STATUS_PARENTAL_LOCK -ignore define CEC_OP_RECORD_STATUS_TERMINATED_OK -ignore define CEC_OP_RECORD_STATUS_ALREADY_TERM -ignore define CEC_OP_RECORD_STATUS_OTHER - -ignore define CEC_MSG_RECORD_TV_SCREEN - -ignore define CEC_MSG_CLEAR_ANALOGUE_TIMER - -ignore define CEC_OP_REC_SEQ_SUNDAY -ignore define CEC_OP_REC_SEQ_MONDAY -ignore define CEC_OP_REC_SEQ_TUESDAY -ignore define CEC_OP_REC_SEQ_WEDNESDAY -ignore define CEC_OP_REC_SEQ_THURSDAY -ignore define CEC_OP_REC_SEQ_FRIDAY -ignore define CEC_OP_REC_SEQ_SATERDAY -ignore define CEC_OP_REC_SEQ_ONCE_ONLY - -ignore define CEC_MSG_CLEAR_DIGITAL_TIMER - -ignore define CEC_MSG_CLEAR_EXT_TIMER - -ignore define CEC_OP_EXT_SRC_PLUG -ignore define CEC_OP_EXT_SRC_PHYS_ADDR - -ignore define CEC_MSG_SET_ANALOGUE_TIMER -ignore define CEC_MSG_SET_DIGITAL_TIMER -ignore define CEC_MSG_SET_EXT_TIMER - -ignore define CEC_MSG_SET_TIMER_PROGRAM_TITLE -ignore define CEC_MSG_TIMER_CLEARED_STATUS - -ignore define CEC_OP_TIMER_CLR_STAT_RECORDING -ignore define CEC_OP_TIMER_CLR_STAT_NO_MATCHING -ignore define CEC_OP_TIMER_CLR_STAT_NO_INFO -ignore define CEC_OP_TIMER_CLR_STAT_CLEARED - -ignore define CEC_MSG_TIMER_STATUS - -ignore define CEC_OP_TIMER_OVERLAP_WARNING_NO_OVERLAP -ignore define CEC_OP_TIMER_OVERLAP_WARNING_OVERLAP - -ignore define CEC_OP_MEDIA_INFO_UNPROT_MEDIA -ignore define CEC_OP_MEDIA_INFO_PROT_MEDIA -ignore define CEC_OP_MEDIA_INFO_NO_MEDIA - -ignore define CEC_OP_PROG_IND_NOT_PROGRAMMED -ignore define CEC_OP_PROG_IND_PROGRAMMED - -ignore define CEC_OP_PROG_INFO_ENOUGH_SPACE -ignore define CEC_OP_PROG_INFO_NOT_ENOUGH_SPACE -ignore define CEC_OP_PROG_INFO_MIGHT_NOT_BE_ENOUGH_SPACE -ignore define CEC_OP_PROG_INFO_NONE_AVAILABLE - -ignore define CEC_OP_PROG_ERROR_NO_FREE_TIMER -ignore define CEC_OP_PROG_ERROR_DATE_OUT_OF_RANGE -ignore define CEC_OP_PROG_ERROR_REC_SEQ_ERROR -ignore define CEC_OP_PROG_ERROR_INV_EXT_PLUG -ignore define CEC_OP_PROG_ERROR_INV_EXT_PHYS_ADDR -ignore define CEC_OP_PROG_ERROR_CA_UNSUPP -ignore define CEC_OP_PROG_ERROR_INSUF_CA_ENTITLEMENTS -ignore define CEC_OP_PROG_ERROR_RESOLUTION_UNSUPP -ignore define CEC_OP_PROG_ERROR_PARENTAL_LOCK -ignore define CEC_OP_PROG_ERROR_CLOCK_FAILURE -ignore define CEC_OP_PROG_ERROR_DUPLICATE - -ignore define CEC_MSG_CEC_VERSION - -ignore define CEC_OP_CEC_VERSION_1_3A -ignore define CEC_OP_CEC_VERSION_1_4 -ignore define CEC_OP_CEC_VERSION_2_0 - -ignore define CEC_MSG_GET_CEC_VERSION -ignore define CEC_MSG_GIVE_PHYSICAL_ADDR -ignore define CEC_MSG_GET_MENU_LANGUAGE -ignore define CEC_MSG_REPORT_PHYSICAL_ADDR - -ignore define CEC_OP_PRIM_DEVTYPE_TV -ignore define CEC_OP_PRIM_DEVTYPE_RECORD -ignore define CEC_OP_PRIM_DEVTYPE_TUNER -ignore define CEC_OP_PRIM_DEVTYPE_PLAYBACK -ignore define CEC_OP_PRIM_DEVTYPE_AUDIOSYSTEM -ignore define CEC_OP_PRIM_DEVTYPE_SWITCH -ignore define CEC_OP_PRIM_DEVTYPE_PROCESSOR - -ignore define CEC_MSG_SET_MENU_LANGUAGE -ignore define CEC_MSG_REPORT_FEATURES - -ignore define CEC_OP_ALL_DEVTYPE_TV -ignore define CEC_OP_ALL_DEVTYPE_RECORD -ignore define CEC_OP_ALL_DEVTYPE_TUNER -ignore define CEC_OP_ALL_DEVTYPE_PLAYBACK -ignore define CEC_OP_ALL_DEVTYPE_AUDIOSYSTEM -ignore define CEC_OP_ALL_DEVTYPE_SWITCH - -ignore define CEC_OP_FEAT_EXT - -ignore define CEC_OP_FEAT_RC_TV_PROFILE_NONE -ignore define CEC_OP_FEAT_RC_TV_PROFILE_1 -ignore define CEC_OP_FEAT_RC_TV_PROFILE_2 -ignore define CEC_OP_FEAT_RC_TV_PROFILE_3 -ignore define CEC_OP_FEAT_RC_TV_PROFILE_4 -ignore define CEC_OP_FEAT_RC_SRC_HAS_DEV_ROOT_MENU -ignore define CEC_OP_FEAT_RC_SRC_HAS_DEV_SETUP_MENU -ignore define CEC_OP_FEAT_RC_SRC_HAS_CONTENTS_MENU -ignore define CEC_OP_FEAT_RC_SRC_HAS_MEDIA_TOP_MENU -ignore define CEC_OP_FEAT_RC_SRC_HAS_MEDIA_CONTEXT_MENU - -ignore define CEC_OP_FEAT_DEV_HAS_RECORD_TV_SCREEN -ignore define CEC_OP_FEAT_DEV_HAS_SET_OSD_STRING -ignore define CEC_OP_FEAT_DEV_HAS_DECK_CONTROL -ignore define CEC_OP_FEAT_DEV_HAS_SET_AUDIO_RATE -ignore define CEC_OP_FEAT_DEV_SINK_HAS_ARC_TX -ignore define CEC_OP_FEAT_DEV_SOURCE_HAS_ARC_RX - -ignore define CEC_MSG_GIVE_FEATURES - -ignore define CEC_MSG_DECK_CONTROL - -ignore define CEC_OP_DECK_CTL_MODE_SKIP_FWD -ignore define CEC_OP_DECK_CTL_MODE_SKIP_REV -ignore define CEC_OP_DECK_CTL_MODE_STOP -ignore define CEC_OP_DECK_CTL_MODE_EJECT - -ignore define CEC_MSG_DECK_STATUS - -ignore define CEC_OP_DECK_INFO_PLAY -ignore define CEC_OP_DECK_INFO_RECORD -ignore define CEC_OP_DECK_INFO_PLAY_REV -ignore define CEC_OP_DECK_INFO_STILL -ignore define CEC_OP_DECK_INFO_SLOW -ignore define CEC_OP_DECK_INFO_SLOW_REV -ignore define CEC_OP_DECK_INFO_FAST_FWD -ignore define CEC_OP_DECK_INFO_FAST_REV -ignore define CEC_OP_DECK_INFO_NO_MEDIA -ignore define CEC_OP_DECK_INFO_STOP -ignore define CEC_OP_DECK_INFO_SKIP_FWD -ignore define CEC_OP_DECK_INFO_SKIP_REV -ignore define CEC_OP_DECK_INFO_INDEX_SEARCH_FWD -ignore define CEC_OP_DECK_INFO_INDEX_SEARCH_REV -ignore define CEC_OP_DECK_INFO_OTHER - -ignore define CEC_MSG_GIVE_DECK_STATUS - -ignore define CEC_OP_STATUS_REQ_ON -ignore define CEC_OP_STATUS_REQ_OFF -ignore define CEC_OP_STATUS_REQ_ONCE - -ignore define CEC_MSG_PLAY - -ignore define CEC_OP_PLAY_MODE_PLAY_FWD -ignore define CEC_OP_PLAY_MODE_PLAY_REV -ignore define CEC_OP_PLAY_MODE_PLAY_STILL -ignore define CEC_OP_PLAY_MODE_PLAY_FAST_FWD_MIN -ignore define CEC_OP_PLAY_MODE_PLAY_FAST_FWD_MED -ignore define CEC_OP_PLAY_MODE_PLAY_FAST_FWD_MAX -ignore define CEC_OP_PLAY_MODE_PLAY_FAST_REV_MIN -ignore define CEC_OP_PLAY_MODE_PLAY_FAST_REV_MED -ignore define CEC_OP_PLAY_MODE_PLAY_FAST_REV_MAX -ignore define CEC_OP_PLAY_MODE_PLAY_SLOW_FWD_MIN -ignore define CEC_OP_PLAY_MODE_PLAY_SLOW_FWD_MED -ignore define CEC_OP_PLAY_MODE_PLAY_SLOW_FWD_MAX -ignore define CEC_OP_PLAY_MODE_PLAY_SLOW_REV_MIN -ignore define CEC_OP_PLAY_MODE_PLAY_SLOW_REV_MED -ignore define CEC_OP_PLAY_MODE_PLAY_SLOW_REV_MAX - -ignore define CEC_MSG_GIVE_TUNER_DEVICE_STATUS -ignore define CEC_MSG_SELECT_ANALOGUE_SERVICE -ignore define CEC_MSG_SELECT_DIGITAL_SERVICE -ignore define CEC_MSG_TUNER_DEVICE_STATUS - -ignore define CEC_OP_REC_FLAG_USED -ignore define CEC_OP_REC_FLAG_NOT_USED - -ignore define CEC_OP_TUNER_DISPLAY_INFO_DIGITAL -ignore define CEC_OP_TUNER_DISPLAY_INFO_NONE -ignore define CEC_OP_TUNER_DISPLAY_INFO_ANALOGUE - -ignore define CEC_MSG_TUNER_STEP_DECREMENT -ignore define CEC_MSG_TUNER_STEP_INCREMENT - -ignore define CEC_MSG_DEVICE_VENDOR_ID -ignore define CEC_MSG_GIVE_DEVICE_VENDOR_ID -ignore define CEC_MSG_VENDOR_COMMAND -ignore define CEC_MSG_VENDOR_COMMAND_WITH_ID -ignore define CEC_MSG_VENDOR_REMOTE_BUTTON_DOWN -ignore define CEC_MSG_VENDOR_REMOTE_BUTTON_UP - -ignore define CEC_MSG_SET_OSD_STRING - -ignore define CEC_OP_DISP_CTL_DEFAULT -ignore define CEC_OP_DISP_CTL_UNTIL_CLEARED -ignore define CEC_OP_DISP_CTL_CLEAR - -ignore define CEC_MSG_GIVE_OSD_NAME -ignore define CEC_MSG_SET_OSD_NAME - -ignore define CEC_MSG_MENU_REQUEST - -ignore define CEC_OP_MENU_REQUEST_ACTIVATE -ignore define CEC_OP_MENU_REQUEST_DEACTIVATE -ignore define CEC_OP_MENU_REQUEST_QUERY - -ignore define CEC_MSG_MENU_STATUS - -ignore define CEC_OP_MENU_STATE_ACTIVATED -ignore define CEC_OP_MENU_STATE_DEACTIVATED - -ignore define CEC_MSG_USER_CONTROL_PRESSED - -ignore define CEC_OP_UI_CMD_SELECT -ignore define CEC_OP_UI_CMD_UP -ignore define CEC_OP_UI_CMD_DOWN -ignore define CEC_OP_UI_CMD_LEFT -ignore define CEC_OP_UI_CMD_RIGHT -ignore define CEC_OP_UI_CMD_RIGHT_UP -ignore define CEC_OP_UI_CMD_RIGHT_DOWN -ignore define CEC_OP_UI_CMD_LEFT_UP -ignore define CEC_OP_UI_CMD_LEFT_DOWN -ignore define CEC_OP_UI_CMD_DEVICE_ROOT_MENU -ignore define CEC_OP_UI_CMD_DEVICE_SETUP_MENU -ignore define CEC_OP_UI_CMD_CONTENTS_MENU -ignore define CEC_OP_UI_CMD_FAVORITE_MENU -ignore define CEC_OP_UI_CMD_BACK -ignore define CEC_OP_UI_CMD_MEDIA_TOP_MENU -ignore define CEC_OP_UI_CMD_MEDIA_CONTEXT_SENSITIVE_MENU -ignore define CEC_OP_UI_CMD_NUMBER_ENTRY_MODE -ignore define CEC_OP_UI_CMD_NUMBER_11 -ignore define CEC_OP_UI_CMD_NUMBER_12 -ignore define CEC_OP_UI_CMD_NUMBER_0_OR_NUMBER_10 -ignore define CEC_OP_UI_CMD_NUMBER_1 -ignore define CEC_OP_UI_CMD_NUMBER_2 -ignore define CEC_OP_UI_CMD_NUMBER_3 -ignore define CEC_OP_UI_CMD_NUMBER_4 -ignore define CEC_OP_UI_CMD_NUMBER_5 -ignore define CEC_OP_UI_CMD_NUMBER_6 -ignore define CEC_OP_UI_CMD_NUMBER_7 -ignore define CEC_OP_UI_CMD_NUMBER_8 -ignore define CEC_OP_UI_CMD_NUMBER_9 -ignore define CEC_OP_UI_CMD_DOT -ignore define CEC_OP_UI_CMD_ENTER -ignore define CEC_OP_UI_CMD_CLEAR -ignore define CEC_OP_UI_CMD_NEXT_FAVORITE -ignore define CEC_OP_UI_CMD_CHANNEL_UP -ignore define CEC_OP_UI_CMD_CHANNEL_DOWN -ignore define CEC_OP_UI_CMD_PREVIOUS_CHANNEL -ignore define CEC_OP_UI_CMD_SOUND_SELECT -ignore define CEC_OP_UI_CMD_INPUT_SELECT -ignore define CEC_OP_UI_CMD_DISPLAY_INFORMATION -ignore define CEC_OP_UI_CMD_HELP -ignore define CEC_OP_UI_CMD_PAGE_UP -ignore define CEC_OP_UI_CMD_PAGE_DOWN -ignore define CEC_OP_UI_CMD_POWER -ignore define CEC_OP_UI_CMD_VOLUME_UP -ignore define CEC_OP_UI_CMD_VOLUME_DOWN -ignore define CEC_OP_UI_CMD_MUTE -ignore define CEC_OP_UI_CMD_PLAY -ignore define CEC_OP_UI_CMD_STOP -ignore define CEC_OP_UI_CMD_PAUSE -ignore define CEC_OP_UI_CMD_RECORD -ignore define CEC_OP_UI_CMD_REWIND -ignore define CEC_OP_UI_CMD_FAST_FORWARD -ignore define CEC_OP_UI_CMD_EJECT -ignore define CEC_OP_UI_CMD_SKIP_FORWARD -ignore define CEC_OP_UI_CMD_SKIP_BACKWARD -ignore define CEC_OP_UI_CMD_STOP_RECORD -ignore define CEC_OP_UI_CMD_PAUSE_RECORD -ignore define CEC_OP_UI_CMD_ANGLE -ignore define CEC_OP_UI_CMD_SUB_PICTURE -ignore define CEC_OP_UI_CMD_VIDEO_ON_DEMAND -ignore define CEC_OP_UI_CMD_ELECTRONIC_PROGRAM_GUIDE -ignore define CEC_OP_UI_CMD_TIMER_PROGRAMMING -ignore define CEC_OP_UI_CMD_INITIAL_CONFIGURATION -ignore define CEC_OP_UI_CMD_SELECT_BROADCAST_TYPE -ignore define CEC_OP_UI_CMD_SELECT_SOUND_PRESENTATION -ignore define CEC_OP_UI_CMD_AUDIO_DESCRIPTION -ignore define CEC_OP_UI_CMD_INTERNET -ignore define CEC_OP_UI_CMD_3D_MODE -ignore define CEC_OP_UI_CMD_PLAY_FUNCTION -ignore define CEC_OP_UI_CMD_PAUSE_PLAY_FUNCTION -ignore define CEC_OP_UI_CMD_RECORD_FUNCTION -ignore define CEC_OP_UI_CMD_PAUSE_RECORD_FUNCTION -ignore define CEC_OP_UI_CMD_STOP_FUNCTION -ignore define CEC_OP_UI_CMD_MUTE_FUNCTION -ignore define CEC_OP_UI_CMD_RESTORE_VOLUME_FUNCTION -ignore define CEC_OP_UI_CMD_TUNE_FUNCTION -ignore define CEC_OP_UI_CMD_SELECT_MEDIA_FUNCTION -ignore define CEC_OP_UI_CMD_SELECT_AV_INPUT_FUNCTION -ignore define CEC_OP_UI_CMD_SELECT_AUDIO_INPUT_FUNCTION -ignore define CEC_OP_UI_CMD_POWER_TOGGLE_FUNCTION -ignore define CEC_OP_UI_CMD_POWER_OFF_FUNCTION -ignore define CEC_OP_UI_CMD_POWER_ON_FUNCTION -ignore define CEC_OP_UI_CMD_F1_BLUE -ignore define CEC_OP_UI_CMD_F2_RED -ignore define CEC_OP_UI_CMD_F3_GREEN -ignore define CEC_OP_UI_CMD_F4_YELLOW -ignore define CEC_OP_UI_CMD_F5 -ignore define CEC_OP_UI_CMD_DATA - -ignore define CEC_OP_UI_BCAST_TYPE_TOGGLE_ALL -ignore define CEC_OP_UI_BCAST_TYPE_TOGGLE_DIG_ANA -ignore define CEC_OP_UI_BCAST_TYPE_ANALOGUE -ignore define CEC_OP_UI_BCAST_TYPE_ANALOGUE_T -ignore define CEC_OP_UI_BCAST_TYPE_ANALOGUE_CABLE -ignore define CEC_OP_UI_BCAST_TYPE_ANALOGUE_SAT -ignore define CEC_OP_UI_BCAST_TYPE_DIGITAL -ignore define CEC_OP_UI_BCAST_TYPE_DIGITAL_T -ignore define CEC_OP_UI_BCAST_TYPE_DIGITAL_CABLE -ignore define CEC_OP_UI_BCAST_TYPE_DIGITAL_SAT -ignore define CEC_OP_UI_BCAST_TYPE_DIGITAL_COM_SAT -ignore define CEC_OP_UI_BCAST_TYPE_DIGITAL_COM_SAT2 -ignore define CEC_OP_UI_BCAST_TYPE_IP - -ignore define CEC_OP_UI_SND_PRES_CTL_DUAL_MONO -ignore define CEC_OP_UI_SND_PRES_CTL_KARAOKE -ignore define CEC_OP_UI_SND_PRES_CTL_DOWNMIX -ignore define CEC_OP_UI_SND_PRES_CTL_REVERB -ignore define CEC_OP_UI_SND_PRES_CTL_EQUALIZER -ignore define CEC_OP_UI_SND_PRES_CTL_BASS_UP -ignore define CEC_OP_UI_SND_PRES_CTL_BASS_NEUTRAL -ignore define CEC_OP_UI_SND_PRES_CTL_BASS_DOWN -ignore define CEC_OP_UI_SND_PRES_CTL_TREBLE_UP -ignore define CEC_OP_UI_SND_PRES_CTL_TREBLE_NEUTRAL -ignore define CEC_OP_UI_SND_PRES_CTL_TREBLE_DOWN - -ignore define CEC_MSG_USER_CONTROL_RELEASED - -ignore define CEC_MSG_GIVE_DEVICE_POWER_STATUS -ignore define CEC_MSG_REPORT_POWER_STATUS - -ignore define CEC_OP_POWER_STATUS_ON -ignore define CEC_OP_POWER_STATUS_STANDBY -ignore define CEC_OP_POWER_STATUS_TO_ON -ignore define CEC_OP_POWER_STATUS_TO_STANDBY - -ignore define CEC_MSG_FEATURE_ABORT - -ignore define CEC_OP_ABORT_UNRECOGNIZED_OP -ignore define CEC_OP_ABORT_INCORRECT_MODE -ignore define CEC_OP_ABORT_NO_SOURCE -ignore define CEC_OP_ABORT_INVALID_OP -ignore define CEC_OP_ABORT_REFUSED -ignore define CEC_OP_ABORT_UNDETERMINED - -ignore define CEC_MSG_ABORT - -ignore define CEC_MSG_GIVE_AUDIO_STATUS -ignore define CEC_MSG_GIVE_SYSTEM_AUDIO_MODE_STATUS -ignore define CEC_MSG_REPORT_AUDIO_STATUS - -ignore define CEC_OP_AUD_MUTE_STATUS_OFF -ignore define CEC_OP_AUD_MUTE_STATUS_ON - -ignore define CEC_MSG_REPORT_SHORT_AUDIO_DESCRIPTOR -ignore define CEC_MSG_REQUEST_SHORT_AUDIO_DESCRIPTOR -ignore define CEC_MSG_SET_SYSTEM_AUDIO_MODE - -ignore define CEC_OP_SYS_AUD_STATUS_OFF -ignore define CEC_OP_SYS_AUD_STATUS_ON - -ignore define CEC_MSG_SYSTEM_AUDIO_MODE_REQUEST -ignore define CEC_MSG_SYSTEM_AUDIO_MODE_STATUS - -ignore define CEC_OP_AUD_FMT_ID_CEA861 -ignore define CEC_OP_AUD_FMT_ID_CEA861_CXT - -ignore define CEC_MSG_SET_AUDIO_RATE - -ignore define CEC_OP_AUD_RATE_OFF -ignore define CEC_OP_AUD_RATE_WIDE_STD -ignore define CEC_OP_AUD_RATE_WIDE_FAST -ignore define CEC_OP_AUD_RATE_WIDE_SLOW -ignore define CEC_OP_AUD_RATE_NARROW_STD -ignore define CEC_OP_AUD_RATE_NARROW_FAST -ignore define CEC_OP_AUD_RATE_NARROW_SLOW - -ignore define CEC_MSG_INITIATE_ARC -ignore define CEC_MSG_REPORT_ARC_INITIATED -ignore define CEC_MSG_REPORT_ARC_TERMINATED -ignore define CEC_MSG_REQUEST_ARC_INITIATION -ignore define CEC_MSG_REQUEST_ARC_TERMINATION -ignore define CEC_MSG_TERMINATE_ARC - -ignore define CEC_MSG_REQUEST_CURRENT_LATENCY -ignore define CEC_MSG_REPORT_CURRENT_LATENCY - -ignore define CEC_OP_LOW_LATENCY_MODE_OFF -ignore define CEC_OP_LOW_LATENCY_MODE_ON - -ignore define CEC_OP_AUD_OUT_COMPENSATED_NA -ignore define CEC_OP_AUD_OUT_COMPENSATED_DELAY -ignore define CEC_OP_AUD_OUT_COMPENSATED_NO_DELAY -ignore define CEC_OP_AUD_OUT_COMPENSATED_PARTIAL_DELAY - -ignore define CEC_MSG_CDC_MESSAGE - -ignore define CEC_MSG_CDC_HEC_INQUIRE_STATE -ignore define CEC_MSG_CDC_HEC_REPORT_STATE - -ignore define CEC_OP_HEC_FUNC_STATE_NOT_SUPPORTED -ignore define CEC_OP_HEC_FUNC_STATE_INACTIVE -ignore define CEC_OP_HEC_FUNC_STATE_ACTIVE -ignore define CEC_OP_HEC_FUNC_STATE_ACTIVATION_FIELD - -ignore define CEC_OP_HOST_FUNC_STATE_NOT_SUPPORTED -ignore define CEC_OP_HOST_FUNC_STATE_INACTIVE -ignore define CEC_OP_HOST_FUNC_STATE_ACTIVE - -ignore define CEC_OP_ENC_FUNC_STATE_EXT_CON_NOT_SUPPORTED -ignore define CEC_OP_ENC_FUNC_STATE_EXT_CON_INACTIVE -ignore define CEC_OP_ENC_FUNC_STATE_EXT_CON_ACTIVE - -ignore define CEC_OP_CDC_ERROR_CODE_NONE -ignore define CEC_OP_CDC_ERROR_CODE_CAP_UNSUPPORTED -ignore define CEC_OP_CDC_ERROR_CODE_WRONG_STATE -ignore define CEC_OP_CDC_ERROR_CODE_OTHER - -ignore define CEC_OP_HEC_SUPPORT_NO -ignore define CEC_OP_HEC_SUPPORT_YES - -ignore define CEC_OP_HEC_ACTIVATION_ON -ignore define CEC_OP_HEC_ACTIVATION_OFF - -ignore define CEC_MSG_CDC_HEC_SET_STATE_ADJACENT -ignore define CEC_MSG_CDC_HEC_SET_STATE - -ignore define CEC_OP_HEC_SET_STATE_DEACTIVATE -ignore define CEC_OP_HEC_SET_STATE_ACTIVATE - -ignore define CEC_MSG_CDC_HEC_REQUEST_DEACTIVATION -ignore define CEC_MSG_CDC_HEC_NOTIFY_ALIVE -ignore define CEC_MSG_CDC_HEC_DISCOVER - -ignore define CEC_MSG_CDC_HPD_SET_STATE - -ignore define CEC_OP_HPD_STATE_CP_EDID_DISABLE -ignore define CEC_OP_HPD_STATE_CP_EDID_ENABLE -ignore define CEC_OP_HPD_STATE_CP_EDID_DISABLE_ENABLE -ignore define CEC_OP_HPD_STATE_EDID_DISABLE -ignore define CEC_OP_HPD_STATE_EDID_ENABLE -ignore define CEC_OP_HPD_STATE_EDID_DISABLE_ENABLE -ignore define CEC_MSG_CDC_HPD_REPORT_STATE - -ignore define CEC_OP_HPD_ERROR_NONE -ignore define CEC_OP_HPD_ERROR_INITIATOR_NOT_CAPABLE -ignore define CEC_OP_HPD_ERROR_INITIATOR_WRONG_STATE -ignore define CEC_OP_HPD_ERROR_OTHER -ignore define CEC_OP_HPD_ERROR_NONE_NO_VIDEO diff --git a/Documentation/media/conf_nitpick.py b/Documentation/media/conf_nitpick.py deleted file mode 100644 index d0c50d75f518..000000000000 --- a/Documentation/media/conf_nitpick.py +++ /dev/null @@ -1,111 +0,0 @@ -# -*- coding: utf-8; mode: python -*- - -# SPDX-License-Identifier: GPL-2.0 - -project = 'Linux Media Subsystem Documentation' - -# It is possible to run Sphinx in nickpick mode with: -nitpicky = True - -# within nit-picking build, do not refer to any intersphinx object -intersphinx_mapping = {} - -# In nickpick mode, it will complain about lots of missing references that -# -# 1) are just typedefs like: bool, __u32, etc; -# 2) It will complain for things like: enum, NULL; -# 3) It will complain for symbols that should be on different -# books (but currently aren't ported to ReST) -# -# The list below has a list of such symbols to be ignored in nitpick mode -# -nitpick_ignore = [ - ("c:func", "clock_gettime"), - ("c:func", "close"), - ("c:func", "container_of"), - ("c:func", "copy_from_user"), - ("c:func", "copy_to_user"), - ("c:func", "determine_valid_ioctls"), - ("c:func", "ERR_PTR"), - ("c:func", "i2c_new_device"), - ("c:func", "ioctl"), - ("c:func", "IS_ERR"), - ("c:func", "KERNEL_VERSION"), - ("c:func", "mmap"), - ("c:func", "open"), - ("c:func", "pci_name"), - ("c:func", "poll"), - ("c:func", "PTR_ERR"), - ("c:func", "read"), - ("c:func", "release"), - ("c:func", "set"), - ("c:func", "struct fd_set"), - ("c:func", "struct pollfd"), - ("c:func", "usb_make_path"), - ("c:func", "wait_finish"), - ("c:func", "wait_prepare"), - ("c:func", "write"), - - ("c:type", "atomic_t"), - ("c:type", "bool"), - ("c:type", "boolean"), - ("c:type", "buf_queue"), - ("c:type", "device"), - ("c:type", "device_driver"), - ("c:type", "device_node"), - ("c:type", "enum"), - ("c:type", "fd"), - ("c:type", "fd_set"), - ("c:type", "file"), - ("c:type", "i2c_adapter"), - ("c:type", "i2c_board_info"), - ("c:type", "i2c_client"), - ("c:type", "int16_t"), - ("c:type", "ktime_t"), - ("c:type", "led_classdev_flash"), - ("c:type", "list_head"), - ("c:type", "lock_class_key"), - ("c:type", "module"), - ("c:type", "mutex"), - ("c:type", "NULL"), - ("c:type", "off_t"), - ("c:type", "pci_dev"), - ("c:type", "pdvbdev"), - ("c:type", "poll_table"), - ("c:type", "platform_device"), - ("c:type", "pollfd"), - ("c:type", "poll_table_struct"), - ("c:type", "s32"), - ("c:type", "s64"), - ("c:type", "sd"), - ("c:type", "size_t"), - ("c:type", "spi_board_info"), - ("c:type", "spi_device"), - ("c:type", "spi_master"), - ("c:type", "ssize_t"), - ("c:type", "fb_fix_screeninfo"), - ("c:type", "pollfd"), - ("c:type", "timeval"), - ("c:type", "video_capability"), - ("c:type", "timeval"), - ("c:type", "__u16"), - ("c:type", "u16"), - ("c:type", "__u32"), - ("c:type", "u32"), - ("c:type", "__u64"), - ("c:type", "u64"), - ("c:type", "u8"), - ("c:type", "uint16_t"), - ("c:type", "uint32_t"), - ("c:type", "union"), - ("c:type", "__user"), - ("c:type", "usb_device"), - ("c:type", "usb_interface"), - ("c:type", "v4l2_std_id"), - ("c:type", "video_system_t"), - ("c:type", "vm_area_struct"), - - # Opaque structures - - ("c:type", "v4l2_m2m_dev"), -] diff --git a/Documentation/media/dmx.h.rst.exceptions b/Documentation/media/dmx.h.rst.exceptions deleted file mode 100644 index afc14d384b83..000000000000 --- a/Documentation/media/dmx.h.rst.exceptions +++ /dev/null @@ -1,66 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 - -# Ignore header name -ignore define _UAPI_DVBDMX_H_ - -# Ignore limit constants -ignore define DMX_FILTER_SIZE - -# dmx_pes_type_t enum symbols -replace enum dmx_ts_pes :c:type:`dmx_pes_type` -replace symbol DMX_PES_AUDIO0 :c:type:`dmx_pes_type` -replace symbol DMX_PES_VIDEO0 :c:type:`dmx_pes_type` -replace symbol DMX_PES_TELETEXT0 :c:type:`dmx_pes_type` -replace symbol DMX_PES_SUBTITLE0 :c:type:`dmx_pes_type` -replace symbol DMX_PES_PCR0 :c:type:`dmx_pes_type` -replace symbol DMX_PES_AUDIO1 :c:type:`dmx_pes_type` -replace symbol DMX_PES_VIDEO1 :c:type:`dmx_pes_type` -replace symbol DMX_PES_TELETEXT1 :c:type:`dmx_pes_type` -replace symbol DMX_PES_SUBTITLE1 :c:type:`dmx_pes_type` -replace symbol DMX_PES_PCR1 :c:type:`dmx_pes_type` -replace symbol DMX_PES_AUDIO2 :c:type:`dmx_pes_type` -replace symbol DMX_PES_VIDEO2 :c:type:`dmx_pes_type` -replace symbol DMX_PES_TELETEXT2 :c:type:`dmx_pes_type` -replace symbol DMX_PES_SUBTITLE2 :c:type:`dmx_pes_type` -replace symbol DMX_PES_PCR2 :c:type:`dmx_pes_type` -replace symbol DMX_PES_AUDIO3 :c:type:`dmx_pes_type` -replace symbol DMX_PES_VIDEO3 :c:type:`dmx_pes_type` -replace symbol DMX_PES_TELETEXT3 :c:type:`dmx_pes_type` -replace symbol DMX_PES_SUBTITLE3 :c:type:`dmx_pes_type` -replace symbol DMX_PES_PCR3 :c:type:`dmx_pes_type` -replace symbol DMX_PES_OTHER :c:type:`dmx_pes_type` - -# Ignore obsolete symbols -ignore define DMX_PES_AUDIO -ignore define DMX_PES_VIDEO -ignore define DMX_PES_TELETEXT -ignore define DMX_PES_SUBTITLE -ignore define DMX_PES_PCR - -# dmx_input_t symbols -replace enum dmx_input :c:type:`dmx_input` -replace symbol DMX_IN_FRONTEND :c:type:`dmx_input` -replace symbol DMX_IN_DVR :c:type:`dmx_input` - -# Flags for struct dmx_sct_filter_params -replace define DMX_CHECK_CRC :c:type:`dmx_sct_filter_params` -replace define DMX_ONESHOT :c:type:`dmx_sct_filter_params` -replace define DMX_IMMEDIATE_START :c:type:`dmx_sct_filter_params` - -# some typedefs should point to struct/enums -replace typedef dmx_filter_t :c:type:`dmx_filter` -replace typedef dmx_pes_type_t :c:type:`dmx_pes_type` -replace typedef dmx_input_t :c:type:`dmx_input` - -replace symbol DMX_BUFFER_FLAG_HAD_CRC32_DISCARD :c:type:`dmx_buffer_flags` -replace symbol DMX_BUFFER_FLAG_TEI :c:type:`dmx_buffer_flags` -replace symbol DMX_BUFFER_PKT_COUNTER_MISMATCH :c:type:`dmx_buffer_flags` -replace symbol DMX_BUFFER_FLAG_DISCONTINUITY_DETECTED :c:type:`dmx_buffer_flags` -replace symbol DMX_BUFFER_FLAG_DISCONTINUITY_INDICATOR :c:type:`dmx_buffer_flags` - -replace symbol DMX_OUT_DECODER :c:type:`dmx_output` -replace symbol DMX_OUT_TAP :c:type:`dmx_output` -replace symbol DMX_OUT_TS_TAP :c:type:`dmx_output` -replace symbol DMX_OUT_TSDEMUX_TAP :c:type:`dmx_output` - -replace ioctl DMX_DQBUF dmx_qbuf diff --git a/Documentation/media/frontend.h.rst.exceptions b/Documentation/media/frontend.h.rst.exceptions deleted file mode 100644 index 6283702c08c8..000000000000 --- a/Documentation/media/frontend.h.rst.exceptions +++ /dev/null @@ -1,214 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 - -# Ignore header name -ignore define _DVBFRONTEND_H_ - -# Group layer A-C symbols together -replace define DTV_ISDBT_LAYERA_FEC dtv-isdbt-layer-fec -replace define DTV_ISDBT_LAYERB_FEC dtv-isdbt-layer-fec -replace define DTV_ISDBT_LAYERC_FEC dtv-isdbt-layer-fec -replace define DTV_ISDBT_LAYERA_MODULATION dtv-isdbt-layer-modulation -replace define DTV_ISDBT_LAYERB_MODULATION dtv-isdbt-layer-modulation -replace define DTV_ISDBT_LAYERC_MODULATION dtv-isdbt-layer-modulation -replace define DTV_ISDBT_LAYERA_SEGMENT_COUNT dtv-isdbt-layer-segment-count -replace define DTV_ISDBT_LAYERB_SEGMENT_COUNT dtv-isdbt-layer-segment-count -replace define DTV_ISDBT_LAYERC_SEGMENT_COUNT dtv-isdbt-layer-segment-count -replace define DTV_ISDBT_LAYERA_TIME_INTERLEAVING dtv-isdbt-layer-time-interleaving -replace define DTV_ISDBT_LAYERB_TIME_INTERLEAVING dtv-isdbt-layer-time-interleaving -replace define DTV_ISDBT_LAYERC_TIME_INTERLEAVING dtv-isdbt-layer-time-interleaving - -# Ignore legacy defines -ignore define DTV_ISDBS_TS_ID_LEGACY -ignore define SYS_DVBC_ANNEX_AC -ignore define SYS_DMBTH - -# Ignore limits -ignore define DTV_MAX_COMMAND -ignore define MAX_DTV_STATS -ignore define DTV_IOCTL_MAX_MSGS - -# the same reference is used for both get and set ioctls -replace ioctl FE_SET_PROPERTY :c:type:`FE_GET_PROPERTY` - -# Typedefs that use the enum reference -replace typedef fe_sec_voltage_t :c:type:`fe_sec_voltage` - -# Replaces for flag constants -replace define FE_TUNE_MODE_ONESHOT :c:func:`FE_SET_FRONTEND_TUNE_MODE` -replace define LNA_AUTO dtv-lna -replace define NO_STREAM_ID_FILTER dtv-stream-id - -# Those enums are defined at the frontend.h header, and not externally - -ignore symbol FE_IS_STUPID -ignore symbol FE_CAN_INVERSION_AUTO -ignore symbol FE_CAN_FEC_1_2 -ignore symbol FE_CAN_FEC_2_3 -ignore symbol FE_CAN_FEC_3_4 -ignore symbol FE_CAN_FEC_4_5 -ignore symbol FE_CAN_FEC_5_6 -ignore symbol FE_CAN_FEC_6_7 -ignore symbol FE_CAN_FEC_7_8 -ignore symbol FE_CAN_FEC_8_9 -ignore symbol FE_CAN_FEC_AUTO -ignore symbol FE_CAN_QPSK -ignore symbol FE_CAN_QAM_16 -ignore symbol FE_CAN_QAM_32 -ignore symbol FE_CAN_QAM_64 -ignore symbol FE_CAN_QAM_128 -ignore symbol FE_CAN_QAM_256 -ignore symbol FE_CAN_QAM_AUTO -ignore symbol FE_CAN_TRANSMISSION_MODE_AUTO -ignore symbol FE_CAN_BANDWIDTH_AUTO -ignore symbol FE_CAN_GUARD_INTERVAL_AUTO -ignore symbol FE_CAN_HIERARCHY_AUTO -ignore symbol FE_CAN_8VSB -ignore symbol FE_CAN_16VSB -ignore symbol FE_HAS_EXTENDED_CAPS -ignore symbol FE_CAN_MULTISTREAM -ignore symbol FE_CAN_TURBO_FEC -ignore symbol FE_CAN_2G_MODULATION -ignore symbol FE_NEEDS_BENDING -ignore symbol FE_CAN_RECOVER -ignore symbol FE_CAN_MUTE_TS - -ignore symbol QPSK -ignore symbol QAM_16 -ignore symbol QAM_32 -ignore symbol QAM_64 -ignore symbol QAM_128 -ignore symbol QAM_256 -ignore symbol QAM_AUTO -ignore symbol VSB_8 -ignore symbol VSB_16 -ignore symbol PSK_8 -ignore symbol APSK_16 -ignore symbol APSK_32 -ignore symbol DQPSK -ignore symbol QAM_4_NR - -ignore symbol SEC_VOLTAGE_13 -ignore symbol SEC_VOLTAGE_18 -ignore symbol SEC_VOLTAGE_OFF - -ignore symbol SEC_TONE_ON -ignore symbol SEC_TONE_OFF - -ignore symbol SEC_MINI_A -ignore symbol SEC_MINI_B - -ignore symbol FE_NONE -ignore symbol FE_HAS_SIGNAL -ignore symbol FE_HAS_CARRIER -ignore symbol FE_HAS_VITERBI -ignore symbol FE_HAS_SYNC -ignore symbol FE_HAS_LOCK -ignore symbol FE_REINIT -ignore symbol FE_TIMEDOUT - -ignore symbol FEC_NONE -ignore symbol FEC_1_2 -ignore symbol FEC_2_3 -ignore symbol FEC_3_4 -ignore symbol FEC_4_5 -ignore symbol FEC_5_6 -ignore symbol FEC_6_7 -ignore symbol FEC_7_8 -ignore symbol FEC_8_9 -ignore symbol FEC_AUTO -ignore symbol FEC_3_5 -ignore symbol FEC_9_10 -ignore symbol FEC_2_5 - -ignore symbol TRANSMISSION_MODE_AUTO -ignore symbol TRANSMISSION_MODE_1K -ignore symbol TRANSMISSION_MODE_2K -ignore symbol TRANSMISSION_MODE_8K -ignore symbol TRANSMISSION_MODE_4K -ignore symbol TRANSMISSION_MODE_16K -ignore symbol TRANSMISSION_MODE_32K -ignore symbol TRANSMISSION_MODE_C1 -ignore symbol TRANSMISSION_MODE_C3780 -ignore symbol TRANSMISSION_MODE_2K -ignore symbol TRANSMISSION_MODE_8K - -ignore symbol GUARD_INTERVAL_AUTO -ignore symbol GUARD_INTERVAL_1_128 -ignore symbol GUARD_INTERVAL_1_32 -ignore symbol GUARD_INTERVAL_1_16 -ignore symbol GUARD_INTERVAL_1_8 -ignore symbol GUARD_INTERVAL_1_4 -ignore symbol GUARD_INTERVAL_19_128 -ignore symbol GUARD_INTERVAL_19_256 -ignore symbol GUARD_INTERVAL_PN420 -ignore symbol GUARD_INTERVAL_PN595 -ignore symbol GUARD_INTERVAL_PN945 - -ignore symbol HIERARCHY_NONE -ignore symbol HIERARCHY_AUTO -ignore symbol HIERARCHY_1 -ignore symbol HIERARCHY_2 -ignore symbol HIERARCHY_4 - -ignore symbol INTERLEAVING_NONE -ignore symbol INTERLEAVING_AUTO -ignore symbol INTERLEAVING_240 -ignore symbol INTERLEAVING_720 - -ignore symbol PILOT_ON -ignore symbol PILOT_OFF -ignore symbol PILOT_AUTO - -ignore symbol ROLLOFF_35 -ignore symbol ROLLOFF_20 -ignore symbol ROLLOFF_25 -ignore symbol ROLLOFF_AUTO - -ignore symbol INVERSION_ON -ignore symbol INVERSION_OFF -ignore symbol INVERSION_AUTO - -ignore symbol SYS_UNDEFINED -ignore symbol SYS_DVBC_ANNEX_A -ignore symbol SYS_DVBC_ANNEX_B -ignore symbol SYS_DVBC_ANNEX_C -ignore symbol SYS_ISDBC -ignore symbol SYS_DVBT -ignore symbol SYS_DVBT2 -ignore symbol SYS_ISDBT -ignore symbol SYS_ATSC -ignore symbol SYS_ATSCMH -ignore symbol SYS_DTMB -ignore symbol SYS_DVBS -ignore symbol SYS_DVBS2 -ignore symbol SYS_TURBO -ignore symbol SYS_ISDBS -ignore symbol SYS_DAB -ignore symbol SYS_DSS -ignore symbol SYS_CMMB -ignore symbol SYS_DVBH - -ignore symbol ATSCMH_SCCC_BLK_SEP -ignore symbol ATSCMH_SCCC_BLK_COMB -ignore symbol ATSCMH_SCCC_BLK_RES - -ignore symbol ATSCMH_SCCC_CODE_HLF -ignore symbol ATSCMH_SCCC_CODE_QTR -ignore symbol ATSCMH_SCCC_CODE_RES - -ignore symbol ATSCMH_RSFRAME_ENS_PRI -ignore symbol ATSCMH_RSFRAME_ENS_SEC - -ignore symbol ATSCMH_RSFRAME_PRI_ONLY -ignore symbol ATSCMH_RSFRAME_PRI_SEC -ignore symbol ATSCMH_RSFRAME_RES - -ignore symbol ATSCMH_RSCODE_211_187 -ignore symbol ATSCMH_RSCODE_223_187 -ignore symbol ATSCMH_RSCODE_235_187 -ignore symbol ATSCMH_RSCODE_RES - -ignore symbol FE_SCALE_NOT_AVAILABLE -ignore symbol FE_SCALE_DECIBEL -ignore symbol FE_SCALE_RELATIVE -ignore symbol FE_SCALE_COUNTER diff --git a/Documentation/media/index.rst b/Documentation/media/index.rst index 0301c25ff887..8118c2d001ff 100644 --- a/Documentation/media/index.rst +++ b/Documentation/media/index.rst @@ -12,7 +12,7 @@ Linux Media Subsystem Documentation .. toctree:: :maxdepth: 2 - media_uapi + ../userspace-api/media/index media_kapi dvb-drivers/index v4l-drivers/index diff --git a/Documentation/media/intro.rst b/Documentation/media/intro.rst deleted file mode 100644 index 4a6bd665b884..000000000000 --- a/Documentation/media/intro.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -============ -Introduction -============ - -This document covers the Linux Kernel to Userspace API's used by video -and radio streaming devices, including video cameras, analog and digital -TV receiver cards, AM/FM receiver cards, Software Defined Radio (SDR), -streaming capture and output devices, codec devices and remote controllers. - -A typical media device hardware is shown at :ref:`typical_media_device`. - -.. _typical_media_device: - -.. kernel-figure:: typical_media_device.svg - :alt: typical_media_device.svg - :align: center - - Typical Media Device - -The media infrastructure API was designed to control such devices. It is -divided into five parts. - -1. The :ref:`first part ` covers radio, video capture and output, - cameras, analog TV devices and codecs. - -2. The :ref:`second part ` covers the API used for digital TV and - Internet reception via one of the several digital tv standards. While it is - called as DVB API, in fact it covers several different video standards - including DVB-T/T2, DVB-S/S2, DVB-C, ATSC, ISDB-T, ISDB-S, DTMB, etc. The - complete list of supported standards can be found at - :c:type:`fe_delivery_system`. - -3. The :ref:`third part ` covers the Remote Controller API. - -4. The :ref:`fourth part ` covers the Media Controller API. - -5. The :ref:`fifth part ` covers the CEC (Consumer Electronics Control) API. - -It should also be noted that a media device may also have audio components, like -mixers, PCM capture, PCM playback, etc, which are controlled via ALSA API. For -additional information and for the latest development code, see: -`https://linuxtv.org `__. For discussing improvements, -reporting troubles, sending new drivers, etc, please mail to: `Linux Media -Mailing List (LMML) `__. diff --git a/Documentation/media/lirc.h.rst.exceptions b/Documentation/media/lirc.h.rst.exceptions deleted file mode 100644 index ac768d769113..000000000000 --- a/Documentation/media/lirc.h.rst.exceptions +++ /dev/null @@ -1,80 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 - -# Ignore header name -ignore define _LINUX_LIRC_H - -# Ignore helper macros - -ignore define lirc_t - -ignore define LIRC_SPACE -ignore define LIRC_PULSE -ignore define LIRC_FREQUENCY -ignore define LIRC_TIMEOUT -ignore define LIRC_VALUE -ignore define LIRC_MODE2 -ignore define LIRC_IS_SPACE -ignore define LIRC_IS_PULSE -ignore define LIRC_IS_FREQUENCY -ignore define LIRC_IS_TIMEOUT - -ignore define LIRC_MODE2SEND -ignore define LIRC_SEND2MODE -ignore define LIRC_MODE2REC -ignore define LIRC_REC2MODE - -ignore define LIRC_CAN_SEND -ignore define LIRC_CAN_REC - -ignore define LIRC_CAN_SEND_MASK -ignore define LIRC_CAN_REC_MASK -ignore define LIRC_CAN_SET_REC_DUTY_CYCLE - -# Obsolete ioctls - -ignore ioctl LIRC_GET_LENGTH - -# rc protocols - -ignore symbol RC_PROTO_UNKNOWN -ignore symbol RC_PROTO_OTHER -ignore symbol RC_PROTO_RC5 -ignore symbol RC_PROTO_RC5X_20 -ignore symbol RC_PROTO_RC5_SZ -ignore symbol RC_PROTO_JVC -ignore symbol RC_PROTO_SONY12 -ignore symbol RC_PROTO_SONY15 -ignore symbol RC_PROTO_SONY20 -ignore symbol RC_PROTO_NEC -ignore symbol RC_PROTO_NECX -ignore symbol RC_PROTO_NEC32 -ignore symbol RC_PROTO_SANYO -ignore symbol RC_PROTO_MCIR2_KBD -ignore symbol RC_PROTO_MCIR2_MSE -ignore symbol RC_PROTO_RC6_0 -ignore symbol RC_PROTO_RC6_6A_20 -ignore symbol RC_PROTO_RC6_6A_24 -ignore symbol RC_PROTO_RC6_6A_32 -ignore symbol RC_PROTO_RC6_MCE -ignore symbol RC_PROTO_SHARP -ignore symbol RC_PROTO_XMP -ignore symbol RC_PROTO_CEC -ignore symbol RC_PROTO_IMON -ignore symbol RC_PROTO_RCMM12 -ignore symbol RC_PROTO_RCMM24 -ignore symbol RC_PROTO_RCMM32 -ignore symbol RC_PROTO_XBOX_DVD - -# Undocumented macros - -ignore define PULSE_BIT -ignore define PULSE_MASK - -ignore define LIRC_MODE2_SPACE -ignore define LIRC_MODE2_PULSE - -ignore define LIRC_VALUE_MASK -ignore define LIRC_MODE2_MASK - -ignore define LIRC_MODE_RAW -ignore define LIRC_MODE_LIRCCODE diff --git a/Documentation/media/media.h.rst.exceptions b/Documentation/media/media.h.rst.exceptions deleted file mode 100644 index 9b4c26502d95..000000000000 --- a/Documentation/media/media.h.rst.exceptions +++ /dev/null @@ -1,32 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 - -# Ignore header name -ignore define __LINUX_MEDIA_H - -# Ignore macros -ignore define MEDIA_API_VERSION -ignore define MEDIA_ENT_F_BASE -ignore define MEDIA_ENT_F_OLD_BASE -ignore define MEDIA_ENT_F_OLD_SUBDEV_BASE -ignore define MEDIA_ENT_F_DTV_DECODER -ignore define MEDIA_INTF_T_DVB_BASE -ignore define MEDIA_INTF_T_V4L_BASE -ignore define MEDIA_INTF_T_ALSA_BASE -#ignore legacy entity type macros -ignore define MEDIA_ENT_TYPE_SHIFT -ignore define MEDIA_ENT_TYPE_MASK -ignore define MEDIA_ENT_SUBTYPE_MASK -ignore define MEDIA_ENT_T_DEVNODE_UNKNOWN -ignore define MEDIA_ENT_T_DEVNODE -ignore define MEDIA_ENT_T_DEVNODE_V4L -ignore define MEDIA_ENT_T_DEVNODE_FB -ignore define MEDIA_ENT_T_DEVNODE_ALSA -ignore define MEDIA_ENT_T_DEVNODE_DVB -ignore define MEDIA_ENT_T_UNKNOWN -ignore define MEDIA_ENT_T_V4L2_VIDEO -ignore define MEDIA_ENT_T_V4L2_SUBDEV -ignore define MEDIA_ENT_T_V4L2_SUBDEV_SENSOR -ignore define MEDIA_ENT_T_V4L2_SUBDEV_FLASH -ignore define MEDIA_ENT_T_V4L2_SUBDEV_LENS -ignore define MEDIA_ENT_T_V4L2_SUBDEV_DECODER -ignore define MEDIA_ENT_T_V4L2_SUBDEV_TUNER diff --git a/Documentation/media/media_uapi.rst b/Documentation/media/media_uapi.rst deleted file mode 100644 index 0753005c7bb4..000000000000 --- a/Documentation/media/media_uapi.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -.. include:: - -######################################## -Linux Media Infrastructure userspace API -######################################## - -**Copyright** |copy| 2009-2016 : LinuxTV Developers - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation, with no -Invariant Sections. A copy of the license is included in the chapter -entitled "GNU Free Documentation License". - -.. only:: html - - .. class:: toc-title - - Table of Contents - -.. toctree:: - :maxdepth: 1 - - intro - uapi/v4l/v4l2 - uapi/dvb/dvbapi - uapi/rc/remote_controllers - uapi/mediactl/media-controller - uapi/cec/cec-api - uapi/gen-errors - uapi/fdl-appendix diff --git a/Documentation/media/net.h.rst.exceptions b/Documentation/media/net.h.rst.exceptions deleted file mode 100644 index 5159aa4bbbb9..000000000000 --- a/Documentation/media/net.h.rst.exceptions +++ /dev/null @@ -1,13 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 - -# Ignore header name -ignore define _DVBNET_H_ - -# Ignore old ioctls/structs -ignore ioctl __NET_ADD_IF_OLD -ignore ioctl __NET_GET_IF_OLD -ignore struct __dvb_net_if_old - -# Macros used at struct dvb_net_if -replace define DVB_NET_FEEDTYPE_MPE :c:type:`dvb_net_if` -replace define DVB_NET_FEEDTYPE_ULE :c:type:`dvb_net_if` diff --git a/Documentation/media/typical_media_device.svg b/Documentation/media/typical_media_device.svg deleted file mode 100644 index bfd5c7db3b00..000000000000 --- a/Documentation/media/typical_media_device.svg +++ /dev/null @@ -1,116 +0,0 @@ - - -image/svg+xmlAudio decoder -Video decoder -Audio encoder -Button Key/IR input logic -EEPROM -Sensor -System Bus -Demux -Conditional Access Module -Video encoder -Radio / Analog TV -Digital TV -PS.: picture is not complete: other blocks may be present -Webcam -Processing blocks -Smartcard -TunerFM/TV -Satellite Equipment Control (SEC) -Demod -I2C Bus (control bus) -Digital TV Frontend - -CPU -PCI, USB, SPI, I2C, ... -Bridge - DMA - diff --git a/Documentation/media/uapi/cec/cec-api.rst b/Documentation/media/uapi/cec/cec-api.rst deleted file mode 100644 index 0780ba07995a..000000000000 --- a/Documentation/media/uapi/cec/cec-api.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. include:: - -.. _cec: - -######################################### -Part V - Consumer Electronics Control API -######################################### - -This part describes the CEC: Consumer Electronics Control - - -.. only:: html - - .. class:: toc-title - - Table of Contents - -.. toctree:: - :maxdepth: 5 - :numbered: - - cec-intro - cec-funcs - cec-pin-error-inj - cec-header - - -********************** -Revision and Copyright -********************** -Authors: - -- Verkuil, Hans - - - Initial version. - -**Copyright** |copy| 2016 : Hans Verkuil - -**************** -Revision History -**************** - -:revision: 1.0.0 / 2016-03-17 (*hv*) - -Initial revision diff --git a/Documentation/media/uapi/cec/cec-func-close.rst b/Documentation/media/uapi/cec/cec-func-close.rst deleted file mode 100644 index e10d675546f8..000000000000 --- a/Documentation/media/uapi/cec/cec-func-close.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _cec-func-close: - -*********** -cec close() -*********** - -Name -==== - -cec-close - Close a cec device - - -Synopsis -======== - -.. code-block:: c - - #include - - -.. c:function:: int close( int fd ) - :name: cec-close - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - - -Description -=========== - -Closes the cec device. Resources associated with the file descriptor are -freed. The device configuration remain unchanged. - - -Return Value -============ - -:c:func:`close() ` returns 0 on success. On error, -1 is returned, and -``errno`` is set appropriately. Possible error codes are: - -``EBADF`` - ``fd`` is not a valid open file descriptor. diff --git a/Documentation/media/uapi/cec/cec-func-ioctl.rst b/Documentation/media/uapi/cec/cec-func-ioctl.rst deleted file mode 100644 index c18d4ba5eb37..000000000000 --- a/Documentation/media/uapi/cec/cec-func-ioctl.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _cec-func-ioctl: - -*********** -cec ioctl() -*********** - -Name -==== - -cec-ioctl - Control a cec device - -Synopsis -======== - -.. code-block:: c - - #include - - -.. c:function:: int ioctl( int fd, int request, void *argp ) - :name: cec-ioctl - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - -``request`` - CEC ioctl request code as defined in the cec.h header file, for - example :ref:`CEC_ADAP_G_CAPS `. - -``argp`` - Pointer to a request-specific structure. - - -Description -=========== - -The :c:func:`ioctl() ` function manipulates cec device parameters. The -argument ``fd`` must be an open file descriptor. - -The ioctl ``request`` code specifies the cec function to be called. It -has encoded in it whether the argument is an input, output or read/write -parameter, and the size of the argument ``argp`` in bytes. - -Macros and structures definitions specifying cec ioctl requests and -their parameters are located in the cec.h header file. All cec ioctl -requests, their respective function and parameters are specified in -:ref:`cec-user-func`. - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. - -Request-specific error codes are listed in the individual requests -descriptions. - -When an ioctl that takes an output or read/write parameter fails, the -parameter remains unmodified. diff --git a/Documentation/media/uapi/cec/cec-func-open.rst b/Documentation/media/uapi/cec/cec-func-open.rst deleted file mode 100644 index f235aa80155c..000000000000 --- a/Documentation/media/uapi/cec/cec-func-open.rst +++ /dev/null @@ -1,85 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _cec-func-open: - -********** -cec open() -********** - -Name -==== - -cec-open - Open a cec device - -Synopsis -======== - -.. code-block:: c - - #include - - -.. c:function:: int open( const char *device_name, int flags ) - :name: cec-open - - -Arguments -========= - -``device_name`` - Device to be opened. - -``flags`` - Open flags. Access mode must be ``O_RDWR``. - - When the ``O_NONBLOCK`` flag is given, the - :ref:`CEC_RECEIVE ` and :ref:`CEC_DQEVENT ` ioctls - will return the ``EAGAIN`` error code when no message or event is available, and - ioctls :ref:`CEC_TRANSMIT `, - :ref:`CEC_ADAP_S_PHYS_ADDR ` and - :ref:`CEC_ADAP_S_LOG_ADDRS ` - all return 0. - - Other flags have no effect. - - -Description -=========== - -To open a cec device applications call :c:func:`open() ` with the -desired device name. The function has no side effects; the device -configuration remain unchanged. - -When the device is opened in read-only mode, attempts to modify its -configuration will result in an error, and ``errno`` will be set to -EBADF. - - -Return Value -============ - -:c:func:`open() ` returns the new file descriptor on success. On error, --1 is returned, and ``errno`` is set appropriately. Possible error codes -include: - -``EACCES`` - The requested access to the file is not allowed. - -``EMFILE`` - The process already has the maximum number of files open. - -``ENFILE`` - The system limit on the total number of open files has been reached. - -``ENOMEM`` - Insufficient kernel memory was available. - -``ENXIO`` - No device corresponding to this device special file exists. diff --git a/Documentation/media/uapi/cec/cec-func-poll.rst b/Documentation/media/uapi/cec/cec-func-poll.rst deleted file mode 100644 index 3f6c5b0effa3..000000000000 --- a/Documentation/media/uapi/cec/cec-func-poll.rst +++ /dev/null @@ -1,85 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _cec-func-poll: - -********** -cec poll() -********** - -Name -==== - -cec-poll - Wait for some event on a file descriptor - - -Synopsis -======== - -.. code-block:: c - - #include - - -.. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout ) - :name: cec-poll - -Arguments -========= - -``ufds`` - List of FD events to be watched - -``nfds`` - Number of FD events at the \*ufds array - -``timeout`` - Timeout to wait for events - - -Description -=========== - -With the :c:func:`poll() ` function applications can wait for CEC -events. - -On success :c:func:`poll() ` returns the number of file descriptors -that have been selected (that is, file descriptors for which the -``revents`` field of the respective struct :c:type:`pollfd` -is non-zero). CEC devices set the ``POLLIN`` and ``POLLRDNORM`` flags in -the ``revents`` field if there are messages in the receive queue. If the -transmit queue has room for new messages, the ``POLLOUT`` and -``POLLWRNORM`` flags are set. If there are events in the event queue, -then the ``POLLPRI`` flag is set. When the function times out it returns -a value of zero, on failure it returns -1 and the ``errno`` variable is -set appropriately. - -For more details see the :c:func:`poll() ` manual page. - - -Return Value -============ - -On success, :c:func:`poll() ` returns the number structures which have -non-zero ``revents`` fields, or zero if the call timed out. On error -1 -is returned, and the ``errno`` variable is set appropriately: - -``EBADF`` - One or more of the ``ufds`` members specify an invalid file - descriptor. - -``EFAULT`` - ``ufds`` references an inaccessible memory area. - -``EINTR`` - The call was interrupted by a signal. - -``EINVAL`` - The ``nfds`` value exceeds the ``RLIMIT_NOFILE`` value. Use - ``getrlimit()`` to obtain this value. diff --git a/Documentation/media/uapi/cec/cec-funcs.rst b/Documentation/media/uapi/cec/cec-funcs.rst deleted file mode 100644 index dc6da9c639a8..000000000000 --- a/Documentation/media/uapi/cec/cec-funcs.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _cec-user-func: - -****************** -Function Reference -****************** - - -.. toctree:: - :maxdepth: 1 - - cec-func-open - cec-func-close - cec-func-ioctl - cec-func-poll - cec-ioc-adap-g-caps - cec-ioc-adap-g-log-addrs - cec-ioc-adap-g-phys-addr - cec-ioc-adap-g-conn-info - cec-ioc-dqevent - cec-ioc-g-mode - cec-ioc-receive diff --git a/Documentation/media/uapi/cec/cec-header.rst b/Documentation/media/uapi/cec/cec-header.rst deleted file mode 100644 index 726f9766a130..000000000000 --- a/Documentation/media/uapi/cec/cec-header.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _cec_header: - -*************** -CEC Header File -*************** - -.. kernel-include:: $BUILDDIR/cec.h.rst - diff --git a/Documentation/media/uapi/cec/cec-intro.rst b/Documentation/media/uapi/cec/cec-intro.rst deleted file mode 100644 index 05088fcefe81..000000000000 --- a/Documentation/media/uapi/cec/cec-intro.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _cec-intro: - -Introduction -============ - -HDMI connectors provide a single pin for use by the Consumer Electronics -Control protocol. This protocol allows different devices connected by an -HDMI cable to communicate. The protocol for CEC version 1.4 is defined -in supplements 1 (CEC) and 2 (HEAC or HDMI Ethernet and Audio Return -Channel) of the HDMI 1.4a (:ref:`hdmi`) specification and the -extensions added to CEC version 2.0 are defined in chapter 11 of the -HDMI 2.0 (:ref:`hdmi2`) specification. - -The bitrate is very slow (effectively no more than 36 bytes per second) -and is based on the ancient AV.link protocol used in old SCART -connectors. The protocol closely resembles a crazy Rube Goldberg -contraption and is an unholy mix of low and high level messages. Some -messages, especially those part of the HEAC protocol layered on top of -CEC, need to be handled by the kernel, others can be handled either by -the kernel or by userspace. - -In addition, CEC can be implemented in HDMI receivers, transmitters and -in USB devices that have an HDMI input and an HDMI output and that -control just the CEC pin. - -Drivers that support CEC will create a CEC device node (/dev/cecX) to -give userspace access to the CEC adapter. The -:ref:`CEC_ADAP_G_CAPS` ioctl will tell userspace what it is allowed to do. - -In order to check the support and test it, it is suggested to download -the `v4l-utils `_ package. It -provides three tools to handle CEC: - -- cec-ctl: the Swiss army knife of CEC. Allows you to configure, transmit - and monitor CEC messages. - -- cec-compliance: does a CEC compliance test of a remote CEC device to - determine how compliant the CEC implementation is. - -- cec-follower: emulates a CEC follower. diff --git a/Documentation/media/uapi/cec/cec-ioc-adap-g-caps.rst b/Documentation/media/uapi/cec/cec-ioc-adap-g-caps.rst deleted file mode 100644 index 76761a98c312..000000000000 --- a/Documentation/media/uapi/cec/cec-ioc-adap-g-caps.rst +++ /dev/null @@ -1,150 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _CEC_ADAP_G_CAPS: - -********************* -ioctl CEC_ADAP_G_CAPS -********************* - -Name -==== - -CEC_ADAP_G_CAPS - Query device capabilities - -Synopsis -======== - -.. c:function:: int ioctl( int fd, CEC_ADAP_G_CAPS, struct cec_caps *argp ) - :name: CEC_ADAP_G_CAPS - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - -``argp`` - - -Description -=========== - -All cec devices must support :ref:`ioctl CEC_ADAP_G_CAPS `. To query -device information, applications call the ioctl with a pointer to a -struct :c:type:`cec_caps`. The driver fills the structure and -returns the information to the application. The ioctl never fails. - -.. tabularcolumns:: |p{1.2cm}|p{2.5cm}|p{13.8cm}| - -.. c:type:: cec_caps - -.. flat-table:: struct cec_caps - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 16 - - * - char - - ``driver[32]`` - - The name of the cec adapter driver. - * - char - - ``name[32]`` - - The name of this CEC adapter. The combination ``driver`` and - ``name`` must be unique. - * - __u32 - - ``capabilities`` - - The capabilities of the CEC adapter, see - :ref:`cec-capabilities`. - * - __u32 - - ``version`` - - CEC Framework API version, formatted with the ``KERNEL_VERSION()`` - macro. - - -.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.6cm}| - -.. _cec-capabilities: - -.. flat-table:: CEC Capabilities Flags - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 8 - - * .. _`CEC-CAP-PHYS-ADDR`: - - - ``CEC_CAP_PHYS_ADDR`` - - 0x00000001 - - Userspace has to configure the physical address by calling - :ref:`ioctl CEC_ADAP_S_PHYS_ADDR `. If - this capability isn't set, then setting the physical address is - handled by the kernel whenever the EDID is set (for an HDMI - receiver) or read (for an HDMI transmitter). - * .. _`CEC-CAP-LOG-ADDRS`: - - - ``CEC_CAP_LOG_ADDRS`` - - 0x00000002 - - Userspace has to configure the logical addresses by calling - :ref:`ioctl CEC_ADAP_S_LOG_ADDRS `. If - this capability isn't set, then the kernel will have configured - this. - * .. _`CEC-CAP-TRANSMIT`: - - - ``CEC_CAP_TRANSMIT`` - - 0x00000004 - - Userspace can transmit CEC messages by calling - :ref:`ioctl CEC_TRANSMIT `. This implies that - userspace can be a follower as well, since being able to transmit - messages is a prerequisite of becoming a follower. If this - capability isn't set, then the kernel will handle all CEC - transmits and process all CEC messages it receives. - * .. _`CEC-CAP-PASSTHROUGH`: - - - ``CEC_CAP_PASSTHROUGH`` - - 0x00000008 - - Userspace can use the passthrough mode by calling - :ref:`ioctl CEC_S_MODE `. - * .. _`CEC-CAP-RC`: - - - ``CEC_CAP_RC`` - - 0x00000010 - - This adapter supports the remote control protocol. - * .. _`CEC-CAP-MONITOR-ALL`: - - - ``CEC_CAP_MONITOR_ALL`` - - 0x00000020 - - The CEC hardware can monitor all messages, not just directed and - broadcast messages. - * .. _`CEC-CAP-NEEDS-HPD`: - - - ``CEC_CAP_NEEDS_HPD`` - - 0x00000040 - - The CEC hardware is only active if the HDMI Hotplug Detect pin is - high. This makes it impossible to use CEC to wake up displays that - set the HPD pin low when in standby mode, but keep the CEC bus - alive. - * .. _`CEC-CAP-MONITOR-PIN`: - - - ``CEC_CAP_MONITOR_PIN`` - - 0x00000080 - - The CEC hardware can monitor CEC pin changes from low to high voltage - and vice versa. When in pin monitoring mode the application will - receive ``CEC_EVENT_PIN_CEC_LOW`` and ``CEC_EVENT_PIN_CEC_HIGH`` events. - * .. _`CEC-CAP-CONNECTOR-INFO`: - - - ``CEC_CAP_CONNECTOR_INFO`` - - 0x00000100 - - If this capability is set, then :ref:`CEC_ADAP_G_CONNECTOR_INFO` can - be used. - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/cec/cec-ioc-adap-g-conn-info.rst b/Documentation/media/uapi/cec/cec-ioc-adap-g-conn-info.rst deleted file mode 100644 index 6818ddf1495c..000000000000 --- a/Documentation/media/uapi/cec/cec-ioc-adap-g-conn-info.rst +++ /dev/null @@ -1,105 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 -.. -.. Copyright 2019 Google LLC -.. -.. _CEC_ADAP_G_CONNECTOR_INFO: - -******************************* -ioctl CEC_ADAP_G_CONNECTOR_INFO -******************************* - -Name -==== - -CEC_ADAP_G_CONNECTOR_INFO - Query HDMI connector information - -Synopsis -======== - -.. c:function:: int ioctl( int fd, CEC_ADAP_G_CONNECTOR_INFO, struct cec_connector_info *argp ) - :name: CEC_ADAP_G_CONNECTOR_INFO - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - -``argp`` - - -Description -=========== - -Using this ioctl an application can learn which HDMI connector this CEC -device corresponds to. While calling this ioctl the application should -provide a pointer to a cec_connector_info struct which will be populated -by the kernel with the info provided by the adapter's driver. This ioctl -is only available if the ``CEC_CAP_CONNECTOR_INFO`` capability is set. - -.. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.6cm}| - -.. c:type:: cec_connector_info - -.. flat-table:: struct cec_connector_info - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 8 - - * - __u32 - - ``type`` - - The type of connector this adapter is associated with. - * - union { - - ``(anonymous)`` - * - ``struct cec_drm_connector_info`` - - drm - - :ref:`cec-drm-connector-info` - * - } - - - - -.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.6cm}| - -.. _connector-type: - -.. flat-table:: Connector types - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 8 - - * .. _`CEC-CONNECTOR-TYPE-NO-CONNECTOR`: - - - ``CEC_CONNECTOR_TYPE_NO_CONNECTOR`` - - 0 - - No connector is associated with the adapter/the information is not - provided by the driver. - * .. _`CEC-CONNECTOR-TYPE-DRM`: - - - ``CEC_CONNECTOR_TYPE_DRM`` - - 1 - - Indicates that a DRM connector is associated with this adapter. - Information about the connector can be found in - :ref:`cec-drm-connector-info`. - -.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.6cm}| - -.. c:type:: cec_drm_connector_info - -.. _cec-drm-connector-info: - -.. flat-table:: struct cec_drm_connector_info - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 8 - - * .. _`CEC-DRM-CONNECTOR-TYPE-CARD-NO`: - - - __u32 - - ``card_no`` - - DRM card number: the number from a card's path, e.g. 0 in case of - /dev/card0. - * .. _`CEC-DRM-CONNECTOR-TYPE-CONNECTOR_ID`: - - - __u32 - - ``connector_id`` - - DRM connector ID. diff --git a/Documentation/media/uapi/cec/cec-ioc-adap-g-log-addrs.rst b/Documentation/media/uapi/cec/cec-ioc-adap-g-log-addrs.rst deleted file mode 100644 index 26465094e3f1..000000000000 --- a/Documentation/media/uapi/cec/cec-ioc-adap-g-log-addrs.rst +++ /dev/null @@ -1,378 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _CEC_ADAP_LOG_ADDRS: -.. _CEC_ADAP_G_LOG_ADDRS: -.. _CEC_ADAP_S_LOG_ADDRS: - -**************************************************** -ioctls CEC_ADAP_G_LOG_ADDRS and CEC_ADAP_S_LOG_ADDRS -**************************************************** - -Name -==== - -CEC_ADAP_G_LOG_ADDRS, CEC_ADAP_S_LOG_ADDRS - Get or set the logical addresses - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, CEC_ADAP_G_LOG_ADDRS, struct cec_log_addrs *argp ) - :name: CEC_ADAP_G_LOG_ADDRS - -.. c:function:: int ioctl( int fd, CEC_ADAP_S_LOG_ADDRS, struct cec_log_addrs *argp ) - :name: CEC_ADAP_S_LOG_ADDRS - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - -``argp`` - Pointer to struct :c:type:`cec_log_addrs`. - -Description -=========== - -To query the current CEC logical addresses, applications call -:ref:`ioctl CEC_ADAP_G_LOG_ADDRS ` with a pointer to a -struct :c:type:`cec_log_addrs` where the driver stores the logical addresses. - -To set new logical addresses, applications fill in -struct :c:type:`cec_log_addrs` and call :ref:`ioctl CEC_ADAP_S_LOG_ADDRS ` -with a pointer to this struct. The :ref:`ioctl CEC_ADAP_S_LOG_ADDRS ` -is only available if ``CEC_CAP_LOG_ADDRS`` is set (the ``ENOTTY`` error code is -returned otherwise). The :ref:`ioctl CEC_ADAP_S_LOG_ADDRS ` -can only be called by a file descriptor in initiator mode (see :ref:`CEC_S_MODE`), if not -the ``EBUSY`` error code will be returned. - -To clear existing logical addresses set ``num_log_addrs`` to 0. All other fields -will be ignored in that case. The adapter will go to the unconfigured state and the -``cec_version``, ``vendor_id`` and ``osd_name`` fields are all reset to their default -values (CEC version 2.0, no vendor ID and an empty OSD name). - -If the physical address is valid (see :ref:`ioctl CEC_ADAP_S_PHYS_ADDR `), -then this ioctl will block until all requested logical -addresses have been claimed. If the file descriptor is in non-blocking mode then it will -not wait for the logical addresses to be claimed, instead it just returns 0. - -A :ref:`CEC_EVENT_STATE_CHANGE ` event is sent when the -logical addresses are claimed or cleared. - -Attempting to call :ref:`ioctl CEC_ADAP_S_LOG_ADDRS ` when -logical address types are already defined will return with error ``EBUSY``. - -.. c:type:: cec_log_addrs - -.. tabularcolumns:: |p{1.0cm}|p{8.0cm}|p{7.5cm}| - -.. cssclass:: longtable - -.. flat-table:: struct cec_log_addrs - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 16 - - * - __u8 - - ``log_addr[CEC_MAX_LOG_ADDRS]`` - - The actual logical addresses that were claimed. This is set by the - driver. If no logical address could be claimed, then it is set to - ``CEC_LOG_ADDR_INVALID``. If this adapter is Unregistered, then - ``log_addr[0]`` is set to 0xf and all others to - ``CEC_LOG_ADDR_INVALID``. - * - __u16 - - ``log_addr_mask`` - - The bitmask of all logical addresses this adapter has claimed. If - this adapter is Unregistered then ``log_addr_mask`` sets bit 15 - and clears all other bits. If this adapter is not configured at - all, then ``log_addr_mask`` is set to 0. Set by the driver. - * - __u8 - - ``cec_version`` - - The CEC version that this adapter shall use. See - :ref:`cec-versions`. Used to implement the - ``CEC_MSG_CEC_VERSION`` and ``CEC_MSG_REPORT_FEATURES`` messages. - Note that :ref:`CEC_OP_CEC_VERSION_1_3A ` is not allowed by the CEC - framework. - * - __u8 - - ``num_log_addrs`` - - Number of logical addresses to set up. Must be ≤ - ``available_log_addrs`` as returned by - :ref:`CEC_ADAP_G_CAPS`. All arrays in - this structure are only filled up to index - ``available_log_addrs``-1. The remaining array elements will be - ignored. Note that the CEC 2.0 standard allows for a maximum of 2 - logical addresses, although some hardware has support for more. - ``CEC_MAX_LOG_ADDRS`` is 4. The driver will return the actual - number of logical addresses it could claim, which may be less than - what was requested. If this field is set to 0, then the CEC - adapter shall clear all claimed logical addresses and all other - fields will be ignored. - * - __u32 - - ``vendor_id`` - - The vendor ID is a 24-bit number that identifies the specific - vendor or entity. Based on this ID vendor specific commands may be - defined. If you do not want a vendor ID then set it to - ``CEC_VENDOR_ID_NONE``. - * - __u32 - - ``flags`` - - Flags. See :ref:`cec-log-addrs-flags` for a list of available flags. - * - char - - ``osd_name[15]`` - - The On-Screen Display name as is returned by the - ``CEC_MSG_SET_OSD_NAME`` message. - * - __u8 - - ``primary_device_type[CEC_MAX_LOG_ADDRS]`` - - Primary device type for each logical address. See - :ref:`cec-prim-dev-types` for possible types. - * - __u8 - - ``log_addr_type[CEC_MAX_LOG_ADDRS]`` - - Logical address types. See :ref:`cec-log-addr-types` for - possible types. The driver will update this with the actual - logical address type that it claimed (e.g. it may have to fallback - to :ref:`CEC_LOG_ADDR_TYPE_UNREGISTERED `). - * - __u8 - - ``all_device_types[CEC_MAX_LOG_ADDRS]`` - - CEC 2.0 specific: the bit mask of all device types. See - :ref:`cec-all-dev-types-flags`. It is used in the CEC 2.0 - ``CEC_MSG_REPORT_FEATURES`` message. For CEC 1.4 you can either leave - this field to 0, or fill it in according to the CEC 2.0 guidelines to - give the CEC framework more information about the device type, even - though the framework won't use it directly in the CEC message. - * - __u8 - - ``features[CEC_MAX_LOG_ADDRS][12]`` - - Features for each logical address. It is used in the CEC 2.0 - ``CEC_MSG_REPORT_FEATURES`` message. The 12 bytes include both the - RC Profile and the Device Features. For CEC 1.4 you can either leave - this field to all 0, or fill it in according to the CEC 2.0 guidelines to - give the CEC framework more information about the device type, even - though the framework won't use it directly in the CEC message. - - -.. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.7cm}| - -.. _cec-log-addrs-flags: - -.. flat-table:: Flags for struct cec_log_addrs - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 4 - - * .. _`CEC-LOG-ADDRS-FL-ALLOW-UNREG-FALLBACK`: - - - ``CEC_LOG_ADDRS_FL_ALLOW_UNREG_FALLBACK`` - - 1 - - By default if no logical address of the requested type can be claimed, then - it will go back to the unconfigured state. If this flag is set, then it will - fallback to the Unregistered logical address. Note that if the Unregistered - logical address was explicitly requested, then this flag has no effect. - * .. _`CEC-LOG-ADDRS-FL-ALLOW-RC-PASSTHRU`: - - - ``CEC_LOG_ADDRS_FL_ALLOW_RC_PASSTHRU`` - - 2 - - By default the ``CEC_MSG_USER_CONTROL_PRESSED`` and ``CEC_MSG_USER_CONTROL_RELEASED`` - messages are only passed on to the follower(s), if any. If this flag is set, - then these messages are also passed on to the remote control input subsystem - and will appear as keystrokes. This features needs to be enabled explicitly. - If CEC is used to enter e.g. passwords, then you may not want to enable this - to avoid trivial snooping of the keystrokes. - * .. _`CEC-LOG-ADDRS-FL-CDC-ONLY`: - - - ``CEC_LOG_ADDRS_FL_CDC_ONLY`` - - 4 - - If this flag is set, then the device is CDC-Only. CDC-Only CEC devices - are CEC devices that can only handle CDC messages. - - All other messages are ignored. - - -.. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.7cm}| - -.. _cec-versions: - -.. flat-table:: CEC Versions - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 4 - - * .. _`CEC-OP-CEC-VERSION-1-3A`: - - - ``CEC_OP_CEC_VERSION_1_3A`` - - 4 - - CEC version according to the HDMI 1.3a standard. - * .. _`CEC-OP-CEC-VERSION-1-4B`: - - - ``CEC_OP_CEC_VERSION_1_4B`` - - 5 - - CEC version according to the HDMI 1.4b standard. - * .. _`CEC-OP-CEC-VERSION-2-0`: - - - ``CEC_OP_CEC_VERSION_2_0`` - - 6 - - CEC version according to the HDMI 2.0 standard. - - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| - -.. _cec-prim-dev-types: - -.. flat-table:: CEC Primary Device Types - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 4 - - * .. _`CEC-OP-PRIM-DEVTYPE-TV`: - - - ``CEC_OP_PRIM_DEVTYPE_TV`` - - 0 - - Use for a TV. - * .. _`CEC-OP-PRIM-DEVTYPE-RECORD`: - - - ``CEC_OP_PRIM_DEVTYPE_RECORD`` - - 1 - - Use for a recording device. - * .. _`CEC-OP-PRIM-DEVTYPE-TUNER`: - - - ``CEC_OP_PRIM_DEVTYPE_TUNER`` - - 3 - - Use for a device with a tuner. - * .. _`CEC-OP-PRIM-DEVTYPE-PLAYBACK`: - - - ``CEC_OP_PRIM_DEVTYPE_PLAYBACK`` - - 4 - - Use for a playback device. - * .. _`CEC-OP-PRIM-DEVTYPE-AUDIOSYSTEM`: - - - ``CEC_OP_PRIM_DEVTYPE_AUDIOSYSTEM`` - - 5 - - Use for an audio system (e.g. an audio/video receiver). - * .. _`CEC-OP-PRIM-DEVTYPE-SWITCH`: - - - ``CEC_OP_PRIM_DEVTYPE_SWITCH`` - - 6 - - Use for a CEC switch. - * .. _`CEC-OP-PRIM-DEVTYPE-VIDEOPROC`: - - - ``CEC_OP_PRIM_DEVTYPE_VIDEOPROC`` - - 7 - - Use for a video processor device. - - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| - -.. _cec-log-addr-types: - -.. flat-table:: CEC Logical Address Types - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 16 - - * .. _`CEC-LOG-ADDR-TYPE-TV`: - - - ``CEC_LOG_ADDR_TYPE_TV`` - - 0 - - Use for a TV. - * .. _`CEC-LOG-ADDR-TYPE-RECORD`: - - - ``CEC_LOG_ADDR_TYPE_RECORD`` - - 1 - - Use for a recording device. - * .. _`CEC-LOG-ADDR-TYPE-TUNER`: - - - ``CEC_LOG_ADDR_TYPE_TUNER`` - - 2 - - Use for a tuner device. - * .. _`CEC-LOG-ADDR-TYPE-PLAYBACK`: - - - ``CEC_LOG_ADDR_TYPE_PLAYBACK`` - - 3 - - Use for a playback device. - * .. _`CEC-LOG-ADDR-TYPE-AUDIOSYSTEM`: - - - ``CEC_LOG_ADDR_TYPE_AUDIOSYSTEM`` - - 4 - - Use for an audio system device. - * .. _`CEC-LOG-ADDR-TYPE-SPECIFIC`: - - - ``CEC_LOG_ADDR_TYPE_SPECIFIC`` - - 5 - - Use for a second TV or for a video processor device. - * .. _`CEC-LOG-ADDR-TYPE-UNREGISTERED`: - - - ``CEC_LOG_ADDR_TYPE_UNREGISTERED`` - - 6 - - Use this if you just want to remain unregistered. Used for pure - CEC switches or CDC-only devices (CDC: Capability Discovery and - Control). - - - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| - -.. _cec-all-dev-types-flags: - -.. flat-table:: CEC All Device Types Flags - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 4 - - * .. _`CEC-OP-ALL-DEVTYPE-TV`: - - - ``CEC_OP_ALL_DEVTYPE_TV`` - - 0x80 - - This supports the TV type. - * .. _`CEC-OP-ALL-DEVTYPE-RECORD`: - - - ``CEC_OP_ALL_DEVTYPE_RECORD`` - - 0x40 - - This supports the Recording type. - * .. _`CEC-OP-ALL-DEVTYPE-TUNER`: - - - ``CEC_OP_ALL_DEVTYPE_TUNER`` - - 0x20 - - This supports the Tuner type. - * .. _`CEC-OP-ALL-DEVTYPE-PLAYBACK`: - - - ``CEC_OP_ALL_DEVTYPE_PLAYBACK`` - - 0x10 - - This supports the Playback type. - * .. _`CEC-OP-ALL-DEVTYPE-AUDIOSYSTEM`: - - - ``CEC_OP_ALL_DEVTYPE_AUDIOSYSTEM`` - - 0x08 - - This supports the Audio System type. - * .. _`CEC-OP-ALL-DEVTYPE-SWITCH`: - - - ``CEC_OP_ALL_DEVTYPE_SWITCH`` - - 0x04 - - This supports the CEC Switch or Video Processing type. - - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. - -The :ref:`ioctl CEC_ADAP_S_LOG_ADDRS ` can return the following -error codes: - -ENOTTY - The ``CEC_CAP_LOG_ADDRS`` capability wasn't set, so this ioctl is not supported. - -EBUSY - The CEC adapter is currently configuring itself, or it is already configured and - ``num_log_addrs`` is non-zero, or another filehandle is in exclusive follower or - initiator mode, or the filehandle is in mode ``CEC_MODE_NO_INITIATOR``. - -EINVAL - The contents of struct :c:type:`cec_log_addrs` is invalid. diff --git a/Documentation/media/uapi/cec/cec-ioc-adap-g-phys-addr.rst b/Documentation/media/uapi/cec/cec-ioc-adap-g-phys-addr.rst deleted file mode 100644 index 693be2f9bf2e..000000000000 --- a/Documentation/media/uapi/cec/cec-ioc-adap-g-phys-addr.rst +++ /dev/null @@ -1,100 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _CEC_ADAP_PHYS_ADDR: -.. _CEC_ADAP_G_PHYS_ADDR: -.. _CEC_ADAP_S_PHYS_ADDR: - -**************************************************** -ioctls CEC_ADAP_G_PHYS_ADDR and CEC_ADAP_S_PHYS_ADDR -**************************************************** - -Name -==== - -CEC_ADAP_G_PHYS_ADDR, CEC_ADAP_S_PHYS_ADDR - Get or set the physical address - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, CEC_ADAP_G_PHYS_ADDR, __u16 *argp ) - :name: CEC_ADAP_G_PHYS_ADDR - -.. c:function:: int ioctl( int fd, CEC_ADAP_S_PHYS_ADDR, __u16 *argp ) - :name: CEC_ADAP_S_PHYS_ADDR - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - -``argp`` - Pointer to the CEC address. - -Description -=========== - -To query the current physical address applications call -:ref:`ioctl CEC_ADAP_G_PHYS_ADDR ` with a pointer to a __u16 where the -driver stores the physical address. - -To set a new physical address applications store the physical address in -a __u16 and call :ref:`ioctl CEC_ADAP_S_PHYS_ADDR ` with a pointer to -this integer. The :ref:`ioctl CEC_ADAP_S_PHYS_ADDR ` is only available if -``CEC_CAP_PHYS_ADDR`` is set (the ``ENOTTY`` error code will be returned -otherwise). The :ref:`ioctl CEC_ADAP_S_PHYS_ADDR ` can only be called -by a file descriptor in initiator mode (see :ref:`CEC_S_MODE`), if not -the ``EBUSY`` error code will be returned. - -To clear an existing physical address use ``CEC_PHYS_ADDR_INVALID``. -The adapter will go to the unconfigured state. - -If logical address types have been defined (see :ref:`ioctl CEC_ADAP_S_LOG_ADDRS `), -then this ioctl will block until all -requested logical addresses have been claimed. If the file descriptor is in non-blocking mode -then it will not wait for the logical addresses to be claimed, instead it just returns 0. - -A :ref:`CEC_EVENT_STATE_CHANGE ` event is sent when the physical address -changes. - -The physical address is a 16-bit number where each group of 4 bits -represent a digit of the physical address a.b.c.d where the most -significant 4 bits represent 'a'. The CEC root device (usually the TV) -has address 0.0.0.0. Every device that is hooked up to an input of the -TV has address a.0.0.0 (where 'a' is ≥ 1), devices hooked up to those in -turn have addresses a.b.0.0, etc. So a topology of up to 5 devices deep -is supported. The physical address a device shall use is stored in the -EDID of the sink. - -For example, the EDID for each HDMI input of the TV will have a -different physical address of the form a.0.0.0 that the sources will -read out and use as their physical address. - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. - -The :ref:`ioctl CEC_ADAP_S_PHYS_ADDR ` can return the following -error codes: - -ENOTTY - The ``CEC_CAP_PHYS_ADDR`` capability wasn't set, so this ioctl is not supported. - -EBUSY - Another filehandle is in exclusive follower or initiator mode, or the filehandle - is in mode ``CEC_MODE_NO_INITIATOR``. - -EINVAL - The physical address is malformed. diff --git a/Documentation/media/uapi/cec/cec-ioc-dqevent.rst b/Documentation/media/uapi/cec/cec-ioc-dqevent.rst deleted file mode 100644 index d16b226b1bef..000000000000 --- a/Documentation/media/uapi/cec/cec-ioc-dqevent.rst +++ /dev/null @@ -1,257 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _CEC_DQEVENT: - -***************** -ioctl CEC_DQEVENT -***************** - -Name -==== - -CEC_DQEVENT - Dequeue a CEC event - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, CEC_DQEVENT, struct cec_event *argp ) - :name: CEC_DQEVENT - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - -``argp`` - - -Description -=========== - -CEC devices can send asynchronous events. These can be retrieved by -calling :c:func:`CEC_DQEVENT`. If the file descriptor is in -non-blocking mode and no event is pending, then it will return -1 and -set errno to the ``EAGAIN`` error code. - -The internal event queues are per-filehandle and per-event type. If -there is no more room in a queue then the last event is overwritten with -the new one. This means that intermediate results can be thrown away but -that the latest event is always available. This also means that is it -possible to read two successive events that have the same value (e.g. -two :ref:`CEC_EVENT_STATE_CHANGE ` events with -the same state). In that case the intermediate state changes were lost but -it is guaranteed that the state did change in between the two events. - -.. tabularcolumns:: |p{1.2cm}|p{2.9cm}|p{13.4cm}| - -.. c:type:: cec_event_state_change - -.. flat-table:: struct cec_event_state_change - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 8 - - * - __u16 - - ``phys_addr`` - - The current physical address. This is ``CEC_PHYS_ADDR_INVALID`` if no - valid physical address is set. - * - __u16 - - ``log_addr_mask`` - - The current set of claimed logical addresses. This is 0 if no logical - addresses are claimed or if ``phys_addr`` is ``CEC_PHYS_ADDR_INVALID``. - If bit 15 is set (``1 << CEC_LOG_ADDR_UNREGISTERED``) then this device - has the unregistered logical address. In that case all other bits are 0. - * - __u16 - - ``have_conn_info`` - - If non-zero, then HDMI connector information is available. - This field is only valid if ``CEC_CAP_CONNECTOR_INFO`` is set. If that - capability is set and ``have_conn_info`` is zero, then that indicates - that the HDMI connector device is not instantiated, either because - the HDMI driver is still configuring the device or because the HDMI - device was unbound. - - -.. c:type:: cec_event_lost_msgs - -.. tabularcolumns:: |p{1.0cm}|p{2.0cm}|p{14.5cm}| - -.. flat-table:: struct cec_event_lost_msgs - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 16 - - * - __u32 - - ``lost_msgs`` - - Set to the number of lost messages since the filehandle was opened - or since the last time this event was dequeued for this - filehandle. The messages lost are the oldest messages. So when a - new message arrives and there is no more room, then the oldest - message is discarded to make room for the new one. The internal - size of the message queue guarantees that all messages received in - the last two seconds will be stored. Since messages should be - replied to within a second according to the CEC specification, - this is more than enough. - - -.. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.6cm}| - -.. c:type:: cec_event - -.. flat-table:: struct cec_event - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 8 - - * - __u64 - - ``ts`` - - Timestamp of the event in ns. - - The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. - - To access the same clock from userspace use :c:func:`clock_gettime`. - * - __u32 - - ``event`` - - The CEC event type, see :ref:`cec-events`. - * - __u32 - - ``flags`` - - Event flags, see :ref:`cec-event-flags`. - * - union { - - (anonymous) - * - struct cec_event_state_change - - ``state_change`` - - The new adapter state as sent by the :ref:`CEC_EVENT_STATE_CHANGE ` - event. - * - struct cec_event_lost_msgs - - ``lost_msgs`` - - The number of lost messages as sent by the :ref:`CEC_EVENT_LOST_MSGS ` - event. - * - } - - - - -.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| - -.. _cec-events: - -.. flat-table:: CEC Events Types - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 16 - - * .. _`CEC-EVENT-STATE-CHANGE`: - - - ``CEC_EVENT_STATE_CHANGE`` - - 1 - - Generated when the CEC Adapter's state changes. When open() is - called an initial event will be generated for that filehandle with - the CEC Adapter's state at that time. - * .. _`CEC-EVENT-LOST-MSGS`: - - - ``CEC_EVENT_LOST_MSGS`` - - 2 - - Generated if one or more CEC messages were lost because the - application didn't dequeue CEC messages fast enough. - * .. _`CEC-EVENT-PIN-CEC-LOW`: - - - ``CEC_EVENT_PIN_CEC_LOW`` - - 3 - - Generated if the CEC pin goes from a high voltage to a low voltage. - Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN`` - capability set. - * .. _`CEC-EVENT-PIN-CEC-HIGH`: - - - ``CEC_EVENT_PIN_CEC_HIGH`` - - 4 - - Generated if the CEC pin goes from a low voltage to a high voltage. - Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN`` - capability set. - * .. _`CEC-EVENT-PIN-HPD-LOW`: - - - ``CEC_EVENT_PIN_HPD_LOW`` - - 5 - - Generated if the HPD pin goes from a high voltage to a low voltage. - Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN`` - capability set. When open() is called, the HPD pin can be read and - if the HPD is low, then an initial event will be generated for that - filehandle. - * .. _`CEC-EVENT-PIN-HPD-HIGH`: - - - ``CEC_EVENT_PIN_HPD_HIGH`` - - 6 - - Generated if the HPD pin goes from a low voltage to a high voltage. - Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN`` - capability set. When open() is called, the HPD pin can be read and - if the HPD is high, then an initial event will be generated for that - filehandle. - * .. _`CEC-EVENT-PIN-5V-LOW`: - - - ``CEC_EVENT_PIN_5V_LOW`` - - 6 - - Generated if the 5V pin goes from a high voltage to a low voltage. - Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN`` - capability set. When open() is called, the 5V pin can be read and - if the 5V is low, then an initial event will be generated for that - filehandle. - * .. _`CEC-EVENT-PIN-5V-HIGH`: - - - ``CEC_EVENT_PIN_5V_HIGH`` - - 7 - - Generated if the 5V pin goes from a low voltage to a high voltage. - Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN`` - capability set. When open() is called, the 5V pin can be read and - if the 5V is high, then an initial event will be generated for that - filehandle. - - -.. tabularcolumns:: |p{6.0cm}|p{0.6cm}|p{10.9cm}| - -.. _cec-event-flags: - -.. flat-table:: CEC Event Flags - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 8 - - * .. _`CEC-EVENT-FL-INITIAL-STATE`: - - - ``CEC_EVENT_FL_INITIAL_STATE`` - - 1 - - Set for the initial events that are generated when the device is - opened. See the table above for which events do this. This allows - applications to learn the initial state of the CEC adapter at - open() time. - * .. _`CEC-EVENT-FL-DROPPED-EVENTS`: - - - ``CEC_EVENT_FL_DROPPED_EVENTS`` - - 2 - - Set if one or more events of the given event type have been dropped. - This is an indication that the application cannot keep up. - - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. - -The :ref:`ioctl CEC_DQEVENT ` can return the following -error codes: - -EAGAIN - This is returned when the filehandle is in non-blocking mode and there - are no pending events. - -ERESTARTSYS - An interrupt (e.g. Ctrl-C) arrived while in blocking mode waiting for - events to arrive. diff --git a/Documentation/media/uapi/cec/cec-ioc-g-mode.rst b/Documentation/media/uapi/cec/cec-ioc-g-mode.rst deleted file mode 100644 index 2535b77e3459..000000000000 --- a/Documentation/media/uapi/cec/cec-ioc-g-mode.rst +++ /dev/null @@ -1,301 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _CEC_MODE: -.. _CEC_G_MODE: -.. _CEC_S_MODE: - -******************************** -ioctls CEC_G_MODE and CEC_S_MODE -******************************** - -CEC_G_MODE, CEC_S_MODE - Get or set exclusive use of the CEC adapter - -Synopsis -======== - -.. c:function:: int ioctl( int fd, CEC_G_MODE, __u32 *argp ) - :name: CEC_G_MODE - -.. c:function:: int ioctl( int fd, CEC_S_MODE, __u32 *argp ) - :name: CEC_S_MODE - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - -``argp`` - Pointer to CEC mode. - -Description -=========== - -By default any filehandle can use :ref:`CEC_TRANSMIT`, but in order to prevent -applications from stepping on each others toes it must be possible to -obtain exclusive access to the CEC adapter. This ioctl sets the -filehandle to initiator and/or follower mode which can be exclusive -depending on the chosen mode. The initiator is the filehandle that is -used to initiate messages, i.e. it commands other CEC devices. The -follower is the filehandle that receives messages sent to the CEC -adapter and processes them. The same filehandle can be both initiator -and follower, or this role can be taken by two different filehandles. - -When a CEC message is received, then the CEC framework will decide how -it will be processed. If the message is a reply to an earlier -transmitted message, then the reply is sent back to the filehandle that -is waiting for it. In addition the CEC framework will process it. - -If the message is not a reply, then the CEC framework will process it -first. If there is no follower, then the message is just discarded and a -feature abort is sent back to the initiator if the framework couldn't -process it. If there is a follower, then the message is passed on to the -follower who will use :ref:`ioctl CEC_RECEIVE ` to dequeue -the new message. The framework expects the follower to make the right -decisions. - -The CEC framework will process core messages unless requested otherwise -by the follower. The follower can enable the passthrough mode. In that -case, the CEC framework will pass on most core messages without -processing them and the follower will have to implement those messages. -There are some messages that the core will always process, regardless of -the passthrough mode. See :ref:`cec-core-processing` for details. - -If there is no initiator, then any CEC filehandle can use -:ref:`ioctl CEC_TRANSMIT `. If there is an exclusive -initiator then only that initiator can call -:ref:`CEC_TRANSMIT`. The follower can of course -always call :ref:`ioctl CEC_TRANSMIT `. - -Available initiator modes are: - -.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| - -.. _cec-mode-initiator_e: - -.. flat-table:: Initiator Modes - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 16 - - * .. _`CEC-MODE-NO-INITIATOR`: - - - ``CEC_MODE_NO_INITIATOR`` - - 0x0 - - This is not an initiator, i.e. it cannot transmit CEC messages or - make any other changes to the CEC adapter. - * .. _`CEC-MODE-INITIATOR`: - - - ``CEC_MODE_INITIATOR`` - - 0x1 - - This is an initiator (the default when the device is opened) and - it can transmit CEC messages and make changes to the CEC adapter, - unless there is an exclusive initiator. - * .. _`CEC-MODE-EXCL-INITIATOR`: - - - ``CEC_MODE_EXCL_INITIATOR`` - - 0x2 - - This is an exclusive initiator and this file descriptor is the - only one that can transmit CEC messages and make changes to the - CEC adapter. If someone else is already the exclusive initiator - then an attempt to become one will return the ``EBUSY`` error code - error. - - -Available follower modes are: - -.. tabularcolumns:: |p{6.6cm}|p{0.9cm}|p{10.0cm}| - -.. _cec-mode-follower_e: - -.. cssclass:: longtable - -.. flat-table:: Follower Modes - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 16 - - * .. _`CEC-MODE-NO-FOLLOWER`: - - - ``CEC_MODE_NO_FOLLOWER`` - - 0x00 - - This is not a follower (the default when the device is opened). - * .. _`CEC-MODE-FOLLOWER`: - - - ``CEC_MODE_FOLLOWER`` - - 0x10 - - This is a follower and it will receive CEC messages unless there - is an exclusive follower. You cannot become a follower if - :ref:`CEC_CAP_TRANSMIT ` is not set or if :ref:`CEC_MODE_NO_INITIATOR ` - was specified, the ``EINVAL`` error code is returned in that case. - * .. _`CEC-MODE-EXCL-FOLLOWER`: - - - ``CEC_MODE_EXCL_FOLLOWER`` - - 0x20 - - This is an exclusive follower and only this file descriptor will - receive CEC messages for processing. If someone else is already - the exclusive follower then an attempt to become one will return - the ``EBUSY`` error code. You cannot become a follower if - :ref:`CEC_CAP_TRANSMIT ` is not set or if :ref:`CEC_MODE_NO_INITIATOR ` - was specified, the ``EINVAL`` error code is returned in that case. - * .. _`CEC-MODE-EXCL-FOLLOWER-PASSTHRU`: - - - ``CEC_MODE_EXCL_FOLLOWER_PASSTHRU`` - - 0x30 - - This is an exclusive follower and only this file descriptor will - receive CEC messages for processing. In addition it will put the - CEC device into passthrough mode, allowing the exclusive follower - to handle most core messages instead of relying on the CEC - framework for that. If someone else is already the exclusive - follower then an attempt to become one will return the ``EBUSY`` error - code. You cannot become a follower if :ref:`CEC_CAP_TRANSMIT ` - is not set or if :ref:`CEC_MODE_NO_INITIATOR ` was specified, - the ``EINVAL`` error code is returned in that case. - * .. _`CEC-MODE-MONITOR-PIN`: - - - ``CEC_MODE_MONITOR_PIN`` - - 0xd0 - - Put the file descriptor into pin monitoring mode. Can only be used in - combination with :ref:`CEC_MODE_NO_INITIATOR `, - otherwise the ``EINVAL`` error code will be returned. - This mode requires that the :ref:`CEC_CAP_MONITOR_PIN ` - capability is set, otherwise the ``EINVAL`` error code is returned. - While in pin monitoring mode this file descriptor can receive the - ``CEC_EVENT_PIN_CEC_LOW`` and ``CEC_EVENT_PIN_CEC_HIGH`` events to see the - low-level CEC pin transitions. This is very useful for debugging. - This mode is only allowed if the process has the ``CAP_NET_ADMIN`` - capability. If that is not set, then the ``EPERM`` error code is returned. - * .. _`CEC-MODE-MONITOR`: - - - ``CEC_MODE_MONITOR`` - - 0xe0 - - Put the file descriptor into monitor mode. Can only be used in - combination with :ref:`CEC_MODE_NO_INITIATOR `, - otherwise the ``EINVAL`` error code will be returned. - In monitor mode all messages this CEC - device transmits and all messages it receives (both broadcast - messages and directed messages for one its logical addresses) will - be reported. This is very useful for debugging. This is only - allowed if the process has the ``CAP_NET_ADMIN`` capability. If - that is not set, then the ``EPERM`` error code is returned. - * .. _`CEC-MODE-MONITOR-ALL`: - - - ``CEC_MODE_MONITOR_ALL`` - - 0xf0 - - Put the file descriptor into 'monitor all' mode. Can only be used - in combination with :ref:`CEC_MODE_NO_INITIATOR `, otherwise - the ``EINVAL`` error code will be returned. In 'monitor all' mode all messages - this CEC device transmits and all messages it receives, including - directed messages for other CEC devices will be reported. This is - very useful for debugging, but not all devices support this. This - mode requires that the :ref:`CEC_CAP_MONITOR_ALL ` capability is set, - otherwise the ``EINVAL`` error code is returned. This is only allowed if - the process has the ``CAP_NET_ADMIN`` capability. If that is not - set, then the ``EPERM`` error code is returned. - - -Core message processing details: - -.. tabularcolumns:: |p{6.6cm}|p{10.9cm}| - -.. _cec-core-processing: - -.. flat-table:: Core Message Processing - :header-rows: 0 - :stub-columns: 0 - :widths: 1 8 - - * .. _`CEC-MSG-GET-CEC-VERSION`: - - - ``CEC_MSG_GET_CEC_VERSION`` - - The core will return the CEC version that was set with - :ref:`ioctl CEC_ADAP_S_LOG_ADDRS `, - except when in passthrough mode. In passthrough mode the core - does nothing and this message has to be handled by a follower - instead. - * .. _`CEC-MSG-GIVE-DEVICE-VENDOR-ID`: - - - ``CEC_MSG_GIVE_DEVICE_VENDOR_ID`` - - The core will return the vendor ID that was set with - :ref:`ioctl CEC_ADAP_S_LOG_ADDRS `, - except when in passthrough mode. In passthrough mode the core - does nothing and this message has to be handled by a follower - instead. - * .. _`CEC-MSG-ABORT`: - - - ``CEC_MSG_ABORT`` - - The core will return a Feature Abort message with reason - 'Feature Refused' as per the specification, except when in - passthrough mode. In passthrough mode the core does nothing - and this message has to be handled by a follower instead. - * .. _`CEC-MSG-GIVE-PHYSICAL-ADDR`: - - - ``CEC_MSG_GIVE_PHYSICAL_ADDR`` - - The core will report the current physical address, except when - in passthrough mode. In passthrough mode the core does nothing - and this message has to be handled by a follower instead. - * .. _`CEC-MSG-GIVE-OSD-NAME`: - - - ``CEC_MSG_GIVE_OSD_NAME`` - - The core will report the current OSD name that was set with - :ref:`ioctl CEC_ADAP_S_LOG_ADDRS `, - except when in passthrough mode. In passthrough mode the core - does nothing and this message has to be handled by a follower - instead. - * .. _`CEC-MSG-GIVE-FEATURES`: - - - ``CEC_MSG_GIVE_FEATURES`` - - The core will do nothing if the CEC version is older than 2.0, - otherwise it will report the current features that were set with - :ref:`ioctl CEC_ADAP_S_LOG_ADDRS `, - except when in passthrough mode. In passthrough mode the core - does nothing (for any CEC version) and this message has to be handled - by a follower instead. - * .. _`CEC-MSG-USER-CONTROL-PRESSED`: - - - ``CEC_MSG_USER_CONTROL_PRESSED`` - - If :ref:`CEC_CAP_RC ` is set and if - :ref:`CEC_LOG_ADDRS_FL_ALLOW_RC_PASSTHRU ` - is set, then generate a remote control key - press. This message is always passed on to the follower(s). - * .. _`CEC-MSG-USER-CONTROL-RELEASED`: - - - ``CEC_MSG_USER_CONTROL_RELEASED`` - - If :ref:`CEC_CAP_RC ` is set and if - :ref:`CEC_LOG_ADDRS_FL_ALLOW_RC_PASSTHRU ` - is set, then generate a remote control key - release. This message is always passed on to the follower(s). - * .. _`CEC-MSG-REPORT-PHYSICAL-ADDR`: - - - ``CEC_MSG_REPORT_PHYSICAL_ADDR`` - - The CEC framework will make note of the reported physical address - and then just pass the message on to the follower(s). - - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. - -The :ref:`ioctl CEC_S_MODE ` can return the following -error codes: - -EINVAL - The requested mode is invalid. - -EPERM - Monitor mode is requested, but the process does have the ``CAP_NET_ADMIN`` - capability. - -EBUSY - Someone else is already an exclusive follower or initiator. diff --git a/Documentation/media/uapi/cec/cec-ioc-receive.rst b/Documentation/media/uapi/cec/cec-ioc-receive.rst deleted file mode 100644 index 4137903d672e..000000000000 --- a/Documentation/media/uapi/cec/cec-ioc-receive.rst +++ /dev/null @@ -1,391 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _CEC_TRANSMIT: -.. _CEC_RECEIVE: - -*********************************** -ioctls CEC_RECEIVE and CEC_TRANSMIT -*********************************** - -Name -==== - -CEC_RECEIVE, CEC_TRANSMIT - Receive or transmit a CEC message - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, CEC_RECEIVE, struct cec_msg \*argp ) - :name: CEC_RECEIVE - -.. c:function:: int ioctl( int fd, CEC_TRANSMIT, struct cec_msg \*argp ) - :name: CEC_TRANSMIT - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - -``argp`` - Pointer to struct cec_msg. - -Description -=========== - -To receive a CEC message the application has to fill in the -``timeout`` field of struct :c:type:`cec_msg` and pass it to -:ref:`ioctl CEC_RECEIVE `. -If the file descriptor is in non-blocking mode and there are no received -messages pending, then it will return -1 and set errno to the ``EAGAIN`` -error code. If the file descriptor is in blocking mode and ``timeout`` -is non-zero and no message arrived within ``timeout`` milliseconds, then -it will return -1 and set errno to the ``ETIMEDOUT`` error code. - -A received message can be: - -1. a message received from another CEC device (the ``sequence`` field will - be 0). -2. the result of an earlier non-blocking transmit (the ``sequence`` field will - be non-zero). - -To send a CEC message the application has to fill in the struct -:c:type:`cec_msg` and pass it to :ref:`ioctl CEC_TRANSMIT `. -The :ref:`ioctl CEC_TRANSMIT ` is only available if -``CEC_CAP_TRANSMIT`` is set. If there is no more room in the transmit -queue, then it will return -1 and set errno to the ``EBUSY`` error code. -The transmit queue has enough room for 18 messages (about 1 second worth -of 2-byte messages). Note that the CEC kernel framework will also reply -to core messages (see :ref:`cec-core-processing`), so it is not a good -idea to fully fill up the transmit queue. - -If the file descriptor is in non-blocking mode then the transmit will -return 0 and the result of the transmit will be available via -:ref:`ioctl CEC_RECEIVE ` once the transmit has finished -(including waiting for a reply, if requested). - -The ``sequence`` field is filled in for every transmit and this can be -checked against the received messages to find the corresponding transmit -result. - -Normally calling :ref:`ioctl CEC_TRANSMIT ` when the physical -address is invalid (due to e.g. a disconnect) will return ``ENONET``. - -However, the CEC specification allows sending messages from 'Unregistered' to -'TV' when the physical address is invalid since some TVs pull the hotplug detect -pin of the HDMI connector low when they go into standby, or when switching to -another input. - -When the hotplug detect pin goes low the EDID disappears, and thus the -physical address, but the cable is still connected and CEC still works. -In order to detect/wake up the device it is allowed to send poll and 'Image/Text -View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). - -.. tabularcolumns:: |p{1.0cm}|p{3.5cm}|p{13.0cm}| - -.. c:type:: cec_msg - -.. cssclass:: longtable - -.. flat-table:: struct cec_msg - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 16 - - * - __u64 - - ``tx_ts`` - - Timestamp in ns of when the last byte of the message was transmitted. - The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. To access - the same clock from userspace use :c:func:`clock_gettime`. - * - __u64 - - ``rx_ts`` - - Timestamp in ns of when the last byte of the message was received. - The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. To access - the same clock from userspace use :c:func:`clock_gettime`. - * - __u32 - - ``len`` - - The length of the message. For :ref:`ioctl CEC_TRANSMIT ` this is filled in - by the application. The driver will fill this in for - :ref:`ioctl CEC_RECEIVE `. For :ref:`ioctl CEC_TRANSMIT ` it will be - filled in by the driver with the length of the reply message if ``reply`` was set. - * - __u32 - - ``timeout`` - - The timeout in milliseconds. This is the time the device will wait - for a message to be received before timing out. If it is set to 0, - then it will wait indefinitely when it is called by :ref:`ioctl CEC_RECEIVE `. - If it is 0 and it is called by :ref:`ioctl CEC_TRANSMIT `, - then it will be replaced by 1000 if the ``reply`` is non-zero or - ignored if ``reply`` is 0. - * - __u32 - - ``sequence`` - - A non-zero sequence number is automatically assigned by the CEC framework - for all transmitted messages. It is used by the CEC framework when it queues - the transmit result (when transmit was called in non-blocking mode). This - allows the application to associate the received message with the original - transmit. - * - __u32 - - ``flags`` - - Flags. See :ref:`cec-msg-flags` for a list of available flags. - * - __u8 - - ``tx_status`` - - The status bits of the transmitted message. See - :ref:`cec-tx-status` for the possible status values. It is 0 if - this message was received, not transmitted. - * - __u8 - - ``msg[16]`` - - The message payload. For :ref:`ioctl CEC_TRANSMIT ` this is filled in by the - application. The driver will fill this in for :ref:`ioctl CEC_RECEIVE `. - For :ref:`ioctl CEC_TRANSMIT ` it will be filled in by the driver with - the payload of the reply message if ``timeout`` was set. - * - __u8 - - ``reply`` - - Wait until this message is replied. If ``reply`` is 0 and the - ``timeout`` is 0, then don't wait for a reply but return after - transmitting the message. Ignored by :ref:`ioctl CEC_RECEIVE `. - The case where ``reply`` is 0 (this is the opcode for the Feature Abort - message) and ``timeout`` is non-zero is specifically allowed to make it - possible to send a message and wait up to ``timeout`` milliseconds for a - Feature Abort reply. In this case ``rx_status`` will either be set - to :ref:`CEC_RX_STATUS_TIMEOUT ` or - :ref:`CEC_RX_STATUS_FEATURE_ABORT `. - - If the transmitter message is ``CEC_MSG_INITIATE_ARC`` then the ``reply`` - values ``CEC_MSG_REPORT_ARC_INITIATED`` and ``CEC_MSG_REPORT_ARC_TERMINATED`` - are processed differently: either value will match both possible replies. - The reason is that the ``CEC_MSG_INITIATE_ARC`` message is the only CEC - message that has two possible replies other than Feature Abort. The - ``reply`` field will be updated with the actual reply so that it is - synchronized with the contents of the received message. - * - __u8 - - ``rx_status`` - - The status bits of the received message. See - :ref:`cec-rx-status` for the possible status values. It is 0 if - this message was transmitted, not received, unless this is the - reply to a transmitted message. In that case both ``rx_status`` - and ``tx_status`` are set. - * - __u8 - - ``tx_status`` - - The status bits of the transmitted message. See - :ref:`cec-tx-status` for the possible status values. It is 0 if - this message was received, not transmitted. - * - __u8 - - ``tx_arb_lost_cnt`` - - A counter of the number of transmit attempts that resulted in the - Arbitration Lost error. This is only set if the hardware supports - this, otherwise it is always 0. This counter is only valid if the - :ref:`CEC_TX_STATUS_ARB_LOST ` status bit is set. - * - __u8 - - ``tx_nack_cnt`` - - A counter of the number of transmit attempts that resulted in the - Not Acknowledged error. This is only set if the hardware supports - this, otherwise it is always 0. This counter is only valid if the - :ref:`CEC_TX_STATUS_NACK ` status bit is set. - * - __u8 - - ``tx_low_drive_cnt`` - - A counter of the number of transmit attempts that resulted in the - Arbitration Lost error. This is only set if the hardware supports - this, otherwise it is always 0. This counter is only valid if the - :ref:`CEC_TX_STATUS_LOW_DRIVE ` status bit is set. - * - __u8 - - ``tx_error_cnt`` - - A counter of the number of transmit errors other than Arbitration - Lost or Not Acknowledged. This is only set if the hardware - supports this, otherwise it is always 0. This counter is only - valid if the :ref:`CEC_TX_STATUS_ERROR ` status bit is set. - - -.. tabularcolumns:: |p{6.2cm}|p{1.0cm}|p{10.3cm}| - -.. _cec-msg-flags: - -.. flat-table:: Flags for struct cec_msg - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 4 - - * .. _`CEC-MSG-FL-REPLY-TO-FOLLOWERS`: - - - ``CEC_MSG_FL_REPLY_TO_FOLLOWERS`` - - 1 - - If a CEC transmit expects a reply, then by default that reply is only sent to - the filehandle that called :ref:`ioctl CEC_TRANSMIT `. If this - flag is set, then the reply is also sent to all followers, if any. If the - filehandle that called :ref:`ioctl CEC_TRANSMIT ` is also a - follower, then that filehandle will receive the reply twice: once as the - result of the :ref:`ioctl CEC_TRANSMIT `, and once via - :ref:`ioctl CEC_RECEIVE `. - - * .. _`CEC-MSG-FL-RAW`: - - - ``CEC_MSG_FL_RAW`` - - 2 - - Normally CEC messages are validated before transmitting them. If this - flag is set when :ref:`ioctl CEC_TRANSMIT ` is called, - then no validation takes place and the message is transmitted as-is. - This is useful when debugging CEC issues. - This flag is only allowed if the process has the ``CAP_SYS_RAWIO`` - capability. If that is not set, then the ``EPERM`` error code is - returned. - - -.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| - -.. _cec-tx-status: - -.. flat-table:: CEC Transmit Status - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 16 - - * .. _`CEC-TX-STATUS-OK`: - - - ``CEC_TX_STATUS_OK`` - - 0x01 - - The message was transmitted successfully. This is mutually - exclusive with :ref:`CEC_TX_STATUS_MAX_RETRIES `. - Other bits can still be set if earlier attempts met with failure before - the transmit was eventually successful. - * .. _`CEC-TX-STATUS-ARB-LOST`: - - - ``CEC_TX_STATUS_ARB_LOST`` - - 0x02 - - CEC line arbitration was lost, i.e. another transmit started at the - same time with a higher priority. Optional status, not all hardware - can detect this error condition. - * .. _`CEC-TX-STATUS-NACK`: - - - ``CEC_TX_STATUS_NACK`` - - 0x04 - - Message was not acknowledged. Note that some hardware cannot tell apart - a 'Not Acknowledged' status from other error conditions, i.e. the result - of a transmit is just OK or FAIL. In that case this status will be - returned when the transmit failed. - * .. _`CEC-TX-STATUS-LOW-DRIVE`: - - - ``CEC_TX_STATUS_LOW_DRIVE`` - - 0x08 - - Low drive was detected on the CEC bus. This indicates that a - follower detected an error on the bus and requests a - retransmission. Optional status, not all hardware can detect this - error condition. - * .. _`CEC-TX-STATUS-ERROR`: - - - ``CEC_TX_STATUS_ERROR`` - - 0x10 - - Some error occurred. This is used for any errors that do not fit - ``CEC_TX_STATUS_ARB_LOST`` or ``CEC_TX_STATUS_LOW_DRIVE``, either because - the hardware could not tell which error occurred, or because the hardware - tested for other conditions besides those two. Optional status. - * .. _`CEC-TX-STATUS-MAX-RETRIES`: - - - ``CEC_TX_STATUS_MAX_RETRIES`` - - 0x20 - - The transmit failed after one or more retries. This status bit is - mutually exclusive with :ref:`CEC_TX_STATUS_OK `. - Other bits can still be set to explain which failures were seen. - * .. _`CEC-TX-STATUS-ABORTED`: - - - ``CEC_TX_STATUS_ABORTED`` - - 0x40 - - The transmit was aborted due to an HDMI disconnect, or the adapter - was unconfigured, or a transmit was interrupted, or the driver - returned an error when attempting to start a transmit. - * .. _`CEC-TX-STATUS-TIMEOUT`: - - - ``CEC_TX_STATUS_TIMEOUT`` - - 0x80 - - The transmit timed out. This should not normally happen and this - indicates a driver problem. - - -.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| - -.. _cec-rx-status: - -.. flat-table:: CEC Receive Status - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 16 - - * .. _`CEC-RX-STATUS-OK`: - - - ``CEC_RX_STATUS_OK`` - - 0x01 - - The message was received successfully. - * .. _`CEC-RX-STATUS-TIMEOUT`: - - - ``CEC_RX_STATUS_TIMEOUT`` - - 0x02 - - The reply to an earlier transmitted message timed out. - * .. _`CEC-RX-STATUS-FEATURE-ABORT`: - - - ``CEC_RX_STATUS_FEATURE_ABORT`` - - 0x04 - - The message was received successfully but the reply was - ``CEC_MSG_FEATURE_ABORT``. This status is only set if this message - was the reply to an earlier transmitted message. - * .. _`CEC-RX-STATUS-ABORTED`: - - - ``CEC_RX_STATUS_ABORTED`` - - 0x08 - - The wait for a reply to an earlier transmitted message was aborted - because the HDMI cable was disconnected, the adapter was unconfigured - or the :ref:`CEC_TRANSMIT ` that waited for a - reply was interrupted. - - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. - -The :ref:`ioctl CEC_RECEIVE ` can return the following -error codes: - -EAGAIN - No messages are in the receive queue, and the filehandle is in non-blocking mode. - -ETIMEDOUT - The ``timeout`` was reached while waiting for a message. - -ERESTARTSYS - The wait for a message was interrupted (e.g. by Ctrl-C). - -The :ref:`ioctl CEC_TRANSMIT ` can return the following -error codes: - -ENOTTY - The ``CEC_CAP_TRANSMIT`` capability wasn't set, so this ioctl is not supported. - -EPERM - The CEC adapter is not configured, i.e. :ref:`ioctl CEC_ADAP_S_LOG_ADDRS ` - has never been called, or ``CEC_MSG_FL_RAW`` was used from a process that - did not have the ``CAP_SYS_RAWIO`` capability. - -ENONET - The CEC adapter is not configured, i.e. :ref:`ioctl CEC_ADAP_S_LOG_ADDRS ` - was called, but the physical address is invalid so no logical address was claimed. - An exception is made in this case for transmits from initiator 0xf ('Unregistered') - to destination 0 ('TV'). In that case the transmit will proceed as usual. - -EBUSY - Another filehandle is in exclusive follower or initiator mode, or the filehandle - is in mode ``CEC_MODE_NO_INITIATOR``. This is also returned if the transmit - queue is full. - -EINVAL - The contents of struct :c:type:`cec_msg` is invalid. - -ERESTARTSYS - The wait for a successful transmit was interrupted (e.g. by Ctrl-C). diff --git a/Documentation/media/uapi/cec/cec-pin-error-inj.rst b/Documentation/media/uapi/cec/cec-pin-error-inj.rst deleted file mode 100644 index 725f8b1c9965..000000000000 --- a/Documentation/media/uapi/cec/cec-pin-error-inj.rst +++ /dev/null @@ -1,334 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -CEC Pin Framework Error Injection -================================= - -The CEC Pin Framework is a core CEC framework for CEC hardware that only -has low-level support for the CEC bus. Most hardware today will have -high-level CEC support where the hardware deals with driving the CEC bus, -but some older devices aren't that fancy. However, this framework also -allows you to connect the CEC pin to a GPIO on e.g. a Raspberry Pi and -you have now made a CEC adapter. - -What makes doing this so interesting is that since we have full control -over the bus it is easy to support error injection. This is ideal to -test how well CEC adapters can handle error conditions. - -Currently only the cec-gpio driver (when the CEC line is directly -connected to a pull-up GPIO line) and the AllWinner A10/A20 drm driver -support this framework. - -If ``CONFIG_CEC_PIN_ERROR_INJ`` is enabled, then error injection is available -through debugfs. Specifically, in ``/sys/kernel/debug/cec/cecX/`` there is -now an ``error-inj`` file. - -.. note:: - - The error injection commands are not a stable ABI and may change in the - future. - -With ``cat error-inj`` you can see both the possible commands and the current -error injection status:: - - $ cat /sys/kernel/debug/cec/cec0/error-inj - # Clear error injections: - # clear clear all rx and tx error injections - # rx-clear clear all rx error injections - # tx-clear clear all tx error injections - # clear clear all rx and tx error injections for - # rx-clear clear all rx error injections for - # tx-clear clear all tx error injections for - # - # RX error injection: - # [,] rx-nack NACK the message instead of sending an ACK - # [,] rx-low-drive force a low-drive condition at this bit position - # [,] rx-add-byte add a spurious byte to the received CEC message - # [,] rx-remove-byte remove the last byte from the received CEC message - # [,] rx-arb-lost generate a POLL message to trigger an arbitration lost - # - # TX error injection settings: - # tx-ignore-nack-until-eom ignore early NACKs until EOM - # tx-custom-low-usecs define the 'low' time for the custom pulse - # tx-custom-high-usecs define the 'high' time for the custom pulse - # tx-custom-pulse transmit the custom pulse once the bus is idle - # - # TX error injection: - # [,] tx-no-eom don't set the EOM bit - # [,] tx-early-eom set the EOM bit one byte too soon - # [,] tx-add-bytes append (1-255) spurious bytes to the message - # [,] tx-remove-byte drop the last byte from the message - # [,] tx-short-bit make this bit shorter than allowed - # [,] tx-long-bit make this bit longer than allowed - # [,] tx-custom-bit send the custom pulse instead of this bit - # [,] tx-short-start send a start pulse that's too short - # [,] tx-long-start send a start pulse that's too long - # [,] tx-custom-start send the custom pulse instead of the start pulse - # [,] tx-last-bit stop sending after this bit - # [,] tx-low-drive force a low-drive condition at this bit position - # - # CEC message opcode (0-255) or 'any' - # 'once' (default), 'always', 'toggle' or 'off' - # CEC message bit (0-159) - # 10 bits per 'byte': bits 0-7: data, bit 8: EOM, bit 9: ACK - # CEC poll message used to test arbitration lost (0x00-0xff, default 0x0f) - # microseconds (0-10000000, default 1000) - - clear - -You can write error injection commands to ``error-inj`` using -``echo 'cmd' >error-inj`` or ``cat cmd.txt >error-inj``. The ``cat error-inj`` -output contains the current error commands. You can save the output to a file -and use it as an input to ``error-inj`` later. - -Basic Syntax ------------- - -Leading spaces/tabs are ignored. If the next character is a ``#`` or the end -of the line was reached, then the whole line is ignored. Otherwise a command -is expected. - -The error injection commands fall in two main groups: those relating to -receiving CEC messages and those relating to transmitting CEC messages. In -addition, there are commands to clear existing error injection commands and -to create custom pulses on the CEC bus. - -Most error injection commands can be executed for specific CEC opcodes or for -all opcodes (``any``). Each command also has a 'mode' which can be ``off`` -(can be used to turn off an existing error injection command), ``once`` -(the default) which will trigger the error injection only once for the next -received or transmitted message, ``always`` to always trigger the error -injection and ``toggle`` to toggle the error injection on or off for every -transmit or receive. - -So '``any rx-nack``' will NACK the next received CEC message, -'``any,always rx-nack``' will NACK all received CEC messages and -'``0x82,toggle rx-nack``' will only NACK if an Active Source message was -received and do that only for every other received message. - -After an error was injected with mode ``once`` the error injection command -is cleared automatically, so ``once`` is a one-time deal. - -All combinations of ```` and error injection commands can co-exist. So -this is fine:: - - 0x9e tx-add-bytes 1 - 0x9e tx-early-eom - 0x9f tx-add-bytes 2 - any rx-nack - -All four error injection commands will be active simultaneously. - -However, if the same ```` and command combination is specified, -but with different arguments:: - - 0x9e tx-add-bytes 1 - 0x9e tx-add-bytes 2 - -Then the second will overwrite the first. - -Clear Error Injections ----------------------- - -``clear`` - Clear all error injections. - -``rx-clear`` - Clear all receive error injections - -``tx-clear`` - Clear all transmit error injections - -`` clear`` - Clear all error injections for the given opcode. - -`` rx-clear`` - Clear all receive error injections for the given opcode. - -`` tx-clear`` - Clear all transmit error injections for the given opcode. - -Receive Messages ----------------- - -``[,] rx-nack`` - NACK broadcast messages and messages directed to this CEC adapter. - Every byte of the message will be NACKed in case the transmitter - keeps transmitting after the first byte was NACKed. - -``[,] rx-low-drive `` - Force a Low Drive condition at this bit position. If specifies - a specific CEC opcode then the bit position must be at least 18, - otherwise the opcode hasn't been received yet. This tests if the - transmitter can handle the Low Drive condition correctly and reports - the error correctly. Note that a Low Drive in the first 4 bits can also - be interpreted as an Arbitration Lost condition by the transmitter. - This is implementation dependent. - -``[,] rx-add-byte`` - Add a spurious 0x55 byte to the received CEC message, provided - the message was 15 bytes long or less. This is useful to test - the high-level protocol since spurious bytes should be ignored. - -``[,] rx-remove-byte`` - Remove the last byte from the received CEC message, provided it - was at least 2 bytes long. This is useful to test the high-level - protocol since messages that are too short should be ignored. - -``[,] rx-arb-lost `` - Generate a POLL message to trigger an Arbitration Lost condition. - This command is only allowed for ```` values of ``next`` or ``all``. - As soon as a start bit has been received the CEC adapter will switch - to transmit mode and it will transmit a POLL message. By default this is - 0x0f, but it can also be specified explicitly via the ```` argument. - - This command can be used to test the Arbitration Lost condition in - the remote CEC transmitter. Arbitration happens when two CEC adapters - start sending a message at the same time. In that case the initiator - with the most leading zeroes wins and the other transmitter has to - stop transmitting ('Arbitration Lost'). This is very hard to test, - except by using this error injection command. - - This does not work if the remote CEC transmitter has logical address - 0 ('TV') since that will always win. - -Transmit Messages ------------------ - -``tx-ignore-nack-until-eom`` - This setting changes the behavior of transmitting CEC messages. Normally - as soon as the receiver NACKs a byte the transmit will stop, but the - specification also allows that the full message is transmitted and only - at the end will the transmitter look at the ACK bit. This is not - recommended behavior since there is no point in keeping the CEC bus busy - for longer than is strictly needed. Especially given how slow the bus is. - - This setting can be used to test how well a receiver deals with - transmitters that ignore NACKs until the very end of the message. - -``[,] tx-no-eom`` - Don't set the EOM bit. Normally the last byte of the message has the EOM - (End-Of-Message) bit set. With this command the transmit will just stop - without ever sending an EOM. This can be used to test how a receiver - handles this case. Normally receivers have a time-out after which - they will go back to the Idle state. - -``[,] tx-early-eom`` - Set the EOM bit one byte too soon. This obviously only works for messages - of two bytes or more. The EOM bit will be set for the second-to-last byte - and not for the final byte. The receiver should ignore the last byte in - this case. Since the resulting message is likely to be too short for this - same reason the whole message is typically ignored. The receiver should be - in Idle state after the last byte was transmitted. - -``[,] tx-add-bytes `` - Append ```` (1-255) spurious bytes to the message. The extra bytes - have the value of the byte position in the message. So if you transmit a - two byte message (e.g. a Get CEC Version message) and add 2 bytes, then - the full message received by the remote CEC adapter is - ``0x40 0x9f 0x02 0x03``. - - This command can be used to test buffer overflows in the receiver. E.g. - what does it do when it receives more than the maximum message size of 16 - bytes. - -``[,] tx-remove-byte`` - Drop the last byte from the message, provided the message is at least - two bytes long. The receiver should ignore messages that are too short. - -``[,] tx-short-bit `` - Make this bit period shorter than allowed. The bit position cannot be - an Ack bit. If specifies a specific CEC opcode then the bit position - must be at least 18, otherwise the opcode hasn't been received yet. - Normally the period of a data bit is between 2.05 and 2.75 milliseconds. - With this command the period of this bit is 1.8 milliseconds, this is - done by reducing the time the CEC bus is high. This bit period is less - than is allowed and the receiver should respond with a Low Drive - condition. - - This command is ignored for 0 bits in bit positions 0 to 3. This is - because the receiver also looks for an Arbitration Lost condition in - those first four bits and it is undefined what will happen if it - sees a too-short 0 bit. - -``[,] tx-long-bit `` - Make this bit period longer than is valid. The bit position cannot be - an Ack bit. If specifies a specific CEC opcode then the bit position - must be at least 18, otherwise the opcode hasn't been received yet. - Normally the period of a data bit is between 2.05 and 2.75 milliseconds. - With this command the period of this bit is 2.9 milliseconds, this is - done by increasing the time the CEC bus is high. - - Even though this bit period is longer than is valid it is undefined what - a receiver will do. It might just accept it, or it might time out and - return to Idle state. Unfortunately the CEC specification is silent about - this. - - This command is ignored for 0 bits in bit positions 0 to 3. This is - because the receiver also looks for an Arbitration Lost condition in - those first four bits and it is undefined what will happen if it - sees a too-long 0 bit. - -``[,] tx-short-start`` - Make this start bit period shorter than allowed. Normally the period of - a start bit is between 4.3 and 4.7 milliseconds. With this command the - period of the start bit is 4.1 milliseconds, this is done by reducing - the time the CEC bus is high. This start bit period is less than is - allowed and the receiver should return to Idle state when this is detected. - -``[,] tx-long-start`` - Make this start bit period longer than is valid. Normally the period of - a start bit is between 4.3 and 4.7 milliseconds. With this command the - period of the start bit is 5 milliseconds, this is done by increasing - the time the CEC bus is high. This start bit period is more than is - valid and the receiver should return to Idle state when this is detected. - - Even though this start bit period is longer than is valid it is undefined - what a receiver will do. It might just accept it, or it might time out and - return to Idle state. Unfortunately the CEC specification is silent about - this. - -``[,] tx-last-bit `` - Just stop transmitting after this bit. If specifies a specific CEC - opcode then the bit position must be at least 18, otherwise the opcode - hasn't been received yet. This command can be used to test how the receiver - reacts when a message just suddenly stops. It should time out and go back - to Idle state. - -``[,] tx-low-drive `` - Force a Low Drive condition at this bit position. If specifies a - specific CEC opcode then the bit position must be at least 18, otherwise - the opcode hasn't been received yet. This can be used to test how the - receiver handles Low Drive conditions. Note that if this happens at bit - positions 0-3 the receiver can interpret this as an Arbitration Lost - condition. This is implementation dependent. - -Custom Pulses -------------- - -``tx-custom-low-usecs `` - This defines the duration in microseconds that the custom pulse pulls - the CEC line low. The default is 1000 microseconds. - -``tx-custom-high-usecs `` - This defines the duration in microseconds that the custom pulse keeps the - CEC line high (unless another CEC adapter pulls it low in that time). - The default is 1000 microseconds. The total period of the custom pulse is - ``tx-custom-low-usecs + tx-custom-high-usecs``. - -``[,] tx-custom-bit `` - Send the custom bit instead of a regular data bit. The bit position cannot - be an Ack bit. If specifies a specific CEC opcode then the bit - position must be at least 18, otherwise the opcode hasn't been received yet. - -``[,] tx-custom-start`` - Send the custom bit instead of a regular start bit. - -``tx-custom-pulse`` - Transmit a single custom pulse as soon as the CEC bus is idle. diff --git a/Documentation/media/uapi/dvb/audio-bilingual-channel-select.rst b/Documentation/media/uapi/dvb/audio-bilingual-channel-select.rst deleted file mode 100644 index ee2ee74dafa3..000000000000 --- a/Documentation/media/uapi/dvb/audio-bilingual-channel-select.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_BILINGUAL_CHANNEL_SELECT: - -============================== -AUDIO_BILINGUAL_CHANNEL_SELECT -============================== - -Name ----- - -AUDIO_BILINGUAL_CHANNEL_SELECT - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_BILINGUAL_CHANNEL_SELECT, struct *audio_channel_select) - :name: AUDIO_BILINGUAL_CHANNEL_SELECT - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - audio_channel_select_t ch - - - Select the output format of the audio (mono left/right, stereo). - - -Description ------------ - -This ioctl is obsolete. Do not use in new drivers. It has been replaced -by the V4L2 ``V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK`` control -for MPEG decoders controlled through V4L2. - -This ioctl call asks the Audio Device to select the requested channel -for bilingual streams if possible. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-channel-select.rst b/Documentation/media/uapi/dvb/audio-channel-select.rst deleted file mode 100644 index ebb2f121c4c8..000000000000 --- a/Documentation/media/uapi/dvb/audio-channel-select.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_CHANNEL_SELECT: - -==================== -AUDIO_CHANNEL_SELECT -==================== - -Name ----- - -AUDIO_CHANNEL_SELECT - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_CHANNEL_SELECT, struct *audio_channel_select) - :name: AUDIO_CHANNEL_SELECT - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - audio_channel_select_t ch - - - Select the output format of the audio (mono left/right, stereo). - - -Description ------------ - -This ioctl is for Digital TV devices only. To control a V4L2 decoder use the -V4L2 ``V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK`` control instead. - -This ioctl call asks the Audio Device to select the requested channel if -possible. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-clear-buffer.rst b/Documentation/media/uapi/dvb/audio-clear-buffer.rst deleted file mode 100644 index c5b62cde18c8..000000000000 --- a/Documentation/media/uapi/dvb/audio-clear-buffer.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_CLEAR_BUFFER: - -================== -AUDIO_CLEAR_BUFFER -================== - -Name ----- - -AUDIO_CLEAR_BUFFER - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_CLEAR_BUFFER) - :name: AUDIO_CLEAR_BUFFER - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - -Description ------------ - -This ioctl call asks the Audio Device to clear all software and hardware -buffers of the audio decoder device. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-continue.rst b/Documentation/media/uapi/dvb/audio-continue.rst deleted file mode 100644 index 6bdc99e39e20..000000000000 --- a/Documentation/media/uapi/dvb/audio-continue.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_CONTINUE: - -============== -AUDIO_CONTINUE -============== - -Name ----- - -AUDIO_CONTINUE - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_CONTINUE) - :name: AUDIO_CONTINUE - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - -Description ------------ - -This ioctl restarts the decoding and playing process previously paused -with AUDIO_PAUSE command. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-fclose.rst b/Documentation/media/uapi/dvb/audio-fclose.rst deleted file mode 100644 index 1e4ad7a0325d..000000000000 --- a/Documentation/media/uapi/dvb/audio-fclose.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _audio_fclose: - -======================== -Digital TV audio close() -======================== - -Name ----- - -Digital TV audio close() - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int close(int fd) - :name: dvb-audio-close - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - -Description ------------ - -This system call closes a previously opened audio device. - - -Return Value ------------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``EBADF`` - - - fd is not a valid open file descriptor. diff --git a/Documentation/media/uapi/dvb/audio-fopen.rst b/Documentation/media/uapi/dvb/audio-fopen.rst deleted file mode 100644 index 2cf4d83661f4..000000000000 --- a/Documentation/media/uapi/dvb/audio-fopen.rst +++ /dev/null @@ -1,115 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _audio_fopen: - -======================= -Digital TV audio open() -======================= - -Name ----- - -Digital TV audio open() - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int open(const char *deviceName, int flags) - :name: dvb-audio-open - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - const char \*deviceName - - - Name of specific audio device. - - - .. row 2 - - - int flags - - - A bit-wise OR of the following flags: - - - .. row 3 - - - - - O_RDONLY read-only access - - - .. row 4 - - - - - O_RDWR read/write access - - - .. row 5 - - - - - O_NONBLOCK open in non-blocking mode - - - .. row 6 - - - - - (blocking mode is the default) - - -Description ------------ - -This system call opens a named audio device (e.g. -/dev/dvb/adapter0/audio0) for subsequent use. When an open() call has -succeeded, the device will be ready for use. The significance of -blocking or non-blocking mode is described in the documentation for -functions where there is a difference. It does not affect the semantics -of the open() call itself. A device opened in blocking mode can later be -put into non-blocking mode (and vice versa) using the F_SETFL command -of the fcntl system call. This is a standard system call, documented in -the Linux manual page for fcntl. Only one user can open the Audio Device -in O_RDWR mode. All other attempts to open the device in this mode will -fail, and an error code will be returned. If the Audio Device is opened -in O_RDONLY mode, the only ioctl call that can be used is -AUDIO_GET_STATUS. All other call will return with an error code. - - -Return Value ------------- - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``ENODEV`` - - - Device driver not loaded/available. - - - .. row 2 - - - ``EBUSY`` - - - Device or resource busy. - - - .. row 3 - - - ``EINVAL`` - - - Invalid argument. diff --git a/Documentation/media/uapi/dvb/audio-fwrite.rst b/Documentation/media/uapi/dvb/audio-fwrite.rst deleted file mode 100644 index 6dc6bf6cbbc7..000000000000 --- a/Documentation/media/uapi/dvb/audio-fwrite.rst +++ /dev/null @@ -1,91 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _audio_fwrite: - -========================= -Digital TV audio write() -========================= - -Name ----- - -Digital TV audio write() - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: size_t write(int fd, const void *buf, size_t count) - :name: dvb-audio-write - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - void \*buf - - - Pointer to the buffer containing the PES data. - - - .. row 3 - - - size_t count - - - Size of buf. - - -Description ------------ - -This system call can only be used if AUDIO_SOURCE_MEMORY is selected -in the ioctl call AUDIO_SELECT_SOURCE. The data provided shall be in -PES format. If O_NONBLOCK is not specified the function will block -until buffer space is available. The amount of data to be transferred is -implied by count. - - -Return Value ------------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``EPERM`` - - - Mode AUDIO_SOURCE_MEMORY not selected. - - - .. row 2 - - - ``ENOMEM`` - - - Attempted to write more data than the internal buffer can hold. - - - .. row 3 - - - ``EBADF`` - - - fd is not a valid open file descriptor. diff --git a/Documentation/media/uapi/dvb/audio-get-capabilities.rst b/Documentation/media/uapi/dvb/audio-get-capabilities.rst deleted file mode 100644 index 4f1ec47e8ac2..000000000000 --- a/Documentation/media/uapi/dvb/audio-get-capabilities.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_GET_CAPABILITIES: - -====================== -AUDIO_GET_CAPABILITIES -====================== - -Name ----- - -AUDIO_GET_CAPABILITIES - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_GET_CAPABILITIES, unsigned int *cap) - :name: AUDIO_GET_CAPABILITIES - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - unsigned int \*cap - - - Returns a bit array of supported sound formats. - - -Description ------------ - -This ioctl call asks the Audio Device to tell us about the decoding -capabilities of the audio hardware. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-get-status.rst b/Documentation/media/uapi/dvb/audio-get-status.rst deleted file mode 100644 index 30e4dd7fce6d..000000000000 --- a/Documentation/media/uapi/dvb/audio-get-status.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_GET_STATUS: - -================ -AUDIO_GET_STATUS -================ - -Name ----- - -AUDIO_GET_STATUS - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_GET_STATUS, struct audio_status *status) - :name: AUDIO_GET_STATUS - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - struct audio_status \*status - - - Returns the current state of Audio Device. - - -Description ------------ - -This ioctl call asks the Audio Device to return the current state of the -Audio Device. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-pause.rst b/Documentation/media/uapi/dvb/audio-pause.rst deleted file mode 100644 index 4567ecd9e0a3..000000000000 --- a/Documentation/media/uapi/dvb/audio-pause.rst +++ /dev/null @@ -1,57 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_PAUSE: - -=========== -AUDIO_PAUSE -=========== - -Name ----- - -AUDIO_PAUSE - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_PAUSE) - :name: AUDIO_PAUSE - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - -Description ------------ - -This ioctl call suspends the audio stream being played. Decoding and -playing are paused. It is then possible to restart again decoding and -playing process of the audio stream using AUDIO_CONTINUE command. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-play.rst b/Documentation/media/uapi/dvb/audio-play.rst deleted file mode 100644 index 17acd4c411b8..000000000000 --- a/Documentation/media/uapi/dvb/audio-play.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_PLAY: - -========== -AUDIO_PLAY -========== - -Name ----- - -AUDIO_PLAY - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_PLAY) - :name: AUDIO_PLAY - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - -Description ------------ - -This ioctl call asks the Audio Device to start playing an audio stream -from the selected source. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-select-source.rst b/Documentation/media/uapi/dvb/audio-select-source.rst deleted file mode 100644 index c5ed6243b11c..000000000000 --- a/Documentation/media/uapi/dvb/audio-select-source.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_SELECT_SOURCE: - -=================== -AUDIO_SELECT_SOURCE -=================== - -Name ----- - -AUDIO_SELECT_SOURCE - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_SELECT_SOURCE, struct audio_stream_source *source) - :name: AUDIO_SELECT_SOURCE - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - audio_stream_source_t source - - - Indicates the source that shall be used for the Audio stream. - - -Description ------------ - -This ioctl call informs the audio device which source shall be used for -the input data. The possible sources are demux or memory. If -AUDIO_SOURCE_MEMORY is selected, the data is fed to the Audio Device -through the write command. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-set-av-sync.rst b/Documentation/media/uapi/dvb/audio-set-av-sync.rst deleted file mode 100644 index c116d105fdea..000000000000 --- a/Documentation/media/uapi/dvb/audio-set-av-sync.rst +++ /dev/null @@ -1,67 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_SET_AV_SYNC: - -================= -AUDIO_SET_AV_SYNC -================= - -Name ----- - -AUDIO_SET_AV_SYNC - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_SET_AV_SYNC, boolean state) - :name: AUDIO_SET_AV_SYNC - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - boolean state - - - Tells the Digital TV subsystem if A/V synchronization shall be ON or OFF. - - TRUE: AV-sync ON - - FALSE: AV-sync OFF - - -Description ------------ - -This ioctl call asks the Audio Device to turn ON or OFF A/V -synchronization. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-set-bypass-mode.rst b/Documentation/media/uapi/dvb/audio-set-bypass-mode.rst deleted file mode 100644 index d68f05d48d12..000000000000 --- a/Documentation/media/uapi/dvb/audio-set-bypass-mode.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_SET_BYPASS_MODE: - -===================== -AUDIO_SET_BYPASS_MODE -===================== - -Name ----- - -AUDIO_SET_BYPASS_MODE - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_SET_BYPASS_MODE, boolean mode) - :name: AUDIO_SET_BYPASS_MODE - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - boolean mode - - - Enables or disables the decoding of the current Audio stream in - the Digital TV subsystem. - - TRUE: Bypass is disabled - - FALSE: Bypass is enabled - - -Description ------------ - -This ioctl call asks the Audio Device to bypass the Audio decoder and -forward the stream without decoding. This mode shall be used if streams -that can’t be handled by the Digital TV system shall be decoded. Dolby -DigitalTM streams are automatically forwarded by the Digital TV subsystem if -the hardware can handle it. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-set-id.rst b/Documentation/media/uapi/dvb/audio-set-id.rst deleted file mode 100644 index aeb6ace6cd1e..000000000000 --- a/Documentation/media/uapi/dvb/audio-set-id.rst +++ /dev/null @@ -1,67 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_SET_ID: - -============ -AUDIO_SET_ID -============ - -Name ----- - -AUDIO_SET_ID - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_SET_ID, int id) - :name: AUDIO_SET_ID - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - int id - - - audio sub-stream id - - -Description ------------ - -This ioctl selects which sub-stream is to be decoded if a program or -system stream is sent to the video device. If no audio stream type is -set the id has to be in [0xC0,0xDF] for MPEG sound, in [0x80,0x87] for -AC3 and in [0xA0,0xA7] for LPCM. More specifications may follow for -other stream types. If the stream type is set the id just specifies the -substream id of the audio stream and only the first 5 bits are -recognized. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-set-mixer.rst b/Documentation/media/uapi/dvb/audio-set-mixer.rst deleted file mode 100644 index 60781aa88202..000000000000 --- a/Documentation/media/uapi/dvb/audio-set-mixer.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_SET_MIXER: - -=============== -AUDIO_SET_MIXER -=============== - -Name ----- - -AUDIO_SET_MIXER - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_SET_MIXER, struct audio_mixer *mix) - :name: AUDIO_SET_MIXER - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - audio_mixer_t \*mix - - - mixer settings. - - -Description ------------ - -This ioctl lets you adjust the mixer settings of the audio decoder. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-set-mute.rst b/Documentation/media/uapi/dvb/audio-set-mute.rst deleted file mode 100644 index 4449f225e48c..000000000000 --- a/Documentation/media/uapi/dvb/audio-set-mute.rst +++ /dev/null @@ -1,71 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_SET_MUTE: - -============== -AUDIO_SET_MUTE -============== - -Name ----- - -AUDIO_SET_MUTE - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_SET_MUTE, boolean state) - :name: AUDIO_SET_MUTE - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - boolean state - - - Indicates if audio device shall mute or not. - - TRUE: Audio Mute - - FALSE: Audio Un-mute - - -Description ------------ - -This ioctl is for Digital TV devices only. To control a V4L2 decoder use the -V4L2 :ref:`VIDIOC_DECODER_CMD` with the -``V4L2_DEC_CMD_START_MUTE_AUDIO`` flag instead. - -This ioctl call asks the audio device to mute the stream that is -currently being played. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-set-streamtype.rst b/Documentation/media/uapi/dvb/audio-set-streamtype.rst deleted file mode 100644 index d20c34fc7128..000000000000 --- a/Documentation/media/uapi/dvb/audio-set-streamtype.rst +++ /dev/null @@ -1,77 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_SET_STREAMTYPE: - -==================== -AUDIO_SET_STREAMTYPE -==================== - -Name ----- - -AUDIO_SET_STREAMTYPE - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(fd, AUDIO_SET_STREAMTYPE, int type) - :name: AUDIO_SET_STREAMTYPE - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - int type - - - stream type - - -Description ------------ - -This ioctl tells the driver which kind of audio stream to expect. This -is useful if the stream offers several audio sub-streams like LPCM and -AC3. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``EINVAL`` - - - type is not a valid or supported stream type. diff --git a/Documentation/media/uapi/dvb/audio-stop.rst b/Documentation/media/uapi/dvb/audio-stop.rst deleted file mode 100644 index 1bba2e50c364..000000000000 --- a/Documentation/media/uapi/dvb/audio-stop.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_STOP: - -========== -AUDIO_STOP -========== - -Name ----- - -AUDIO_STOP - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_STOP) - :name: AUDIO_STOP - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - -Description ------------ - -This ioctl call asks the Audio Device to stop playing the current -stream. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/audio.rst b/Documentation/media/uapi/dvb/audio.rst deleted file mode 100644 index ebc18fca76a4..000000000000 --- a/Documentation/media/uapi/dvb/audio.rst +++ /dev/null @@ -1,34 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dvb_audio: - -####################### -Digital TV Audio Device -####################### - -The Digital TV audio device controls the MPEG2 audio decoder of the Digital -TV hardware. It can be accessed through ``/dev/dvb/adapter?/audio?``. Data -types and and ioctl definitions can be accessed by including -``linux/dvb/audio.h`` in your application. - -Please note that some Digital TV cards don’t have their own MPEG decoder, which -results in the omission of the audio and video device. - -These ioctls were also used by V4L2 to control MPEG decoders implemented -in V4L2. The use of these ioctls for that purpose has been made obsolete -and proper V4L2 ioctls or controls have been created to replace that -functionality. - - -.. toctree:: - :maxdepth: 1 - - audio_data_types - audio_function_calls diff --git a/Documentation/media/uapi/dvb/audio_data_types.rst b/Documentation/media/uapi/dvb/audio_data_types.rst deleted file mode 100644 index 5b032fe13b9d..000000000000 --- a/Documentation/media/uapi/dvb/audio_data_types.rst +++ /dev/null @@ -1,123 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _audio_data_types: - -**************** -Audio Data Types -**************** - -This section describes the structures, data types and defines used when -talking to the audio device. - -.. c:type:: audio_stream_source - -The audio stream source is set through the AUDIO_SELECT_SOURCE call -and can take the following values, depending on whether we are replaying -from an internal (demux) or external (user write) source. - - -.. code-block:: c - - typedef enum { - AUDIO_SOURCE_DEMUX, - AUDIO_SOURCE_MEMORY - } audio_stream_source_t; - -AUDIO_SOURCE_DEMUX selects the demultiplexer (fed either by the -frontend or the DVR device) as the source of the video stream. If -AUDIO_SOURCE_MEMORY is selected the stream comes from the application -through the ``write()`` system call. - - -.. c:type:: audio_play_state - -The following values can be returned by the AUDIO_GET_STATUS call -representing the state of audio playback. - - -.. code-block:: c - - typedef enum { - AUDIO_STOPPED, - AUDIO_PLAYING, - AUDIO_PAUSED - } audio_play_state_t; - - -.. c:type:: audio_channel_select - -The audio channel selected via AUDIO_CHANNEL_SELECT is determined by -the following values. - - -.. code-block:: c - - typedef enum { - AUDIO_STEREO, - AUDIO_MONO_LEFT, - AUDIO_MONO_RIGHT, - AUDIO_MONO, - AUDIO_STEREO_SWAPPED - } audio_channel_select_t; - - -.. c:type:: audio_status - -The AUDIO_GET_STATUS call returns the following structure informing -about various states of the playback operation. - - -.. code-block:: c - - typedef struct audio_status { - boolean AV_sync_state; - boolean mute_state; - audio_play_state_t play_state; - audio_stream_source_t stream_source; - audio_channel_select_t channel_select; - boolean bypass_mode; - audio_mixer_t mixer_state; - } audio_status_t; - - -.. c:type:: audio_mixer - -The following structure is used by the AUDIO_SET_MIXER call to set the -audio volume. - - -.. code-block:: c - - typedef struct audio_mixer { - unsigned int volume_left; - unsigned int volume_right; - } audio_mixer_t; - - -.. _audio_encodings: - -audio encodings -=============== - -A call to AUDIO_GET_CAPABILITIES returns an unsigned integer with the -following bits set according to the hardwares capabilities. - - -.. code-block:: c - - #define AUDIO_CAP_DTS 1 - #define AUDIO_CAP_LPCM 2 - #define AUDIO_CAP_MP1 4 - #define AUDIO_CAP_MP2 8 - #define AUDIO_CAP_MP3 16 - #define AUDIO_CAP_AAC 32 - #define AUDIO_CAP_OGG 64 - #define AUDIO_CAP_SDDS 128 - #define AUDIO_CAP_AC3 256 diff --git a/Documentation/media/uapi/dvb/audio_function_calls.rst b/Documentation/media/uapi/dvb/audio_function_calls.rst deleted file mode 100644 index 5478e78b085e..000000000000 --- a/Documentation/media/uapi/dvb/audio_function_calls.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _audio_function_calls: - -******************** -Audio Function Calls -******************** - -.. toctree:: - :maxdepth: 1 - - audio-fopen - audio-fclose - audio-fwrite - audio-stop - audio-play - audio-pause - audio-continue - audio-select-source - audio-set-mute - audio-set-av-sync - audio-set-bypass-mode - audio-channel-select - audio-bilingual-channel-select - audio-get-status - audio-get-capabilities - audio-clear-buffer - audio-set-id - audio-set-mixer - audio-set-streamtype diff --git a/Documentation/media/uapi/dvb/ca-fclose.rst b/Documentation/media/uapi/dvb/ca-fclose.rst deleted file mode 100644 index e273444ccc67..000000000000 --- a/Documentation/media/uapi/dvb/ca-fclose.rst +++ /dev/null @@ -1,50 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _ca_fclose: - -===================== -Digital TV CA close() -===================== - -Name ----- - -Digital TV CA close() - - -Synopsis --------- - -.. c:function:: int close(int fd) - :name: dvb-ca-close - - -Arguments ---------- - -``fd`` - File descriptor returned by a previous call to :c:func:`open() `. - -Description ------------ - -This system call closes a previously opened CA device. - - -Return Value ------------- - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/ca-fopen.rst b/Documentation/media/uapi/dvb/ca-fopen.rst deleted file mode 100644 index e11ebeae5693..000000000000 --- a/Documentation/media/uapi/dvb/ca-fopen.rst +++ /dev/null @@ -1,84 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _ca_fopen: - -==================== -Digital TV CA open() -==================== - -Name ----- - -Digital TV CA open() - - -Synopsis --------- - -.. c:function:: int open(const char *name, int flags) - :name: dvb-ca-open - - -Arguments ---------- - -``name`` - Name of specific Digital TV CA device. - -``flags`` - A bit-wise OR of the following flags: - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 16 - - - - ``O_RDONLY`` - - read-only access - - - - ``O_RDWR`` - - read/write access - - - - ``O_NONBLOCK`` - - open in non-blocking mode - (blocking mode is the default) - - -Description ------------ - -This system call opens a named ca device (e.g. ``/dev/dvb/adapter?/ca?``) -for subsequent use. - -When an ``open()`` call has succeeded, the device will be ready for use. The -significance of blocking or non-blocking mode is described in the -documentation for functions where there is a difference. It does not -affect the semantics of the ``open()`` call itself. A device opened in -blocking mode can later be put into non-blocking mode (and vice versa) -using the ``F_SETFL`` command of the ``fcntl`` system call. This is a -standard system call, documented in the Linux manual page for fcntl. -Only one user can open the CA Device in ``O_RDWR`` mode. All other -attempts to open the device in this mode will fail, and an error code -will be returned. - - -Return Value ------------- - - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/ca-get-cap.rst b/Documentation/media/uapi/dvb/ca-get-cap.rst deleted file mode 100644 index 9e4fb5186373..000000000000 --- a/Documentation/media/uapi/dvb/ca-get-cap.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _CA_GET_CAP: - -========== -CA_GET_CAP -========== - -Name ----- - -CA_GET_CAP - - -Synopsis --------- - -.. c:function:: int ioctl(fd, CA_GET_CAP, struct ca_caps *caps) - :name: CA_GET_CAP - - -Arguments ---------- - -``fd`` - File descriptor returned by a previous call to :c:func:`open() `. - -``caps`` - Pointer to struct :c:type:`ca_caps`. - -Description ------------ - -Queries the Kernel for information about the available CA and descrambler -slots, and their types. - -Return Value ------------- - -On success 0 is returned and :c:type:`ca_caps` is filled. - -On error, -1 is returned and the ``errno`` variable is set -appropriately. - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/ca-get-descr-info.rst b/Documentation/media/uapi/dvb/ca-get-descr-info.rst deleted file mode 100644 index 80ef43a339df..000000000000 --- a/Documentation/media/uapi/dvb/ca-get-descr-info.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _CA_GET_DESCR_INFO: - -================= -CA_GET_DESCR_INFO -================= - -Name ----- - -CA_GET_DESCR_INFO - - -Synopsis --------- - -.. c:function:: int ioctl(fd, CA_GET_DESCR_INFO, struct ca_descr_info *desc) - :name: CA_GET_DESCR_INFO - -Arguments ---------- - -``fd`` - File descriptor returned by a previous call to :c:func:`open() `. - -``desc`` - Pointer to struct :c:type:`ca_descr_info`. - -Description ------------ - -Returns information about all descrambler slots. - -Return Value ------------- - -On success 0 is returned, and :c:type:`ca_descr_info` is filled. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/ca-get-msg.rst b/Documentation/media/uapi/dvb/ca-get-msg.rst deleted file mode 100644 index bcb7955a0ddc..000000000000 --- a/Documentation/media/uapi/dvb/ca-get-msg.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _CA_GET_MSG: - -========== -CA_GET_MSG -========== - -Name ----- - -CA_GET_MSG - - -Synopsis --------- - -.. c:function:: int ioctl(fd, CA_GET_MSG, struct ca_msg *msg) - :name: CA_GET_MSG - - -Arguments ---------- - -``fd`` - File descriptor returned by a previous call to :c:func:`open() `. - -``msg`` - Pointer to struct :c:type:`ca_msg`. - -Description ------------ - -Receives a message via a CI CA module. - -.. note:: - - Please notice that, on most drivers, this is done by reading from - the /dev/adapter?/ca? device node. - - -Return Value ------------- - - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/ca-get-slot-info.rst b/Documentation/media/uapi/dvb/ca-get-slot-info.rst deleted file mode 100644 index 1ea5c497f2ea..000000000000 --- a/Documentation/media/uapi/dvb/ca-get-slot-info.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _CA_GET_SLOT_INFO: - -================ -CA_GET_SLOT_INFO -================ - -Name ----- - -CA_GET_SLOT_INFO - - -Synopsis --------- - -.. c:function:: int ioctl(fd, CA_GET_SLOT_INFO, struct ca_slot_info *info) - :name: CA_GET_SLOT_INFO - - -Arguments ---------- - -``fd`` - File descriptor returned by a previous call to :c:func:`open() `. - -``info`` - Pointer to struct :c:type:`ca_slot_info`. - -Description ------------ - -Returns information about a CA slot identified by -:c:type:`ca_slot_info`.slot_num. - - -Return Value ------------- - -On success 0 is returned, and :c:type:`ca_slot_info` is filled. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 16 - - - - ``ENODEV`` - - the slot is not available. - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/ca-reset.rst b/Documentation/media/uapi/dvb/ca-reset.rst deleted file mode 100644 index 29fda19984be..000000000000 --- a/Documentation/media/uapi/dvb/ca-reset.rst +++ /dev/null @@ -1,51 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _CA_RESET: - -======== -CA_RESET -======== - -Name ----- - -CA_RESET - - -Synopsis --------- - -.. c:function:: int ioctl(fd, CA_RESET) - :name: CA_RESET - - -Arguments ---------- - -``fd`` - File descriptor returned by a previous call to :c:func:`open() `. - -Description ------------ - -Puts the Conditional Access hardware on its initial state. It should -be called before start using the CA hardware. - - -Return Value ------------- - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/ca-send-msg.rst b/Documentation/media/uapi/dvb/ca-send-msg.rst deleted file mode 100644 index 5a3c4e8120c4..000000000000 --- a/Documentation/media/uapi/dvb/ca-send-msg.rst +++ /dev/null @@ -1,58 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _CA_SEND_MSG: - -=========== -CA_SEND_MSG -=========== - -Name ----- - -CA_SEND_MSG - - -Synopsis --------- - -.. c:function:: int ioctl(fd, CA_SEND_MSG, struct ca_msg *msg) - :name: CA_SEND_MSG - - -Arguments ---------- - -``fd`` - File descriptor returned by a previous call to :c:func:`open() `. - -``msg`` - Pointer to struct :c:type:`ca_msg`. - - -Description ------------ - -Sends a message via a CI CA module. - -.. note:: - - Please notice that, on most drivers, this is done by writing - to the /dev/adapter?/ca? device node. - -Return Value ------------- - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/ca-set-descr.rst b/Documentation/media/uapi/dvb/ca-set-descr.rst deleted file mode 100644 index d36464ba2317..000000000000 --- a/Documentation/media/uapi/dvb/ca-set-descr.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _CA_SET_DESCR: - -============ -CA_SET_DESCR -============ - -Name ----- - -CA_SET_DESCR - - -Synopsis --------- - -.. c:function:: int ioctl(fd, CA_SET_DESCR, struct ca_descr *desc) - :name: CA_SET_DESCR - - -Arguments ---------- - -``fd`` - File descriptor returned by a previous call to :c:func:`open() `. - -``msg`` - Pointer to struct :c:type:`ca_descr`. - -Description ------------ - -CA_SET_DESCR is used for feeding descrambler CA slots with descrambling -keys (referred as control words). - -Return Value ------------- - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/ca.rst b/Documentation/media/uapi/dvb/ca.rst deleted file mode 100644 index c6ee624b1234..000000000000 --- a/Documentation/media/uapi/dvb/ca.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dvb_ca: - -#################### -Digital TV CA Device -#################### - -The Digital TV CA device controls the conditional access hardware. It -can be accessed through ``/dev/dvb/adapter?/ca?``. Data types and and ioctl -definitions can be accessed by including ``linux/dvb/ca.h`` in your -application. - -.. note:: - - There are three ioctls at this API that aren't documented: - :ref:`CA_GET_MSG`, :ref:`CA_SEND_MSG` and :ref:`CA_SET_DESCR`. - Documentation for them are welcome. - -.. toctree:: - :maxdepth: 1 - - ca_data_types - ca_function_calls - ca_high_level diff --git a/Documentation/media/uapi/dvb/ca_data_types.rst b/Documentation/media/uapi/dvb/ca_data_types.rst deleted file mode 100644 index 834c8ab4c300..000000000000 --- a/Documentation/media/uapi/dvb/ca_data_types.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _ca_data_types: - -************* -CA Data Types -************* - -.. kernel-doc:: include/uapi/linux/dvb/ca.h diff --git a/Documentation/media/uapi/dvb/ca_function_calls.rst b/Documentation/media/uapi/dvb/ca_function_calls.rst deleted file mode 100644 index 6985bebd0661..000000000000 --- a/Documentation/media/uapi/dvb/ca_function_calls.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _ca_function_calls: - -***************** -CA Function Calls -***************** - -.. toctree:: - :maxdepth: 1 - - ca-fopen - ca-fclose - ca-reset - ca-get-cap - ca-get-slot-info - ca-get-descr-info - ca-get-msg - ca-send-msg - ca-set-descr diff --git a/Documentation/media/uapi/dvb/ca_high_level.rst b/Documentation/media/uapi/dvb/ca_high_level.rst deleted file mode 100644 index a73f3691c31f..000000000000 --- a/Documentation/media/uapi/dvb/ca_high_level.rst +++ /dev/null @@ -1,157 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -The High level CI API -===================== - -.. note:: - - This documentation is outdated. - -This document describes the high level CI API as in accordance to the -Linux DVB API. - - -With the High Level CI approach any new card with almost any random -architecture can be implemented with this style, the definitions -inside the switch statement can be easily adapted for any card, thereby -eliminating the need for any additional ioctls. - -The disadvantage is that the driver/hardware has to manage the rest. For -the application programmer it would be as simple as sending/receiving an -array to/from the CI ioctls as defined in the Linux DVB API. No changes -have been made in the API to accommodate this feature. - - -Why the need for another CI interface? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This is one of the most commonly asked question. Well a nice question. -Strictly speaking this is not a new interface. - -The CI interface is defined in the DVB API in ca.h as: - -.. code-block:: c - - typedef struct ca_slot_info { - int num; /* slot number */ - - int type; /* CA interface this slot supports */ - #define CA_CI 1 /* CI high level interface */ - #define CA_CI_LINK 2 /* CI link layer level interface */ - #define CA_CI_PHYS 4 /* CI physical layer level interface */ - #define CA_DESCR 8 /* built-in descrambler */ - #define CA_SC 128 /* simple smart card interface */ - - unsigned int flags; - #define CA_CI_MODULE_PRESENT 1 /* module (or card) inserted */ - #define CA_CI_MODULE_READY 2 - } ca_slot_info_t; - -This CI interface follows the CI high level interface, which is not -implemented by most applications. Hence this area is revisited. - -This CI interface is quite different in the case that it tries to -accommodate all other CI based devices, that fall into the other categories. - -This means that this CI interface handles the EN50221 style tags in the -Application layer only and no session management is taken care of by the -application. The driver/hardware will take care of all that. - -This interface is purely an EN50221 interface exchanging APDU's. This -means that no session management, link layer or a transport layer do -exist in this case in the application to driver communication. It is -as simple as that. The driver/hardware has to take care of that. - -With this High Level CI interface, the interface can be defined with the -regular ioctls. - -All these ioctls are also valid for the High level CI interface - -#define CA_RESET _IO('o', 128) -#define CA_GET_CAP _IOR('o', 129, ca_caps_t) -#define CA_GET_SLOT_INFO _IOR('o', 130, ca_slot_info_t) -#define CA_GET_DESCR_INFO _IOR('o', 131, ca_descr_info_t) -#define CA_GET_MSG _IOR('o', 132, ca_msg_t) -#define CA_SEND_MSG _IOW('o', 133, ca_msg_t) -#define CA_SET_DESCR _IOW('o', 134, ca_descr_t) - - -On querying the device, the device yields information thus: - -.. code-block:: none - - CA_GET_SLOT_INFO - ---------------------------- - Command = [info] - APP: Number=[1] - APP: Type=[1] - APP: flags=[1] - APP: CI High level interface - APP: CA/CI Module Present - - CA_GET_CAP - ---------------------------- - Command = [caps] - APP: Slots=[1] - APP: Type=[1] - APP: Descrambler keys=[16] - APP: Type=[1] - - CA_SEND_MSG - ---------------------------- - Descriptors(Program Level)=[ 09 06 06 04 05 50 ff f1] - Found CA descriptor @ program level - - (20) ES type=[2] ES pid=[201] ES length =[0 (0x0)] - (25) ES type=[4] ES pid=[301] ES length =[0 (0x0)] - ca_message length is 25 (0x19) bytes - EN50221 CA MSG=[ 9f 80 32 19 03 01 2d d1 f0 08 01 09 06 06 04 05 50 ff f1 02 e0 c9 00 00 04 e1 2d 00 00] - - -Not all ioctl's are implemented in the driver from the API, the other -features of the hardware that cannot be implemented by the API are achieved -using the CA_GET_MSG and CA_SEND_MSG ioctls. An EN50221 style wrapper is -used to exchange the data to maintain compatibility with other hardware. - -.. code-block:: c - - /* a message to/from a CI-CAM */ - typedef struct ca_msg { - unsigned int index; - unsigned int type; - unsigned int length; - unsigned char msg[256]; - } ca_msg_t; - - -The flow of data can be described thus, - -.. code-block:: none - - App (User) - ----- - parse - | - | - v - en50221 APDU (package) - -------------------------------------- - | | | High Level CI driver - | | | - | v | - | en50221 APDU (unpackage) | - | | | - | | | - | v | - | sanity checks | - | | | - | | | - | v | - | do (H/W dep) | - -------------------------------------- - | Hardware - | - v - -The High Level CI interface uses the EN50221 DVB standard, following a -standard ensures futureproofness. diff --git a/Documentation/media/uapi/dvb/demux.rst b/Documentation/media/uapi/dvb/demux.rst deleted file mode 100644 index d8c0ff4015fe..000000000000 --- a/Documentation/media/uapi/dvb/demux.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dvb_demux: - -####################### -Digital TV Demux Device -####################### - -The Digital TV demux device controls the MPEG-TS filters for the -digital TV. If the driver and hardware supports, those filters are -implemented at the hardware. Otherwise, the Kernel provides a software -emulation. - -It can be accessed through ``/dev/adapter?/demux?``. Data types and and -ioctl definitions can be accessed by including ``linux/dvb/dmx.h`` in -your application. - - -.. toctree:: - :maxdepth: 1 - - dmx_types - dmx_fcalls diff --git a/Documentation/media/uapi/dvb/dmx-add-pid.rst b/Documentation/media/uapi/dvb/dmx-add-pid.rst deleted file mode 100644 index f483268e4ede..000000000000 --- a/Documentation/media/uapi/dvb/dmx-add-pid.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _DMX_ADD_PID: - -=========== -DMX_ADD_PID -=========== - -Name ----- - -DMX_ADD_PID - - -Synopsis --------- - -.. c:function:: int ioctl(fd, DMX_ADD_PID, __u16 *pid) - :name: DMX_ADD_PID - - -Arguments ---------- - -``fd`` - File descriptor returned by :c:func:`open() `. - -``pid`` - PID number to be filtered. - - -Description ------------ - -This ioctl call allows to add multiple PIDs to a transport stream filter -previously set up with :ref:`DMX_SET_PES_FILTER` and output equal to -:c:type:`DMX_OUT_TSDEMUX_TAP `. - - -Return Value ------------- - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/dmx-expbuf.rst b/Documentation/media/uapi/dvb/dmx-expbuf.rst deleted file mode 100644 index d7f0658f3db3..000000000000 --- a/Documentation/media/uapi/dvb/dmx-expbuf.rst +++ /dev/null @@ -1,97 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _DMX_EXPBUF: - -**************** -ioctl DMX_EXPBUF -**************** - -Name -==== - -DMX_EXPBUF - Export a buffer as a DMABUF file descriptor. - -.. warning:: this API is still experimental - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, DMX_EXPBUF, struct dmx_exportbuffer *argp ) - :name: DMX_EXPBUF - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``argp`` - Pointer to struct :c:type:`dmx_exportbuffer`. - - -Description -=========== - -This ioctl is an extension to the memory mapping I/O method. -It can be used to export a buffer as a DMABUF file at any time after -buffers have been allocated with the :ref:`DMX_REQBUFS` ioctl. - -To export a buffer, applications fill struct :c:type:`dmx_exportbuffer`. -Applications must set the ``index`` field. Valid index numbers -range from zero to the number of buffers allocated with :ref:`DMX_REQBUFS` -(struct :c:type:`dmx_requestbuffers` ``count``) minus one. -Additional flags may be posted in the ``flags`` field. Refer to a manual -for open() for details. Currently only O_CLOEXEC, O_RDONLY, O_WRONLY, -and O_RDWR are supported. -All other fields must be set to zero. In the -case of multi-planar API, every plane is exported separately using -multiple :ref:`DMX_EXPBUF` calls. - -After calling :ref:`DMX_EXPBUF` the ``fd`` field will be set by a -driver, on success. This is a DMABUF file descriptor. The application may -pass it to other DMABUF-aware devices. It is recommended to close a DMABUF -file when it is no longer used to allow the associated memory to be reclaimed. - - -Examples -======== - - -.. code-block:: c - - int buffer_export(int v4lfd, enum dmx_buf_type bt, int index, int *dmafd) - { - struct dmx_exportbuffer expbuf; - - memset(&expbuf, 0, sizeof(expbuf)); - expbuf.type = bt; - expbuf.index = index; - if (ioctl(v4lfd, DMX_EXPBUF, &expbuf) == -1) { - perror("DMX_EXPBUF"); - return -1; - } - - *dmafd = expbuf.fd; - - return 0; - } - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. - -EINVAL - A queue is not in MMAP mode or DMABUF exporting is not supported or - ``flags`` or ``index`` fields are invalid. diff --git a/Documentation/media/uapi/dvb/dmx-fclose.rst b/Documentation/media/uapi/dvb/dmx-fclose.rst deleted file mode 100644 index 05ff32270274..000000000000 --- a/Documentation/media/uapi/dvb/dmx-fclose.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dmx_fclose: - -======================== -Digital TV demux close() -======================== - -Name ----- - -Digital TV demux close() - - -Synopsis --------- - -.. c:function:: int close(int fd) - :name: dvb-dmx-close - - -Arguments ---------- - -``fd`` - File descriptor returned by a previous call to - :c:func:`open() `. - -Description ------------ - -This system call deactivates and deallocates a filter that was -previously allocated via the :c:func:`open() ` call. - - -Return Value ------------- - -On success 0 is returned. - -On error, -1 is returned and the ``errno`` variable is set -appropriately. - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/dmx-fopen.rst b/Documentation/media/uapi/dvb/dmx-fopen.rst deleted file mode 100644 index 2700a2fad68b..000000000000 --- a/Documentation/media/uapi/dvb/dmx-fopen.rst +++ /dev/null @@ -1,98 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dmx_fopen: - -======================= -Digital TV demux open() -======================= - -Name ----- - -Digital TV demux open() - - -Synopsis --------- - -.. c:function:: int open(const char *deviceName, int flags) - :name: dvb-dmx-open - -Arguments ---------- - -``name`` - Name of specific Digital TV demux device. - -``flags`` - A bit-wise OR of the following flags: - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 16 - - - - - ``O_RDONLY`` - - read-only access - - - - - ``O_RDWR`` - - read/write access - - - - - ``O_NONBLOCK`` - - open in non-blocking mode - (blocking mode is the default) - - -Description ------------ - -This system call, used with a device name of ``/dev/dvb/adapter?/demux?``, -allocates a new filter and returns a handle which can be used for -subsequent control of that filter. This call has to be made for each -filter to be used, i.e. every returned file descriptor is a reference to -a single filter. ``/dev/dvb/adapter?/dvr?`` is a logical device to be used -for retrieving Transport Streams for digital video recording. When -reading from this device a transport stream containing the packets from -all PES filters set in the corresponding demux device -(``/dev/dvb/adapter?/demux?``) having the output set to ``DMX_OUT_TS_TAP``. -A recorded Transport Stream is replayed by writing to this device. - -The significance of blocking or non-blocking mode is described in the -documentation for functions where there is a difference. It does not -affect the semantics of the ``open()`` call itself. A device opened -in blocking mode can later be put into non-blocking mode (and vice versa) -using the ``F_SETFL`` command of the fcntl system call. - - -Return Value ------------- - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 16 - - - - ``EMFILE`` - - “Too many open files”, i.e. no more filters available. - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/dmx-fread.rst b/Documentation/media/uapi/dvb/dmx-fread.rst deleted file mode 100644 index 292fa98f39ff..000000000000 --- a/Documentation/media/uapi/dvb/dmx-fread.rst +++ /dev/null @@ -1,87 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dmx_fread: - -======================= -Digital TV demux read() -======================= - -Name ----- - -Digital TV demux read() - - -Synopsis --------- - -.. c:function:: size_t read(int fd, void *buf, size_t count) - :name: dvb-dmx-read - -Arguments ---------- - -``fd`` - File descriptor returned by a previous call to :c:func:`open() `. - - ``buf`` - Buffer to be filled - -``count`` - Max number of bytes to read - -Description ------------ - -This system call returns filtered data, which might be section or Packetized -Elementary Stream (PES) data. The filtered data is transferred from -the driver’s internal circular buffer to ``buf``. The maximum amount of data -to be transferred is implied by count. - -.. note:: - - if a section filter created with - :c:type:`DMX_CHECK_CRC ` flag set, - data that fails on CRC check will be silently ignored. - - -Return Value ------------- - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 16 - - - - ``EWOULDBLOCK`` - - No data to return and ``O_NONBLOCK`` was specified. - - - - ``EOVERFLOW`` - - The filtered data was not read from the buffer in due time, - resulting in non-read data being lost. The buffer is flushed. - - - - ``ETIMEDOUT`` - - The section was not loaded within the stated timeout period. - See ioctl :ref:`DMX_SET_FILTER` for how to set a timeout. - - - - ``EFAULT`` - - The driver failed to write to the callers buffer due to an - invalid \*buf pointer. - - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/dmx-fwrite.rst b/Documentation/media/uapi/dvb/dmx-fwrite.rst deleted file mode 100644 index bdd4d4743bd5..000000000000 --- a/Documentation/media/uapi/dvb/dmx-fwrite.rst +++ /dev/null @@ -1,79 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dmx_fwrite: - -======================== -Digital TV demux write() -======================== - -Name ----- - -Digital TV demux write() - - -Synopsis --------- - -.. c:function:: ssize_t write(int fd, const void *buf, size_t count) - :name: dvb-dmx-write - -Arguments ---------- - -``fd`` - File descriptor returned by a previous call to :c:func:`open() `. - -``buf`` - Buffer with data to be written - -``count`` - Number of bytes at the buffer - -Description ------------ - -This system call is only provided by the logical device -``/dev/dvb/adapter?/dvr?``, associated with the physical demux device that -provides the actual DVR functionality. It is used for replay of a -digitally recorded Transport Stream. Matching filters have to be defined -in the corresponding physical demux device, ``/dev/dvb/adapter?/demux?``. -The amount of data to be transferred is implied by count. - - -Return Value ------------- - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 16 - - - - ``EWOULDBLOCK`` - - No data was written. This might happen if ``O_NONBLOCK`` was - specified and there is no more buffer space available (if - ``O_NONBLOCK`` is not specified the function will block until buffer - space is available). - - - - ``EBUSY`` - - This error code indicates that there are conflicting requests. The - corresponding demux device is setup to receive data from the - front- end. Make sure that these filters are stopped and that the - filters with input set to ``DMX_IN_DVR`` are started. - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/dmx-get-pes-pids.rst b/Documentation/media/uapi/dvb/dmx-get-pes-pids.rst deleted file mode 100644 index fcd3dc06c095..000000000000 --- a/Documentation/media/uapi/dvb/dmx-get-pes-pids.rst +++ /dev/null @@ -1,71 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _DMX_GET_PES_PIDS: - -================ -DMX_GET_PES_PIDS -================ - -Name ----- - -DMX_GET_PES_PIDS - - -Synopsis --------- - -.. c:function:: int ioctl(fd, DMX_GET_PES_PIDS, __u16 pids[5]) - :name: DMX_GET_PES_PIDS - -Arguments ---------- - -``fd`` - File descriptor returned by :c:func:`open() `. - -``pids`` - Array used to store 5 Program IDs. - - -Description ------------ - -This ioctl allows to query a DVB device to return the first PID used -by audio, video, textext, subtitle and PCR programs on a given service. -They're stored as: - -======================= ======== ======================================= -PID element position content -======================= ======== ======================================= -pids[DMX_PES_AUDIO] 0 first audio PID -pids[DMX_PES_VIDEO] 1 first video PID -pids[DMX_PES_TELETEXT] 2 first teletext PID -pids[DMX_PES_SUBTITLE] 3 first subtitle PID -pids[DMX_PES_PCR] 4 first Program Clock Reference PID -======================= ======== ======================================= - - -.. note:: - - A value equal to 0xffff means that the PID was not filled by the - Kernel. - - -Return Value ------------- - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/dmx-get-stc.rst b/Documentation/media/uapi/dvb/dmx-get-stc.rst deleted file mode 100644 index 2c81595f470a..000000000000 --- a/Documentation/media/uapi/dvb/dmx-get-stc.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _DMX_GET_STC: - -=========== -DMX_GET_STC -=========== - -Name ----- - -DMX_GET_STC - - -Synopsis --------- - -.. c:function:: int ioctl( int fd, DMX_GET_STC, struct dmx_stc *stc) - :name: DMX_GET_STC - -Arguments ---------- - -``fd`` - File descriptor returned by :c:func:`open() `. - -``stc`` - Pointer to :c:type:`dmx_stc` where the stc data is to be stored. - - -Description ------------ - -This ioctl call returns the current value of the system time counter -(which is driven by a PES filter of type :c:type:`DMX_PES_PCR `). -Some hardware supports more than one STC, so you must specify which one by -setting the :c:type:`num ` field of stc before the ioctl (range 0...n). -The result is returned in form of a ratio with a 64 bit numerator -and a 32 bit denominator, so the real 90kHz STC value is -``stc->stc / stc->base``. - - -Return Value ------------- - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 16 - - - .. row 1 - - - ``EINVAL`` - - - Invalid stc number. - - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/dmx-mmap.rst b/Documentation/media/uapi/dvb/dmx-mmap.rst deleted file mode 100644 index 34bb7766718f..000000000000 --- a/Documentation/media/uapi/dvb/dmx-mmap.rst +++ /dev/null @@ -1,125 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dmx-mmap: - -***************** -Digital TV mmap() -***************** - -Name -==== - -dmx-mmap - Map device memory into application address space - -.. warning:: this API is still experimental - -Synopsis -======== - -.. code-block:: c - - #include - #include - - -.. c:function:: void *mmap( void *start, size_t length, int prot, int flags, int fd, off_t offset ) - :name: dmx-mmap - -Arguments -========= - -``start`` - Map the buffer to this address in the application's address space. - When the ``MAP_FIXED`` flag is specified, ``start`` must be a - multiple of the pagesize and mmap will fail when the specified - address cannot be used. Use of this option is discouraged; - applications should just specify a ``NULL`` pointer here. - -``length`` - Length of the memory area to map. This must be a multiple of the - DVB packet length (188, on most drivers). - -``prot`` - The ``prot`` argument describes the desired memory protection. - Regardless of the device type and the direction of data exchange it - should be set to ``PROT_READ`` | ``PROT_WRITE``, permitting read - and write access to image buffers. Drivers should support at least - this combination of flags. - -``flags`` - The ``flags`` parameter specifies the type of the mapped object, - mapping options and whether modifications made to the mapped copy of - the page are private to the process or are to be shared with other - references. - - ``MAP_FIXED`` requests that the driver selects no other address than - the one specified. If the specified address cannot be used, - :ref:`mmap() ` will fail. If ``MAP_FIXED`` is specified, - ``start`` must be a multiple of the pagesize. Use of this option is - discouraged. - - One of the ``MAP_SHARED`` or ``MAP_PRIVATE`` flags must be set. - ``MAP_SHARED`` allows applications to share the mapped memory with - other (e. g. child-) processes. - - .. note:: - - The Linux Digital TV applications should not set the - ``MAP_PRIVATE``, ``MAP_DENYWRITE``, ``MAP_EXECUTABLE`` or ``MAP_ANON`` - flags. - -``fd`` - File descriptor returned by :ref:`open() `. - -``offset`` - Offset of the buffer in device memory, as returned by - :ref:`DMX_QUERYBUF` ioctl. - - -Description -=========== - -The :ref:`mmap() ` function asks to map ``length`` bytes starting at -``offset`` in the memory of the device specified by ``fd`` into the -application address space, preferably at address ``start``. This latter -address is a hint only, and is usually specified as 0. - -Suitable length and offset parameters are queried with the -:ref:`DMX_QUERYBUF` ioctl. Buffers must be allocated with the -:ref:`DMX_REQBUFS` ioctl before they can be queried. - -To unmap buffers the :ref:`munmap() ` function is used. - - -Return Value -============ - -On success :ref:`mmap() ` returns a pointer to the mapped buffer. On -error ``MAP_FAILED`` (-1) is returned, and the ``errno`` variable is set -appropriately. Possible error codes are: - -EBADF - ``fd`` is not a valid file descriptor. - -EACCES - ``fd`` is not open for reading and writing. - -EINVAL - The ``start`` or ``length`` or ``offset`` are not suitable. (E. g. - they are too large, or not aligned on a ``PAGESIZE`` boundary.) - - The ``flags`` or ``prot`` value is not supported. - - No buffers have been allocated with the - :ref:`DMX_REQBUFS` ioctl. - -ENOMEM - Not enough physical or virtual memory was available to complete the - request. diff --git a/Documentation/media/uapi/dvb/dmx-munmap.rst b/Documentation/media/uapi/dvb/dmx-munmap.rst deleted file mode 100644 index ef26b6f2b12b..000000000000 --- a/Documentation/media/uapi/dvb/dmx-munmap.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dmx-munmap: - -************ -DVB munmap() -************ - -Name -==== - -dmx-munmap - Unmap device memory - -.. warning:: This API is still experimental. - - -Synopsis -======== - -.. code-block:: c - - #include - #include - - -.. c:function:: int munmap( void *start, size_t length ) - :name: dmx-munmap - -Arguments -========= - -``start`` - Address of the mapped buffer as returned by the - :ref:`mmap() ` function. - -``length`` - Length of the mapped buffer. This must be the same value as given to - :ref:`mmap() `. - - -Description -=========== - -Unmaps a previously with the :ref:`mmap() ` function mapped -buffer and frees it, if possible. - - -Return Value -============ - -On success :ref:`munmap() ` returns 0, on failure -1 and the -``errno`` variable is set appropriately: - -EINVAL - The ``start`` or ``length`` is incorrect, or no buffers have been - mapped yet. diff --git a/Documentation/media/uapi/dvb/dmx-qbuf.rst b/Documentation/media/uapi/dvb/dmx-qbuf.rst deleted file mode 100644 index 9dc845daa59d..000000000000 --- a/Documentation/media/uapi/dvb/dmx-qbuf.rst +++ /dev/null @@ -1,93 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _DMX_QBUF: - -************************* -ioctl DMX_QBUF, DMX_DQBUF -************************* - -Name -==== - -DMX_QBUF - DMX_DQBUF - Exchange a buffer with the driver - -.. warning:: this API is still experimental - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, DMX_QBUF, struct dmx_buffer *argp ) - :name: DMX_QBUF - -.. c:function:: int ioctl( int fd, DMX_DQBUF, struct dmx_buffer *argp ) - :name: DMX_DQBUF - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``argp`` - Pointer to struct :c:type:`dmx_buffer`. - - -Description -=========== - -Applications call the ``DMX_QBUF`` ioctl to enqueue an empty -(capturing) or filled (output) buffer in the driver's incoming queue. -The semantics depend on the selected I/O method. - -To enqueue a buffer applications set the ``index`` field. Valid index -numbers range from zero to the number of buffers allocated with -:ref:`DMX_REQBUFS` (struct :c:type:`dmx_requestbuffers` ``count``) minus -one. The contents of the struct :c:type:`dmx_buffer` returned -by a :ref:`DMX_QUERYBUF` ioctl will do as well. - -When ``DMX_QBUF`` is called with a pointer to this structure, it locks the -memory pages of the buffer in physical memory, so they cannot be swapped -out to disk. Buffers remain locked until dequeued, until the -the device is closed. - -Applications call the ``DMX_DQBUF`` ioctl to dequeue a filled -(capturing) buffer from the driver's outgoing queue. -They just set the ``index`` field with the buffer ID to be queued. -When ``DMX_DQBUF`` is called with a pointer to struct :c:type:`dmx_buffer`, -the driver fills the remaining fields or returns an error code. - -By default ``DMX_DQBUF`` blocks when no buffer is in the outgoing -queue. When the ``O_NONBLOCK`` flag was given to the -:ref:`open() ` function, ``DMX_DQBUF`` returns -immediately with an ``EAGAIN`` error code when no buffer is available. - -The struct :c:type:`dmx_buffer` structure is specified in -:ref:`buffer`. - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. - -EAGAIN - Non-blocking I/O has been selected using ``O_NONBLOCK`` and no - buffer was in the outgoing queue. - -EINVAL - The ``index`` is out of bounds, or no buffers have been allocated yet. - -EIO - ``DMX_DQBUF`` failed due to an internal error. Can also indicate - temporary problems like signal loss or CRC errors. diff --git a/Documentation/media/uapi/dvb/dmx-querybuf.rst b/Documentation/media/uapi/dvb/dmx-querybuf.rst deleted file mode 100644 index 4cf36e821696..000000000000 --- a/Documentation/media/uapi/dvb/dmx-querybuf.rst +++ /dev/null @@ -1,72 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _DMX_QUERYBUF: - -****************** -ioctl DMX_QUERYBUF -****************** - -Name -==== - -DMX_QUERYBUF - Query the status of a buffer - -.. warning:: this API is still experimental - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, DMX_QUERYBUF, struct dvb_buffer *argp ) - :name: DMX_QUERYBUF - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``argp`` - Pointer to struct :c:type:`dvb_buffer`. - - -Description -=========== - -This ioctl is part of the mmap streaming I/O method. It can -be used to query the status of a buffer at any time after buffers have -been allocated with the :ref:`DMX_REQBUFS` ioctl. - -Applications set the ``index`` field. Valid index numbers range from zero -to the number of buffers allocated with :ref:`DMX_REQBUFS` -(struct :c:type:`dvb_requestbuffers` ``count``) minus one. - -After calling :ref:`DMX_QUERYBUF` with a pointer to this structure, -drivers return an error code or fill the rest of the structure. - -On success, the ``offset`` will contain the offset of the buffer from the -start of the device memory, the ``length`` field its size, and the -``bytesused`` the number of bytes occupied by data in the buffer (payload). - -Return Value -============ - -On success 0 is returned, the ``offset`` will contain the offset of the -buffer from the start of the device memory, the ``length`` field its size, -and the ``bytesused`` the number of bytes occupied by data in the buffer -(payload). - -On error it returns -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. - -EINVAL - The ``index`` is out of bounds. diff --git a/Documentation/media/uapi/dvb/dmx-remove-pid.rst b/Documentation/media/uapi/dvb/dmx-remove-pid.rst deleted file mode 100644 index be992f44f306..000000000000 --- a/Documentation/media/uapi/dvb/dmx-remove-pid.rst +++ /dev/null @@ -1,57 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _DMX_REMOVE_PID: - -============== -DMX_REMOVE_PID -============== - -Name ----- - -DMX_REMOVE_PID - - -Synopsis --------- - -.. c:function:: int ioctl(fd, DMX_REMOVE_PID, __u16 *pid) - :name: DMX_REMOVE_PID - - -Arguments ---------- - -``fd`` - File descriptor returned by :c:func:`open() `. - -``pid`` - PID of the PES filter to be removed. - - -Description ------------ - -This ioctl call allows to remove a PID when multiple PIDs are set on a -transport stream filter, e. g. a filter previously set up with output -equal to :c:type:`DMX_OUT_TSDEMUX_TAP `, created via either -:ref:`DMX_SET_PES_FILTER` or :ref:`DMX_ADD_PID`. - - -Return Value ------------- - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/dmx-reqbufs.rst b/Documentation/media/uapi/dvb/dmx-reqbufs.rst deleted file mode 100644 index b302785bf678..000000000000 --- a/Documentation/media/uapi/dvb/dmx-reqbufs.rst +++ /dev/null @@ -1,83 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _DMX_REQBUFS: - -***************** -ioctl DMX_REQBUFS -***************** - -Name -==== - -DMX_REQBUFS - Initiate Memory Mapping and/or DMA buffer I/O - -.. warning:: this API is still experimental - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, DMX_REQBUFS, struct dmx_requestbuffers *argp ) - :name: DMX_REQBUFS - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``argp`` - Pointer to struct :c:type:`dmx_requestbuffers`. - -Description -=========== - -This ioctl is used to initiate a memory mapped or DMABUF based demux I/O. - -Memory mapped buffers are located in device memory and must be allocated -with this ioctl before they can be mapped into the application's address -space. User buffers are allocated by applications themselves, and this -ioctl is merely used to switch the driver into user pointer I/O mode and -to setup some internal structures. Similarly, DMABUF buffers are -allocated by applications through a device driver, and this ioctl only -configures the driver into DMABUF I/O mode without performing any direct -allocation. - -To allocate device buffers applications initialize all fields of the -struct :c:type:`dmx_requestbuffers` structure. They set the ``count`` field -to the desired number of buffers, and ``size`` to the size of each -buffer. - -When the ioctl is called with a pointer to this structure, the driver will -attempt to allocate the requested number of buffers and it stores the actual -number allocated in the ``count`` field. The ``count`` can be smaller than the number requested, even zero, when the driver runs out of free memory. A larger -number is also possible when the driver requires more buffers to -function correctly. The actual allocated buffer size can is returned -at ``size``, and can be smaller than what's requested. - -When this I/O method is not supported, the ioctl returns an ``EOPNOTSUPP`` -error code. - -Applications can call :ref:`DMX_REQBUFS` again to change the number of -buffers, however this cannot succeed when any buffers are still mapped. -A ``count`` value of zero frees all buffers, after aborting or finishing -any DMA in progress. - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. - -EOPNOTSUPP - The the requested I/O method is not supported. diff --git a/Documentation/media/uapi/dvb/dmx-set-buffer-size.rst b/Documentation/media/uapi/dvb/dmx-set-buffer-size.rst deleted file mode 100644 index 2dee0fb11f62..000000000000 --- a/Documentation/media/uapi/dvb/dmx-set-buffer-size.rst +++ /dev/null @@ -1,57 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _DMX_SET_BUFFER_SIZE: - -=================== -DMX_SET_BUFFER_SIZE -=================== - -Name ----- - -DMX_SET_BUFFER_SIZE - - -Synopsis --------- - -.. c:function:: int ioctl( int fd, DMX_SET_BUFFER_SIZE, unsigned long size) - :name: DMX_SET_BUFFER_SIZE - - -Arguments ---------- - -``fd`` - File descriptor returned by :c:func:`open() `. - -``size`` - Unsigned long size - -Description ------------ - -This ioctl call is used to set the size of the circular buffer used for -filtered data. The default size is two maximum sized sections, i.e. if -this function is not called a buffer size of ``2 * 4096`` bytes will be -used. - - -Return Value ------------- - - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/dmx-set-filter.rst b/Documentation/media/uapi/dvb/dmx-set-filter.rst deleted file mode 100644 index 66afbb9f2fe4..000000000000 --- a/Documentation/media/uapi/dvb/dmx-set-filter.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _DMX_SET_FILTER: - -============== -DMX_SET_FILTER -============== - -Name ----- - -DMX_SET_FILTER - - -Synopsis --------- - -.. c:function:: int ioctl( int fd, DMX_SET_FILTER, struct dmx_sct_filter_params *params) - :name: DMX_SET_FILTER - -Arguments ---------- - -``fd`` - File descriptor returned by :c:func:`open() `. - -``params`` - - Pointer to structure containing filter parameters. - - -Description ------------ - -This ioctl call sets up a filter according to the filter and mask -parameters provided. A timeout may be defined stating number of seconds -to wait for a section to be loaded. A value of 0 means that no timeout -should be applied. Finally there is a flag field where it is possible to -state whether a section should be CRC-checked, whether the filter should -be a ”one-shot” filter, i.e. if the filtering operation should be -stopped after the first section is received, and whether the filtering -operation should be started immediately (without waiting for a -:ref:`DMX_START` ioctl call). If a filter was previously set-up, this -filter will be canceled, and the receive buffer will be flushed. - - -Return Value ------------- - - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/dmx-set-pes-filter.rst b/Documentation/media/uapi/dvb/dmx-set-pes-filter.rst deleted file mode 100644 index dae5ab7878e5..000000000000 --- a/Documentation/media/uapi/dvb/dmx-set-pes-filter.rst +++ /dev/null @@ -1,76 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _DMX_SET_PES_FILTER: - -================== -DMX_SET_PES_FILTER -================== - -Name ----- - -DMX_SET_PES_FILTER - - -Synopsis --------- - -.. c:function:: int ioctl( int fd, DMX_SET_PES_FILTER, struct dmx_pes_filter_params *params) - :name: DMX_SET_PES_FILTER - - -Arguments ---------- - - -``fd`` - File descriptor returned by :c:func:`open() `. - -``params`` - Pointer to structure containing filter parameters. - - -Description ------------ - -This ioctl call sets up a PES filter according to the parameters -provided. By a PES filter is meant a filter that is based just on the -packet identifier (PID), i.e. no PES header or payload filtering -capability is supported. - - -Return Value ------------- - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 16 - - - - .. row 1 - - - ``EBUSY`` - - - This error code indicates that there are conflicting requests. - There are active filters filtering data from another input source. - Make sure that these filters are stopped before starting this - filter. - - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/dmx-start.rst b/Documentation/media/uapi/dvb/dmx-start.rst deleted file mode 100644 index 488289d02504..000000000000 --- a/Documentation/media/uapi/dvb/dmx-start.rst +++ /dev/null @@ -1,75 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _DMX_START: - -========= -DMX_START -========= - -Name ----- - -DMX_START - - -Synopsis --------- - -.. c:function:: int ioctl( int fd, DMX_START) - :name: DMX_START - - -Arguments ---------- - -``fd`` - File descriptor returned by :c:func:`open() `. - -Description ------------ - -This ioctl call is used to start the actual filtering operation defined -via the ioctl calls :ref:`DMX_SET_FILTER` or :ref:`DMX_SET_PES_FILTER`. - - -Return Value ------------- - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``EINVAL`` - - - Invalid argument, i.e. no filtering parameters provided via the - :ref:`DMX_SET_FILTER` or :ref:`DMX_SET_PES_FILTER` ioctls. - - - .. row 2 - - - ``EBUSY`` - - - This error code indicates that there are conflicting requests. - There are active filters filtering data from another input source. - Make sure that these filters are stopped before starting this - filter. - - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/dmx-stop.rst b/Documentation/media/uapi/dvb/dmx-stop.rst deleted file mode 100644 index 982384d12923..000000000000 --- a/Documentation/media/uapi/dvb/dmx-stop.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _DMX_STOP: - -======== -DMX_STOP -======== - -Name ----- - -DMX_STOP - - -Synopsis --------- - -.. c:function:: int ioctl( int fd, DMX_STOP) - :name: DMX_STOP - - -Arguments ---------- - -``fd`` - File descriptor returned by :c:func:`open() `. - -Description ------------ - -This ioctl call is used to stop the actual filtering operation defined -via the ioctl calls :ref:`DMX_SET_FILTER` or :ref:`DMX_SET_PES_FILTER` and -started via the :ref:`DMX_START` command. - - -Return Value ------------- - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/dmx_fcalls.rst b/Documentation/media/uapi/dvb/dmx_fcalls.rst deleted file mode 100644 index 67312ab65f94..000000000000 --- a/Documentation/media/uapi/dvb/dmx_fcalls.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dmx_fcalls: - -******************** -Demux Function Calls -******************** - -.. toctree:: - :maxdepth: 1 - - dmx-fopen - dmx-fclose - dmx-fread - dmx-fwrite - dmx-mmap - dmx-munmap - dmx-start - dmx-stop - dmx-set-filter - dmx-set-pes-filter - dmx-set-buffer-size - dmx-get-stc - dmx-get-pes-pids - dmx-add-pid - dmx-remove-pid - dmx-reqbufs - dmx-querybuf - dmx-expbuf - dmx-qbuf diff --git a/Documentation/media/uapi/dvb/dmx_types.rst b/Documentation/media/uapi/dvb/dmx_types.rst deleted file mode 100644 index b5cf704199e5..000000000000 --- a/Documentation/media/uapi/dvb/dmx_types.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dmx_types: - -**************** -Demux Data Types -**************** - -.. kernel-doc:: include/uapi/linux/dvb/dmx.h diff --git a/Documentation/media/uapi/dvb/dvb-fe-read-status.rst b/Documentation/media/uapi/dvb/dvb-fe-read-status.rst deleted file mode 100644 index 172783b75fb7..000000000000 --- a/Documentation/media/uapi/dvb/dvb-fe-read-status.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dvb-fe-read-status: - -*************************************** -Querying frontend status and statistics -*************************************** - -Once :ref:`FE_SET_PROPERTY ` is called, the -frontend will run a kernel thread that will periodically check for the -tuner lock status and provide statistics about the quality of the -signal. - -The information about the frontend tuner locking status can be queried -using :ref:`FE_READ_STATUS`. - -Signal statistics are provided via -:ref:`FE_GET_PROPERTY`. - -.. note:: - - Most statistics require the demodulator to be fully locked - (e. g. with :c:type:`FE_HAS_LOCK ` bit set). See - :ref:`Frontend statistics indicators ` for - more details. diff --git a/Documentation/media/uapi/dvb/dvb-frontend-event.rst b/Documentation/media/uapi/dvb/dvb-frontend-event.rst deleted file mode 100644 index ad4af66040c7..000000000000 --- a/Documentation/media/uapi/dvb/dvb-frontend-event.rst +++ /dev/null @@ -1,22 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. c:type:: dvb_frontend_event - -*************** -frontend events -*************** - - -.. code-block:: c - - struct dvb_frontend_event { - fe_status_t status; - struct dvb_frontend_parameters parameters; - }; diff --git a/Documentation/media/uapi/dvb/dvb-frontend-parameters.rst b/Documentation/media/uapi/dvb/dvb-frontend-parameters.rst deleted file mode 100644 index 67c2a316019f..000000000000 --- a/Documentation/media/uapi/dvb/dvb-frontend-parameters.rst +++ /dev/null @@ -1,126 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. c:type:: dvb_frontend_parameters - -******************* -frontend parameters -******************* - -The kind of parameters passed to the frontend device for tuning depend -on the kind of hardware you are using. - -The struct ``dvb_frontend_parameters`` uses a union with specific -per-system parameters. However, as newer delivery systems required more -data, the structure size weren't enough to fit, and just extending its -size would break the existing applications. So, those parameters were -replaced by the usage of -:ref:`FE_GET_PROPERTY/FE_SET_PROPERTY ` -ioctl's. The new API is flexible enough to add new parameters to -existing delivery systems, and to add newer delivery systems. - -So, newer applications should use -:ref:`FE_GET_PROPERTY/FE_SET_PROPERTY ` -instead, in order to be able to support the newer System Delivery like -DVB-S2, DVB-T2, DVB-C2, ISDB, etc. - -All kinds of parameters are combined as a union in the -``dvb_frontend_parameters`` structure: - - -.. code-block:: c - - struct dvb_frontend_parameters { - uint32_t frequency; /* (absolute) frequency in Hz for QAM/OFDM */ - /* intermediate frequency in kHz for QPSK */ - fe_spectral_inversion_t inversion; - union { - struct dvb_qpsk_parameters qpsk; - struct dvb_qam_parameters qam; - struct dvb_ofdm_parameters ofdm; - struct dvb_vsb_parameters vsb; - } u; - }; - -In the case of QPSK frontends the ``frequency`` field specifies the -intermediate frequency, i.e. the offset which is effectively added to -the local oscillator frequency (LOF) of the LNB. The intermediate -frequency has to be specified in units of kHz. For QAM and OFDM -frontends the ``frequency`` specifies the absolute frequency and is -given in Hz. - - -.. c:type:: dvb_qpsk_parameters - -QPSK parameters -=============== - -For satellite QPSK frontends you have to use the ``dvb_qpsk_parameters`` -structure: - - -.. code-block:: c - - struct dvb_qpsk_parameters { - uint32_t symbol_rate; /* symbol rate in Symbols per second */ - fe_code_rate_t fec_inner; /* forward error correction (see above) */ - }; - - -.. c:type:: dvb_qam_parameters - -QAM parameters -============== - -for cable QAM frontend you use the ``dvb_qam_parameters`` structure: - - -.. code-block:: c - - struct dvb_qam_parameters { - uint32_t symbol_rate; /* symbol rate in Symbols per second */ - fe_code_rate_t fec_inner; /* forward error correction (see above) */ - fe_modulation_t modulation; /* modulation type (see above) */ - }; - - -.. c:type:: dvb_vsb_parameters - -VSB parameters -============== - -ATSC frontends are supported by the ``dvb_vsb_parameters`` structure: - - -.. code-block:: c - - struct dvb_vsb_parameters { - fe_modulation_t modulation; /* modulation type (see above) */ - }; - - -.. c:type:: dvb_ofdm_parameters - -OFDM parameters -=============== - -DVB-T frontends are supported by the ``dvb_ofdm_parameters`` structure: - - -.. code-block:: c - - struct dvb_ofdm_parameters { - fe_bandwidth_t bandwidth; - fe_code_rate_t code_rate_HP; /* high priority stream code rate */ - fe_code_rate_t code_rate_LP; /* low priority stream code rate */ - fe_modulation_t constellation; /* modulation type (see above) */ - fe_transmit_mode_t transmission_mode; - fe_guard_interval_t guard_interval; - fe_hierarchy_t hierarchy_information; - }; diff --git a/Documentation/media/uapi/dvb/dvbapi.rst b/Documentation/media/uapi/dvb/dvbapi.rst deleted file mode 100644 index 0fcc01f182f9..000000000000 --- a/Documentation/media/uapi/dvb/dvbapi.rst +++ /dev/null @@ -1,126 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. include:: - -.. _dvbapi: - -######################## -Part II - Digital TV API -######################## - -.. note:: - - This API is also known as Linux **DVB API**. - - It it was originally written to support the European digital TV - standard (DVB), and later extended to support all digital TV standards. - - In order to avoid confusion, within this document, it was opted to refer to - it, and to associated hardware as **Digital TV**. - - The word **DVB** is reserved to be used for: - - - the Digital TV API version - (e. g. DVB API version 3 or DVB API version 5); - - digital TV data types (enums, structs, defines, etc); - - digital TV device nodes (``/dev/dvb/...``); - - the European DVB standard. - -**Version 5.10** - -.. only:: html - - .. class:: toc-title - - Table of Contents - -.. toctree:: - :maxdepth: 5 - :numbered: - - intro - frontend - demux - ca - net - legacy_dvb_apis - examples - headers - - -********************** -Revision and Copyright -********************** - -Authors: - -- J. K. Metzler, Ralph - - - Original author of the Digital TV API documentation. - -- O. C. Metzler, Marcus - - - Original author of the Digital TV API documentation. - -- Carvalho Chehab, Mauro - - - Ported document to Docbook XML, addition of DVBv5 API, documentation gaps fix. - -**Copyright** |copy| 2002-2003 : Convergence GmbH - -**Copyright** |copy| 2009-2017 : Mauro Carvalho Chehab - -**************** -Revision History -**************** - -:revision: 2.2.0 / 2017-09-01 (*mcc*) - -Most gaps between the uAPI document and the Kernel implementation -got fixed for the non-legacy API. - -:revision: 2.1.0 / 2015-05-29 (*mcc*) - -DocBook improvements and cleanups, in order to document the system calls -on a more standard way and provide more description about the current -Digital TV API. - -:revision: 2.0.4 / 2011-05-06 (*mcc*) - -Add more information about DVBv5 API, better describing the frontend -GET/SET props ioctl's. - - -:revision: 2.0.3 / 2010-07-03 (*mcc*) - -Add some frontend capabilities flags, present on kernel, but missing at -the specs. - - -:revision: 2.0.2 / 2009-10-25 (*mcc*) - -documents FE_SET_FRONTEND_TUNE_MODE and -FE_DISHETWORK_SEND_LEGACY_CMD ioctls. - - -:revision: 2.0.1 / 2009-09-16 (*mcc*) - -Added ISDB-T test originally written by Patrick Boettcher - - -:revision: 2.0.0 / 2009-09-06 (*mcc*) - -Conversion from LaTex to DocBook XML. The contents is the same as the -original LaTex version. - - -:revision: 1.0.0 / 2003-07-24 (*rjkm*) - -Initial revision on LaTEX. diff --git a/Documentation/media/uapi/dvb/dvbproperty.rst b/Documentation/media/uapi/dvb/dvbproperty.rst deleted file mode 100644 index 0c4f5598f2be..000000000000 --- a/Documentation/media/uapi/dvb/dvbproperty.rst +++ /dev/null @@ -1,133 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _frontend-properties: - -************** -Property types -************** - -Tuning into a Digital TV physical channel and starting decoding it -requires changing a set of parameters, in order to control the tuner, -the demodulator, the Linear Low-noise Amplifier (LNA) and to set the -antenna subsystem via Satellite Equipment Control - SEC (on satellite -systems). The actual parameters are specific to each particular digital -TV standards, and may change as the digital TV specs evolves. - -In the past (up to DVB API version 3 - DVBv3), the strategy used was to have a -union with the parameters needed to tune for DVB-S, DVB-C, DVB-T and -ATSC delivery systems grouped there. The problem is that, as the second -generation standards appeared, the size of such union was not big -enough to group the structs that would be required for those new -standards. Also, extending it would break userspace. - -So, the legacy union/struct based approach was deprecated, in favor -of a properties set approach. On such approach, -:ref:`FE_GET_PROPERTY and FE_SET_PROPERTY ` are used -to setup the frontend and read its status. - -The actual action is determined by a set of dtv_property cmd/data pairs. -With one single ioctl, is possible to get/set up to 64 properties. - -This section describes the new and recommended way to set the frontend, -with supports all digital TV delivery systems. - -.. note:: - - 1. On Linux DVB API version 3, setting a frontend was done via - struct :c:type:`dvb_frontend_parameters`. - - 2. Don't use DVB API version 3 calls on hardware with supports - newer standards. Such API provides no support or a very limited - support to new standards and/or new hardware. - - 3. Nowadays, most frontends support multiple delivery systems. - Only with DVB API version 5 calls it is possible to switch between - the multiple delivery systems supported by a frontend. - - 4. DVB API version 5 is also called *S2API*, as the first - new standard added to it was DVB-S2. - -**Example**: in order to set the hardware to tune into a DVB-C channel -at 651 kHz, modulated with 256-QAM, FEC 3/4 and symbol rate of 5.217 -Mbauds, those properties should be sent to -:ref:`FE_SET_PROPERTY ` ioctl: - - :ref:`DTV_DELIVERY_SYSTEM ` = SYS_DVBC_ANNEX_A - - :ref:`DTV_FREQUENCY ` = 651000000 - - :ref:`DTV_MODULATION ` = QAM_256 - - :ref:`DTV_INVERSION ` = INVERSION_AUTO - - :ref:`DTV_SYMBOL_RATE ` = 5217000 - - :ref:`DTV_INNER_FEC ` = FEC_3_4 - - :ref:`DTV_TUNE ` - -The code that would that would do the above is show in -:ref:`dtv-prop-example`. - -.. code-block:: c - :caption: Example: Setting digital TV frontend properties - :name: dtv-prop-example - - #include - #include - #include - #include - - static struct dtv_property props[] = { - { .cmd = DTV_DELIVERY_SYSTEM, .u.data = SYS_DVBC_ANNEX_A }, - { .cmd = DTV_FREQUENCY, .u.data = 651000000 }, - { .cmd = DTV_MODULATION, .u.data = QAM_256 }, - { .cmd = DTV_INVERSION, .u.data = INVERSION_AUTO }, - { .cmd = DTV_SYMBOL_RATE, .u.data = 5217000 }, - { .cmd = DTV_INNER_FEC, .u.data = FEC_3_4 }, - { .cmd = DTV_TUNE } - }; - - static struct dtv_properties dtv_prop = { - .num = 6, .props = props - }; - - int main(void) - { - int fd = open("/dev/dvb/adapter0/frontend0", O_RDWR); - - if (!fd) { - perror ("open"); - return -1; - } - if (ioctl(fd, FE_SET_PROPERTY, &dtv_prop) == -1) { - perror("ioctl"); - return -1; - } - printf("Frontend set\\n"); - return 0; - } - -.. attention:: While it is possible to directly call the Kernel code like the - above example, it is strongly recommended to use - `libdvbv5 `__, as it - provides abstraction to work with the supported digital TV standards and - provides methods for usual operations like program scanning and to - read/write channel descriptor files. - -.. toctree:: - :maxdepth: 1 - - fe_property_parameters - frontend-stat-properties - frontend-property-terrestrial-systems - frontend-property-cable-systems - frontend-property-satellite-systems - frontend-header diff --git a/Documentation/media/uapi/dvb/dvbstb.svg b/Documentation/media/uapi/dvb/dvbstb.svg deleted file mode 100644 index c7672148d6ff..000000000000 --- a/Documentation/media/uapi/dvb/dvbstb.svg +++ /dev/null @@ -1,43 +0,0 @@ - - -image/svg+xmlAntena -Frontend -CA -Demux -SEC -Audio -Video -TV -Decoder -Decoder - diff --git a/Documentation/media/uapi/dvb/examples.rst b/Documentation/media/uapi/dvb/examples.rst deleted file mode 100644 index eaa41bc8d173..000000000000 --- a/Documentation/media/uapi/dvb/examples.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dvb_examples: - -******** -Examples -******** - -In the past, we used to have a set of examples here. However, those -examples got out of date and doesn't even compile nowadays. - -Also, nowadays, the best is to use the libdvbv5 DVB API nowadays, -with is fully documented. - -Please refer to the `libdvbv5 `__ -for updated/recommended examples. diff --git a/Documentation/media/uapi/dvb/fe-bandwidth-t.rst b/Documentation/media/uapi/dvb/fe-bandwidth-t.rst deleted file mode 100644 index c3d7837b5f87..000000000000 --- a/Documentation/media/uapi/dvb/fe-bandwidth-t.rst +++ /dev/null @@ -1,81 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -****************** -Frontend bandwidth -****************** - -.. c:type:: fe_bandwidth - -.. flat-table:: enum fe_bandwidth - :header-rows: 1 - :stub-columns: 0 - - - - .. row 1 - - - ID - - - Description - - - .. row 2 - - - .. _BANDWIDTH-AUTO: - - ``BANDWIDTH_AUTO`` - - - Autodetect bandwidth (if supported) - - - .. row 3 - - - .. _BANDWIDTH-1-712-MHZ: - - ``BANDWIDTH_1_712_MHZ`` - - - 1.712 MHz - - - .. row 4 - - - .. _BANDWIDTH-5-MHZ: - - ``BANDWIDTH_5_MHZ`` - - - 5 MHz - - - .. row 5 - - - .. _BANDWIDTH-6-MHZ: - - ``BANDWIDTH_6_MHZ`` - - - 6 MHz - - - .. row 6 - - - .. _BANDWIDTH-7-MHZ: - - ``BANDWIDTH_7_MHZ`` - - - 7 MHz - - - .. row 7 - - - .. _BANDWIDTH-8-MHZ: - - ``BANDWIDTH_8_MHZ`` - - - 8 MHz - - - .. row 8 - - - .. _BANDWIDTH-10-MHZ: - - ``BANDWIDTH_10_MHZ`` - - - 10 MHz diff --git a/Documentation/media/uapi/dvb/fe-diseqc-recv-slave-reply.rst b/Documentation/media/uapi/dvb/fe-diseqc-recv-slave-reply.rst deleted file mode 100644 index 88fd2186ca4d..000000000000 --- a/Documentation/media/uapi/dvb/fe-diseqc-recv-slave-reply.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_DISEQC_RECV_SLAVE_REPLY: - -******************************** -ioctl FE_DISEQC_RECV_SLAVE_REPLY -******************************** - -Name -==== - -FE_DISEQC_RECV_SLAVE_REPLY - Receives reply from a DiSEqC 2.0 command - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, FE_DISEQC_RECV_SLAVE_REPLY, struct dvb_diseqc_slave_reply *argp ) - :name: FE_DISEQC_RECV_SLAVE_REPLY - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``argp`` - pointer to struct :c:type:`dvb_diseqc_slave_reply`. - - -Description -=========== - -Receives reply from a DiSEqC 2.0 command. - -The received message is stored at the buffer pointed by ``argp``. - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-diseqc-reset-overload.rst b/Documentation/media/uapi/dvb/fe-diseqc-reset-overload.rst deleted file mode 100644 index 92929c2e75db..000000000000 --- a/Documentation/media/uapi/dvb/fe-diseqc-reset-overload.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_DISEQC_RESET_OVERLOAD: - -****************************** -ioctl FE_DISEQC_RESET_OVERLOAD -****************************** - -Name -==== - -FE_DISEQC_RESET_OVERLOAD - Restores the power to the antenna subsystem, if it was powered off due - to power overload. - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, FE_DISEQC_RESET_OVERLOAD, NULL ) - :name: FE_DISEQC_RESET_OVERLOAD - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -Description -=========== - -If the bus has been automatically powered off due to power overload, -this ioctl call restores the power to the bus. The call requires -read/write access to the device. This call has no effect if the device -is manually powered off. Not all Digital TV adapters support this ioctl. - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-diseqc-send-burst.rst b/Documentation/media/uapi/dvb/fe-diseqc-send-burst.rst deleted file mode 100644 index 8af872d306aa..000000000000 --- a/Documentation/media/uapi/dvb/fe-diseqc-send-burst.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_DISEQC_SEND_BURST: - -************************** -ioctl FE_DISEQC_SEND_BURST -************************** - -Name -==== - -FE_DISEQC_SEND_BURST - Sends a 22KHz tone burst for 2x1 mini DiSEqC satellite selection. - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, FE_DISEQC_SEND_BURST, enum fe_sec_mini_cmd tone ) - :name: FE_DISEQC_SEND_BURST - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``tone`` - An integer enumered value described at :c:type:`fe_sec_mini_cmd`. - - -Description -=========== - -This ioctl is used to set the generation of a 22kHz tone burst for mini -DiSEqC satellite selection for 2x1 switches. This call requires -read/write permissions. - -It provides support for what's specified at -`Digital Satellite Equipment Control (DiSEqC) - Simple "ToneBurst" Detection Circuit specification. `__ - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-diseqc-send-master-cmd.rst b/Documentation/media/uapi/dvb/fe-diseqc-send-master-cmd.rst deleted file mode 100644 index 30a48114153c..000000000000 --- a/Documentation/media/uapi/dvb/fe-diseqc-send-master-cmd.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_DISEQC_SEND_MASTER_CMD: - -******************************* -ioctl FE_DISEQC_SEND_MASTER_CMD -******************************* - -Name -==== - -FE_DISEQC_SEND_MASTER_CMD - Sends a DiSEqC command - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, FE_DISEQC_SEND_MASTER_CMD, struct dvb_diseqc_master_cmd *argp ) - :name: FE_DISEQC_SEND_MASTER_CMD - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``argp`` - pointer to struct - :c:type:`dvb_diseqc_master_cmd` - - -Description -=========== - -Sends the DiSEqC command pointed by :c:type:`dvb_diseqc_master_cmd` -to the antenna subsystem. - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. - diff --git a/Documentation/media/uapi/dvb/fe-dishnetwork-send-legacy-cmd.rst b/Documentation/media/uapi/dvb/fe-dishnetwork-send-legacy-cmd.rst deleted file mode 100644 index 13811289971b..000000000000 --- a/Documentation/media/uapi/dvb/fe-dishnetwork-send-legacy-cmd.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_DISHNETWORK_SEND_LEGACY_CMD: - -****************************** -FE_DISHNETWORK_SEND_LEGACY_CMD -****************************** - -Name -==== - -FE_DISHNETWORK_SEND_LEGACY_CMD - - -Synopsis -======== - -.. c:function:: int ioctl(int fd, FE_DISHNETWORK_SEND_LEGACY_CMD, unsigned long cmd) - :name: FE_DISHNETWORK_SEND_LEGACY_CMD - - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - -``cmd`` - Sends the specified raw cmd to the dish via DISEqC. - - -Description -=========== - -.. warning:: - This is a very obscure legacy command, used only at stv0299 - driver. Should not be used on newer drivers. - -It provides a non-standard method for selecting Diseqc voltage on the -frontend, for Dish Network legacy switches. - -As support for this ioctl were added in 2004, this means that such -dishes were already legacy in 2004. - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-enable-high-lnb-voltage.rst b/Documentation/media/uapi/dvb/fe-enable-high-lnb-voltage.rst deleted file mode 100644 index 32b7d140d80b..000000000000 --- a/Documentation/media/uapi/dvb/fe-enable-high-lnb-voltage.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_ENABLE_HIGH_LNB_VOLTAGE: - -******************************** -ioctl FE_ENABLE_HIGH_LNB_VOLTAGE -******************************** - -Name -==== - -FE_ENABLE_HIGH_LNB_VOLTAGE - Select output DC level between normal LNBf voltages or higher LNBf - voltages. - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, FE_ENABLE_HIGH_LNB_VOLTAGE, unsigned int high ) - :name: FE_ENABLE_HIGH_LNB_VOLTAGE - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``high`` - Valid flags: - - - 0 - normal 13V and 18V. - - - >0 - enables slightly higher voltages instead of 13/18V, in order - to compensate for long antenna cables. - - -Description -=========== - -Select output DC level between normal LNBf voltages or higher LNBf -voltages between 0 (normal) or a value grater than 0 for higher -voltages. - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-get-event.rst b/Documentation/media/uapi/dvb/fe-get-event.rst deleted file mode 100644 index 2573d5b9b636..000000000000 --- a/Documentation/media/uapi/dvb/fe-get-event.rst +++ /dev/null @@ -1,78 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_GET_EVENT: - -************ -FE_GET_EVENT -************ - -Name -==== - -FE_GET_EVENT - -.. attention:: This ioctl is deprecated. - - -Synopsis -======== - -.. c:function:: int ioctl(int fd, FE_GET_EVENT, struct dvb_frontend_event *ev) - :name: FE_GET_EVENT - - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - -``ev`` - Points to the location where the event, if any, is to be stored. - - -Description -=========== - -This ioctl call returns a frontend event if available. If an event is -not available, the behavior depends on whether the device is in blocking -or non-blocking mode. In the latter case, the call fails immediately -with errno set to ``EWOULDBLOCK``. In the former case, the call blocks until -an event becomes available. - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``EWOULDBLOCK`` - - - There is no event pending, and the device is in non-blocking mode. - - - .. row 2 - - - ``EOVERFLOW`` - - - Overflow in event queue - one or more events were lost. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-get-frontend.rst b/Documentation/media/uapi/dvb/fe-get-frontend.rst deleted file mode 100644 index 6cd5250d1832..000000000000 --- a/Documentation/media/uapi/dvb/fe-get-frontend.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_GET_FRONTEND: - -*************** -FE_GET_FRONTEND -*************** - -Name -==== - -FE_GET_FRONTEND - -.. attention:: This ioctl is deprecated. - - -Synopsis -======== - -.. c:function:: int ioctl(int fd, FE_GET_FRONTEND, struct dvb_frontend_parameters *p) - :name: FE_GET_FRONTEND - - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - - -``p`` - Points to parameters for tuning operation. - - -Description -=========== - -This ioctl call queries the currently effective frontend parameters. For -this command, read-only access to the device is sufficient. - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``EINVAL`` - - - Maximum supported symbol rate reached. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-get-info.rst b/Documentation/media/uapi/dvb/fe-get-info.rst deleted file mode 100644 index 551e68b11528..000000000000 --- a/Documentation/media/uapi/dvb/fe-get-info.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_GET_INFO: - -***************** -ioctl FE_GET_INFO -***************** - -Name -==== - -FE_GET_INFO - Query Digital TV frontend capabilities and returns information -about the - front-end. This call only requires read-only access to the device. - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, FE_GET_INFO, struct dvb_frontend_info *argp ) - :name: FE_GET_INFO - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``argp`` - pointer to struct struct - :c:type:`dvb_frontend_info` - - -Description -=========== - -All Digital TV frontend devices support the :ref:`FE_GET_INFO` ioctl. It is -used to identify kernel devices compatible with this specification and to -obtain information about driver and hardware capabilities. The ioctl -takes a pointer to dvb_frontend_info which is filled by the driver. -When the driver is not compatible with this specification the ioctl -returns an error. - - -frontend capabilities -===================== - -Capabilities describe what a frontend can do. Some capabilities are -supported only on some specific frontend types. - -The frontend capabilities are described at :c:type:`fe_caps`. - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-get-property.rst b/Documentation/media/uapi/dvb/fe-get-property.rst deleted file mode 100644 index 99386c7461b3..000000000000 --- a/Documentation/media/uapi/dvb/fe-get-property.rst +++ /dev/null @@ -1,83 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_GET_PROPERTY: - -************************************** -ioctl FE_SET_PROPERTY, FE_GET_PROPERTY -************************************** - -Name -==== - -FE_SET_PROPERTY - FE_GET_PROPERTY - FE_SET_PROPERTY sets one or more frontend properties. - FE_GET_PROPERTY returns one or more frontend properties. - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, FE_GET_PROPERTY, struct dtv_properties *argp ) - :name: FE_GET_PROPERTY - -.. c:function:: int ioctl( int fd, FE_SET_PROPERTY, struct dtv_properties *argp ) - :name: FE_SET_PROPERTY - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``argp`` - Pointer to struct :c:type:`dtv_properties`. - - -Description -=========== - -All Digital TV frontend devices support the ``FE_SET_PROPERTY`` and -``FE_GET_PROPERTY`` ioctls. The supported properties and statistics -depends on the delivery system and on the device: - -- ``FE_SET_PROPERTY:`` - - - This ioctl is used to set one or more frontend properties. - - - This is the basic command to request the frontend to tune into - some frequency and to start decoding the digital TV signal. - - - This call requires read/write access to the device. - -.. note:: - - At return, the values aren't updated to reflect the actual - parameters used. If the actual parameters are needed, an explicit - call to ``FE_GET_PROPERTY`` is needed. - -- ``FE_GET_PROPERTY:`` - - - This ioctl is used to get properties and statistics from the - frontend. - - - No properties are changed, and statistics aren't reset. - - - This call only requires read-only access to the device. - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-read-ber.rst b/Documentation/media/uapi/dvb/fe-read-ber.rst deleted file mode 100644 index e579d648687e..000000000000 --- a/Documentation/media/uapi/dvb/fe-read-ber.rst +++ /dev/null @@ -1,57 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_READ_BER: - -*********** -FE_READ_BER -*********** - -Name -==== - -FE_READ_BER - -.. attention:: This ioctl is deprecated. - -Synopsis -======== - -.. c:function:: int ioctl(int fd, FE_READ_BER, uint32_t *ber) - :name: FE_READ_BER - - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - -``ber`` - The bit error rate is stored into \*ber. - - -Description -=========== - -This ioctl call returns the bit error rate for the signal currently -received/demodulated by the front-end. For this command, read-only -access to the device is sufficient. - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-read-signal-strength.rst b/Documentation/media/uapi/dvb/fe-read-signal-strength.rst deleted file mode 100644 index 0a0c0c2ff207..000000000000 --- a/Documentation/media/uapi/dvb/fe-read-signal-strength.rst +++ /dev/null @@ -1,57 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_READ_SIGNAL_STRENGTH: - -*********************** -FE_READ_SIGNAL_STRENGTH -*********************** - -Name -==== - -FE_READ_SIGNAL_STRENGTH - -.. attention:: This ioctl is deprecated. - -Synopsis -======== - -.. c:function:: int ioctl( int fd, FE_READ_SIGNAL_STRENGTH, uint16_t *strength) - :name: FE_READ_SIGNAL_STRENGTH - - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - -``strength`` - The signal strength value is stored into \*strength. - - -Description -=========== - -This ioctl call returns the signal strength value for the signal -currently received by the front-end. For this command, read-only access -to the device is sufficient. - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-read-snr.rst b/Documentation/media/uapi/dvb/fe-read-snr.rst deleted file mode 100644 index 2a7a0d8f1fd5..000000000000 --- a/Documentation/media/uapi/dvb/fe-read-snr.rst +++ /dev/null @@ -1,57 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_READ_SNR: - -*********** -FE_READ_SNR -*********** - -Name -==== - -FE_READ_SNR - -.. attention:: This ioctl is deprecated. - -Synopsis -======== - -.. c:function:: int ioctl(int fd, FE_READ_SNR, int16_t *snr) - :name: FE_READ_SNR - - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - -``snr`` - The signal-to-noise ratio is stored into \*snr. - - -Description -=========== - -This ioctl call returns the signal-to-noise ratio for the signal -currently received by the front-end. For this command, read-only access -to the device is sufficient. - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-read-status.rst b/Documentation/media/uapi/dvb/fe-read-status.rst deleted file mode 100644 index 0dfc9fdf568f..000000000000 --- a/Documentation/media/uapi/dvb/fe-read-status.rst +++ /dev/null @@ -1,72 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_READ_STATUS: - -******************** -ioctl FE_READ_STATUS -******************** - -Name -==== - -FE_READ_STATUS - Returns status information about the front-end. This call only requires - read-only access to the device - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, FE_READ_STATUS, unsigned int *status ) - :name: FE_READ_STATUS - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``status`` - pointer to a bitmask integer filled with the values defined by enum - :c:type:`fe_status`. - - -Description -=========== - -All Digital TV frontend devices support the ``FE_READ_STATUS`` ioctl. It is -used to check about the locking status of the frontend after being -tuned. The ioctl takes a pointer to an integer where the status will be -written. - -.. note:: - - The size of status is actually sizeof(enum fe_status), with - varies according with the architecture. This needs to be fixed in the - future. - - -int fe_status -============= - -The fe_status parameter is used to indicate the current state and/or -state changes of the frontend hardware. It is produced using the enum -:c:type:`fe_status` values on a bitmask - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-read-uncorrected-blocks.rst b/Documentation/media/uapi/dvb/fe-read-uncorrected-blocks.rst deleted file mode 100644 index 19c532f750aa..000000000000 --- a/Documentation/media/uapi/dvb/fe-read-uncorrected-blocks.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_READ_UNCORRECTED_BLOCKS: - -************************** -FE_READ_UNCORRECTED_BLOCKS -************************** - -Name -==== - -FE_READ_UNCORRECTED_BLOCKS - -.. attention:: This ioctl is deprecated. - -Synopsis -======== - -.. c:function:: int ioctl( int fd, FE_READ_UNCORRECTED_BLOCKS, uint32_t *ublocks) - :name: FE_READ_UNCORRECTED_BLOCKS - - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - -``ublocks`` - The total number of uncorrected blocks seen by the driver so far. - - -Description -=========== - -This ioctl call returns the number of uncorrected blocks detected by the -device driver during its lifetime. For meaningful measurements, the -increment in block count during a specific time interval should be -calculated. For this command, read-only access to the device is -sufficient. - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-set-frontend-tune-mode.rst b/Documentation/media/uapi/dvb/fe-set-frontend-tune-mode.rst deleted file mode 100644 index 36e8913170e1..000000000000 --- a/Documentation/media/uapi/dvb/fe-set-frontend-tune-mode.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_SET_FRONTEND_TUNE_MODE: - -******************************* -ioctl FE_SET_FRONTEND_TUNE_MODE -******************************* - -Name -==== - -FE_SET_FRONTEND_TUNE_MODE - Allow setting tuner mode flags to the frontend. - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, FE_SET_FRONTEND_TUNE_MODE, unsigned int flags ) - :name: FE_SET_FRONTEND_TUNE_MODE - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``flags`` - Valid flags: - - - 0 - normal tune mode - - - ``FE_TUNE_MODE_ONESHOT`` - When set, this flag will disable any - zigzagging or other "normal" tuning behaviour. Additionally, - there will be no automatic monitoring of the lock status, and - hence no frontend events will be generated. If a frontend device - is closed, this flag will be automatically turned off when the - device is reopened read-write. - - -Description -=========== - -Allow setting tuner mode flags to the frontend, between 0 (normal) or -``FE_TUNE_MODE_ONESHOT`` mode - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-set-frontend.rst b/Documentation/media/uapi/dvb/fe-set-frontend.rst deleted file mode 100644 index 23caae2588d2..000000000000 --- a/Documentation/media/uapi/dvb/fe-set-frontend.rst +++ /dev/null @@ -1,78 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_SET_FRONTEND: - -*************** -FE_SET_FRONTEND -*************** - -.. attention:: This ioctl is deprecated. - -Name -==== - -FE_SET_FRONTEND - - -Synopsis -======== - -.. c:function:: int ioctl(int fd, FE_SET_FRONTEND, struct dvb_frontend_parameters *p) - :name: FE_SET_FRONTEND - - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - -``p`` - Points to parameters for tuning operation. - - -Description -=========== - -This ioctl call starts a tuning operation using specified parameters. -The result of this call will be successful if the parameters were valid -and the tuning could be initiated. The result of the tuning operation in -itself, however, will arrive asynchronously as an event (see -documentation for :ref:`FE_GET_EVENT` and -FrontendEvent.) If a new :ref:`FE_SET_FRONTEND` -operation is initiated before the previous one was completed, the -previous operation will be aborted in favor of the new one. This command -requires read/write access to the device. - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 16 - - - .. row 1 - - - ``EINVAL`` - - - Maximum supported symbol rate reached. - - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-set-tone.rst b/Documentation/media/uapi/dvb/fe-set-tone.rst deleted file mode 100644 index fb605e8c9fc4..000000000000 --- a/Documentation/media/uapi/dvb/fe-set-tone.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_SET_TONE: - -***************** -ioctl FE_SET_TONE -***************** - -Name -==== - -FE_SET_TONE - Sets/resets the generation of the continuous 22kHz tone. - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, FE_SET_TONE, enum fe_sec_tone_mode tone ) - :name: FE_SET_TONE - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``tone`` - an integer enumered value described at :c:type:`fe_sec_tone_mode` - - -Description -=========== - -This ioctl is used to set the generation of the continuous 22kHz tone. -This call requires read/write permissions. - -Usually, satellite antenna subsystems require that the digital TV device -to send a 22kHz tone in order to select between high/low band on some -dual-band LNBf. It is also used to send signals to DiSEqC equipment, but -this is done using the DiSEqC ioctls. - -.. attention:: If more than one device is connected to the same antenna, - setting a tone may interfere on other devices, as they may lose the - capability of selecting the band. So, it is recommended that applications - would change to SEC_TONE_OFF when the device is not used. - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-set-voltage.rst b/Documentation/media/uapi/dvb/fe-set-voltage.rst deleted file mode 100644 index c81a8e6a59aa..000000000000 --- a/Documentation/media/uapi/dvb/fe-set-voltage.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_SET_VOLTAGE: - -******************** -ioctl FE_SET_VOLTAGE -******************** - -Name -==== - -FE_SET_VOLTAGE - Allow setting the DC level sent to the antenna subsystem. - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, FE_SET_VOLTAGE, enum fe_sec_voltage voltage ) - :name: FE_SET_VOLTAGE - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``voltage`` - an integer enumered value described at :c:type:`fe_sec_voltage` - - -Description -=========== - -This ioctl allows to set the DC voltage level sent through the antenna -cable to 13V, 18V or off. - -Usually, a satellite antenna subsystems require that the digital TV -device to send a DC voltage to feed power to the LNBf. Depending on the -LNBf type, the polarization or the intermediate frequency (IF) of the -LNBf can controlled by the voltage level. Other devices (for example, -the ones that implement DISEqC and multipoint LNBf's don't need to -control the voltage level, provided that either 13V or 18V is sent to -power up the LNBf. - -.. attention:: if more than one device is connected to the same antenna, - setting a voltage level may interfere on other devices, as they may lose - the capability of setting polarization or IF. So, on those cases, setting - the voltage to SEC_VOLTAGE_OFF while the device is not is used is - recommended. - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-type-t.rst b/Documentation/media/uapi/dvb/fe-type-t.rst deleted file mode 100644 index 9720d2f7ba35..000000000000 --- a/Documentation/media/uapi/dvb/fe-type-t.rst +++ /dev/null @@ -1,98 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -************* -Frontend type -************* - -For historical reasons, frontend types are named by the type of -modulation used in transmission. The fontend types are given by -fe_type_t type, defined as: - - -.. c:type:: fe_type - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| - -.. flat-table:: Frontend types - :header-rows: 1 - :stub-columns: 0 - :widths: 3 1 4 - - - - .. row 1 - - - fe_type - - - Description - - - :ref:`DTV_DELIVERY_SYSTEM ` equivalent - type - - - .. row 2 - - - .. _FE-QPSK: - - ``FE_QPSK`` - - - For DVB-S standard - - - ``SYS_DVBS`` - - - .. row 3 - - - .. _FE-QAM: - - ``FE_QAM`` - - - For DVB-C annex A standard - - - ``SYS_DVBC_ANNEX_A`` - - - .. row 4 - - - .. _FE-OFDM: - - ``FE_OFDM`` - - - For DVB-T standard - - - ``SYS_DVBT`` - - - .. row 5 - - - .. _FE-ATSC: - - ``FE_ATSC`` - - - For ATSC standard (terrestrial) or for DVB-C Annex B (cable) used - in US. - - - ``SYS_ATSC`` (terrestrial) or ``SYS_DVBC_ANNEX_B`` (cable) - - -Newer formats like DVB-S2, ISDB-T, ISDB-S and DVB-T2 are not described -at the above, as they're supported via the new -:ref:`FE_GET_PROPERTY/FE_GET_SET_PROPERTY ` -ioctl's, using the :ref:`DTV_DELIVERY_SYSTEM ` -parameter. - -In the old days, struct :c:type:`dvb_frontend_info` -used to contain ``fe_type_t`` field to indicate the delivery systems, -filled with either ``FE_QPSK, FE_QAM, FE_OFDM`` or ``FE_ATSC``. While this -is still filled to keep backward compatibility, the usage of this field -is deprecated, as it can report just one delivery system, but some -devices support multiple delivery systems. Please use -:ref:`DTV_ENUM_DELSYS ` instead. - -On devices that support multiple delivery systems, struct -:c:type:`dvb_frontend_info`::``fe_type_t`` is -filled with the currently standard, as selected by the last call to -:ref:`FE_SET_PROPERTY ` using the -:ref:`DTV_DELIVERY_SYSTEM ` property. diff --git a/Documentation/media/uapi/dvb/fe_property_parameters.rst b/Documentation/media/uapi/dvb/fe_property_parameters.rst deleted file mode 100644 index 2fd2954d8dae..000000000000 --- a/Documentation/media/uapi/dvb/fe_property_parameters.rst +++ /dev/null @@ -1,1014 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _fe_property_parameters: - -****************************** -Digital TV property parameters -****************************** - -There are several different Digital TV parameters that can be used by -:ref:`FE_SET_PROPERTY and FE_GET_PROPERTY ioctls`. -This section describes each of them. Please notice, however, that only -a subset of them are needed to setup a frontend. - - -.. _DTV-UNDEFINED: - -DTV_UNDEFINED -============= - -Used internally. A GET/SET operation for it won't change or return -anything. - - -.. _DTV-TUNE: - -DTV_TUNE -======== - -Interpret the cache of data, build either a traditional frontend -tunerequest so we can pass validation in the ``FE_SET_FRONTEND`` ioctl. - - -.. _DTV-CLEAR: - -DTV_CLEAR -========= - -Reset a cache of data specific to the frontend here. This does not -effect hardware. - - -.. _DTV-FREQUENCY: - -DTV_FREQUENCY -============= - -Frequency of the digital TV transponder/channel. - -.. note:: - - #. For satellite delivery systems, the frequency is in kHz. - - #. For cable and terrestrial delivery systems, the frequency is in - Hz. - - #. On most delivery systems, the frequency is the center frequency - of the transponder/channel. The exception is for ISDB-T, where - the main carrier has a 1/7 offset from the center. - - #. For ISDB-T, the channels are usually transmitted with an offset of - about 143kHz. E.g. a valid frequency could be 474,143 kHz. The - stepping is bound to the bandwidth of the channel which is - typically 6MHz. - - #. In ISDB-Tsb, the channel consists of only one or three segments the - frequency step is 429kHz, 3*429 respectively. - - -.. _DTV-MODULATION: - -DTV_MODULATION -============== - -Specifies the frontend modulation type for delivery systems that -supports more multiple modulations. - -The modulation can be one of the types defined by enum :c:type:`fe_modulation`. - -Most of the digital TV standards offers more than one possible -modulation type. - -The table below presents a summary of the types of modulation types -supported by each delivery system, as currently defined by specs. - -======================= ======================================================= -Standard Modulation types -======================= ======================================================= -ATSC (version 1) 8-VSB and 16-VSB. -DMTB 4-QAM, 16-QAM, 32-QAM, 64-QAM and 4-QAM-NR. -DVB-C Annex A/C 16-QAM, 32-QAM, 64-QAM and 256-QAM. -DVB-C Annex B 64-QAM. -DVB-T QPSK, 16-QAM and 64-QAM. -DVB-T2 QPSK, 16-QAM, 64-QAM and 256-QAM. -DVB-S No need to set. It supports only QPSK. -DVB-S2 QPSK, 8-PSK, 16-APSK and 32-APSK. -ISDB-T QPSK, DQPSK, 16-QAM and 64-QAM. -ISDB-S 8-PSK, QPSK and BPSK. -======================= ======================================================= - -.. note:: - - Please notice that some of the above modulation types may not be - defined currently at the Kernel. The reason is simple: no driver - needed such definition yet. - - -.. _DTV-BANDWIDTH-HZ: - -DTV_BANDWIDTH_HZ -================ - -Bandwidth for the channel, in HZ. - -Should be set only for terrestrial delivery systems. - -Possible values: ``1712000``, ``5000000``, ``6000000``, ``7000000``, -``8000000``, ``10000000``. - -======================= ======================================================= -Terrestrial Standard Possible values for bandwidth -======================= ======================================================= -ATSC (version 1) No need to set. It is always 6MHz. -DMTB No need to set. It is always 8MHz. -DVB-T 6MHz, 7MHz and 8MHz. -DVB-T2 1.172 MHz, 5MHz, 6MHz, 7MHz, 8MHz and 10MHz -ISDB-T 5MHz, 6MHz, 7MHz and 8MHz, although most places - use 6MHz. -======================= ======================================================= - - -.. note:: - - - #. For ISDB-Tsb, the bandwidth can vary depending on the number of - connected segments. - - It can be easily derived from other parameters - (DTV_ISDBT_SB_SEGMENT_IDX, DTV_ISDBT_SB_SEGMENT_COUNT). - - #. On Satellite and Cable delivery systems, the bandwidth depends on - the symbol rate. So, the Kernel will silently ignore any setting - :ref:`DTV-BANDWIDTH-HZ`. I will however fill it back with a - bandwidth estimation. - - Such bandwidth estimation takes into account the symbol rate set with - :ref:`DTV-SYMBOL-RATE`, and the rolloff factor, with is fixed for - DVB-C and DVB-S. - - For DVB-S2, the rolloff should also be set via :ref:`DTV-ROLLOFF`. - - -.. _DTV-INVERSION: - -DTV_INVERSION -============= - -Specifies if the frontend should do spectral inversion or not. - -The acceptable values are defined by :c:type:`fe_spectral_inversion`. - - -.. _DTV-DISEQC-MASTER: - -DTV_DISEQC_MASTER -================= - -Currently not implemented. - - -.. _DTV-SYMBOL-RATE: - -DTV_SYMBOL_RATE -=============== - -Used on cable and satellite delivery systems. - -Digital TV symbol rate, in bauds (symbols/second). - - -.. _DTV-INNER-FEC: - -DTV_INNER_FEC -============= - -Used on cable and satellite delivery systems. - -The acceptable values are defined by :c:type:`fe_code_rate`. - - -.. _DTV-VOLTAGE: - -DTV_VOLTAGE -=========== - -Used on satellite delivery systems. - -The voltage is usually used with non-DiSEqC capable LNBs to switch the -polarzation (horizontal/vertical). When using DiSEqC epuipment this -voltage has to be switched consistently to the DiSEqC commands as -described in the DiSEqC spec. - -The acceptable values are defined by :c:type:`fe_sec_voltage`. - - -.. _DTV-TONE: - -DTV_TONE -======== - -Currently not used. - - -.. _DTV-PILOT: - -DTV_PILOT -========= - -Used on DVB-S2. - -Sets DVB-S2 pilot. - -The acceptable values are defined by :c:type:`fe_pilot`. - - -.. _DTV-ROLLOFF: - -DTV_ROLLOFF -=========== - -Used on DVB-S2. - -Sets DVB-S2 rolloff. - -The acceptable values are defined by :c:type:`fe_rolloff`. - - -.. _DTV-DISEQC-SLAVE-REPLY: - -DTV_DISEQC_SLAVE_REPLY -====================== - -Currently not implemented. - - -.. _DTV-FE-CAPABILITY-COUNT: - -DTV_FE_CAPABILITY_COUNT -======================= - -Currently not implemented. - - -.. _DTV-FE-CAPABILITY: - -DTV_FE_CAPABILITY -================= - -Currently not implemented. - - -.. _DTV-DELIVERY-SYSTEM: - -DTV_DELIVERY_SYSTEM -=================== - -Specifies the type of the delivery system. - -The acceptable values are defined by :c:type:`fe_delivery_system`. - - -.. _DTV-ISDBT-PARTIAL-RECEPTION: - -DTV_ISDBT_PARTIAL_RECEPTION -=========================== - -Used only on ISDB. - -If ``DTV_ISDBT_SOUND_BROADCASTING`` is '0' this bit-field represents -whether the channel is in partial reception mode or not. - -If '1' ``DTV_ISDBT_LAYERA_*`` values are assigned to the center segment -and ``DTV_ISDBT_LAYERA_SEGMENT_COUNT`` has to be '1'. - -If in addition ``DTV_ISDBT_SOUND_BROADCASTING`` is '1' -``DTV_ISDBT_PARTIAL_RECEPTION`` represents whether this ISDB-Tsb channel -is consisting of one segment and layer or three segments and two layers. - -Possible values: 0, 1, -1 (AUTO) - - -.. _DTV-ISDBT-SOUND-BROADCASTING: - -DTV_ISDBT_SOUND_BROADCASTING -============================ - -Used only on ISDB. - -This field represents whether the other DTV_ISDBT_*-parameters are -referring to an ISDB-T and an ISDB-Tsb channel. (See also -``DTV_ISDBT_PARTIAL_RECEPTION``). - -Possible values: 0, 1, -1 (AUTO) - - -.. _DTV-ISDBT-SB-SUBCHANNEL-ID: - -DTV_ISDBT_SB_SUBCHANNEL_ID -========================== - -Used only on ISDB. - -This field only applies if ``DTV_ISDBT_SOUND_BROADCASTING`` is '1'. - -(Note of the author: This might not be the correct description of the -``SUBCHANNEL-ID`` in all details, but it is my understanding of the -technical background needed to program a device) - -An ISDB-Tsb channel (1 or 3 segments) can be broadcasted alone or in a -set of connected ISDB-Tsb channels. In this set of channels every -channel can be received independently. The number of connected ISDB-Tsb -segment can vary, e.g. depending on the frequency spectrum bandwidth -available. - -Example: Assume 8 ISDB-Tsb connected segments are broadcasted. The -broadcaster has several possibilities to put those channels in the air: -Assuming a normal 13-segment ISDB-T spectrum he can align the 8 segments -from position 1-8 to 5-13 or anything in between. - -The underlying layer of segments are subchannels: each segment is -consisting of several subchannels with a predefined IDs. A sub-channel -is used to help the demodulator to synchronize on the channel. - -An ISDB-T channel is always centered over all sub-channels. As for the -example above, in ISDB-Tsb it is no longer as simple as that. - -``The DTV_ISDBT_SB_SUBCHANNEL_ID`` parameter is used to give the -sub-channel ID of the segment to be demodulated. - -Possible values: 0 .. 41, -1 (AUTO) - - -.. _DTV-ISDBT-SB-SEGMENT-IDX: - -DTV_ISDBT_SB_SEGMENT_IDX -======================== - -Used only on ISDB. - -This field only applies if ``DTV_ISDBT_SOUND_BROADCASTING`` is '1'. - -``DTV_ISDBT_SB_SEGMENT_IDX`` gives the index of the segment to be -demodulated for an ISDB-Tsb channel where several of them are -transmitted in the connected manner. - -Possible values: 0 .. ``DTV_ISDBT_SB_SEGMENT_COUNT`` - 1 - -Note: This value cannot be determined by an automatic channel search. - - -.. _DTV-ISDBT-SB-SEGMENT-COUNT: - -DTV_ISDBT_SB_SEGMENT_COUNT -========================== - -Used only on ISDB. - -This field only applies if ``DTV_ISDBT_SOUND_BROADCASTING`` is '1'. - -``DTV_ISDBT_SB_SEGMENT_COUNT`` gives the total count of connected -ISDB-Tsb channels. - -Possible values: 1 .. 13 - -Note: This value cannot be determined by an automatic channel search. - - -.. _isdb-hierq-layers: - -DTV-ISDBT-LAYER[A-C] parameters -=============================== - -Used only on ISDB. - -ISDB-T channels can be coded hierarchically. As opposed to DVB-T in -ISDB-T hierarchical layers can be decoded simultaneously. For that -reason a ISDB-T demodulator has 3 Viterbi and 3 Reed-Solomon decoders. - -ISDB-T has 3 hierarchical layers which each can use a part of the -available segments. The total number of segments over all layers has to -13 in ISDB-T. - -There are 3 parameter sets, for Layers A, B and C. - - -.. _DTV-ISDBT-LAYER-ENABLED: - -DTV_ISDBT_LAYER_ENABLED ------------------------ - -Used only on ISDB. - -Hierarchical reception in ISDB-T is achieved by enabling or disabling -layers in the decoding process. Setting all bits of -``DTV_ISDBT_LAYER_ENABLED`` to '1' forces all layers (if applicable) to -be demodulated. This is the default. - -If the channel is in the partial reception mode -(``DTV_ISDBT_PARTIAL_RECEPTION`` = 1) the central segment can be decoded -independently of the other 12 segments. In that mode layer A has to have -a ``SEGMENT_COUNT`` of 1. - -In ISDB-Tsb only layer A is used, it can be 1 or 3 in ISDB-Tsb according -to ``DTV_ISDBT_PARTIAL_RECEPTION``. ``SEGMENT_COUNT`` must be filled -accordingly. - -Only the values of the first 3 bits are used. Other bits will be silently ignored: - -``DTV_ISDBT_LAYER_ENABLED`` bit 0: layer A enabled - -``DTV_ISDBT_LAYER_ENABLED`` bit 1: layer B enabled - -``DTV_ISDBT_LAYER_ENABLED`` bit 2: layer C enabled - -``DTV_ISDBT_LAYER_ENABLED`` bits 3-31: unused - - -.. _DTV-ISDBT-LAYER-FEC: - -DTV_ISDBT_LAYER[A-C]_FEC ------------------------- - -Used only on ISDB. - -The Forward Error Correction mechanism used by a given ISDB Layer, as -defined by :c:type:`fe_code_rate`. - - -Possible values are: ``FEC_AUTO``, ``FEC_1_2``, ``FEC_2_3``, ``FEC_3_4``, -``FEC_5_6``, ``FEC_7_8`` - - -.. _DTV-ISDBT-LAYER-MODULATION: - -DTV_ISDBT_LAYER[A-C]_MODULATION -------------------------------- - -Used only on ISDB. - -The modulation used by a given ISDB Layer, as defined by -:c:type:`fe_modulation`. - -Possible values are: ``QAM_AUTO``, ``QPSK``, ``QAM_16``, ``QAM_64``, ``DQPSK`` - -.. note:: - - #. If layer C is ``DQPSK``, then layer B has to be ``DQPSK``. - - #. If layer B is ``DQPSK`` and ``DTV_ISDBT_PARTIAL_RECEPTION``\ = 0, - then layer has to be ``DQPSK``. - - -.. _DTV-ISDBT-LAYER-SEGMENT-COUNT: - -DTV_ISDBT_LAYER[A-C]_SEGMENT_COUNT ----------------------------------- - -Used only on ISDB. - -Possible values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, -1 (AUTO) - -Note: Truth table for ``DTV_ISDBT_SOUND_BROADCASTING`` and -``DTV_ISDBT_PARTIAL_RECEPTION`` and ``LAYER[A-C]_SEGMENT_COUNT`` - -.. _isdbt-layer_seg-cnt-table: - -.. flat-table:: Truth table for ISDB-T Sound Broadcasting - :header-rows: 1 - :stub-columns: 0 - - - - .. row 1 - - - Partial Reception - - - Sound Broadcasting - - - Layer A width - - - Layer B width - - - Layer C width - - - total width - - - .. row 2 - - - 0 - - - 0 - - - 1 .. 13 - - - 1 .. 13 - - - 1 .. 13 - - - 13 - - - .. row 3 - - - 1 - - - 0 - - - 1 - - - 1 .. 13 - - - 1 .. 13 - - - 13 - - - .. row 4 - - - 0 - - - 1 - - - 1 - - - 0 - - - 0 - - - 1 - - - .. row 5 - - - 1 - - - 1 - - - 1 - - - 2 - - - 0 - - - 13 - - - -.. _DTV-ISDBT-LAYER-TIME-INTERLEAVING: - -DTV_ISDBT_LAYER[A-C]_TIME_INTERLEAVING --------------------------------------- - -Used only on ISDB. - -Valid values: 0, 1, 2, 4, -1 (AUTO) - -when DTV_ISDBT_SOUND_BROADCASTING is active, value 8 is also valid. - -Note: The real time interleaving length depends on the mode (fft-size). -The values here are referring to what can be found in the -TMCC-structure, as shown in the table below. - - -.. c:type:: isdbt_layer_interleaving_table - -.. flat-table:: ISDB-T time interleaving modes - :header-rows: 1 - :stub-columns: 0 - - - - .. row 1 - - - ``DTV_ISDBT_LAYER[A-C]_TIME_INTERLEAVING`` - - - Mode 1 (2K FFT) - - - Mode 2 (4K FFT) - - - Mode 3 (8K FFT) - - - .. row 2 - - - 0 - - - 0 - - - 0 - - - 0 - - - .. row 3 - - - 1 - - - 4 - - - 2 - - - 1 - - - .. row 4 - - - 2 - - - 8 - - - 4 - - - 2 - - - .. row 5 - - - 4 - - - 16 - - - 8 - - - 4 - - - -.. _DTV-ATSCMH-FIC-VER: - -DTV_ATSCMH_FIC_VER ------------------- - -Used only on ATSC-MH. - -Version number of the FIC (Fast Information Channel) signaling data. - -FIC is used for relaying information to allow rapid service acquisition -by the receiver. - -Possible values: 0, 1, 2, 3, ..., 30, 31 - - -.. _DTV-ATSCMH-PARADE-ID: - -DTV_ATSCMH_PARADE_ID --------------------- - -Used only on ATSC-MH. - -Parade identification number - -A parade is a collection of up to eight MH groups, conveying one or two -ensembles. - -Possible values: 0, 1, 2, 3, ..., 126, 127 - - -.. _DTV-ATSCMH-NOG: - -DTV_ATSCMH_NOG --------------- - -Used only on ATSC-MH. - -Number of MH groups per MH subframe for a designated parade. - -Possible values: 1, 2, 3, 4, 5, 6, 7, 8 - - -.. _DTV-ATSCMH-TNOG: - -DTV_ATSCMH_TNOG ---------------- - -Used only on ATSC-MH. - -Total number of MH groups including all MH groups belonging to all MH -parades in one MH subframe. - -Possible values: 0, 1, 2, 3, ..., 30, 31 - - -.. _DTV-ATSCMH-SGN: - -DTV_ATSCMH_SGN --------------- - -Used only on ATSC-MH. - -Start group number. - -Possible values: 0, 1, 2, 3, ..., 14, 15 - - -.. _DTV-ATSCMH-PRC: - -DTV_ATSCMH_PRC --------------- - -Used only on ATSC-MH. - -Parade repetition cycle. - -Possible values: 1, 2, 3, 4, 5, 6, 7, 8 - - -.. _DTV-ATSCMH-RS-FRAME-MODE: - -DTV_ATSCMH_RS_FRAME_MODE ------------------------- - -Used only on ATSC-MH. - -Reed Solomon (RS) frame mode. - -The acceptable values are defined by :c:type:`atscmh_rs_frame_mode`. - - -.. _DTV-ATSCMH-RS-FRAME-ENSEMBLE: - -DTV_ATSCMH_RS_FRAME_ENSEMBLE ----------------------------- - -Used only on ATSC-MH. - -Reed Solomon(RS) frame ensemble. - -The acceptable values are defined by :c:type:`atscmh_rs_frame_ensemble`. - - -.. _DTV-ATSCMH-RS-CODE-MODE-PRI: - -DTV_ATSCMH_RS_CODE_MODE_PRI ---------------------------- - -Used only on ATSC-MH. - -Reed Solomon (RS) code mode (primary). - -The acceptable values are defined by :c:type:`atscmh_rs_code_mode`. - - -.. _DTV-ATSCMH-RS-CODE-MODE-SEC: - -DTV_ATSCMH_RS_CODE_MODE_SEC ---------------------------- - -Used only on ATSC-MH. - -Reed Solomon (RS) code mode (secondary). - -The acceptable values are defined by :c:type:`atscmh_rs_code_mode`. - - -.. _DTV-ATSCMH-SCCC-BLOCK-MODE: - -DTV_ATSCMH_SCCC_BLOCK_MODE --------------------------- - -Used only on ATSC-MH. - -Series Concatenated Convolutional Code Block Mode. - -The acceptable values are defined by :c:type:`atscmh_sccc_block_mode`. - - -.. _DTV-ATSCMH-SCCC-CODE-MODE-A: - -DTV_ATSCMH_SCCC_CODE_MODE_A ---------------------------- - -Used only on ATSC-MH. - -Series Concatenated Convolutional Code Rate. - -The acceptable values are defined by :c:type:`atscmh_sccc_code_mode`. - -.. _DTV-ATSCMH-SCCC-CODE-MODE-B: - -DTV_ATSCMH_SCCC_CODE_MODE_B ---------------------------- - -Used only on ATSC-MH. - -Series Concatenated Convolutional Code Rate. - -Possible values are the same as documented on enum -:c:type:`atscmh_sccc_code_mode`. - - -.. _DTV-ATSCMH-SCCC-CODE-MODE-C: - -DTV_ATSCMH_SCCC_CODE_MODE_C ---------------------------- - -Used only on ATSC-MH. - -Series Concatenated Convolutional Code Rate. - -Possible values are the same as documented on enum -:c:type:`atscmh_sccc_code_mode`. - - -.. _DTV-ATSCMH-SCCC-CODE-MODE-D: - -DTV_ATSCMH_SCCC_CODE_MODE_D ---------------------------- - -Used only on ATSC-MH. - -Series Concatenated Convolutional Code Rate. - -Possible values are the same as documented on enum -:c:type:`atscmh_sccc_code_mode`. - - -.. _DTV-API-VERSION: - -DTV_API_VERSION -=============== - -Returns the major/minor version of the Digital TV API - - -.. _DTV-CODE-RATE-HP: - -DTV_CODE_RATE_HP -================ - -Used on terrestrial transmissions. - -The acceptable values are defined by :c:type:`fe_transmit_mode`. - - -.. _DTV-CODE-RATE-LP: - -DTV_CODE_RATE_LP -================ - -Used on terrestrial transmissions. - -The acceptable values are defined by :c:type:`fe_transmit_mode`. - - -.. _DTV-GUARD-INTERVAL: - -DTV_GUARD_INTERVAL -================== - -The acceptable values are defined by :c:type:`fe_guard_interval`. - -.. note:: - - #. If ``DTV_GUARD_INTERVAL`` is set the ``GUARD_INTERVAL_AUTO`` the - hardware will try to find the correct guard interval (if capable) and - will use TMCC to fill in the missing parameters. - #. Intervals ``GUARD_INTERVAL_1_128``, ``GUARD_INTERVAL_19_128`` - and ``GUARD_INTERVAL_19_256`` are used only for DVB-T2 at - present. - #. Intervals ``GUARD_INTERVAL_PN420``, ``GUARD_INTERVAL_PN595`` and - ``GUARD_INTERVAL_PN945`` are used only for DMTB at the present. - On such standard, only those intervals and ``GUARD_INTERVAL_AUTO`` - are valid. - -.. _DTV-TRANSMISSION-MODE: - -DTV_TRANSMISSION_MODE -===================== - - -Used only on OFTM-based standards, e. g. DVB-T/T2, ISDB-T, DTMB. - -Specifies the FFT size (with corresponds to the approximate number of -carriers) used by the standard. - -The acceptable values are defined by :c:type:`fe_transmit_mode`. - -.. note:: - - #. ISDB-T supports three carrier/symbol-size: 8K, 4K, 2K. It is called - **mode** on such standard, and are numbered from 1 to 3: - - ==== ======== ======================== - Mode FFT size Transmission mode - ==== ======== ======================== - 1 2K ``TRANSMISSION_MODE_2K`` - 2 4K ``TRANSMISSION_MODE_4K`` - 3 8K ``TRANSMISSION_MODE_8K`` - ==== ======== ======================== - - #. If ``DTV_TRANSMISSION_MODE`` is set the ``TRANSMISSION_MODE_AUTO`` - the hardware will try to find the correct FFT-size (if capable) and - will use TMCC to fill in the missing parameters. - - #. DVB-T specifies 2K and 8K as valid sizes. - - #. DVB-T2 specifies 1K, 2K, 4K, 8K, 16K and 32K. - - #. DTMB specifies C1 and C3780. - - -.. _DTV-HIERARCHY: - -DTV_HIERARCHY -============= - -Used only on DVB-T and DVB-T2. - -Frontend hierarchy. - -The acceptable values are defined by :c:type:`fe_hierarchy`. - - -.. _DTV-STREAM-ID: - -DTV_STREAM_ID -============= - -Used on DVB-S2, DVB-T2 and ISDB-S. - -DVB-S2, DVB-T2 and ISDB-S support the transmission of several streams on -a single transport stream. This property enables the digital TV driver to -handle substream filtering, when supported by the hardware. By default, -substream filtering is disabled. - -For DVB-S2 and DVB-T2, the valid substream id range is from 0 to 255. - -For ISDB, the valid substream id range is from 1 to 65535. - -To disable it, you should use the special macro NO_STREAM_ID_FILTER. - -Note: any value outside the id range also disables filtering. - - -.. _DTV-DVBT2-PLP-ID-LEGACY: - -DTV_DVBT2_PLP_ID_LEGACY -======================= - -Obsolete, replaced with DTV_STREAM_ID. - - -.. _DTV-ENUM-DELSYS: - -DTV_ENUM_DELSYS -=============== - -A Multi standard frontend needs to advertise the delivery systems -provided. Applications need to enumerate the provided delivery systems, -before using any other operation with the frontend. Prior to it's -introduction, FE_GET_INFO was used to determine a frontend type. A -frontend which provides more than a single delivery system, -FE_GET_INFO doesn't help much. Applications which intends to use a -multistandard frontend must enumerate the delivery systems associated -with it, rather than trying to use FE_GET_INFO. In the case of a -legacy frontend, the result is just the same as with FE_GET_INFO, but -in a more structured format - -The acceptable values are defined by :c:type:`fe_delivery_system`. - - -.. _DTV-INTERLEAVING: - -DTV_INTERLEAVING -================ - -Time interleaving to be used. - -The acceptable values are defined by :c:type:`fe_interleaving`. - - -.. _DTV-LNA: - -DTV_LNA -======= - -Low-noise amplifier. - -Hardware might offer controllable LNA which can be set manually using -that parameter. Usually LNA could be found only from terrestrial devices -if at all. - -Possible values: 0, 1, LNA_AUTO - -0, LNA off - -1, LNA on - -use the special macro LNA_AUTO to set LNA auto - - -.. _DTV-SCRAMBLING-SEQUENCE-INDEX: - -DTV_SCRAMBLING_SEQUENCE_INDEX -============================= - -Used on DVB-S2. - -This 18 bit field, when present, carries the index of the DVB-S2 physical -layer scrambling sequence as defined in clause 5.5.4 of EN 302 307. -There is no explicit signalling method to convey scrambling sequence index -to the receiver. If S2 satellite delivery system descriptor is available -it can be used to read the scrambling sequence index (EN 300 468 table 41). - -By default, gold scrambling sequence index 0 is used. - -The valid scrambling sequence index range is from 0 to 262142. diff --git a/Documentation/media/uapi/dvb/frontend-header.rst b/Documentation/media/uapi/dvb/frontend-header.rst deleted file mode 100644 index 635fb4251214..000000000000 --- a/Documentation/media/uapi/dvb/frontend-header.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -Frontend uAPI data types -======================== - -.. kernel-doc:: include/uapi/linux/dvb/frontend.h diff --git a/Documentation/media/uapi/dvb/frontend-property-cable-systems.rst b/Documentation/media/uapi/dvb/frontend-property-cable-systems.rst deleted file mode 100644 index 97fbfc228c10..000000000000 --- a/Documentation/media/uapi/dvb/frontend-property-cable-systems.rst +++ /dev/null @@ -1,82 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _frontend-property-cable-systems: - -***************************************** -Properties used on cable delivery systems -***************************************** - - -.. _dvbc-params: - -DVB-C delivery system -===================== - -The DVB-C Annex-A is the widely used cable standard. Transmission uses -QAM modulation. - -The DVB-C Annex-C is optimized for 6MHz, and is used in Japan. It -supports a subset of the Annex A modulation types, and a roll-off of -0.13, instead of 0.15 - -The following parameters are valid for DVB-C Annex A/C: - -- :ref:`DTV_API_VERSION ` - -- :ref:`DTV_DELIVERY_SYSTEM ` - -- :ref:`DTV_TUNE ` - -- :ref:`DTV_CLEAR ` - -- :ref:`DTV_FREQUENCY ` - -- :ref:`DTV_MODULATION ` - -- :ref:`DTV_INVERSION ` - -- :ref:`DTV_SYMBOL_RATE ` - -- :ref:`DTV_INNER_FEC ` - -- :ref:`DTV_LNA ` - -In addition, the :ref:`DTV QoS statistics ` -are also valid. - - -.. _dvbc-annex-b-params: - -DVB-C Annex B delivery system -============================= - -The DVB-C Annex-B is only used on a few Countries like the United -States. - -The following parameters are valid for DVB-C Annex B: - -- :ref:`DTV_API_VERSION ` - -- :ref:`DTV_DELIVERY_SYSTEM ` - -- :ref:`DTV_TUNE ` - -- :ref:`DTV_CLEAR ` - -- :ref:`DTV_FREQUENCY ` - -- :ref:`DTV_MODULATION ` - -- :ref:`DTV_INVERSION ` - -- :ref:`DTV_LNA ` - -In addition, the :ref:`DTV QoS statistics ` -are also valid. diff --git a/Documentation/media/uapi/dvb/frontend-property-satellite-systems.rst b/Documentation/media/uapi/dvb/frontend-property-satellite-systems.rst deleted file mode 100644 index 2bc880a3c826..000000000000 --- a/Documentation/media/uapi/dvb/frontend-property-satellite-systems.rst +++ /dev/null @@ -1,112 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _frontend-property-satellite-systems: - -********************************************* -Properties used on satellite delivery systems -********************************************* - - -.. _dvbs-params: - -DVB-S delivery system -===================== - -The following parameters are valid for DVB-S: - -- :ref:`DTV_API_VERSION ` - -- :ref:`DTV_DELIVERY_SYSTEM ` - -- :ref:`DTV_TUNE ` - -- :ref:`DTV_CLEAR ` - -- :ref:`DTV_FREQUENCY ` - -- :ref:`DTV_INVERSION ` - -- :ref:`DTV_SYMBOL_RATE ` - -- :ref:`DTV_INNER_FEC ` - -- :ref:`DTV_VOLTAGE ` - -- :ref:`DTV_TONE ` - -In addition, the :ref:`DTV QoS statistics ` -are also valid. - -Future implementations might add those two missing parameters: - -- :ref:`DTV_DISEQC_MASTER ` - -- :ref:`DTV_DISEQC_SLAVE_REPLY ` - - -.. _dvbs2-params: - -DVB-S2 delivery system -====================== - -In addition to all parameters valid for DVB-S, DVB-S2 supports the -following parameters: - -- :ref:`DTV_MODULATION ` - -- :ref:`DTV_PILOT ` - -- :ref:`DTV_ROLLOFF ` - -- :ref:`DTV_STREAM_ID ` - -- :ref:`DTV_SCRAMBLING_SEQUENCE_INDEX ` - -In addition, the :ref:`DTV QoS statistics ` -are also valid. - - -.. _turbo-params: - -Turbo code delivery system -========================== - -In addition to all parameters valid for DVB-S, turbo code supports the -following parameters: - -- :ref:`DTV_MODULATION ` - - -.. _isdbs-params: - -ISDB-S delivery system -====================== - -The following parameters are valid for ISDB-S: - -- :ref:`DTV_API_VERSION ` - -- :ref:`DTV_DELIVERY_SYSTEM ` - -- :ref:`DTV_TUNE ` - -- :ref:`DTV_CLEAR ` - -- :ref:`DTV_FREQUENCY ` - -- :ref:`DTV_INVERSION ` - -- :ref:`DTV_SYMBOL_RATE ` - -- :ref:`DTV_INNER_FEC ` - -- :ref:`DTV_VOLTAGE ` - -- :ref:`DTV_STREAM_ID ` diff --git a/Documentation/media/uapi/dvb/frontend-property-terrestrial-systems.rst b/Documentation/media/uapi/dvb/frontend-property-terrestrial-systems.rst deleted file mode 100644 index c20af13297e5..000000000000 --- a/Documentation/media/uapi/dvb/frontend-property-terrestrial-systems.rst +++ /dev/null @@ -1,301 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _frontend-property-terrestrial-systems: - -*********************************************** -Properties used on terrestrial delivery systems -*********************************************** - - -.. _dvbt-params: - -DVB-T delivery system -===================== - -The following parameters are valid for DVB-T: - -- :ref:`DTV_API_VERSION ` - -- :ref:`DTV_DELIVERY_SYSTEM ` - -- :ref:`DTV_TUNE ` - -- :ref:`DTV_CLEAR ` - -- :ref:`DTV_FREQUENCY ` - -- :ref:`DTV_MODULATION ` - -- :ref:`DTV_BANDWIDTH_HZ ` - -- :ref:`DTV_INVERSION ` - -- :ref:`DTV_CODE_RATE_HP ` - -- :ref:`DTV_CODE_RATE_LP ` - -- :ref:`DTV_GUARD_INTERVAL ` - -- :ref:`DTV_TRANSMISSION_MODE ` - -- :ref:`DTV_HIERARCHY ` - -- :ref:`DTV_LNA ` - -In addition, the :ref:`DTV QoS statistics ` -are also valid. - - -.. _dvbt2-params: - -DVB-T2 delivery system -====================== - -DVB-T2 support is currently in the early stages of development, so -expect that this section maygrow and become more detailed with time. - -The following parameters are valid for DVB-T2: - -- :ref:`DTV_API_VERSION ` - -- :ref:`DTV_DELIVERY_SYSTEM ` - -- :ref:`DTV_TUNE ` - -- :ref:`DTV_CLEAR ` - -- :ref:`DTV_FREQUENCY ` - -- :ref:`DTV_MODULATION ` - -- :ref:`DTV_BANDWIDTH_HZ ` - -- :ref:`DTV_INVERSION ` - -- :ref:`DTV_CODE_RATE_HP ` - -- :ref:`DTV_CODE_RATE_LP ` - -- :ref:`DTV_GUARD_INTERVAL ` - -- :ref:`DTV_TRANSMISSION_MODE ` - -- :ref:`DTV_HIERARCHY ` - -- :ref:`DTV_STREAM_ID ` - -- :ref:`DTV_LNA ` - -In addition, the :ref:`DTV QoS statistics ` -are also valid. - - -.. _isdbt: - -ISDB-T delivery system -====================== - -This ISDB-T/ISDB-Tsb API extension should reflect all information needed -to tune any ISDB-T/ISDB-Tsb hardware. Of course it is possible that some -very sophisticated devices won't need certain parameters to tune. - -The information given here should help application writers to know how -to handle ISDB-T and ISDB-Tsb hardware using the Linux Digital TV API. - -The details given here about ISDB-T and ISDB-Tsb are just enough to -basically show the dependencies between the needed parameter values, but -surely some information is left out. For more detailed information see -the following documents: - -ARIB STD-B31 - "Transmission System for Digital Terrestrial Television -Broadcasting" and - -ARIB TR-B14 - "Operational Guidelines for Digital Terrestrial Television -Broadcasting". - -In order to understand the ISDB specific parameters, one has to have -some knowledge the channel structure in ISDB-T and ISDB-Tsb. I.e. it has -to be known to the reader that an ISDB-T channel consists of 13 -segments, that it can have up to 3 layer sharing those segments, and -things like that. - -The following parameters are valid for ISDB-T: - -- :ref:`DTV_API_VERSION ` - -- :ref:`DTV_DELIVERY_SYSTEM ` - -- :ref:`DTV_TUNE ` - -- :ref:`DTV_CLEAR ` - -- :ref:`DTV_FREQUENCY ` - -- :ref:`DTV_BANDWIDTH_HZ ` - -- :ref:`DTV_INVERSION ` - -- :ref:`DTV_GUARD_INTERVAL ` - -- :ref:`DTV_TRANSMISSION_MODE ` - -- :ref:`DTV_ISDBT_LAYER_ENABLED ` - -- :ref:`DTV_ISDBT_PARTIAL_RECEPTION ` - -- :ref:`DTV_ISDBT_SOUND_BROADCASTING ` - -- :ref:`DTV_ISDBT_SB_SUBCHANNEL_ID ` - -- :ref:`DTV_ISDBT_SB_SEGMENT_IDX ` - -- :ref:`DTV_ISDBT_SB_SEGMENT_COUNT ` - -- :ref:`DTV_ISDBT_LAYERA_FEC ` - -- :ref:`DTV_ISDBT_LAYERA_MODULATION ` - -- :ref:`DTV_ISDBT_LAYERA_SEGMENT_COUNT ` - -- :ref:`DTV_ISDBT_LAYERA_TIME_INTERLEAVING ` - -- :ref:`DTV_ISDBT_LAYERB_FEC ` - -- :ref:`DTV_ISDBT_LAYERB_MODULATION ` - -- :ref:`DTV_ISDBT_LAYERB_SEGMENT_COUNT ` - -- :ref:`DTV_ISDBT_LAYERB_TIME_INTERLEAVING ` - -- :ref:`DTV_ISDBT_LAYERC_FEC ` - -- :ref:`DTV_ISDBT_LAYERC_MODULATION ` - -- :ref:`DTV_ISDBT_LAYERC_SEGMENT_COUNT ` - -- :ref:`DTV_ISDBT_LAYERC_TIME_INTERLEAVING ` - -In addition, the :ref:`DTV QoS statistics ` -are also valid. - - -.. _atsc-params: - -ATSC delivery system -==================== - -The following parameters are valid for ATSC: - -- :ref:`DTV_API_VERSION ` - -- :ref:`DTV_DELIVERY_SYSTEM ` - -- :ref:`DTV_TUNE ` - -- :ref:`DTV_CLEAR ` - -- :ref:`DTV_FREQUENCY ` - -- :ref:`DTV_MODULATION ` - -- :ref:`DTV_BANDWIDTH_HZ ` - -In addition, the :ref:`DTV QoS statistics ` -are also valid. - - -.. _atscmh-params: - -ATSC-MH delivery system -======================= - -The following parameters are valid for ATSC-MH: - -- :ref:`DTV_API_VERSION ` - -- :ref:`DTV_DELIVERY_SYSTEM ` - -- :ref:`DTV_TUNE ` - -- :ref:`DTV_CLEAR ` - -- :ref:`DTV_FREQUENCY ` - -- :ref:`DTV_BANDWIDTH_HZ ` - -- :ref:`DTV_ATSCMH_FIC_VER ` - -- :ref:`DTV_ATSCMH_PARADE_ID ` - -- :ref:`DTV_ATSCMH_NOG ` - -- :ref:`DTV_ATSCMH_TNOG ` - -- :ref:`DTV_ATSCMH_SGN ` - -- :ref:`DTV_ATSCMH_PRC ` - -- :ref:`DTV_ATSCMH_RS_FRAME_MODE ` - -- :ref:`DTV_ATSCMH_RS_FRAME_ENSEMBLE ` - -- :ref:`DTV_ATSCMH_RS_CODE_MODE_PRI ` - -- :ref:`DTV_ATSCMH_RS_CODE_MODE_SEC ` - -- :ref:`DTV_ATSCMH_SCCC_BLOCK_MODE ` - -- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_A ` - -- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_B ` - -- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_C ` - -- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_D ` - -In addition, the :ref:`DTV QoS statistics ` -are also valid. - - -.. _dtmb-params: - -DTMB delivery system -==================== - -The following parameters are valid for DTMB: - -- :ref:`DTV_API_VERSION ` - -- :ref:`DTV_DELIVERY_SYSTEM ` - -- :ref:`DTV_TUNE ` - -- :ref:`DTV_CLEAR ` - -- :ref:`DTV_FREQUENCY ` - -- :ref:`DTV_MODULATION ` - -- :ref:`DTV_BANDWIDTH_HZ ` - -- :ref:`DTV_INVERSION ` - -- :ref:`DTV_INNER_FEC ` - -- :ref:`DTV_GUARD_INTERVAL ` - -- :ref:`DTV_TRANSMISSION_MODE ` - -- :ref:`DTV_INTERLEAVING ` - -- :ref:`DTV_LNA ` - -In addition, the :ref:`DTV QoS statistics ` -are also valid. diff --git a/Documentation/media/uapi/dvb/frontend-stat-properties.rst b/Documentation/media/uapi/dvb/frontend-stat-properties.rst deleted file mode 100644 index 546464db04b5..000000000000 --- a/Documentation/media/uapi/dvb/frontend-stat-properties.rst +++ /dev/null @@ -1,252 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _frontend-stat-properties: - -****************************** -Frontend statistics indicators -****************************** - -The values are returned via ``dtv_property.stat``. If the property is -supported, ``dtv_property.stat.len`` is bigger than zero. - -For most delivery systems, ``dtv_property.stat.len`` will be 1 if the -stats is supported, and the properties will return a single value for -each parameter. - -It should be noted, however, that new OFDM delivery systems like ISDB -can use different modulation types for each group of carriers. On such -standards, up to 3 groups of statistics can be provided, and -``dtv_property.stat.len`` is updated to reflect the "global" metrics, -plus one metric per each carrier group (called "layer" on ISDB). - -So, in order to be consistent with other delivery systems, the first -value at :c:type:`dtv_property.stat.dtv_stats ` array refers -to the global metric. The other elements of the array represent each -layer, starting from layer A(index 1), layer B (index 2) and so on. - -The number of filled elements are stored at ``dtv_property.stat.len``. - -Each element of the ``dtv_property.stat.dtv_stats`` array consists on -two elements: - -- ``svalue`` or ``uvalue``, where ``svalue`` is for signed values of - the measure (dB measures) and ``uvalue`` is for unsigned values - (counters, relative scale) - -- ``scale`` - Scale for the value. It can be: - - - ``FE_SCALE_NOT_AVAILABLE`` - The parameter is supported by the - frontend, but it was not possible to collect it (could be a - transitory or permanent condition) - - - ``FE_SCALE_DECIBEL`` - parameter is a signed value, measured in - 1/1000 dB - - - ``FE_SCALE_RELATIVE`` - parameter is a unsigned value, where 0 - means 0% and 65535 means 100%. - - - ``FE_SCALE_COUNTER`` - parameter is a unsigned value that counts - the occurrence of an event, like bit error, block error, or lapsed - time. - - -.. _DTV-STAT-SIGNAL-STRENGTH: - -DTV_STAT_SIGNAL_STRENGTH -======================== - -Indicates the signal strength level at the analog part of the tuner or -of the demod. - -Possible scales for this metric are: - -- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the - measurement was not complete yet. - -- ``FE_SCALE_DECIBEL`` - signal strength is in 0.001 dBm units, power - measured in miliwatts. This value is generally negative. - -- ``FE_SCALE_RELATIVE`` - The frontend provides a 0% to 100% - measurement for power (actually, 0 to 65535). - - -.. _DTV-STAT-CNR: - -DTV_STAT_CNR -============ - -Indicates the Signal to Noise ratio for the main carrier. - -Possible scales for this metric are: - -- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the - measurement was not complete yet. - -- ``FE_SCALE_DECIBEL`` - Signal/Noise ratio is in 0.001 dB units. - -- ``FE_SCALE_RELATIVE`` - The frontend provides a 0% to 100% - measurement for Signal/Noise (actually, 0 to 65535). - - -.. _DTV-STAT-PRE-ERROR-BIT-COUNT: - -DTV_STAT_PRE_ERROR_BIT_COUNT -============================ - -Measures the number of bit errors before the forward error correction -(FEC) on the inner coding block (before Viterbi, LDPC or other inner -code). - -This measure is taken during the same interval as -``DTV_STAT_PRE_TOTAL_BIT_COUNT``. - -In order to get the BER (Bit Error Rate) measurement, it should be -divided by -:ref:`DTV_STAT_PRE_TOTAL_BIT_COUNT `. - -This measurement is monotonically increased, as the frontend gets more -bit count measurements. The frontend may reset it when a -channel/transponder is tuned. - -Possible scales for this metric are: - -- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the - measurement was not complete yet. - -- ``FE_SCALE_COUNTER`` - Number of error bits counted before the inner - coding. - - -.. _DTV-STAT-PRE-TOTAL-BIT-COUNT: - -DTV_STAT_PRE_TOTAL_BIT_COUNT -============================ - -Measures the amount of bits received before the inner code block, during -the same period as -:ref:`DTV_STAT_PRE_ERROR_BIT_COUNT ` -measurement was taken. - -It should be noted that this measurement can be smaller than the total -amount of bits on the transport stream, as the frontend may need to -manually restart the measurement, losing some data between each -measurement interval. - -This measurement is monotonically increased, as the frontend gets more -bit count measurements. The frontend may reset it when a -channel/transponder is tuned. - -Possible scales for this metric are: - -- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the - measurement was not complete yet. - -- ``FE_SCALE_COUNTER`` - Number of bits counted while measuring - :ref:`DTV_STAT_PRE_ERROR_BIT_COUNT `. - - -.. _DTV-STAT-POST-ERROR-BIT-COUNT: - -DTV_STAT_POST_ERROR_BIT_COUNT -============================= - -Measures the number of bit errors after the forward error correction -(FEC) done by inner code block (after Viterbi, LDPC or other inner -code). - -This measure is taken during the same interval as -``DTV_STAT_POST_TOTAL_BIT_COUNT``. - -In order to get the BER (Bit Error Rate) measurement, it should be -divided by -:ref:`DTV_STAT_POST_TOTAL_BIT_COUNT `. - -This measurement is monotonically increased, as the frontend gets more -bit count measurements. The frontend may reset it when a -channel/transponder is tuned. - -Possible scales for this metric are: - -- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the - measurement was not complete yet. - -- ``FE_SCALE_COUNTER`` - Number of error bits counted after the inner - coding. - - -.. _DTV-STAT-POST-TOTAL-BIT-COUNT: - -DTV_STAT_POST_TOTAL_BIT_COUNT -============================= - -Measures the amount of bits received after the inner coding, during the -same period as -:ref:`DTV_STAT_POST_ERROR_BIT_COUNT ` -measurement was taken. - -It should be noted that this measurement can be smaller than the total -amount of bits on the transport stream, as the frontend may need to -manually restart the measurement, losing some data between each -measurement interval. - -This measurement is monotonically increased, as the frontend gets more -bit count measurements. The frontend may reset it when a -channel/transponder is tuned. - -Possible scales for this metric are: - -- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the - measurement was not complete yet. - -- ``FE_SCALE_COUNTER`` - Number of bits counted while measuring - :ref:`DTV_STAT_POST_ERROR_BIT_COUNT `. - - -.. _DTV-STAT-ERROR-BLOCK-COUNT: - -DTV_STAT_ERROR_BLOCK_COUNT -========================== - -Measures the number of block errors after the outer forward error -correction coding (after Reed-Solomon or other outer code). - -This measurement is monotonically increased, as the frontend gets more -bit count measurements. The frontend may reset it when a -channel/transponder is tuned. - -Possible scales for this metric are: - -- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the - measurement was not complete yet. - -- ``FE_SCALE_COUNTER`` - Number of error blocks counted after the outer - coding. - - -.. _DTV-STAT-TOTAL-BLOCK-COUNT: - -DTV-STAT_TOTAL_BLOCK_COUNT -========================== - -Measures the total number of blocks received during the same period as -:ref:`DTV_STAT_ERROR_BLOCK_COUNT ` -measurement was taken. - -It can be used to calculate the PER indicator, by dividing -:ref:`DTV_STAT_ERROR_BLOCK_COUNT ` by -:ref:`DTV-STAT-TOTAL-BLOCK-COUNT`. - -Possible scales for this metric are: - -- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the - measurement was not complete yet. - -- ``FE_SCALE_COUNTER`` - Number of blocks counted while measuring - :ref:`DTV_STAT_ERROR_BLOCK_COUNT `. diff --git a/Documentation/media/uapi/dvb/frontend.rst b/Documentation/media/uapi/dvb/frontend.rst deleted file mode 100644 index 7ff225dfe11c..000000000000 --- a/Documentation/media/uapi/dvb/frontend.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dvb_frontend: - -####################### -Digital TV Frontend API -####################### - -The Digital TV frontend API was designed to support three groups of delivery -systems: Terrestrial, cable and Satellite. Currently, the following -delivery systems are supported: - -- Terrestrial systems: DVB-T, DVB-T2, ATSC, ATSC M/H, ISDB-T, DVB-H, - DTMB, CMMB - -- Cable systems: DVB-C Annex A/C, ClearQAM (DVB-C Annex B) - -- Satellite systems: DVB-S, DVB-S2, DVB Turbo, ISDB-S, DSS - -The Digital TV frontend controls several sub-devices including: - -- Tuner - -- Digital TV demodulator - -- Low noise amplifier (LNA) - -- Satellite Equipment Control (SEC) [#f1]_. - -The frontend can be accessed through ``/dev/dvb/adapter?/frontend?``. -Data types and ioctl definitions can be accessed by including -``linux/dvb/frontend.h`` in your application. - -.. note:: - - Transmission via the internet (DVB-IP) and MMT (MPEG Media Transport) - is not yet handled by this API but a future extension is possible. - -.. [#f1] - - On Satellite systems, the API support for the Satellite Equipment - Control (SEC) allows to power control and to send/receive signals to - control the antenna subsystem, selecting the polarization and choosing - the Intermediate Frequency IF) of the Low Noise Block Converter Feed - Horn (LNBf). It supports the DiSEqC and V-SEC protocols. The DiSEqC - (digital SEC) specification is available at - `Eutelsat `__. - - -.. toctree:: - :maxdepth: 1 - - query-dvb-frontend-info - dvb-fe-read-status - dvbproperty - frontend_fcalls diff --git a/Documentation/media/uapi/dvb/frontend_f_close.rst b/Documentation/media/uapi/dvb/frontend_f_close.rst deleted file mode 100644 index af87c2a83719..000000000000 --- a/Documentation/media/uapi/dvb/frontend_f_close.rst +++ /dev/null @@ -1,57 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _frontend_f_close: - -*************************** -Digital TV frontend close() -*************************** - -Name -==== - -fe-close - Close a frontend device - - -Synopsis -======== - -.. code-block:: c - - #include - - -.. c:function:: int close( int fd ) - :name: dvb-fe-close - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - - -Description -=========== - -This system call closes a previously opened front-end device. After -closing a front-end device, its corresponding hardware might be powered -down automatically. - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/frontend_f_open.rst b/Documentation/media/uapi/dvb/frontend_f_open.rst deleted file mode 100644 index 6a46ec5acf7b..000000000000 --- a/Documentation/media/uapi/dvb/frontend_f_open.rst +++ /dev/null @@ -1,117 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _frontend_f_open: - -*************************** -Digital TV frontend open() -*************************** - -Name -==== - -fe-open - Open a frontend device - - -Synopsis -======== - -.. code-block:: c - - #include - - -.. c:function:: int open( const char *device_name, int flags ) - :name: dvb-fe-open - -Arguments -========= - -``device_name`` - Device to be opened. - -``flags`` - Open flags. Access can either be ``O_RDWR`` or ``O_RDONLY``. - - Multiple opens are allowed with ``O_RDONLY``. In this mode, only - query and read ioctls are allowed. - - Only one open is allowed in ``O_RDWR``. In this mode, all ioctls are - allowed. - - When the ``O_NONBLOCK`` flag is given, the system calls may return - ``EAGAIN`` error code when no data is available or when the device - driver is temporarily busy. - - Other flags have no effect. - - -Description -=========== - -This system call opens a named frontend device -(``/dev/dvb/adapter?/frontend?``) for subsequent use. Usually the first -thing to do after a successful open is to find out the frontend type -with :ref:`FE_GET_INFO`. - -The device can be opened in read-only mode, which only allows monitoring -of device status and statistics, or read/write mode, which allows any -kind of use (e.g. performing tuning operations.) - -In a system with multiple front-ends, it is usually the case that -multiple devices cannot be open in read/write mode simultaneously. As -long as a front-end device is opened in read/write mode, other open() -calls in read/write mode will either fail or block, depending on whether -non-blocking or blocking mode was specified. A front-end device opened -in blocking mode can later be put into non-blocking mode (and vice -versa) using the F_SETFL command of the fcntl system call. This is a -standard system call, documented in the Linux manual page for fcntl. -When an open() call has succeeded, the device will be ready for use in -the specified mode. This implies that the corresponding hardware is -powered up, and that other front-ends may have been powered down to make -that possible. - - -Return Value -============ - -On success :ref:`open() ` returns the new file descriptor. -On error, -1 is returned, and the ``errno`` variable is set appropriately. - -Possible error codes are: - - -On success 0 is returned, and :c:type:`ca_slot_info` is filled. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 16 - - - - ``EPERM`` - - The caller has no permission to access the device. - - - - ``EBUSY`` - - The the device driver is already in use. - - - - ``EMFILE`` - - The process already has the maximum number of files open. - - - - ``ENFILE`` - - The limit on the total number of files open on the system has been - reached. - - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/frontend_fcalls.rst b/Documentation/media/uapi/dvb/frontend_fcalls.rst deleted file mode 100644 index 9b3586f538ea..000000000000 --- a/Documentation/media/uapi/dvb/frontend_fcalls.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _frontend_fcalls: - -####################### -Frontend Function Calls -####################### - -.. toctree:: - :maxdepth: 1 - - frontend_f_open - frontend_f_close - fe-get-info - fe-read-status - fe-get-property - fe-diseqc-reset-overload - fe-diseqc-send-master-cmd - fe-diseqc-recv-slave-reply - fe-diseqc-send-burst - fe-set-tone - fe-set-voltage - fe-enable-high-lnb-voltage - fe-set-frontend-tune-mode diff --git a/Documentation/media/uapi/dvb/frontend_legacy_api.rst b/Documentation/media/uapi/dvb/frontend_legacy_api.rst deleted file mode 100644 index 1ea749d09ca2..000000000000 --- a/Documentation/media/uapi/dvb/frontend_legacy_api.rst +++ /dev/null @@ -1,45 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _frontend_legacy_types: - -Frontend Legacy Data Types -========================== - - -.. toctree:: - :maxdepth: 1 - - fe-type-t - fe-bandwidth-t - dvb-frontend-parameters - dvb-frontend-event - - -.. _frontend_legacy_fcalls: - -Frontend Legacy Function Calls -============================== - -Those functions are defined at DVB version 3. The support is kept in the -kernel due to compatibility issues only. Their usage is strongly not -recommended - - -.. toctree:: - :maxdepth: 1 - - fe-read-ber - fe-read-snr - fe-read-signal-strength - fe-read-uncorrected-blocks - fe-set-frontend - fe-get-frontend - fe-get-event - fe-dishnetwork-send-legacy-cmd diff --git a/Documentation/media/uapi/dvb/frontend_legacy_dvbv3_api.rst b/Documentation/media/uapi/dvb/frontend_legacy_dvbv3_api.rst deleted file mode 100644 index 1567bc73855a..000000000000 --- a/Documentation/media/uapi/dvb/frontend_legacy_dvbv3_api.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _frontend_legacy_dvbv3_api: - -*********************************************** -Digital TV Frontend legacy API (a. k. a. DVBv3) -*********************************************** - -The usage of this API is deprecated, as it doesn't support all digital -TV standards, doesn't provide good statistics measurements and provides -incomplete information. This is kept only to support legacy -applications. - - -.. toctree:: - :maxdepth: 1 - - frontend_legacy_api diff --git a/Documentation/media/uapi/dvb/headers.rst b/Documentation/media/uapi/dvb/headers.rst deleted file mode 100644 index edeabd9e8e90..000000000000 --- a/Documentation/media/uapi/dvb/headers.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -**************************** -Digital TV uAPI header files -**************************** - -Digital TV uAPI headers -*********************** - -.. kernel-include:: $BUILDDIR/frontend.h.rst - -.. kernel-include:: $BUILDDIR/dmx.h.rst - -.. kernel-include:: $BUILDDIR/ca.h.rst - -.. kernel-include:: $BUILDDIR/net.h.rst - -Legacy uAPI -*********** - -.. kernel-include:: $BUILDDIR/audio.h.rst - -.. kernel-include:: $BUILDDIR/video.h.rst diff --git a/Documentation/media/uapi/dvb/intro.rst b/Documentation/media/uapi/dvb/intro.rst deleted file mode 100644 index f1384616ac4e..000000000000 --- a/Documentation/media/uapi/dvb/intro.rst +++ /dev/null @@ -1,190 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dvb_introdution: - -************ -Introduction -************ - - -.. _requisites: - -What you need to know -===================== - -The reader of this document is required to have some knowledge in the -area of digital video broadcasting (Digital TV) and should be familiar with -part I of the MPEG2 specification ISO/IEC 13818 (aka ITU-T H.222), i.e -you should know what a program/transport stream (PS/TS) is and what is -meant by a packetized elementary stream (PES) or an I-frame. - -Various Digital TV standards documents are available for download at: - -- European standards (DVB): http://www.dvb.org and/or http://www.etsi.org. -- American standards (ATSC): https://www.atsc.org/standards/ -- Japanese standards (ISDB): http://www.dibeg.org/ - -It is also necessary to know how to access Linux devices and how to -use ioctl calls. This also includes the knowledge of C or C++. - - -.. _history: - -History -======= - -The first API for Digital TV cards we used at Convergence in late 1999 was an -extension of the Video4Linux API which was primarily developed for frame -grabber cards. As such it was not really well suited to be used for Digital -TV cards and their new features like recording MPEG streams and filtering -several section and PES data streams at the same time. - -In early 2000, Convergence was approached by Nokia with a proposal for a new -standard Linux Digital TV API. As a commitment to the development of terminals -based on open standards, Nokia and Convergence made it available to all -Linux developers and published it on https://linuxtv.org in September -2000. With the Linux driver for the Siemens/Hauppauge DVB PCI card, -Convergence provided a first implementation of the Linux Digital TV API. -Convergence was the maintainer of the Linux Digital TV API in the early -days. - -Now, the API is maintained by the LinuxTV community (i.e. you, the reader -of this document). The Linux Digital TV API is constantly reviewed and -improved together with the improvements at the subsystem's core at the -Kernel. - - -.. _overview: - -Overview -======== - - -.. _stb_components: - -.. kernel-figure:: dvbstb.svg - :alt: dvbstb.svg - :align: center - - Components of a Digital TV card/STB - -A Digital TV card or set-top-box (STB) usually consists of the -following main hardware components: - -Frontend consisting of tuner and digital TV demodulator - Here the raw signal reaches the digital TV hardware from a satellite dish or - antenna or directly from cable. The frontend down-converts and - demodulates this signal into an MPEG transport stream (TS). In case - of a satellite frontend, this includes a facility for satellite - equipment control (SEC), which allows control of LNB polarization, - multi feed switches or dish rotors. - -Conditional Access (CA) hardware like CI adapters and smartcard slots - The complete TS is passed through the CA hardware. Programs to which - the user has access (controlled by the smart card) are decoded in - real time and re-inserted into the TS. - - .. note:: - - Not every digital TV hardware provides conditional access hardware. - -Demultiplexer which filters the incoming Digital TV MPEG-TS stream - The demultiplexer splits the TS into its components like audio and - video streams. Besides usually several of such audio and video - streams it also contains data streams with information about the - programs offered in this or other streams of the same provider. - -Audio and video decoder - The main targets of the demultiplexer are audio and video - decoders. After decoding, they pass on the uncompressed audio and - video to the computer screen or to a TV set. - - .. note:: - - Modern hardware usually doesn't have a separate decoder hardware, as - such functionality can be provided by the main CPU, by the graphics - adapter of the system or by a signal processing hardware embedded on - a Systems on a Chip (SoC) integrated circuit. - - It may also not be needed for certain usages (e.g. for data-only - uses like “internet over satellite”). - -:ref:`stb_components` shows a crude schematic of the control and data -flow between those components. - - - -.. _dvb_devices: - -Linux Digital TV Devices -======================== - -The Linux Digital TV API lets you control these hardware components through -currently six Unix-style character devices for video, audio, frontend, -demux, CA and IP-over-DVB networking. The video and audio devices -control the MPEG2 decoder hardware, the frontend device the tuner and -the Digital TV demodulator. The demux device gives you control over the PES -and section filters of the hardware. If the hardware does not support -filtering these filters can be implemented in software. Finally, the CA -device controls all the conditional access capabilities of the hardware. -It can depend on the individual security requirements of the platform, -if and how many of the CA functions are made available to the -application through this device. - -All devices can be found in the ``/dev`` tree under ``/dev/dvb``. The -individual devices are called: - -- ``/dev/dvb/adapterN/audioM``, - -- ``/dev/dvb/adapterN/videoM``, - -- ``/dev/dvb/adapterN/frontendM``, - -- ``/dev/dvb/adapterN/netM``, - -- ``/dev/dvb/adapterN/demuxM``, - -- ``/dev/dvb/adapterN/dvrM``, - -- ``/dev/dvb/adapterN/caM``, - -where ``N`` enumerates the Digital TV cards in a system starting from 0, and -``M`` enumerates the devices of each type within each adapter, starting -from 0, too. We will omit the “``/dev/dvb/adapterN/``\ ” in the further -discussion of these devices. - -More details about the data structures and function calls of all the -devices are described in the following chapters. - - -.. _include_files: - -API include files -================= - -For each of the Digital TV devices a corresponding include file exists. The -Digital TV API include files should be included in application sources with a -partial path like: - - -.. code-block:: c - - #include - - #include - - #include - - #include - - -To enable applications to support different API version, an additional -include file ``linux/dvb/version.h`` exists, which defines the constant -``DVB_API_VERSION``. This document describes ``DVB_API_VERSION 5.10``. diff --git a/Documentation/media/uapi/dvb/legacy_dvb_apis.rst b/Documentation/media/uapi/dvb/legacy_dvb_apis.rst deleted file mode 100644 index a43b4c36d935..000000000000 --- a/Documentation/media/uapi/dvb/legacy_dvb_apis.rst +++ /dev/null @@ -1,39 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _legacy_dvb_apis: - -*************************** -Digital TV Deprecated APIs -*************************** - -The APIs described here **should not** be used on new drivers or applications. - -The DVBv3 frontend API has issues with new delivery systems, including -DVB-S2, DVB-T2, ISDB, etc. - -There's just one driver for a very legacy hardware using the Digital TV -audio and video APIs. No modern drivers should use it. Instead, audio and -video should be using the V4L2 and ALSA APIs, and the pipelines should -be set via the Media Controller API. - -.. attention:: - - The APIs described here doesn't necessarily reflect the current - code implementation, as this section of the document was written - for DVB version 1, while the code reflects DVB version 3 - implementation. - - -.. toctree:: - :maxdepth: 1 - - frontend_legacy_dvbv3_api - video - audio diff --git a/Documentation/media/uapi/dvb/net-add-if.rst b/Documentation/media/uapi/dvb/net-add-if.rst deleted file mode 100644 index 1188641b453e..000000000000 --- a/Documentation/media/uapi/dvb/net-add-if.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _NET_ADD_IF: - -**************** -ioctl NET_ADD_IF -**************** - -Name -==== - -NET_ADD_IF - Creates a new network interface for a given Packet ID. - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, NET_ADD_IF, struct dvb_net_if *net_if ) - :name: NET_ADD_IF - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``net_if`` - pointer to struct :c:type:`dvb_net_if` - - -Description -=========== - -The NET_ADD_IF ioctl system call selects the Packet ID (PID) that -contains a TCP/IP traffic, the type of encapsulation to be used (MPE or -ULE) and the interface number for the new interface to be created. When -the system call successfully returns, a new virtual network interface is -created. - -The struct :c:type:`dvb_net_if`::ifnum field will be -filled with the number of the created interface. - -Return Value -============ - -On success 0 is returned, and :c:type:`ca_slot_info` is filled. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/net-get-if.rst b/Documentation/media/uapi/dvb/net-get-if.rst deleted file mode 100644 index 7c4ef4b9d6cc..000000000000 --- a/Documentation/media/uapi/dvb/net-get-if.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _NET_GET_IF: - -**************** -ioctl NET_GET_IF -**************** - -Name -==== - -NET_GET_IF - Read the configuration data of an interface created via - :ref:`NET_ADD_IF `. - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, NET_GET_IF, struct dvb_net_if *net_if ) - :name: NET_GET_IF - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``net_if`` - pointer to struct :c:type:`dvb_net_if` - - -Description -=========== - -The NET_GET_IF ioctl uses the interface number given by the struct -:c:type:`dvb_net_if`::ifnum field and fills the content of -struct :c:type:`dvb_net_if` with the packet ID and -encapsulation type used on such interface. If the interface was not -created yet with :ref:`NET_ADD_IF `, it will return -1 and fill -the ``errno`` with ``EINVAL`` error code. - - -Return Value -============ - -On success 0 is returned, and :c:type:`ca_slot_info` is filled. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/net-remove-if.rst b/Documentation/media/uapi/dvb/net-remove-if.rst deleted file mode 100644 index bf9a1602eeec..000000000000 --- a/Documentation/media/uapi/dvb/net-remove-if.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _NET_REMOVE_IF: - -******************* -ioctl NET_REMOVE_IF -******************* - -Name -==== - -NET_REMOVE_IF - Removes a network interface. - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, NET_REMOVE_IF, int ifnum ) - :name: NET_REMOVE_IF - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``net_if`` - number of the interface to be removed - - -Description -=========== - -The NET_REMOVE_IF ioctl deletes an interface previously created via -:ref:`NET_ADD_IF `. - - -Return Value -============ - -On success 0 is returned, and :c:type:`ca_slot_info` is filled. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/net-types.rst b/Documentation/media/uapi/dvb/net-types.rst deleted file mode 100644 index 9e16462a1ef4..000000000000 --- a/Documentation/media/uapi/dvb/net-types.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _net_types: - -************** -Net Data Types -************** - -.. kernel-doc:: include/uapi/linux/dvb/net.h diff --git a/Documentation/media/uapi/dvb/net.rst b/Documentation/media/uapi/dvb/net.rst deleted file mode 100644 index 833daa381968..000000000000 --- a/Documentation/media/uapi/dvb/net.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _net: - -###################### -Digital TV Network API -###################### - -The Digital TV net device controls the mapping of data packages that are part -of a transport stream to be mapped into a virtual network interface, -visible through the standard Linux network protocol stack. - -Currently, two encapsulations are supported: - -- `Multi Protocol Encapsulation (MPE) `__ - -- `Ultra Lightweight Encapsulation (ULE) `__ - -In order to create the Linux virtual network interfaces, an application -needs to tell to the Kernel what are the PIDs and the encapsulation -types that are present on the transport stream. This is done through -``/dev/dvb/adapter?/net?`` device node. The data will be available via -virtual ``dvb?_?`` network interfaces, and will be controlled/routed via -the standard ip tools (like ip, route, netstat, ifconfig, etc). - -Data types and and ioctl definitions are defined via ``linux/dvb/net.h`` -header. - - -.. _net_fcalls: - -Digital TV net Function Calls -############################# - -.. toctree:: - :maxdepth: 1 - - net-types - net-add-if - net-remove-if - net-get-if diff --git a/Documentation/media/uapi/dvb/query-dvb-frontend-info.rst b/Documentation/media/uapi/dvb/query-dvb-frontend-info.rst deleted file mode 100644 index 9a6badc1d295..000000000000 --- a/Documentation/media/uapi/dvb/query-dvb-frontend-info.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _query-dvb-frontend-info: - -***************************** -Querying frontend information -***************************** - -Usually, the first thing to do when the frontend is opened is to check -the frontend capabilities. This is done using -:ref:`FE_GET_INFO`. This ioctl will enumerate the -Digital TV API version and other characteristics about the frontend, and can -be opened either in read only or read/write mode. diff --git a/Documentation/media/uapi/dvb/video-clear-buffer.rst b/Documentation/media/uapi/dvb/video-clear-buffer.rst deleted file mode 100644 index 5eb5546e8ce4..000000000000 --- a/Documentation/media/uapi/dvb/video-clear-buffer.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_CLEAR_BUFFER: - -================== -VIDEO_CLEAR_BUFFER -================== - -Name ----- - -VIDEO_CLEAR_BUFFER - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_CLEAR_BUFFER) - :name: VIDEO_CLEAR_BUFFER - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_CLEAR_BUFFER for this command. - - -Description ------------ - -This ioctl call clears all video buffers in the driver and in the -decoder hardware. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/video-command.rst b/Documentation/media/uapi/dvb/video-command.rst deleted file mode 100644 index 020b49645c6b..000000000000 --- a/Documentation/media/uapi/dvb/video-command.rst +++ /dev/null @@ -1,105 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_COMMAND: - -============= -VIDEO_COMMAND -============= - -Name ----- - -VIDEO_COMMAND - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(int fd, VIDEO_COMMAND, struct video_command *cmd) - :name: VIDEO_COMMAND - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_COMMAND for this command. - - - .. row 3 - - - struct video_command \*cmd - - - Commands the decoder. - - -Description ------------ - -This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders -this ioctl has been replaced by the -:ref:`VIDIOC_DECODER_CMD` ioctl. - -This ioctl commands the decoder. The ``video_command`` struct is a -subset of the ``v4l2_decoder_cmd`` struct, so refer to the -:ref:`VIDIOC_DECODER_CMD` documentation for -more information. - -.. c:type:: struct video_command - -.. code-block:: c - - /* The structure must be zeroed before use by the application - This ensures it can be extended safely in the future. */ - struct video_command { - __u32 cmd; - __u32 flags; - union { - struct { - __u64 pts; - } stop; - - struct { - /* 0 or 1000 specifies normal speed, - 1 specifies forward single stepping, - -1 specifies backward single stepping, - >1: playback at speed/1000 of the normal speed, - <-1: reverse playback at (-speed/1000) of the normal speed. */ - __s32 speed; - __u32 format; - } play; - - struct { - __u32 data[16]; - } raw; - }; - }; - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/video-continue.rst b/Documentation/media/uapi/dvb/video-continue.rst deleted file mode 100644 index 2ae2067dfba8..000000000000 --- a/Documentation/media/uapi/dvb/video-continue.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_CONTINUE: - -============== -VIDEO_CONTINUE -============== - -Name ----- - -VIDEO_CONTINUE - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_CONTINUE) - :name: VIDEO_CONTINUE - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_CONTINUE for this command. - - -Description ------------ - -This ioctl is for Digital TV devices only. To control a V4L2 decoder use the -V4L2 :ref:`VIDIOC_DECODER_CMD` instead. - -This ioctl call restarts decoding and playing processes of the video -stream which was played before a call to VIDEO_FREEZE was made. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/video-fast-forward.rst b/Documentation/media/uapi/dvb/video-fast-forward.rst deleted file mode 100644 index 3f805f334ae1..000000000000 --- a/Documentation/media/uapi/dvb/video-fast-forward.rst +++ /dev/null @@ -1,83 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_FAST_FORWARD: - -================== -VIDEO_FAST_FORWARD -================== - -Name ----- - -VIDEO_FAST_FORWARD - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_FAST_FORWARD, int nFrames) - :name: VIDEO_FAST_FORWARD - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_FAST_FORWARD for this command. - - - .. row 3 - - - int nFrames - - - The number of frames to skip. - - -Description ------------ - -This ioctl call asks the Video Device to skip decoding of N number of -I-frames. This call can only be used if VIDEO_SOURCE_MEMORY is -selected. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``EPERM`` - - - Mode VIDEO_SOURCE_MEMORY not selected. diff --git a/Documentation/media/uapi/dvb/video-fclose.rst b/Documentation/media/uapi/dvb/video-fclose.rst deleted file mode 100644 index 3b0285b96a3c..000000000000 --- a/Documentation/media/uapi/dvb/video-fclose.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _video_fclose: - -================= -dvb video close() -================= - -Name ----- - -dvb video close() - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int close(int fd) - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - -Description ------------ - -This system call closes a previously opened video device. - - -Return Value ------------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``EBADF`` - - - fd is not a valid open file descriptor. diff --git a/Documentation/media/uapi/dvb/video-fopen.rst b/Documentation/media/uapi/dvb/video-fopen.rst deleted file mode 100644 index 7b2a8c750e6a..000000000000 --- a/Documentation/media/uapi/dvb/video-fopen.rst +++ /dev/null @@ -1,122 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _video_fopen: - -================ -dvb video open() -================ - -Name ----- - -dvb video open() - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int open(const char *deviceName, int flags) - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - const char \*deviceName - - - Name of specific video device. - - - .. row 2 - - - int flags - - - A bit-wise OR of the following flags: - - - .. row 3 - - - - - O_RDONLY read-only access - - - .. row 4 - - - - - O_RDWR read/write access - - - .. row 5 - - - - - O_NONBLOCK open in non-blocking mode - - - .. row 6 - - - - - (blocking mode is the default) - - -Description ------------ - -This system call opens a named video device (e.g. -/dev/dvb/adapter0/video0) for subsequent use. - -When an open() call has succeeded, the device will be ready for use. The -significance of blocking or non-blocking mode is described in the -documentation for functions where there is a difference. It does not -affect the semantics of the open() call itself. A device opened in -blocking mode can later be put into non-blocking mode (and vice versa) -using the F_SETFL command of the fcntl system call. This is a standard -system call, documented in the Linux manual page for fcntl. Only one -user can open the Video Device in O_RDWR mode. All other attempts to -open the device in this mode will fail, and an error-code will be -returned. If the Video Device is opened in O_RDONLY mode, the only -ioctl call that can be used is VIDEO_GET_STATUS. All other call will -return an error code. - - -Return Value ------------- - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``ENODEV`` - - - Device driver not loaded/available. - - - .. row 2 - - - ``EINTERNAL`` - - - Internal error. - - - .. row 3 - - - ``EBUSY`` - - - Device or resource busy. - - - .. row 4 - - - ``EINVAL`` - - - Invalid argument. diff --git a/Documentation/media/uapi/dvb/video-freeze.rst b/Documentation/media/uapi/dvb/video-freeze.rst deleted file mode 100644 index 6b31a4755d2c..000000000000 --- a/Documentation/media/uapi/dvb/video-freeze.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_FREEZE: - -============ -VIDEO_FREEZE -============ - -Name ----- - -VIDEO_FREEZE - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_FREEZE) - :name: VIDEO_FREEZE - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_FREEZE for this command. - - -Description ------------ - -This ioctl is for Digital TV devices only. To control a V4L2 decoder use the -V4L2 :ref:`VIDIOC_DECODER_CMD` instead. - -This ioctl call suspends the live video stream being played. Decoding -and playing are frozen. It is then possible to restart the decoding and -playing process of the video stream using the VIDEO_CONTINUE command. -If VIDEO_SOURCE_MEMORY is selected in the ioctl call -VIDEO_SELECT_SOURCE, the Digital TV subsystem will not decode any more data -until the ioctl call VIDEO_CONTINUE or VIDEO_PLAY is performed. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/video-fwrite.rst b/Documentation/media/uapi/dvb/video-fwrite.rst deleted file mode 100644 index eb35b79eb85c..000000000000 --- a/Documentation/media/uapi/dvb/video-fwrite.rst +++ /dev/null @@ -1,90 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _video_fwrite: - -================= -dvb video write() -================= - -Name ----- - -dvb video write() - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: size_t write(int fd, const void *buf, size_t count) - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - void \*buf - - - Pointer to the buffer containing the PES data. - - - .. row 3 - - - size_t count - - - Size of buf. - - -Description ------------ - -This system call can only be used if VIDEO_SOURCE_MEMORY is selected -in the ioctl call VIDEO_SELECT_SOURCE. The data provided shall be in -PES format, unless the capability allows other formats. If O_NONBLOCK -is not specified the function will block until buffer space is -available. The amount of data to be transferred is implied by count. - - -Return Value ------------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``EPERM`` - - - Mode VIDEO_SOURCE_MEMORY not selected. - - - .. row 2 - - - ``ENOMEM`` - - - Attempted to write more data than the internal buffer can hold. - - - .. row 3 - - - ``EBADF`` - - - fd is not a valid open file descriptor. diff --git a/Documentation/media/uapi/dvb/video-get-capabilities.rst b/Documentation/media/uapi/dvb/video-get-capabilities.rst deleted file mode 100644 index 971fdab70e15..000000000000 --- a/Documentation/media/uapi/dvb/video-get-capabilities.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_GET_CAPABILITIES: - -====================== -VIDEO_GET_CAPABILITIES -====================== - -Name ----- - -VIDEO_GET_CAPABILITIES - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_GET_CAPABILITIES, unsigned int *cap) - :name: VIDEO_GET_CAPABILITIES - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_GET_CAPABILITIES for this command. - - - .. row 3 - - - unsigned int \*cap - - - Pointer to a location where to store the capability information. - - -Description ------------ - -This ioctl call asks the video device about its decoding capabilities. -On success it returns and integer which has bits set according to the -defines in section ??. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/video-get-event.rst b/Documentation/media/uapi/dvb/video-get-event.rst deleted file mode 100644 index 7f03fbe3d3b0..000000000000 --- a/Documentation/media/uapi/dvb/video-get-event.rst +++ /dev/null @@ -1,114 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_GET_EVENT: - -=============== -VIDEO_GET_EVENT -=============== - -Name ----- - -VIDEO_GET_EVENT - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_GET_EVENT, struct video_event *ev) - :name: VIDEO_GET_EVENT - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_GET_EVENT for this command. - - - .. row 3 - - - struct video_event \*ev - - - Points to the location where the event, if any, is to be stored. - - -Description ------------ - -This ioctl is for Digital TV devices only. To get events from a V4L2 decoder -use the V4L2 :ref:`VIDIOC_DQEVENT` ioctl instead. - -This ioctl call returns an event of type video_event if available. If -an event is not available, the behavior depends on whether the device is -in blocking or non-blocking mode. In the latter case, the call fails -immediately with errno set to ``EWOULDBLOCK``. In the former case, the call -blocks until an event becomes available. The standard Linux poll() -and/or select() system calls can be used with the device file descriptor -to watch for new events. For select(), the file descriptor should be -included in the exceptfds argument, and for poll(), POLLPRI should be -specified as the wake-up condition. Read-only permissions are sufficient -for this ioctl call. - -.. c:type:: video_event - -.. code-block:: c - - struct video_event { - __s32 type; - #define VIDEO_EVENT_SIZE_CHANGED 1 - #define VIDEO_EVENT_FRAME_RATE_CHANGED 2 - #define VIDEO_EVENT_DECODER_STOPPED 3 - #define VIDEO_EVENT_VSYNC 4 - long timestamp; - union { - video_size_t size; - unsigned int frame_rate; /* in frames per 1000sec */ - unsigned char vsync_field; /* unknown/odd/even/progressive */ - } u; - }; - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``EWOULDBLOCK`` - - - There is no event pending, and the device is in non-blocking mode. - - - .. row 2 - - - ``EOVERFLOW`` - - - Overflow in event queue - one or more events were lost. diff --git a/Documentation/media/uapi/dvb/video-get-frame-count.rst b/Documentation/media/uapi/dvb/video-get-frame-count.rst deleted file mode 100644 index ef35da7d4861..000000000000 --- a/Documentation/media/uapi/dvb/video-get-frame-count.rst +++ /dev/null @@ -1,74 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_GET_FRAME_COUNT: - -===================== -VIDEO_GET_FRAME_COUNT -===================== - -Name ----- - -VIDEO_GET_FRAME_COUNT - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(int fd, VIDEO_GET_FRAME_COUNT, __u64 *pts) - :name: VIDEO_GET_FRAME_COUNT - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_GET_FRAME_COUNT for this command. - - - .. row 3 - - - __u64 \*pts - - - Returns the number of frames displayed since the decoder was - started. - - -Description ------------ - -This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders -this ioctl has been replaced by the ``V4L2_CID_MPEG_VIDEO_DEC_FRAME`` -control. - -This ioctl call asks the Video Device to return the number of displayed -frames since the decoder was started. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/video-get-pts.rst b/Documentation/media/uapi/dvb/video-get-pts.rst deleted file mode 100644 index 86ceefff7834..000000000000 --- a/Documentation/media/uapi/dvb/video-get-pts.rst +++ /dev/null @@ -1,78 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_GET_PTS: - -============= -VIDEO_GET_PTS -============= - -Name ----- - -VIDEO_GET_PTS - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(int fd, VIDEO_GET_PTS, __u64 *pts) - :name: VIDEO_GET_PTS - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_GET_PTS for this command. - - - .. row 3 - - - __u64 \*pts - - - Returns the 33-bit timestamp as defined in ITU T-REC-H.222.0 / - ISO/IEC 13818-1. - - The PTS should belong to the currently played frame if possible, - but may also be a value close to it like the PTS of the last - decoded frame or the last PTS extracted by the PES parser. - - -Description ------------ - -This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders -this ioctl has been replaced by the ``V4L2_CID_MPEG_VIDEO_DEC_PTS`` -control. - -This ioctl call asks the Video Device to return the current PTS -timestamp. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/video-get-size.rst b/Documentation/media/uapi/dvb/video-get-size.rst deleted file mode 100644 index cc92189d31fd..000000000000 --- a/Documentation/media/uapi/dvb/video-get-size.rst +++ /dev/null @@ -1,78 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_GET_SIZE: - -============== -VIDEO_GET_SIZE -============== - -Name ----- - -VIDEO_GET_SIZE - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(int fd, VIDEO_GET_SIZE, video_size_t *size) - :name: VIDEO_GET_SIZE - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_GET_SIZE for this command. - - - .. row 3 - - - video_size_t \*size - - - Returns the size and aspect ratio. - - -Description ------------ - -This ioctl returns the size and aspect ratio. - -.. c:type:: video_size_t - -.. code-block::c - - typedef struct { - int w; - int h; - video_format_t aspect_ratio; - } video_size_t; - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/video-get-status.rst b/Documentation/media/uapi/dvb/video-get-status.rst deleted file mode 100644 index 8bfcf8fc3e19..000000000000 --- a/Documentation/media/uapi/dvb/video-get-status.rst +++ /dev/null @@ -1,80 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_GET_STATUS: - -================ -VIDEO_GET_STATUS -================ - -Name ----- - -VIDEO_GET_STATUS - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_GET_STATUS, struct video_status *status) - :name: VIDEO_GET_STATUS - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_GET_STATUS for this command. - - - .. row 3 - - - struct video_status \*status - - - Returns the current status of the Video Device. - - -Description ------------ - -This ioctl call asks the Video Device to return the current status of -the device. - -.. c:type:: video_status - -.. code-block:: c - - struct video_status { - int video_blank; /* blank video on freeze? */ - video_play_state_t play_state; /* current state of playback */ - video_stream_source_t stream_source; /* current source (demux/memory) */ - video_format_t video_format; /* current aspect ratio of stream*/ - video_displayformat_t display_format;/* selected cropping mode */ - }; - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/video-play.rst b/Documentation/media/uapi/dvb/video-play.rst deleted file mode 100644 index fb3f4f168814..000000000000 --- a/Documentation/media/uapi/dvb/video-play.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_PLAY: - -========== -VIDEO_PLAY -========== - -Name ----- - -VIDEO_PLAY - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_PLAY) - :name: VIDEO_PLAY - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_PLAY for this command. - - -Description ------------ - -This ioctl is for Digital TV devices only. To control a V4L2 decoder use the -V4L2 :ref:`VIDIOC_DECODER_CMD` instead. - -This ioctl call asks the Video Device to start playing a video stream -from the selected source. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/video-select-source.rst b/Documentation/media/uapi/dvb/video-select-source.rst deleted file mode 100644 index 32cf025356dc..000000000000 --- a/Documentation/media/uapi/dvb/video-select-source.rst +++ /dev/null @@ -1,84 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_SELECT_SOURCE: - -=================== -VIDEO_SELECT_SOURCE -=================== - -Name ----- - -VIDEO_SELECT_SOURCE - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_SELECT_SOURCE, video_stream_source_t source) - :name: VIDEO_SELECT_SOURCE - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_SELECT_SOURCE for this command. - - - .. row 3 - - - video_stream_source_t source - - - Indicates which source shall be used for the Video stream. - - -Description ------------ - -This ioctl is for Digital TV devices only. This ioctl was also supported by the -V4L2 ivtv driver, but that has been replaced by the ivtv-specific -``IVTV_IOC_PASSTHROUGH_MODE`` ioctl. - -This ioctl call informs the video device which source shall be used for -the input data. The possible sources are demux or memory. If memory is -selected, the data is fed to the video device through the write command. - -.. c:type:: video_stream_source_t - -.. code-block:: c - - typedef enum { - VIDEO_SOURCE_DEMUX, /* Select the demux as the main source */ - VIDEO_SOURCE_MEMORY /* If this source is selected, the stream - comes from the user through the write - system call */ - } video_stream_source_t; - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/video-set-blank.rst b/Documentation/media/uapi/dvb/video-set-blank.rst deleted file mode 100644 index 901c3c80f167..000000000000 --- a/Documentation/media/uapi/dvb/video-set-blank.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_SET_BLANK: - -=============== -VIDEO_SET_BLANK -=============== - -Name ----- - -VIDEO_SET_BLANK - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_SET_BLANK, boolean mode) - :name: VIDEO_SET_BLANK - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_SET_BLANK for this command. - - - .. row 3 - - - boolean mode - - - TRUE: Blank screen when stop. - - - .. row 4 - - - - - FALSE: Show last decoded frame. - - -Description ------------ - -This ioctl call asks the Video Device to blank out the picture. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/video-set-display-format.rst b/Documentation/media/uapi/dvb/video-set-display-format.rst deleted file mode 100644 index ffdefa341207..000000000000 --- a/Documentation/media/uapi/dvb/video-set-display-format.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_SET_DISPLAY_FORMAT: - -======================== -VIDEO_SET_DISPLAY_FORMAT -======================== - -Name ----- - -VIDEO_SET_DISPLAY_FORMAT - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_SET_DISPLAY_FORMAT) - :name: VIDEO_SET_DISPLAY_FORMAT - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_SET_DISPLAY_FORMAT for this command. - - - .. row 3 - - - video_display_format_t format - - - Selects the video format to be used. - - -Description ------------ - -This ioctl call asks the Video Device to select the video format to be -applied by the MPEG chip on the video. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/video-set-format.rst b/Documentation/media/uapi/dvb/video-set-format.rst deleted file mode 100644 index 63e60214ab37..000000000000 --- a/Documentation/media/uapi/dvb/video-set-format.rst +++ /dev/null @@ -1,92 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_SET_FORMAT: - -================ -VIDEO_SET_FORMAT -================ - -Name ----- - -VIDEO_SET_FORMAT - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_SET_FORMAT, video_format_t format) - :name: VIDEO_SET_FORMAT - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_SET_FORMAT for this command. - - - .. row 3 - - - video_format_t format - - - video format of TV as defined in section ??. - - -Description ------------ - -This ioctl sets the screen format (aspect ratio) of the connected output -device (TV) so that the output of the decoder can be adjusted -accordingly. - -.. c:type:: video_format_t - -.. code-block:: c - - typedef enum { - VIDEO_FORMAT_4_3, /* Select 4:3 format */ - VIDEO_FORMAT_16_9, /* Select 16:9 format. */ - VIDEO_FORMAT_221_1 /* 2.21:1 */ - } video_format_t; - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``EINVAL`` - - - format is not a valid video format. diff --git a/Documentation/media/uapi/dvb/video-set-streamtype.rst b/Documentation/media/uapi/dvb/video-set-streamtype.rst deleted file mode 100644 index 845486a6e049..000000000000 --- a/Documentation/media/uapi/dvb/video-set-streamtype.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_SET_STREAMTYPE: - -==================== -VIDEO_SET_STREAMTYPE -==================== - -Name ----- - -VIDEO_SET_STREAMTYPE - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_SET_STREAMTYPE, int type) - :name: VIDEO_SET_STREAMTYPE - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_SET_STREAMTYPE for this command. - - - .. row 3 - - - int type - - - stream type - - -Description ------------ - -This ioctl tells the driver which kind of stream to expect being written -to it. If this call is not used the default of video PES is used. Some -drivers might not support this call and always expect PES. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/video-slowmotion.rst b/Documentation/media/uapi/dvb/video-slowmotion.rst deleted file mode 100644 index 32c934aaf2ba..000000000000 --- a/Documentation/media/uapi/dvb/video-slowmotion.rst +++ /dev/null @@ -1,83 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_SLOWMOTION: - -================ -VIDEO_SLOWMOTION -================ - -Name ----- - -VIDEO_SLOWMOTION - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_SLOWMOTION, int nFrames) - :name: VIDEO_SLOWMOTION - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_SLOWMOTION for this command. - - - .. row 3 - - - int nFrames - - - The number of times to repeat each frame. - - -Description ------------ - -This ioctl call asks the video device to repeat decoding frames N number -of times. This call can only be used if VIDEO_SOURCE_MEMORY is -selected. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``EPERM`` - - - Mode VIDEO_SOURCE_MEMORY not selected. diff --git a/Documentation/media/uapi/dvb/video-stillpicture.rst b/Documentation/media/uapi/dvb/video-stillpicture.rst deleted file mode 100644 index 58035a7630e6..000000000000 --- a/Documentation/media/uapi/dvb/video-stillpicture.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_STILLPICTURE: - -================== -VIDEO_STILLPICTURE -================== - -Name ----- - -VIDEO_STILLPICTURE - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_STILLPICTURE, struct video_still_picture *sp) - :name: VIDEO_STILLPICTURE - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_STILLPICTURE for this command. - - - .. row 3 - - - struct video_still_picture \*sp - - - Pointer to a location where an I-frame and size is stored. - - -Description ------------ - -This ioctl call asks the Video Device to display a still picture -(I-frame). The input data shall contain an I-frame. If the pointer is -NULL, then the current displayed still picture is blanked. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/video-stop.rst b/Documentation/media/uapi/dvb/video-stop.rst deleted file mode 100644 index 732ace05e34b..000000000000 --- a/Documentation/media/uapi/dvb/video-stop.rst +++ /dev/null @@ -1,83 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_STOP: - -========== -VIDEO_STOP -========== - -Name ----- - -VIDEO_STOP - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_STOP, boolean mode) - :name: VIDEO_STOP - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_STOP for this command. - - - .. row 3 - - - Boolean mode - - - Indicates how the screen shall be handled. - - - .. row 4 - - - - - TRUE: Blank screen when stop. - - - .. row 5 - - - - - FALSE: Show last decoded frame. - - -Description ------------ - -This ioctl is for Digital TV devices only. To control a V4L2 decoder use the -V4L2 :ref:`VIDIOC_DECODER_CMD` instead. - -This ioctl call asks the Video Device to stop playing the current -stream. Depending on the input parameter, the screen can be blanked out -or displaying the last decoded frame. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/video-try-command.rst b/Documentation/media/uapi/dvb/video-try-command.rst deleted file mode 100644 index 37ecf8e91eb8..000000000000 --- a/Documentation/media/uapi/dvb/video-try-command.rst +++ /dev/null @@ -1,75 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_TRY_COMMAND: - -================= -VIDEO_TRY_COMMAND -================= - -Name ----- - -VIDEO_TRY_COMMAND - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(int fd, VIDEO_TRY_COMMAND, struct video_command *cmd) - :name: VIDEO_TRY_COMMAND - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - - .. row 2 - - - int request - - - Equals VIDEO_TRY_COMMAND for this command. - - - .. row 3 - - - struct video_command \*cmd - - - Try a decoder command. - - -Description ------------ - -This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders -this ioctl has been replaced by the -:ref:`VIDIOC_TRY_DECODER_CMD ` ioctl. - -This ioctl tries a decoder command. The ``video_command`` struct is a -subset of the ``v4l2_decoder_cmd`` struct, so refer to the -:ref:`VIDIOC_TRY_DECODER_CMD ` documentation -for more information. - - -Return Value ------------- - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/video.rst b/Documentation/media/uapi/dvb/video.rst deleted file mode 100644 index 6d72ed0e2b2d..000000000000 --- a/Documentation/media/uapi/dvb/video.rst +++ /dev/null @@ -1,43 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dvb_video: - -####################### -Digital TV Video Device -####################### - -The Digital TV video device controls the MPEG2 video decoder of the Digital -TV hardware. It can be accessed through **/dev/dvb/adapter0/video0**. Data -types and and ioctl definitions can be accessed by including -**linux/dvb/video.h** in your application. - -Note that the Digital TV video device only controls decoding of the MPEG video -stream, not its presentation on the TV or computer screen. On PCs this -is typically handled by an associated video4linux device, e.g. -**/dev/video**, which allows scaling and defining output windows. - -Some Digital TV cards don’t have their own MPEG decoder, which results in the -omission of the audio and video device as well as the video4linux -device. - -The ioctls that deal with SPUs (sub picture units) and navigation -packets are only supported on some MPEG decoders made for DVD playback. - -These ioctls were also used by V4L2 to control MPEG decoders implemented -in V4L2. The use of these ioctls for that purpose has been made obsolete -and proper V4L2 ioctls or controls have been created to replace that -functionality. - - -.. toctree:: - :maxdepth: 1 - - video_types - video_function_calls diff --git a/Documentation/media/uapi/dvb/video_function_calls.rst b/Documentation/media/uapi/dvb/video_function_calls.rst deleted file mode 100644 index 9e8e49e52b19..000000000000 --- a/Documentation/media/uapi/dvb/video_function_calls.rst +++ /dev/null @@ -1,42 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _video_function_calls: - -******************** -Video Function Calls -******************** - -.. toctree:: - :maxdepth: 1 - - video-fopen - video-fclose - video-fwrite - video-stop - video-play - video-freeze - video-continue - video-select-source - video-set-blank - video-get-status - video-get-frame-count - video-get-pts - video-get-event - video-command - video-try-command - video-get-size - video-set-display-format - video-stillpicture - video-fast-forward - video-slowmotion - video-get-capabilities - video-clear-buffer - video-set-streamtype - video-set-format diff --git a/Documentation/media/uapi/dvb/video_types.rst b/Documentation/media/uapi/dvb/video_types.rst deleted file mode 100644 index 2697400ccf62..000000000000 --- a/Documentation/media/uapi/dvb/video_types.rst +++ /dev/null @@ -1,255 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _video_types: - -**************** -Video Data Types -**************** - - -.. _video-format-t: - -video_format_t -============== - -The ``video_format_t`` data type defined by - - -.. code-block:: c - - typedef enum { - VIDEO_FORMAT_4_3, /* Select 4:3 format */ - VIDEO_FORMAT_16_9, /* Select 16:9 format. */ - VIDEO_FORMAT_221_1 /* 2.21:1 */ - } video_format_t; - -is used in the VIDEO_SET_FORMAT function (??) to tell the driver which -aspect ratio the output hardware (e.g. TV) has. It is also used in the -data structures video_status (??) returned by VIDEO_GET_STATUS (??) -and video_event (??) returned by VIDEO_GET_EVENT (??) which report -about the display format of the current video stream. - - -.. _video-displayformat-t: - -video_displayformat_t -===================== - -In case the display format of the video stream and of the display -hardware differ the application has to specify how to handle the -cropping of the picture. This can be done using the -VIDEO_SET_DISPLAY_FORMAT call (??) which accepts - - -.. code-block:: c - - typedef enum { - VIDEO_PAN_SCAN, /* use pan and scan format */ - VIDEO_LETTER_BOX, /* use letterbox format */ - VIDEO_CENTER_CUT_OUT /* use center cut out format */ - } video_displayformat_t; - -as argument. - - -.. _video-stream-source-t: - -video_stream_source_t -===================== - -The video stream source is set through the VIDEO_SELECT_SOURCE call -and can take the following values, depending on whether we are replaying -from an internal (demuxer) or external (user write) source. - - -.. code-block:: c - - typedef enum { - VIDEO_SOURCE_DEMUX, /* Select the demux as the main source */ - VIDEO_SOURCE_MEMORY /* If this source is selected, the stream - comes from the user through the write - system call */ - } video_stream_source_t; - -VIDEO_SOURCE_DEMUX selects the demultiplexer (fed either by the -frontend or the DVR device) as the source of the video stream. If -VIDEO_SOURCE_MEMORY is selected the stream comes from the application -through the **write()** system call. - - -.. _video-play-state-t: - -video_play_state_t -================== - -The following values can be returned by the VIDEO_GET_STATUS call -representing the state of video playback. - - -.. code-block:: c - - typedef enum { - VIDEO_STOPPED, /* Video is stopped */ - VIDEO_PLAYING, /* Video is currently playing */ - VIDEO_FREEZED /* Video is freezed */ - } video_play_state_t; - - -.. c:type:: video_command - -struct video_command -==================== - -The structure must be zeroed before use by the application This ensures -it can be extended safely in the future. - - -.. code-block:: c - - struct video_command { - __u32 cmd; - __u32 flags; - union { - struct { - __u64 pts; - } stop; - - struct { - /* 0 or 1000 specifies normal speed, - 1 specifies forward single stepping, - -1 specifies backward single stepping, - >>1: playback at speed/1000 of the normal speed, - <-1: reverse playback at (-speed/1000) of the normal speed. */ - __s32 speed; - __u32 format; - } play; - - struct { - __u32 data[16]; - } raw; - }; - }; - - -.. _video-size-t: - -video_size_t -============ - - -.. code-block:: c - - typedef struct { - int w; - int h; - video_format_t aspect_ratio; - } video_size_t; - - -.. c:type:: video_event - -struct video_event -================== - -The following is the structure of a video event as it is returned by the -VIDEO_GET_EVENT call. - - -.. code-block:: c - - struct video_event { - __s32 type; - #define VIDEO_EVENT_SIZE_CHANGED 1 - #define VIDEO_EVENT_FRAME_RATE_CHANGED 2 - #define VIDEO_EVENT_DECODER_STOPPED 3 - #define VIDEO_EVENT_VSYNC 4 - long timestamp; - union { - video_size_t size; - unsigned int frame_rate; /* in frames per 1000sec */ - unsigned char vsync_field; /* unknown/odd/even/progressive */ - } u; - }; - - -.. c:type:: video_status - -struct video_status -=================== - -The VIDEO_GET_STATUS call returns the following structure informing -about various states of the playback operation. - - -.. code-block:: c - - struct video_status { - int video_blank; /* blank video on freeze? */ - video_play_state_t play_state; /* current state of playback */ - video_stream_source_t stream_source; /* current source (demux/memory) */ - video_format_t video_format; /* current aspect ratio of stream */ - video_displayformat_t display_format;/* selected cropping mode */ - }; - -If video_blank is set video will be blanked out if the channel is -changed or if playback is stopped. Otherwise, the last picture will be -displayed. play_state indicates if the video is currently frozen, -stopped, or being played back. The stream_source corresponds to the -selected source for the video stream. It can come either from the -demultiplexer or from memory. The video_format indicates the aspect -ratio (one of 4:3 or 16:9) of the currently played video stream. -Finally, display_format corresponds to the selected cropping mode in -case the source video format is not the same as the format of the output -device. - - -.. c:type:: video_still_picture - -struct video_still_picture -========================== - -An I-frame displayed via the VIDEO_STILLPICTURE call is passed on -within the following structure. - - -.. code-block:: c - - /* pointer to and size of a single iframe in memory */ - struct video_still_picture { - char *iFrame; /* pointer to a single iframe in memory */ - int32_t size; - }; - - -.. _video_caps: - -video capabilities -================== - -A call to VIDEO_GET_CAPABILITIES returns an unsigned integer with the -following bits set according to the hardwares capabilities. - - -.. code-block:: c - - /* bit definitions for capabilities: */ - /* can the hardware decode MPEG1 and/or MPEG2? */ - #define VIDEO_CAP_MPEG1 1 - #define VIDEO_CAP_MPEG2 2 - /* can you send a system and/or program stream to video device? - (you still have to open the video and the audio device but only - send the stream to the video device) */ - #define VIDEO_CAP_SYS 4 - #define VIDEO_CAP_PROG 8 - /* can the driver also handle SPU, NAVI and CSS encoded data? - (CSS API is not present yet) */ - #define VIDEO_CAP_SPU 16 - #define VIDEO_CAP_NAVI 32 - #define VIDEO_CAP_CSS 64 diff --git a/Documentation/media/uapi/fdl-appendix.rst b/Documentation/media/uapi/fdl-appendix.rst deleted file mode 100644 index 9316b8617502..000000000000 --- a/Documentation/media/uapi/fdl-appendix.rst +++ /dev/null @@ -1,478 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _fdl: - -****************************** -GNU Free Documentation License -****************************** - - -.. _fdl-preamble: - -0. PREAMBLE -=========== - -The purpose of this License is to make a manual, textbook, or other -written document “free” in the sense of freedom: to assure everyone the -effective freedom to copy and redistribute it, with or without modifying -it, either commercially or noncommercially. Secondarily, this License -preserves for the author and publisher a way to get credit for their -work, while not being considered responsible for modifications made by -others. - -This License is a kind of “copyleft”, which means that derivative works -of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft license -designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free program -should come with manuals providing the same freedoms that the software -does. But this License is not limited to software manuals; it can be -used for any textual work, regardless of subject matter or whether it is -published as a printed book. We recommend this License principally for -works whose purpose is instruction or reference. - - -.. _fdl-section1: - -1. APPLICABILITY AND DEFINITIONS -================================ - - -.. _fdl-document: - -This License applies to any manual or other work that contains a notice -placed by the copyright holder saying it can be distributed under the -terms of this License. The “Document”, below, refers to any such manual -or work. Any member of the public is a licensee, and is addressed as -“you”. - - -.. _fdl-modified: - -A “Modified Version” of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - - -.. _fdl-secondary: - -A “Secondary Section” is a named appendix or a front-matter section of -the :ref:`Document ` that deals exclusively with the -relationship of the publishers or authors of the Document to the -Document's overall subject (or to related matters) and contains nothing -that could fall directly within that overall subject. (For example, if -the Document is in part a textbook of mathematics, a Secondary Section -may not explain any mathematics.) The relationship could be a matter of -historical connection with the subject or with related matters, or of -legal, commercial, philosophical, ethical or political position -regarding them. - - -.. _fdl-invariant: - -The “Invariant Sections” are certain -:ref:`Secondary Sections ` whose titles are designated, -as being those of Invariant Sections, in the notice that says that the -:ref:`Document ` is released under this License. - - -.. _fdl-cover-texts: - -The “Cover Texts” are certain short passages of text that are listed, as -Front-Cover Texts or Back-Cover Texts, in the notice that says that the -:ref:`Document ` is released under this License. - - -.. _fdl-transparent: - -A “Transparent” copy of the :ref:`Document ` means a -machine-readable copy, represented in a format whose specification is -available to the general public, whose contents can be viewed and edited -directly and straightforwardly with generic text editors or (for images -composed of pixels) generic paint programs or (for drawings) some widely -available drawing editor, and that is suitable for input to text -formatters or for automatic translation to a variety of formats suitable -for input to text formatters. A copy made in an otherwise Transparent -file format whose markup has been designed to thwart or discourage -subsequent modification by readers is not Transparent. A copy that is -not “Transparent” is called “Opaque”. - -Examples of suitable formats for Transparent copies include plain ASCII -without markup, Texinfo input format, LaTeX input format, SGML or XML -using a publicly available DTD, and standard-conforming simple HTML -designed for human modification. Opaque formats include PostScript, PDF, -proprietary formats that can be read and edited only by proprietary word -processors, SGML or XML for which the DTD and/or processing tools are -not generally available, and the machine-generated HTML produced by some -word processors for output purposes only. - - -.. _fdl-title-page: - -The “Title Page” means, for a printed book, the title page itself, plus -such following pages as are needed to hold, legibly, the material this -License requires to appear in the title page. For works in formats which -do not have any title page as such, “Title Page” means the text near the -most prominent appearance of the work's title, preceding the beginning -of the body of the text. - - -.. _fdl-section2: - -2. VERBATIM COPYING -=================== - -You may copy and distribute the :ref:`Document ` in any -medium, either commercially or noncommercially, provided that this -License, the copyright notices, and the license notice saying this -License applies to the Document are reproduced in all copies, and that -you add no other conditions whatsoever to those of this License. You may -not use technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in -:ref:`section 3 `. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - - -.. _fdl-section3: - -3. COPYING IN QUANTITY -====================== - -If you publish printed copies of the :ref:`Document ` -numbering more than 100, and the Document's license notice requires -:ref:`Cover Texts `, you must enclose the copies in -covers that carry, clearly and legibly, all these Cover Texts: -Front-Cover Texts on the front cover, and Back-Cover Texts on the back -cover. Both covers must also clearly and legibly identify you as the -publisher of these copies. The front cover must present the full title -with all words of the title equally prominent and visible. You may add -other material on the covers in addition. Copying with changes limited -to the covers, as long as they preserve the title of the -:ref:`Document ` and satisfy these conditions, can be -treated as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute :ref:`Opaque ` copies of -the :ref:`Document ` numbering more than 100, you must -either include a machine-readable :ref:`Transparent ` -copy along with each Opaque copy, or state in or with each Opaque copy a -publicly-accessible computer-network location containing a complete -Transparent copy of the Document, free of added material, which the -general network-using public has access to download anonymously at no -charge using public-standard network protocols. If you use the latter -option, you must take reasonably prudent steps, when you begin -distribution of Opaque copies in quantity, to ensure that this -Transparent copy will remain thus accessible at the stated location -until at least one year after the last time you distribute an Opaque -copy (directly or through your agents or retailers) of that edition to -the public. - -It is requested, but not required, that you contact the authors of the -:ref:`Document ` well before redistributing any large -number of copies, to give them a chance to provide you with an updated -version of the Document. - - -.. _fdl-section4: - -4. MODIFICATIONS -================ - -You may copy and distribute a :ref:`Modified Version ` -of the :ref:`Document ` under the conditions of sections -:ref:`2 ` and :ref:`3 ` above, provided -that you release the Modified Version under precisely this License, with -the Modified Version filling the role of the Document, thus licensing -distribution and modification of the Modified Version to whoever -possesses a copy of it. In addition, you must do these things in the -Modified Version: - -- **A.** - Use in the :ref:`Title Page ` (and on the covers, - if any) a title distinct from that of the - :ref:`Document `, and from those of previous versions - (which should, if there were any, be listed in the History section of - the Document). You may use the same title as a previous version if - the original publisher of that version gives permission. - -- **B.** - List on the :ref:`Title Page `, as authors, one or - more persons or entities responsible for authorship of the - modifications in the :ref:`Modified Version `, - together with at least five of the principal authors of the - :ref:`Document ` (all of its principal authors, if it - has less than five). - -- **C.** - State on the :ref:`Title Page ` the name of the - publisher of the :ref:`Modified Version `, as the - publisher. - -- **D.** - Preserve all the copyright notices of the - :ref:`Document `. - -- **E.** - Add an appropriate copyright notice for your modifications adjacent - to the other copyright notices. - -- **F.** - Include, immediately after the copyright notices, a license notice - giving the public permission to use the - :ref:`Modified Version ` under the terms of this - License, in the form shown in the Addendum below. - -- **G.** - Preserve in that license notice the full lists of - :ref:`Invariant Sections ` and required - :ref:`Cover Texts ` given in the - :ref:`Document's ` license notice. - -- **H.** - Include an unaltered copy of this License. - -- **I.** - Preserve the section entitled “History”, and its title, and add to it - an item stating at least the title, year, new authors, and publisher - of the :ref:`Modified Version ` as given on the - :ref:`Title Page `. If there is no section entitled - “History” in the :ref:`Document `, create one stating - the title, year, authors, and publisher of the Document as given on - its Title Page, then add an item describing the Modified Version as - stated in the previous sentence. - -- **J.** - Preserve the network location, if any, given in the - :ref:`Document ` for public access to a - :ref:`Transparent ` copy of the Document, and - likewise the network locations given in the Document for previous - versions it was based on. These may be placed in the “History” - section. You may omit a network location for a work that was - published at least four years before the Document itself, or if the - original publisher of the version it refers to gives permission. - -- **K.** - In any section entitled “Acknowledgements” or “Dedications”, preserve - the section's title, and preserve in the section all the substance - and tone of each of the contributor acknowledgements and/or - dedications given therein. - -- **L.** - Preserve all the :ref:`Invariant Sections ` of the - :ref:`Document `, unaltered in their text and in - their titles. Section numbers or the equivalent are not considered - part of the section titles. - -- **M.** - Delete any section entitled “Endorsements”. Such a section may not be - included in the :ref:`Modified Version `. - -- **N.** - Do not retitle any existing section as “Endorsements” or to conflict - in title with any :ref:`Invariant Section `. - -If the :ref:`Modified Version ` includes new -front-matter sections or appendices that qualify as -:ref:`Secondary Sections ` and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the list -of :ref:`Invariant Sections ` in the Modified Version's -license notice. These titles must be distinct from any other section -titles. - -You may add a section entitled “Endorsements”, provided it contains -nothing but endorsements of your -:ref:`Modified Version ` by various parties--for -example, statements of peer review or that the text has been approved by -an organization as the authoritative definition of a standard. - -You may add a passage of up to five words as a -:ref:`Front-Cover Text `, and a passage of up to 25 -words as a :ref:`Back-Cover Text `, to the end of the -list of :ref:`Cover Texts ` in the -:ref:`Modified Version `. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or through -arrangements made by) any one entity. If the -:ref:`Document ` already includes a cover text for the -same cover, previously added by you or by arrangement made by the same -entity you are acting on behalf of, you may not add another; but you may -replace the old one, on explicit permission from the previous publisher -that added the old one. - -The author(s) and publisher(s) of the :ref:`Document ` -do not by this License give permission to use their names for publicity -for or to assert or imply endorsement of any -:ref:`Modified Version `. - - -.. _fdl-section5: - -5. COMBINING DOCUMENTS -====================== - -You may combine the :ref:`Document ` with other -documents released under this License, under the terms defined in -:ref:`section 4 ` above for modified versions, provided -that you include in the combination all of the -:ref:`Invariant Sections ` of all of the original -documents, unmodified, and list them all as Invariant Sections of your -combined work in its license notice. - -The combined work need only contain one copy of this License, and -multiple identical :ref:`Invariant Sections ` may be -replaced with a single copy. If there are multiple Invariant Sections -with the same name but different contents, make the title of each such -section unique by adding at the end of it, in parentheses, the name of -the original author or publisher of that section if known, or else a -unique number. Make the same adjustment to the section titles in the -list of Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections entitled “History” in -the various original documents, forming one section entitled “History”; -likewise combine any sections entitled “Acknowledgements”, and any -sections entitled “Dedications”. You must delete all sections entitled -“Endorsements.” - - -.. _fdl-section6: - -6. COLLECTIONS OF DOCUMENTS -=========================== - -You may make a collection consisting of the -:ref:`Document ` and other documents released under this -License, and replace the individual copies of this License in the -various documents with a single copy that is included in the collection, -provided that you follow the rules of this License for verbatim copying -of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - - -.. _fdl-section7: - -7. AGGREGATION WITH INDEPENDENT WORKS -===================================== - -A compilation of the :ref:`Document ` or its derivatives -with other separate and independent documents or works, in or on a -volume of a storage or distribution medium, does not as a whole count as -a :ref:`Modified Version ` of the Document, provided no -compilation copyright is claimed for the compilation. Such a compilation -is called an “aggregate”, and this License does not apply to the other -self-contained works thus compiled with the Document , on account of -their being thus compiled, if they are not themselves derivative works -of the Document. If the :ref:`Cover Text ` -requirement of :ref:`section 3 ` is applicable to these -copies of the Document, then if the Document is less than one quarter of -the entire aggregate, the Document's Cover Texts may be placed on covers -that surround only the Document within the aggregate. Otherwise they -must appear on covers around the whole aggregate. - - -.. _fdl-section8: - -8. TRANSLATION -============== - -Translation is considered a kind of modification, so you may distribute -translations of the :ref:`Document ` under the terms of -:ref:`section 4 `. Replacing -:ref:`Invariant Sections ` with translations requires -special permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License provided that you also include the original -English version of this License. In case of a disagreement between the -translation and the original English version of this License, the -original English version will prevail. - - -.. _fdl-section9: - -9. TERMINATION -============== - -You may not copy, modify, sublicense, or distribute the -:ref:`Document ` except as expressly provided for under -this License. Any other attempt to copy, modify, sublicense or -distribute the Document is void, and will automatically terminate your -rights under this License. However, parties who have received copies, or -rights, from you under this License will not have their licenses -terminated so long as such parties remain in full compliance. - - -.. _fdl-section10: - -10. FUTURE REVISIONS OF THIS LICENSE -==================================== - -The `Free Software Foundation `__ -may publish new, revised versions of the GNU Free Documentation License -from time to time. Such new versions will be similar in spirit to the -present version, but may differ in detail to address new problems or -concerns. See -`http://www.gnu.org/copyleft/ `__. - -Each version of the License is given a distinguishing version number. If -the :ref:`Document ` specifies that a particular -numbered version of this License “or any later version” applies to it, -you have the option of following the terms and conditions either of that -specified version or of any later version that has been published (not -as a draft) by the Free Software Foundation. If the Document does not -specify a version number of this License, you may choose any version -ever published (not as a draft) by the Free Software Foundation. - - -.. _fdl-using: - -Addendum -======== - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and license -notices just after the title page: - - Copyright © YEAR YOUR NAME. - - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation; with the :ref:`Invariant Sections ` - being LIST THEIR TITLES, with the - :ref:`Front-Cover Texts ` being LIST, and with - the :ref:`Back-Cover Texts ` being LIST. A copy - of the license is included in the section entitled “GNU Free - Documentation License”. - -If you have no :ref:`Invariant Sections `, write “with -no Invariant Sections” instead of saying which ones are invariant. If -you have no :ref:`Front-Cover Texts `, write “no -Front-Cover Texts” instead of “Front-Cover Texts being LIST”; likewise -for :ref:`Back-Cover Texts `. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of free -software license, such as the -`GNU General Public License `__, -to permit their use in free software. diff --git a/Documentation/media/uapi/gen-errors.rst b/Documentation/media/uapi/gen-errors.rst deleted file mode 100644 index 043c312dc06d..000000000000 --- a/Documentation/media/uapi/gen-errors.rst +++ /dev/null @@ -1,103 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _gen_errors: - -******************* -Generic Error Codes -******************* - - -.. _gen-errors: - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: Generic error codes - :header-rows: 0 - :stub-columns: 0 - :widths: 1 16 - - - - - ``EAGAIN`` (aka ``EWOULDBLOCK``) - - - The ioctl can't be handled because the device is in state where it - can't perform it. This could happen for example in case where - device is sleeping and ioctl is performed to query statistics. It - is also returned when the ioctl would need to wait for an event, - but the device was opened in non-blocking mode. - - - - ``EBADF`` - - - The file descriptor is not a valid. - - - - ``EBUSY`` - - - The ioctl can't be handled because the device is busy. This is - typically return while device is streaming, and an ioctl tried to - change something that would affect the stream, or would require - the usage of a hardware resource that was already allocated. The - ioctl must not be retried without performing another action to fix - the problem first (typically: stop the stream before retrying). - - - - ``EFAULT`` - - - There was a failure while copying data from/to userspace, probably - caused by an invalid pointer reference. - - - - ``EINVAL`` - - - One or more of the ioctl parameters are invalid or out of the - allowed range. This is a widely used error code. See the - individual ioctl requests for specific causes. - - - - ``ENODEV`` - - - Device not found or was removed. - - - - ``ENOMEM`` - - - There's not enough memory to handle the desired operation. - - - - ``ENOTTY`` - - - The ioctl is not supported by the driver, actually meaning that - the required functionality is not available, or the file - descriptor is not for a media device. - - - - ``ENOSPC`` - - - On USB devices, the stream ioctl's can return this error, meaning - that this request would overcommit the usb bandwidth reserved for - periodic transfers (up to 80% of the USB bandwidth). - - - - ``EPERM`` - - - Permission denied. Can be returned if the device needs write - permission, or some special capabilities is needed (e. g. root) - - - - ``EIO`` - - - I/O error. Typically used when there are problems communicating with - a hardware device. This could indicate broken or flaky hardware. - It's a 'Something is wrong, I give up!' type of error. - - - - ``ENXIO`` - - - No device corresponding to this device special file exists. - - -.. note:: - - #. This list is not exhaustive; ioctls may return other error codes. - Since errors may have side effects such as a driver reset, - applications should abort on unexpected errors, or otherwise - assume that the device is in a bad state. - - #. Request-specific error codes are listed in the individual - requests descriptions. diff --git a/Documentation/media/uapi/mediactl/media-controller-intro.rst b/Documentation/media/uapi/mediactl/media-controller-intro.rst deleted file mode 100644 index 281c559c2f3c..000000000000 --- a/Documentation/media/uapi/mediactl/media-controller-intro.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _media-controller-intro: - -Introduction -============ - -Media devices increasingly handle multiple related functions. Many USB -cameras include microphones, video capture hardware can also output -video, or SoC camera interfaces also perform memory-to-memory operations -similar to video codecs. - -Independent functions, even when implemented in the same hardware, can -be modelled as separate devices. A USB camera with a microphone will be -presented to userspace applications as V4L2 and ALSA capture devices. -The devices' relationships (when using a webcam, end-users shouldn't -have to manually select the associated USB microphone), while not made -available directly to applications by the drivers, can usually be -retrieved from sysfs. - -With more and more advanced SoC devices being introduced, the current -approach will not scale. Device topologies are getting increasingly -complex and can't always be represented by a tree structure. Hardware -blocks are shared between different functions, creating dependencies -between seemingly unrelated devices. - -Kernel abstraction APIs such as V4L2 and ALSA provide means for -applications to access hardware parameters. As newer hardware expose an -increasingly high number of those parameters, drivers need to guess what -applications really require based on limited information, thereby -implementing policies that belong to userspace. - -The media controller API aims at solving those problems. diff --git a/Documentation/media/uapi/mediactl/media-controller-model.rst b/Documentation/media/uapi/mediactl/media-controller-model.rst deleted file mode 100644 index b6d5902b556d..000000000000 --- a/Documentation/media/uapi/mediactl/media-controller-model.rst +++ /dev/null @@ -1,42 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _media-controller-model: - -Media device model -================== - -Discovering a device internal topology, and configuring it at runtime, -is one of the goals of the media controller API. To achieve this, -hardware devices and Linux Kernel interfaces are modelled as graph -objects on an oriented graph. The object types that constitute the graph -are: - -- An **entity** is a basic media hardware or software building block. - It can correspond to a large variety of logical blocks such as - physical hardware devices (CMOS sensor for instance), logical - hardware devices (a building block in a System-on-Chip image - processing pipeline), DMA channels or physical connectors. - -- An **interface** is a graph representation of a Linux Kernel - userspace API interface, like a device node or a sysfs file that - controls one or more entities in the graph. - -- A **pad** is a data connection endpoint through which an entity can - interact with other entities. Data (not restricted to video) produced - by an entity flows from the entity's output to one or more entity - inputs. Pads should not be confused with physical pins at chip - boundaries. - -- A **data link** is a point-to-point oriented connection between two - pads, either on the same entity or on different entities. Data flows - from a source pad to a sink pad. - -- An **interface link** is a point-to-point bidirectional control - connection between a Linux Kernel interface and an entity. diff --git a/Documentation/media/uapi/mediactl/media-controller.rst b/Documentation/media/uapi/mediactl/media-controller.rst deleted file mode 100644 index 6e624f690331..000000000000 --- a/Documentation/media/uapi/mediactl/media-controller.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. include:: - -.. _media_controller: - -############################## -Part IV - Media Controller API -############################## - -.. only:: html - - .. class:: toc-title - - Table of Contents - -.. toctree:: - :maxdepth: 5 - :numbered: - - media-controller-intro - media-controller-model - media-types - request-api - media-funcs - media-header - - -********************** -Revision and Copyright -********************** - -Authors: - -- Pinchart, Laurent - - - Initial version. - -- Carvalho Chehab, Mauro - - - MEDIA_IOC_G_TOPOLOGY documentation and documentation improvements. - -**Copyright** |copy| 2010 : Laurent Pinchart - -**Copyright** |copy| 2015-2016 : Mauro Carvalho Chehab - -**************** -Revision History -**************** - -:revision: 1.1.0 / 2015-12-12 (*mcc*) - -:revision: 1.0.0 / 2010-11-10 (*lp*) - -Initial revision diff --git a/Documentation/media/uapi/mediactl/media-func-close.rst b/Documentation/media/uapi/mediactl/media-func-close.rst deleted file mode 100644 index 369ccd4dee56..000000000000 --- a/Documentation/media/uapi/mediactl/media-func-close.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _media-func-close: - -************* -media close() -************* - -Name -==== - -media-close - Close a media device - - -Synopsis -======== - -.. code-block:: c - - #include - - -.. c:function:: int close( int fd ) - :name: mc-close - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - - -Description -=========== - -Closes the media device. Resources associated with the file descriptor -are freed. The device configuration remain unchanged. - - -Return Value -============ - -:ref:`close() ` returns 0 on success. On error, -1 is returned, and -``errno`` is set appropriately. Possible error codes are: - -EBADF - ``fd`` is not a valid open file descriptor. diff --git a/Documentation/media/uapi/mediactl/media-func-ioctl.rst b/Documentation/media/uapi/mediactl/media-func-ioctl.rst deleted file mode 100644 index 9a990d6480f5..000000000000 --- a/Documentation/media/uapi/mediactl/media-func-ioctl.rst +++ /dev/null @@ -1,74 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _media-func-ioctl: - -************* -media ioctl() -************* - -Name -==== - -media-ioctl - Control a media device - - -Synopsis -======== - -.. code-block:: c - - #include - - -.. c:function:: int ioctl( int fd, int request, void *argp ) - :name: mc-ioctl - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - -``request`` - Media ioctl request code as defined in the media.h header file, for - example MEDIA_IOC_SETUP_LINK. - -``argp`` - Pointer to a request-specific structure. - - -Description -=========== - -The :ref:`ioctl() ` function manipulates media device -parameters. The argument ``fd`` must be an open file descriptor. - -The ioctl ``request`` code specifies the media function to be called. It -has encoded in it whether the argument is an input, output or read/write -parameter, and the size of the argument ``argp`` in bytes. - -Macros and structures definitions specifying media ioctl requests and -their parameters are located in the media.h header file. All media ioctl -requests, their respective function and parameters are specified in -:ref:`media-user-func`. - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. - -Request-specific error codes are listed in the individual requests -descriptions. - -When an ioctl that takes an output or read/write parameter fails, the -parameter remains unmodified. diff --git a/Documentation/media/uapi/mediactl/media-func-open.rst b/Documentation/media/uapi/mediactl/media-func-open.rst deleted file mode 100644 index cd2f840ddf73..000000000000 --- a/Documentation/media/uapi/mediactl/media-func-open.rst +++ /dev/null @@ -1,76 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _media-func-open: - -************ -media open() -************ - -Name -==== - -media-open - Open a media device - - -Synopsis -======== - -.. code-block:: c - - #include - - -.. c:function:: int open( const char *device_name, int flags ) - :name: mc-open - -Arguments -========= - -``device_name`` - Device to be opened. - -``flags`` - Open flags. Access mode must be either ``O_RDONLY`` or ``O_RDWR``. - Other flags have no effect. - - -Description -=========== - -To open a media device applications call :ref:`open() ` with the -desired device name. The function has no side effects; the device -configuration remain unchanged. - -When the device is opened in read-only mode, attempts to modify its -configuration will result in an error, and ``errno`` will be set to -EBADF. - - -Return Value -============ - -:ref:`open() ` returns the new file descriptor on success. On error, --1 is returned, and ``errno`` is set appropriately. Possible error codes -are: - -EACCES - The requested access to the file is not allowed. - -EMFILE - The process already has the maximum number of files open. - -ENFILE - The system limit on the total number of open files has been reached. - -ENOMEM - Insufficient kernel memory was available. - -ENXIO - No device corresponding to this device special file exists. diff --git a/Documentation/media/uapi/mediactl/media-funcs.rst b/Documentation/media/uapi/mediactl/media-funcs.rst deleted file mode 100644 index 87b65df8252a..000000000000 --- a/Documentation/media/uapi/mediactl/media-funcs.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _media-user-func: - -****************** -Function Reference -****************** - - -.. toctree:: - :maxdepth: 1 - - media-func-open - media-func-close - media-func-ioctl - media-ioc-device-info - media-ioc-g-topology - media-ioc-enum-entities - media-ioc-enum-links - media-ioc-setup-link - media-ioc-request-alloc - request-func-close - request-func-ioctl - request-func-poll - media-request-ioc-queue - media-request-ioc-reinit diff --git a/Documentation/media/uapi/mediactl/media-header.rst b/Documentation/media/uapi/mediactl/media-header.rst deleted file mode 100644 index 1cb7c88aeff0..000000000000 --- a/Documentation/media/uapi/mediactl/media-header.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _media_header: - -**************************** -Media Controller Header File -**************************** - -.. kernel-include:: $BUILDDIR/media.h.rst - diff --git a/Documentation/media/uapi/mediactl/media-ioc-device-info.rst b/Documentation/media/uapi/mediactl/media-ioc-device-info.rst deleted file mode 100644 index f8038cfb708c..000000000000 --- a/Documentation/media/uapi/mediactl/media-ioc-device-info.rst +++ /dev/null @@ -1,118 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _media_ioc_device_info: - -*************************** -ioctl MEDIA_IOC_DEVICE_INFO -*************************** - -Name -==== - -MEDIA_IOC_DEVICE_INFO - Query device information - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, MEDIA_IOC_DEVICE_INFO, struct media_device_info *argp ) - :name: MEDIA_IOC_DEVICE_INFO - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``argp`` - Pointer to struct :c:type:`media_device_info`. - - -Description -=========== - -All media devices must support the ``MEDIA_IOC_DEVICE_INFO`` ioctl. To -query device information, applications call the ioctl with a pointer to -a struct :c:type:`media_device_info`. The driver -fills the structure and returns the information to the application. The -ioctl never fails. - - -.. c:type:: media_device_info - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. flat-table:: struct media_device_info - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - - * - char - - ``driver``\ [16] - - Name of the driver implementing the media API as a NUL-terminated - ASCII string. The driver version is stored in the - ``driver_version`` field. - - Driver specific applications can use this information to verify - the driver identity. It is also useful to work around known bugs, - or to identify drivers in error reports. - - * - char - - ``model``\ [32] - - Device model name as a NUL-terminated UTF-8 string. The device - version is stored in the ``device_version`` field and is not be - appended to the model name. - - * - char - - ``serial``\ [40] - - Serial number as a NUL-terminated ASCII string. - - * - char - - ``bus_info``\ [32] - - Location of the device in the system as a NUL-terminated ASCII - string. This includes the bus type name (PCI, USB, ...) and a - bus-specific identifier. - - * - __u32 - - ``media_version`` - - Media API version, formatted with the ``KERNEL_VERSION()`` macro. - - * - __u32 - - ``hw_revision`` - - Hardware device revision in a driver-specific format. - - * - __u32 - - ``driver_version`` - - Media device driver version, formatted with the - ``KERNEL_VERSION()`` macro. Together with the ``driver`` field - this identifies a particular driver. - - * - __u32 - - ``reserved``\ [31] - - Reserved for future extensions. Drivers and applications must set - this array to zero. - - -The ``serial`` and ``bus_info`` fields can be used to distinguish -between multiple instances of otherwise identical hardware. The serial -number takes precedence when provided and can be assumed to be unique. -If the serial number is an empty string, the ``bus_info`` field can be -used instead. The ``bus_info`` field is guaranteed to be unique, but can -vary across reboots or device unplug/replug. - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/mediactl/media-ioc-enum-entities.rst b/Documentation/media/uapi/mediactl/media-ioc-enum-entities.rst deleted file mode 100644 index 33e2b110145c..000000000000 --- a/Documentation/media/uapi/mediactl/media-ioc-enum-entities.rst +++ /dev/null @@ -1,156 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _media_ioc_enum_entities: - -***************************** -ioctl MEDIA_IOC_ENUM_ENTITIES -***************************** - -Name -==== - -MEDIA_IOC_ENUM_ENTITIES - Enumerate entities and their properties - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, MEDIA_IOC_ENUM_ENTITIES, struct media_entity_desc *argp ) - :name: MEDIA_IOC_ENUM_ENTITIES - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``argp`` - Pointer to struct :c:type:`media_entity_desc`. - - -Description -=========== - -To query the attributes of an entity, applications set the id field of a -struct :c:type:`media_entity_desc` structure and -call the MEDIA_IOC_ENUM_ENTITIES ioctl with a pointer to this -structure. The driver fills the rest of the structure or returns an -EINVAL error code when the id is invalid. - -.. _media-ent-id-flag-next: - -Entities can be enumerated by or'ing the id with the -``MEDIA_ENT_ID_FLAG_NEXT`` flag. The driver will return information -about the entity with the smallest id strictly larger than the requested -one ('next entity'), or the ``EINVAL`` error code if there is none. - -Entity IDs can be non-contiguous. Applications must *not* try to -enumerate entities by calling MEDIA_IOC_ENUM_ENTITIES with increasing -id's until they get an error. - - -.. c:type:: media_entity_desc - -.. tabularcolumns:: |p{1.5cm}|p{1.7cm}|p{1.6cm}|p{1.5cm}|p{11.2cm}| - -.. flat-table:: struct media_entity_desc - :header-rows: 0 - :stub-columns: 0 - :widths: 2 2 1 8 - - * - __u32 - - ``id`` - - - - Entity ID, set by the application. When the ID is or'ed with - ``MEDIA_ENT_ID_FLAG_NEXT``, the driver clears the flag and returns - the first entity with a larger ID. Do not expect that the ID will - always be the same for each instance of the device. In other words, - do not hardcode entity IDs in an application. - - * - char - - ``name``\ [32] - - - - Entity name as an UTF-8 NULL-terminated string. This name must be unique - within the media topology. - - * - __u32 - - ``type`` - - - - Entity type, see :ref:`media-entity-functions` for details. - - * - __u32 - - ``revision`` - - - - Entity revision. Always zero (obsolete) - - * - __u32 - - ``flags`` - - - - Entity flags, see :ref:`media-entity-flag` for details. - - * - __u32 - - ``group_id`` - - - - Entity group ID. Always zero (obsolete) - - * - __u16 - - ``pads`` - - - - Number of pads - - * - __u16 - - ``links`` - - - - Total number of outbound links. Inbound links are not counted in - this field. - - * - __u32 - - ``reserved[4]`` - - - - Reserved for future extensions. Drivers and applications must set - the array to zero. - - * - union { - - (anonymous) - - * - struct - - ``dev`` - - - - Valid for (sub-)devices that create a single device node. - - * - - - __u32 - - ``major`` - - Device node major number. - - * - - - __u32 - - ``minor`` - - Device node minor number. - - * - __u8 - - ``raw``\ [184] - - - - - * - } - - - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. - -EINVAL - The struct :c:type:`media_entity_desc` ``id`` - references a non-existing entity. diff --git a/Documentation/media/uapi/mediactl/media-ioc-enum-links.rst b/Documentation/media/uapi/mediactl/media-ioc-enum-links.rst deleted file mode 100644 index b827ebc398f8..000000000000 --- a/Documentation/media/uapi/mediactl/media-ioc-enum-links.rst +++ /dev/null @@ -1,157 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _media_ioc_enum_links: - -************************** -ioctl MEDIA_IOC_ENUM_LINKS -************************** - -Name -==== - -MEDIA_IOC_ENUM_LINKS - Enumerate all pads and links for a given entity - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, MEDIA_IOC_ENUM_LINKS, struct media_links_enum *argp ) - :name: MEDIA_IOC_ENUM_LINKS - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``argp`` - Pointer to struct :c:type:`media_links_enum`. - - -Description -=========== - -To enumerate pads and/or links for a given entity, applications set the -entity field of a struct :c:type:`media_links_enum` -structure and initialize the struct -:c:type:`media_pad_desc` and struct -:c:type:`media_link_desc` structure arrays pointed by -the ``pads`` and ``links`` fields. They then call the -MEDIA_IOC_ENUM_LINKS ioctl with a pointer to this structure. - -If the ``pads`` field is not NULL, the driver fills the ``pads`` array -with information about the entity's pads. The array must have enough -room to store all the entity's pads. The number of pads can be retrieved -with :ref:`MEDIA_IOC_ENUM_ENTITIES`. - -If the ``links`` field is not NULL, the driver fills the ``links`` array -with information about the entity's outbound links. The array must have -enough room to store all the entity's outbound links. The number of -outbound links can be retrieved with :ref:`MEDIA_IOC_ENUM_ENTITIES`. - -Only forward links that originate at one of the entity's source pads are -returned during the enumeration process. - - -.. c:type:: media_links_enum - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. flat-table:: struct media_links_enum - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u32 - - ``entity`` - - Entity id, set by the application. - - * - struct :c:type:`media_pad_desc` - - \*\ ``pads`` - - Pointer to a pads array allocated by the application. Ignored if - NULL. - - * - struct :c:type:`media_link_desc` - - \*\ ``links`` - - Pointer to a links array allocated by the application. Ignored if - NULL. - - * - __u32 - - ``reserved[4]`` - - Reserved for future extensions. Drivers and applications must set - the array to zero. - - -.. c:type:: media_pad_desc - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. flat-table:: struct media_pad_desc - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u32 - - ``entity`` - - ID of the entity this pad belongs to. - - * - __u16 - - ``index`` - - Pad index, starts at 0. - - * - __u32 - - ``flags`` - - Pad flags, see :ref:`media-pad-flag` for more details. - - * - __u32 - - ``reserved[2]`` - - Reserved for future extensions. Drivers and applications must set - the array to zero. - - - -.. c:type:: media_link_desc - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. flat-table:: struct media_link_desc - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - struct :c:type:`media_pad_desc` - - ``source`` - - Pad at the origin of this link. - - * - struct :c:type:`media_pad_desc` - - ``sink`` - - Pad at the target of this link. - - * - __u32 - - ``flags`` - - Link flags, see :ref:`media-link-flag` for more details. - - * - __u32 - - ``reserved[2]`` - - Reserved for future extensions. Drivers and applications must set - the array to zero. - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. - -EINVAL - The struct :c:type:`media_links_enum` ``id`` - references a non-existing entity. diff --git a/Documentation/media/uapi/mediactl/media-ioc-g-topology.rst b/Documentation/media/uapi/mediactl/media-ioc-g-topology.rst deleted file mode 100644 index 0a7d76ac8ded..000000000000 --- a/Documentation/media/uapi/mediactl/media-ioc-g-topology.rst +++ /dev/null @@ -1,307 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _media_ioc_g_topology: - -************************** -ioctl MEDIA_IOC_G_TOPOLOGY -************************** - -Name -==== - -MEDIA_IOC_G_TOPOLOGY - Enumerate the graph topology and graph element properties - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, MEDIA_IOC_G_TOPOLOGY, struct media_v2_topology *argp ) - :name: MEDIA_IOC_G_TOPOLOGY - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``argp`` - Pointer to struct :c:type:`media_v2_topology`. - - -Description -=========== - -The typical usage of this ioctl is to call it twice. On the first call, -the structure defined at struct -:c:type:`media_v2_topology` should be zeroed. At -return, if no errors happen, this ioctl will return the -``topology_version`` and the total number of entities, interfaces, pads -and links. - -Before the second call, the userspace should allocate arrays to store -the graph elements that are desired, putting the pointers to them at the -ptr_entities, ptr_interfaces, ptr_links and/or ptr_pads, keeping the -other values untouched. - -If the ``topology_version`` remains the same, the ioctl should fill the -desired arrays with the media graph elements. - -.. tabularcolumns:: |p{1.6cm}|p{3.4cm}|p{12.5cm}| - -.. c:type:: media_v2_topology - -.. flat-table:: struct media_v2_topology - :header-rows: 0 - :stub-columns: 0 - :widths: 1 2 8 - - * - __u64 - - ``topology_version`` - - Version of the media graph topology. When the graph is created, - this field starts with zero. Every time a graph element is added - or removed, this field is incremented. - - * - __u32 - - ``num_entities`` - - Number of entities in the graph - - * - __u32 - - ``reserved1`` - - Applications and drivers shall set this to 0. - - * - __u64 - - ``ptr_entities`` - - A pointer to a memory area where the entities array will be - stored, converted to a 64-bits integer. It can be zero. if zero, - the ioctl won't store the entities. It will just update - ``num_entities`` - - * - __u32 - - ``num_interfaces`` - - Number of interfaces in the graph - - * - __u32 - - ``reserved2`` - - Applications and drivers shall set this to 0. - - * - __u64 - - ``ptr_interfaces`` - - A pointer to a memory area where the interfaces array will be - stored, converted to a 64-bits integer. It can be zero. if zero, - the ioctl won't store the interfaces. It will just update - ``num_interfaces`` - - * - __u32 - - ``num_pads`` - - Total number of pads in the graph - - * - __u32 - - ``reserved3`` - - Applications and drivers shall set this to 0. - - * - __u64 - - ``ptr_pads`` - - A pointer to a memory area where the pads array will be stored, - converted to a 64-bits integer. It can be zero. if zero, the ioctl - won't store the pads. It will just update ``num_pads`` - - * - __u32 - - ``num_links`` - - Total number of data and interface links in the graph - - * - __u32 - - ``reserved4`` - - Applications and drivers shall set this to 0. - - * - __u64 - - ``ptr_links`` - - A pointer to a memory area where the links array will be stored, - converted to a 64-bits integer. It can be zero. if zero, the ioctl - won't store the links. It will just update ``num_links`` - - -.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| - -.. c:type:: media_v2_entity - -.. flat-table:: struct media_v2_entity - :header-rows: 0 - :stub-columns: 0 - :widths: 1 2 8 - - * - __u32 - - ``id`` - - Unique ID for the entity. Do not expect that the ID will - always be the same for each instance of the device. In other words, - do not hardcode entity IDs in an application. - - * - char - - ``name``\ [64] - - Entity name as an UTF-8 NULL-terminated string. This name must be unique - within the media topology. - - * - __u32 - - ``function`` - - Entity main function, see :ref:`media-entity-functions` for details. - - * - __u32 - - ``flags`` - - Entity flags, see :ref:`media-entity-flag` for details. - Only valid if ``MEDIA_V2_ENTITY_HAS_FLAGS(media_version)`` - returns true. The ``media_version`` is defined in struct - :c:type:`media_device_info` and can be retrieved using - :ref:`MEDIA_IOC_DEVICE_INFO`. - - * - __u32 - - ``reserved``\ [5] - - Reserved for future extensions. Drivers and applications must set - this array to zero. - - -.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| - -.. c:type:: media_v2_interface - -.. flat-table:: struct media_v2_interface - :header-rows: 0 - :stub-columns: 0 - :widths: 1 2 8 - - * - __u32 - - ``id`` - - Unique ID for the interface. Do not expect that the ID will - always be the same for each instance of the device. In other words, - do not hardcode interface IDs in an application. - - * - __u32 - - ``intf_type`` - - Interface type, see :ref:`media-intf-type` for details. - - * - __u32 - - ``flags`` - - Interface flags. Currently unused. - - * - __u32 - - ``reserved``\ [9] - - Reserved for future extensions. Drivers and applications must set - this array to zero. - - * - struct media_v2_intf_devnode - - ``devnode`` - - Used only for device node interfaces. See - :c:type:`media_v2_intf_devnode` for details. - - -.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| - -.. c:type:: media_v2_intf_devnode - -.. flat-table:: struct media_v2_intf_devnode - :header-rows: 0 - :stub-columns: 0 - :widths: 1 2 8 - - * - __u32 - - ``major`` - - Device node major number. - - * - __u32 - - ``minor`` - - Device node minor number. - -.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| - -.. c:type:: media_v2_pad - -.. flat-table:: struct media_v2_pad - :header-rows: 0 - :stub-columns: 0 - :widths: 1 2 8 - - * - __u32 - - ``id`` - - Unique ID for the pad. Do not expect that the ID will - always be the same for each instance of the device. In other words, - do not hardcode pad IDs in an application. - - * - __u32 - - ``entity_id`` - - Unique ID for the entity where this pad belongs. - - * - __u32 - - ``flags`` - - Pad flags, see :ref:`media-pad-flag` for more details. - - * - __u32 - - ``index`` - - Pad index, starts at 0. Only valid if ``MEDIA_V2_PAD_HAS_INDEX(media_version)`` - returns true. The ``media_version`` is defined in struct - :c:type:`media_device_info` and can be retrieved using - :ref:`MEDIA_IOC_DEVICE_INFO`. - - * - __u32 - - ``reserved``\ [4] - - Reserved for future extensions. Drivers and applications must set - this array to zero. - - -.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| - -.. c:type:: media_v2_link - -.. flat-table:: struct media_v2_link - :header-rows: 0 - :stub-columns: 0 - :widths: 1 2 8 - - * - __u32 - - ``id`` - - Unique ID for the link. Do not expect that the ID will - always be the same for each instance of the device. In other words, - do not hardcode link IDs in an application. - - * - __u32 - - ``source_id`` - - On pad to pad links: unique ID for the source pad. - - On interface to entity links: unique ID for the interface. - - * - __u32 - - ``sink_id`` - - On pad to pad links: unique ID for the sink pad. - - On interface to entity links: unique ID for the entity. - - * - __u32 - - ``flags`` - - Link flags, see :ref:`media-link-flag` for more details. - - * - __u32 - - ``reserved``\ [6] - - Reserved for future extensions. Drivers and applications must set - this array to zero. - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. - -ENOSPC - This is returned when either one or more of the num_entities, - num_interfaces, num_links or num_pads are non-zero and are - smaller than the actual number of elements inside the graph. This - may happen if the ``topology_version`` changed when compared to the - last time this ioctl was called. Userspace should usually free the - area for the pointers, zero the struct elements and call this ioctl - again. diff --git a/Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst b/Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst deleted file mode 100644 index 6d4ca4ada2e0..000000000000 --- a/Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst +++ /dev/null @@ -1,90 +0,0 @@ -.. This file is dual-licensed: you can use it either under the terms -.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this -.. dual licensing only applies to this file, and not this project as a -.. whole. -.. -.. a) This file 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 file 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. -.. -.. Or, alternatively, -.. -.. b) Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections - -.. _media_ioc_request_alloc: - -***************************** -ioctl MEDIA_IOC_REQUEST_ALLOC -***************************** - -Name -==== - -MEDIA_IOC_REQUEST_ALLOC - Allocate a request - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, MEDIA_IOC_REQUEST_ALLOC, int *argp ) - :name: MEDIA_IOC_REQUEST_ALLOC - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``argp`` - Pointer to an integer. - - -Description -=========== - -If the media device supports :ref:`requests `, then -this ioctl can be used to allocate a request. If it is not supported, then -``errno`` is set to ``ENOTTY``. A request is accessed through a file descriptor -that is returned in ``*argp``. - -If the request was successfully allocated, then the request file descriptor -can be passed to the :ref:`VIDIOC_QBUF `, -:ref:`VIDIOC_G_EXT_CTRLS `, -:ref:`VIDIOC_S_EXT_CTRLS ` and -:ref:`VIDIOC_TRY_EXT_CTRLS ` ioctls. - -In addition, the request can be queued by calling -:ref:`MEDIA_REQUEST_IOC_QUEUE` and re-initialized by calling -:ref:`MEDIA_REQUEST_IOC_REINIT`. - -Finally, the file descriptor can be :ref:`polled ` to wait -for the request to complete. - -The request will remain allocated until all the file descriptors associated -with it are closed by :ref:`close() ` and the driver no -longer uses the request internally. See also -:ref:`here ` for more information. - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. - -ENOTTY - The driver has no support for requests. diff --git a/Documentation/media/uapi/mediactl/media-ioc-setup-link.rst b/Documentation/media/uapi/mediactl/media-ioc-setup-link.rst deleted file mode 100644 index ae39dbbe48a0..000000000000 --- a/Documentation/media/uapi/mediactl/media-ioc-setup-link.rst +++ /dev/null @@ -1,74 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _media_ioc_setup_link: - -************************** -ioctl MEDIA_IOC_SETUP_LINK -************************** - -Name -==== - -MEDIA_IOC_SETUP_LINK - Modify the properties of a link - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, MEDIA_IOC_SETUP_LINK, struct media_link_desc *argp ) - :name: MEDIA_IOC_SETUP_LINK - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``argp`` - Pointer to struct :c:type:`media_link_desc`. - - -Description -=========== - -To change link properties applications fill a struct -:c:type:`media_link_desc` with link identification -information (source and sink pad) and the new requested link flags. They -then call the MEDIA_IOC_SETUP_LINK ioctl with a pointer to that -structure. - -The only configurable property is the ``ENABLED`` link flag to -enable/disable a link. Links marked with the ``IMMUTABLE`` link flag can -not be enabled or disabled. - -Link configuration has no side effect on other links. If an enabled link -at the sink pad prevents the link from being enabled, the driver returns -with an ``EBUSY`` error code. - -Only links marked with the ``DYNAMIC`` link flag can be enabled/disabled -while streaming media data. Attempting to enable or disable a streaming -non-dynamic link will return an ``EBUSY`` error code. - -If the specified link can't be found the driver returns with an ``EINVAL`` -error code. - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. - -EINVAL - The struct :c:type:`media_link_desc` references a - non-existing link, or the link is immutable and an attempt to modify - its configuration was made. diff --git a/Documentation/media/uapi/mediactl/media-request-ioc-queue.rst b/Documentation/media/uapi/mediactl/media-request-ioc-queue.rst deleted file mode 100644 index fc8458746d51..000000000000 --- a/Documentation/media/uapi/mediactl/media-request-ioc-queue.rst +++ /dev/null @@ -1,102 +0,0 @@ -.. This file is dual-licensed: you can use it either under the terms -.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this -.. dual licensing only applies to this file, and not this project as a -.. whole. -.. -.. a) This file 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 file 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. -.. -.. Or, alternatively, -.. -.. b) Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections - -.. _media_request_ioc_queue: - -***************************** -ioctl MEDIA_REQUEST_IOC_QUEUE -***************************** - -Name -==== - -MEDIA_REQUEST_IOC_QUEUE - Queue a request - - -Synopsis -======== - -.. c:function:: int ioctl( int request_fd, MEDIA_REQUEST_IOC_QUEUE ) - :name: MEDIA_REQUEST_IOC_QUEUE - - -Arguments -========= - -``request_fd`` - File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`. - - -Description -=========== - -If the media device supports :ref:`requests `, then -this request ioctl can be used to queue a previously allocated request. - -If the request was successfully queued, then the file descriptor can be -:ref:`polled ` to wait for the request to complete. - -If the request was already queued before, then ``EBUSY`` is returned. -Other errors can be returned if the contents of the request contained -invalid or inconsistent data, see the next section for a list of -common error codes. On error both the request and driver state are unchanged. - -Once a request is queued, then the driver is required to gracefully handle -errors that occur when the request is applied to the hardware. The -exception is the ``EIO`` error which signals a fatal error that requires -the application to stop streaming to reset the hardware state. - -It is not allowed to mix queuing requests with queuing buffers directly -(without a request). ``EBUSY`` will be returned if the first buffer was -queued directly and you next try to queue a request, or vice versa. - -A request must contain at least one buffer, otherwise this ioctl will -return an ``ENOENT`` error. - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. - -EBUSY - The request was already queued or the application queued the first - buffer directly, but later attempted to use a request. It is not permitted - to mix the two APIs. -ENOENT - The request did not contain any buffers. All requests are required - to have at least one buffer. This can also be returned if some required - configuration is missing in the request. -ENOMEM - Out of memory when allocating internal data structures for this - request. -EINVAL - The request has invalid data. -EIO - The hardware is in a bad state. To recover, the application needs to - stop streaming to reset the hardware state and then try to restart - streaming. diff --git a/Documentation/media/uapi/mediactl/media-request-ioc-reinit.rst b/Documentation/media/uapi/mediactl/media-request-ioc-reinit.rst deleted file mode 100644 index 61381e87665a..000000000000 --- a/Documentation/media/uapi/mediactl/media-request-ioc-reinit.rst +++ /dev/null @@ -1,75 +0,0 @@ -.. This file is dual-licensed: you can use it either under the terms -.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this -.. dual licensing only applies to this file, and not this project as a -.. whole. -.. -.. a) This file 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 file 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. -.. -.. Or, alternatively, -.. -.. b) Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections - -.. _media_request_ioc_reinit: - -****************************** -ioctl MEDIA_REQUEST_IOC_REINIT -****************************** - -Name -==== - -MEDIA_REQUEST_IOC_REINIT - Re-initialize a request - - -Synopsis -======== - -.. c:function:: int ioctl( int request_fd, MEDIA_REQUEST_IOC_REINIT ) - :name: MEDIA_REQUEST_IOC_REINIT - - -Arguments -========= - -``request_fd`` - File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`. - -Description -=========== - -If the media device supports :ref:`requests `, then -this request ioctl can be used to re-initialize a previously allocated -request. - -Re-initializing a request will clear any existing data from the request. -This avoids having to :ref:`close() ` a completed -request and allocate a new request. Instead the completed request can just -be re-initialized and it is ready to be used again. - -A request can only be re-initialized if it either has not been queued -yet, or if it was queued and completed. Otherwise it will set ``errno`` -to ``EBUSY``. No other error codes can be returned. - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. - -EBUSY - The request is queued but not yet completed. diff --git a/Documentation/media/uapi/mediactl/media-types.rst b/Documentation/media/uapi/mediactl/media-types.rst deleted file mode 100644 index 3af6a414b501..000000000000 --- a/Documentation/media/uapi/mediactl/media-types.rst +++ /dev/null @@ -1,425 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _media-controller-types: - -Types and flags used to represent the media graph elements -========================================================== - -.. tabularcolumns:: |p{8.2cm}|p{10.3cm}| - -.. _media-entity-functions: -.. _MEDIA-ENT-F-UNKNOWN: -.. _MEDIA-ENT-F-V4L2-SUBDEV-UNKNOWN: -.. _MEDIA-ENT-F-IO-V4L: -.. _MEDIA-ENT-F-IO-VBI: -.. _MEDIA-ENT-F-IO-SWRADIO: -.. _MEDIA-ENT-F-IO-DTV: -.. _MEDIA-ENT-F-DTV-DEMOD: -.. _MEDIA-ENT-F-TS-DEMUX: -.. _MEDIA-ENT-F-DTV-CA: -.. _MEDIA-ENT-F-DTV-NET-DECAP: -.. _MEDIA-ENT-F-CONN-RF: -.. _MEDIA-ENT-F-CONN-SVIDEO: -.. _MEDIA-ENT-F-CONN-COMPOSITE: -.. _MEDIA-ENT-F-CAM-SENSOR: -.. _MEDIA-ENT-F-FLASH: -.. _MEDIA-ENT-F-LENS: -.. _MEDIA-ENT-F-ATV-DECODER: -.. _MEDIA-ENT-F-TUNER: -.. _MEDIA-ENT-F-IF-VID-DECODER: -.. _MEDIA-ENT-F-IF-AUD-DECODER: -.. _MEDIA-ENT-F-AUDIO-CAPTURE: -.. _MEDIA-ENT-F-AUDIO-PLAYBACK: -.. _MEDIA-ENT-F-AUDIO-MIXER: -.. _MEDIA-ENT-F-PROC-VIDEO-COMPOSER: -.. _MEDIA-ENT-F-PROC-VIDEO-PIXEL-FORMATTER: -.. _MEDIA-ENT-F-PROC-VIDEO-PIXEL-ENC-CONV: -.. _MEDIA-ENT-F-PROC-VIDEO-LUT: -.. _MEDIA-ENT-F-PROC-VIDEO-SCALER: -.. _MEDIA-ENT-F-PROC-VIDEO-STATISTICS: -.. _MEDIA-ENT-F-PROC-VIDEO-ENCODER: -.. _MEDIA-ENT-F-PROC-VIDEO-DECODER: -.. _MEDIA-ENT-F-VID-MUX: -.. _MEDIA-ENT-F-VID-IF-BRIDGE: -.. _MEDIA-ENT-F-DV-DECODER: -.. _MEDIA-ENT-F-DV-ENCODER: - -.. cssclass:: longtable - -.. flat-table:: Media entity functions - :header-rows: 0 - :stub-columns: 0 - - * - ``MEDIA_ENT_F_UNKNOWN`` and - ``MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN`` - - Unknown entity. That generally indicates that a driver didn't - initialize properly the entity, which is a Kernel bug - - * - ``MEDIA_ENT_F_IO_V4L`` - - Data streaming input and/or output entity. - - * - ``MEDIA_ENT_F_IO_VBI`` - - V4L VBI streaming input or output entity - - * - ``MEDIA_ENT_F_IO_SWRADIO`` - - V4L Software Digital Radio (SDR) streaming input or output entity - - * - ``MEDIA_ENT_F_IO_DTV`` - - DVB Digital TV streaming input or output entity - - * - ``MEDIA_ENT_F_DTV_DEMOD`` - - Digital TV demodulator entity. - - * - ``MEDIA_ENT_F_TS_DEMUX`` - - MPEG Transport stream demux entity. Could be implemented on - hardware or in Kernelspace by the Linux DVB subsystem. - - * - ``MEDIA_ENT_F_DTV_CA`` - - Digital TV Conditional Access module (CAM) entity - - * - ``MEDIA_ENT_F_DTV_NET_DECAP`` - - Digital TV network ULE/MLE desencapsulation entity. Could be - implemented on hardware or in Kernelspace - - * - ``MEDIA_ENT_F_CONN_RF`` - - Connector for a Radio Frequency (RF) signal. - - * - ``MEDIA_ENT_F_CONN_SVIDEO`` - - Connector for a S-Video signal. - - * - ``MEDIA_ENT_F_CONN_COMPOSITE`` - - Connector for a RGB composite signal. - - * - ``MEDIA_ENT_F_CAM_SENSOR`` - - Camera video sensor entity. - - * - ``MEDIA_ENT_F_FLASH`` - - Flash controller entity. - - * - ``MEDIA_ENT_F_LENS`` - - Lens controller entity. - - * - ``MEDIA_ENT_F_ATV_DECODER`` - - Analog video decoder, the basic function of the video decoder is - to accept analogue video from a wide variety of sources such as - broadcast, DVD players, cameras and video cassette recorders, in - either NTSC, PAL, SECAM or HD format, separating the stream into - its component parts, luminance and chrominance, and output it in - some digital video standard, with appropriate timing signals. - - * - ``MEDIA_ENT_F_TUNER`` - - Digital TV, analog TV, radio and/or software radio tuner, with - consists on a PLL tuning stage that converts radio frequency (RF) - signal into an Intermediate Frequency (IF). Modern tuners have - internally IF-PLL decoders for audio and video, but older models - have those stages implemented on separate entities. - - * - ``MEDIA_ENT_F_IF_VID_DECODER`` - - IF-PLL video decoder. It receives the IF from a PLL and decodes - the analog TV video signal. This is commonly found on some very - old analog tuners, like Philips MK3 designs. They all contain a - tda9887 (or some software compatible similar chip, like tda9885). - Those devices use a different I2C address than the tuner PLL. - - * - ``MEDIA_ENT_F_IF_AUD_DECODER`` - - IF-PLL sound decoder. It receives the IF from a PLL and decodes - the analog TV audio signal. This is commonly found on some very - old analog hardware, like Micronas msp3400, Philips tda9840, - tda985x, etc. Those devices use a different I2C address than the - tuner PLL and should be controlled together with the IF-PLL video - decoder. - - * - ``MEDIA_ENT_F_AUDIO_CAPTURE`` - - Audio Capture Function Entity. - - * - ``MEDIA_ENT_F_AUDIO_PLAYBACK`` - - Audio Playback Function Entity. - - * - ``MEDIA_ENT_F_AUDIO_MIXER`` - - Audio Mixer Function Entity. - - * - ``MEDIA_ENT_F_PROC_VIDEO_COMPOSER`` - - Video composer (blender). An entity capable of video - composing must have at least two sink pads and one source - pad, and composes input video frames onto output video - frames. Composition can be performed using alpha blending, - color keying, raster operations (ROP), stitching or any other - means. - - * - ``MEDIA_ENT_F_PROC_VIDEO_PIXEL_FORMATTER`` - - Video pixel formatter. An entity capable of pixel formatting - must have at least one sink pad and one source pad. Read - pixel formatters read pixels from memory and perform a subset - of unpacking, cropping, color keying, alpha multiplication - and pixel encoding conversion. Write pixel formatters perform - a subset of dithering, pixel encoding conversion and packing - and write pixels to memory. - - * - ``MEDIA_ENT_F_PROC_VIDEO_PIXEL_ENC_CONV`` - - Video pixel encoding converter. An entity capable of pixel - encoding conversion must have at least one sink pad and one - source pad, and convert the encoding of pixels received on - its sink pad(s) to a different encoding output on its source - pad(s). Pixel encoding conversion includes but isn't limited - to RGB to/from HSV, RGB to/from YUV and CFA (Bayer) to RGB - conversions. - - * - ``MEDIA_ENT_F_PROC_VIDEO_LUT`` - - Video look-up table. An entity capable of video lookup table - processing must have one sink pad and one source pad. It uses - the values of the pixels received on its sink pad to look up - entries in internal tables and output them on its source pad. - The lookup processing can be performed on all components - separately or combine them for multi-dimensional table - lookups. - - * - ``MEDIA_ENT_F_PROC_VIDEO_SCALER`` - - Video scaler. An entity capable of video scaling must have - at least one sink pad and one source pad, and scale the - video frame(s) received on its sink pad(s) to a different - resolution output on its source pad(s). The range of - supported scaling ratios is entity-specific and can differ - between the horizontal and vertical directions (in particular - scaling can be supported in one direction only). Binning and - sub-sampling (occasionally also referred to as skipping) are - considered as scaling. - - * - ``MEDIA_ENT_F_PROC_VIDEO_STATISTICS`` - - Video statistics computation (histogram, 3A, etc.). An entity - capable of statistics computation must have one sink pad and - one source pad. It computes statistics over the frames - received on its sink pad and outputs the statistics data on - its source pad. - - * - ``MEDIA_ENT_F_PROC_VIDEO_ENCODER`` - - Video (MPEG, HEVC, VPx, etc.) encoder. An entity capable of - compressing video frames. Must have one sink pad and at least - one source pad. - - * - ``MEDIA_ENT_F_PROC_VIDEO_DECODER`` - - Video (MPEG, HEVC, VPx, etc.) decoder. An entity capable of - decompressing a compressed video stream into uncompressed video - frames. Must have one sink pad and at least one source pad. - - * - ``MEDIA_ENT_F_VID_MUX`` - - Video multiplexer. An entity capable of multiplexing must have at - least two sink pads and one source pad, and must pass the video - frame(s) received from the active sink pad to the source pad. - - * - ``MEDIA_ENT_F_VID_IF_BRIDGE`` - - Video interface bridge. A video interface bridge entity must have at - least one sink pad and at least one source pad. It receives video - frames on its sink pad from an input video bus of one type (HDMI, eDP, - MIPI CSI-2, etc.), and outputs them on its source pad to an output - video bus of another type (eDP, MIPI CSI-2, parallel, etc.). - - * - ``MEDIA_ENT_F_DV_DECODER`` - - Digital video decoder. The basic function of the video decoder is - to accept digital video from a wide variety of sources - and output it in some digital video standard, with appropriate - timing signals. - - * - ``MEDIA_ENT_F_DV_ENCODER`` - - Digital video encoder. The basic function of the video encoder is - to accept digital video from some digital video standard with - appropriate timing signals (usually a parallel video bus with sync - signals) and output this to a digital video output connector such - as HDMI or DisplayPort. - -.. tabularcolumns:: |p{5.5cm}|p{12.0cm}| - -.. _media-entity-flag: -.. _MEDIA-ENT-FL-DEFAULT: -.. _MEDIA-ENT-FL-CONNECTOR: - -.. flat-table:: Media entity flags - :header-rows: 0 - :stub-columns: 0 - - * - ``MEDIA_ENT_FL_DEFAULT`` - - Default entity for its type. Used to discover the default audio, - VBI and video devices, the default camera sensor, etc. - - * - ``MEDIA_ENT_FL_CONNECTOR`` - - The entity represents a connector. - - -.. tabularcolumns:: |p{6.5cm}|p{6.0cm}|p{5.0cm}| - -.. _media-intf-type: -.. _MEDIA-INTF-T-DVB-FE: -.. _MEDIA-INTF-T-DVB-DEMUX: -.. _MEDIA-INTF-T-DVB-DVR: -.. _MEDIA-INTF-T-DVB-CA: -.. _MEDIA-INTF-T-DVB-NET: -.. _MEDIA-INTF-T-V4L-VIDEO: -.. _MEDIA-INTF-T-V4L-VBI: -.. _MEDIA-INTF-T-V4L-RADIO: -.. _MEDIA-INTF-T-V4L-SUBDEV: -.. _MEDIA-INTF-T-V4L-SWRADIO: -.. _MEDIA-INTF-T-V4L-TOUCH: -.. _MEDIA-INTF-T-ALSA-PCM-CAPTURE: -.. _MEDIA-INTF-T-ALSA-PCM-PLAYBACK: -.. _MEDIA-INTF-T-ALSA-CONTROL: -.. _MEDIA-INTF-T-ALSA-COMPRESS: -.. _MEDIA-INTF-T-ALSA-RAWMIDI: -.. _MEDIA-INTF-T-ALSA-HWDEP: -.. _MEDIA-INTF-T-ALSA-SEQUENCER: -.. _MEDIA-INTF-T-ALSA-TIMER: - -.. flat-table:: Media interface types - :header-rows: 0 - :stub-columns: 0 - - * - ``MEDIA_INTF_T_DVB_FE`` - - Device node interface for the Digital TV frontend - - typically, /dev/dvb/adapter?/frontend? - - * - ``MEDIA_INTF_T_DVB_DEMUX`` - - Device node interface for the Digital TV demux - - typically, /dev/dvb/adapter?/demux? - - * - ``MEDIA_INTF_T_DVB_DVR`` - - Device node interface for the Digital TV DVR - - typically, /dev/dvb/adapter?/dvr? - - * - ``MEDIA_INTF_T_DVB_CA`` - - Device node interface for the Digital TV Conditional Access - - typically, /dev/dvb/adapter?/ca? - - * - ``MEDIA_INTF_T_DVB_NET`` - - Device node interface for the Digital TV network control - - typically, /dev/dvb/adapter?/net? - - * - ``MEDIA_INTF_T_V4L_VIDEO`` - - Device node interface for video (V4L) - - typically, /dev/video? - - * - ``MEDIA_INTF_T_V4L_VBI`` - - Device node interface for VBI (V4L) - - typically, /dev/vbi? - - * - ``MEDIA_INTF_T_V4L_RADIO`` - - Device node interface for radio (V4L) - - typically, /dev/radio? - - * - ``MEDIA_INTF_T_V4L_SUBDEV`` - - Device node interface for a V4L subdevice - - typically, /dev/v4l-subdev? - - * - ``MEDIA_INTF_T_V4L_SWRADIO`` - - Device node interface for Software Defined Radio (V4L) - - typically, /dev/swradio? - - * - ``MEDIA_INTF_T_V4L_TOUCH`` - - Device node interface for Touch device (V4L) - - typically, /dev/v4l-touch? - - * - ``MEDIA_INTF_T_ALSA_PCM_CAPTURE`` - - Device node interface for ALSA PCM Capture - - typically, /dev/snd/pcmC?D?c - - * - ``MEDIA_INTF_T_ALSA_PCM_PLAYBACK`` - - Device node interface for ALSA PCM Playback - - typically, /dev/snd/pcmC?D?p - - * - ``MEDIA_INTF_T_ALSA_CONTROL`` - - Device node interface for ALSA Control - - typically, /dev/snd/controlC? - - * - ``MEDIA_INTF_T_ALSA_COMPRESS`` - - Device node interface for ALSA Compress - - typically, /dev/snd/compr? - - * - ``MEDIA_INTF_T_ALSA_RAWMIDI`` - - Device node interface for ALSA Raw MIDI - - typically, /dev/snd/midi? - - * - ``MEDIA_INTF_T_ALSA_HWDEP`` - - Device node interface for ALSA Hardware Dependent - - typically, /dev/snd/hwC?D? - - * - ``MEDIA_INTF_T_ALSA_SEQUENCER`` - - Device node interface for ALSA Sequencer - - typically, /dev/snd/seq - - * - ``MEDIA_INTF_T_ALSA_TIMER`` - - Device node interface for ALSA Timer - - typically, /dev/snd/timer - - -.. tabularcolumns:: |p{5.5cm}|p{12.0cm}| - -.. _media-pad-flag: -.. _MEDIA-PAD-FL-SINK: -.. _MEDIA-PAD-FL-SOURCE: -.. _MEDIA-PAD-FL-MUST-CONNECT: - -.. flat-table:: Media pad flags - :header-rows: 0 - :stub-columns: 0 - - * - ``MEDIA_PAD_FL_SINK`` - - Input pad, relative to the entity. Input pads sink data and are - targets of links. - - * - ``MEDIA_PAD_FL_SOURCE`` - - Output pad, relative to the entity. Output pads source data and - are origins of links. - - * - ``MEDIA_PAD_FL_MUST_CONNECT`` - - If this flag is set and the pad is linked to any other pad, then - at least one of those links must be enabled for the entity to be - able to stream. There could be temporary reasons (e.g. device - configuration dependent) for the pad to need enabled links even - when this flag isn't set; the absence of the flag doesn't imply - there is none. - - -One and only one of ``MEDIA_PAD_FL_SINK`` and ``MEDIA_PAD_FL_SOURCE`` -must be set for every pad. - -.. tabularcolumns:: |p{5.5cm}|p{12.0cm}| - -.. _media-link-flag: -.. _MEDIA-LNK-FL-ENABLED: -.. _MEDIA-LNK-FL-IMMUTABLE: -.. _MEDIA-LNK-FL-DYNAMIC: -.. _MEDIA-LNK-FL-LINK-TYPE: - -.. flat-table:: Media link flags - :header-rows: 0 - :stub-columns: 0 - - * - ``MEDIA_LNK_FL_ENABLED`` - - The link is enabled and can be used to transfer media data. When - two or more links target a sink pad, only one of them can be - enabled at a time. - - * - ``MEDIA_LNK_FL_IMMUTABLE`` - - The link enabled state can't be modified at runtime. An immutable - link is always enabled. - - * - ``MEDIA_LNK_FL_DYNAMIC`` - - The link enabled state can be modified during streaming. This flag - is set by drivers and is read-only for applications. - - * - ``MEDIA_LNK_FL_LINK_TYPE`` - - This is a bitmask that defines the type of the link. Currently, - two types of links are supported: - - .. _MEDIA-LNK-FL-DATA-LINK: - - ``MEDIA_LNK_FL_DATA_LINK`` if the link is between two pads - - .. _MEDIA-LNK-FL-INTERFACE-LINK: - - ``MEDIA_LNK_FL_INTERFACE_LINK`` if the link is between an - interface and an entity diff --git a/Documentation/media/uapi/mediactl/request-api.rst b/Documentation/media/uapi/mediactl/request-api.rst deleted file mode 100644 index 01abe8103bdd..000000000000 --- a/Documentation/media/uapi/mediactl/request-api.rst +++ /dev/null @@ -1,276 +0,0 @@ -.. This file is dual-licensed: you can use it either under the terms -.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this -.. dual licensing only applies to this file, and not this project as a -.. whole. -.. -.. a) This file 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 file 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. -.. -.. Or, alternatively, -.. -.. b) Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections - -.. _media-request-api: - -Request API -=========== - -The Request API has been designed to allow V4L2 to deal with requirements of -modern devices (stateless codecs, complex camera pipelines, ...) and APIs -(Android Codec v2). One such requirement is the ability for devices belonging to -the same pipeline to reconfigure and collaborate closely on a per-frame basis. -Another is support of stateless codecs, which require controls to be applied -to specific frames (aka 'per-frame controls') in order to be used efficiently. - -While the initial use-case was V4L2, it can be extended to other subsystems -as well, as long as they use the media controller. - -Supporting these features without the Request API is not always possible and if -it is, it is terribly inefficient: user-space would have to flush all activity -on the media pipeline, reconfigure it for the next frame, queue the buffers to -be processed with that configuration, and wait until they are all available for -dequeuing before considering the next frame. This defeats the purpose of having -buffer queues since in practice only one buffer would be queued at a time. - -The Request API allows a specific configuration of the pipeline (media -controller topology + configuration for each media entity) to be associated with -specific buffers. This allows user-space to schedule several tasks ("requests") -with different configurations in advance, knowing that the configuration will be -applied when needed to get the expected result. Configuration values at the time -of request completion are also available for reading. - -General Usage -------------- - -The Request API extends the Media Controller API and cooperates with -subsystem-specific APIs to support request usage. At the Media Controller -level, requests are allocated from the supporting Media Controller device -node. Their life cycle is then managed through the request file descriptors in -an opaque way. Configuration data, buffer handles and processing results -stored in requests are accessed through subsystem-specific APIs extended for -request support, such as V4L2 APIs that take an explicit ``request_fd`` -parameter. - -Request Allocation ------------------- - -User-space allocates requests using :ref:`MEDIA_IOC_REQUEST_ALLOC` -for the media device node. This returns a file descriptor representing the -request. Typically, several such requests will be allocated. - -Request Preparation -------------------- - -Standard V4L2 ioctls can then receive a request file descriptor to express the -fact that the ioctl is part of said request, and is not to be applied -immediately. See :ref:`MEDIA_IOC_REQUEST_ALLOC` for a list of ioctls that -support this. Configurations set with a ``request_fd`` parameter are stored -instead of being immediately applied, and buffers queued to a request do not -enter the regular buffer queue until the request itself is queued. - -Request Submission ------------------- - -Once the configuration and buffers of the request are specified, it can be -queued by calling :ref:`MEDIA_REQUEST_IOC_QUEUE` on the request file descriptor. -A request must contain at least one buffer, otherwise ``ENOENT`` is returned. -A queued request cannot be modified anymore. - -.. caution:: - For :ref:`memory-to-memory devices ` you can use requests only for - output buffers, not for capture buffers. Attempting to add a capture buffer - to a request will result in an ``EBADR`` error. - -If the request contains configurations for multiple entities, individual drivers -may synchronize so the requested pipeline's topology is applied before the -buffers are processed. Media controller drivers do a best effort implementation -since perfect atomicity may not be possible due to hardware limitations. - -.. caution:: - - It is not allowed to mix queuing requests with directly queuing buffers: - whichever method is used first locks this in place until - :ref:`VIDIOC_STREAMOFF ` is called or the device is - :ref:`closed `. Attempts to directly queue a buffer when earlier - a buffer was queued via a request or vice versa will result in an ``EBUSY`` - error. - -Controls can still be set without a request and are applied immediately, -regardless of whether a request is in use or not. - -.. caution:: - - Setting the same control through a request and also directly can lead to - undefined behavior! - -User-space can :ref:`poll() ` a request file descriptor in -order to wait until the request completes. A request is considered complete -once all its associated buffers are available for dequeuing and all the -associated controls have been updated with the values at the time of completion. -Note that user-space does not need to wait for the request to complete to -dequeue its buffers: buffers that are available halfway through a request can -be dequeued independently of the request's state. - -A completed request contains the state of the device after the request was -executed. User-space can query that state by calling -:ref:`ioctl VIDIOC_G_EXT_CTRLS ` with the request file -descriptor. Calling :ref:`ioctl VIDIOC_G_EXT_CTRLS ` for a -request that has been queued but not yet completed will return ``EBUSY`` -since the control values might be changed at any time by the driver while the -request is in flight. - -.. _media-request-life-time: - -Recycling and Destruction -------------------------- - -Finally, a completed request can either be discarded or be reused. Calling -:ref:`close() ` on a request file descriptor will make -that file descriptor unusable and the request will be freed once it is no -longer in use by the kernel. That is, if the request is queued and then the -file descriptor is closed, then it won't be freed until the driver completed -the request. - -The :ref:`MEDIA_REQUEST_IOC_REINIT` will clear a request's state and make it -available again. No state is retained by this operation: the request is as -if it had just been allocated. - -Example for a Codec Device --------------------------- - -For use-cases such as :ref:`codecs `, the request API can be used -to associate specific controls to -be applied by the driver for the OUTPUT buffer, allowing user-space -to queue many such buffers in advance. It can also take advantage of requests' -ability to capture the state of controls when the request completes to read back -information that may be subject to change. - -Put into code, after obtaining a request, user-space can assign controls and one -OUTPUT buffer to it: - -.. code-block:: c - - struct v4l2_buffer buf; - struct v4l2_ext_controls ctrls; - int req_fd; - ... - if (ioctl(media_fd, MEDIA_IOC_REQUEST_ALLOC, &req_fd)) - return errno; - ... - ctrls.which = V4L2_CTRL_WHICH_REQUEST_VAL; - ctrls.request_fd = req_fd; - if (ioctl(codec_fd, VIDIOC_S_EXT_CTRLS, &ctrls)) - return errno; - ... - buf.type = V4L2_BUF_TYPE_VIDEO_OUTPUT; - buf.flags |= V4L2_BUF_FLAG_REQUEST_FD; - buf.request_fd = req_fd; - if (ioctl(codec_fd, VIDIOC_QBUF, &buf)) - return errno; - -Note that it is not allowed to use the Request API for CAPTURE buffers -since there are no per-frame settings to report there. - -Once the request is fully prepared, it can be queued to the driver: - -.. code-block:: c - - if (ioctl(req_fd, MEDIA_REQUEST_IOC_QUEUE)) - return errno; - -User-space can then either wait for the request to complete by calling poll() on -its file descriptor, or start dequeuing CAPTURE buffers. Most likely, it will -want to get CAPTURE buffers as soon as possible and this can be done using a -regular :ref:`VIDIOC_DQBUF `: - -.. code-block:: c - - struct v4l2_buffer buf; - - memset(&buf, 0, sizeof(buf)); - buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - if (ioctl(codec_fd, VIDIOC_DQBUF, &buf)) - return errno; - -Note that this example assumes for simplicity that for every OUTPUT buffer -there will be one CAPTURE buffer, but this does not have to be the case. - -We can then, after ensuring that the request is completed via polling the -request file descriptor, query control values at the time of its completion via -a call to :ref:`VIDIOC_G_EXT_CTRLS `. -This is particularly useful for volatile controls for which we want to -query values as soon as the capture buffer is produced. - -.. code-block:: c - - struct pollfd pfd = { .events = POLLPRI, .fd = req_fd }; - poll(&pfd, 1, -1); - ... - ctrls.which = V4L2_CTRL_WHICH_REQUEST_VAL; - ctrls.request_fd = req_fd; - if (ioctl(codec_fd, VIDIOC_G_EXT_CTRLS, &ctrls)) - return errno; - -Once we don't need the request anymore, we can either recycle it for reuse with -:ref:`MEDIA_REQUEST_IOC_REINIT`... - -.. code-block:: c - - if (ioctl(req_fd, MEDIA_REQUEST_IOC_REINIT)) - return errno; - -... or close its file descriptor to completely dispose of it. - -.. code-block:: c - - close(req_fd); - -Example for a Simple Capture Device ------------------------------------ - -With a simple capture device, requests can be used to specify controls to apply -for a given CAPTURE buffer. - -.. code-block:: c - - struct v4l2_buffer buf; - struct v4l2_ext_controls ctrls; - int req_fd; - ... - if (ioctl(media_fd, MEDIA_IOC_REQUEST_ALLOC, &req_fd)) - return errno; - ... - ctrls.which = V4L2_CTRL_WHICH_REQUEST_VAL; - ctrls.request_fd = req_fd; - if (ioctl(camera_fd, VIDIOC_S_EXT_CTRLS, &ctrls)) - return errno; - ... - buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - buf.flags |= V4L2_BUF_FLAG_REQUEST_FD; - buf.request_fd = req_fd; - if (ioctl(camera_fd, VIDIOC_QBUF, &buf)) - return errno; - -Once the request is fully prepared, it can be queued to the driver: - -.. code-block:: c - - if (ioctl(req_fd, MEDIA_REQUEST_IOC_QUEUE)) - return errno; - -User-space can then dequeue buffers, wait for the request completion, query -controls and recycle the request as in the M2M example above. diff --git a/Documentation/media/uapi/mediactl/request-func-close.rst b/Documentation/media/uapi/mediactl/request-func-close.rst deleted file mode 100644 index 2cff7770558e..000000000000 --- a/Documentation/media/uapi/mediactl/request-func-close.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. This file is dual-licensed: you can use it either under the terms -.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this -.. dual licensing only applies to this file, and not this project as a -.. whole. -.. -.. a) This file 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 file 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. -.. -.. Or, alternatively, -.. -.. b) Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections - -.. _request-func-close: - -*************** -request close() -*************** - -Name -==== - -request-close - Close a request file descriptor - - -Synopsis -======== - -.. code-block:: c - - #include - - -.. c:function:: int close( int fd ) - :name: req-close - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`. - - -Description -=========== - -Closes the request file descriptor. Resources associated with the request -are freed once all file descriptors associated with the request are closed -and the driver has completed the request. -See :ref:`here ` for more information. - - -Return Value -============ - -:ref:`close() ` returns 0 on success. On error, -1 is -returned, and ``errno`` is set appropriately. Possible error codes are: - -EBADF - ``fd`` is not a valid open file descriptor. diff --git a/Documentation/media/uapi/mediactl/request-func-ioctl.rst b/Documentation/media/uapi/mediactl/request-func-ioctl.rst deleted file mode 100644 index de0781c61873..000000000000 --- a/Documentation/media/uapi/mediactl/request-func-ioctl.rst +++ /dev/null @@ -1,91 +0,0 @@ -.. This file is dual-licensed: you can use it either under the terms -.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this -.. dual licensing only applies to this file, and not this project as a -.. whole. -.. -.. a) This file 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 file 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. -.. -.. Or, alternatively, -.. -.. b) Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections - -.. _request-func-ioctl: - -*************** -request ioctl() -*************** - -Name -==== - -request-ioctl - Control a request file descriptor - - -Synopsis -======== - -.. code-block:: c - - #include - - -.. c:function:: int ioctl( int fd, int cmd, void *argp ) - :name: req-ioctl - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`. - -``cmd`` - The request ioctl command code as defined in the media.h header file, for - example :ref:`MEDIA_REQUEST_IOC_QUEUE`. - -``argp`` - Pointer to a request-specific structure. - - -Description -=========== - -The :ref:`ioctl() ` function manipulates request -parameters. The argument ``fd`` must be an open file descriptor. - -The ioctl ``cmd`` code specifies the request function to be called. It -has encoded in it whether the argument is an input, output or read/write -parameter, and the size of the argument ``argp`` in bytes. - -Macros and structures definitions specifying request ioctl commands and -their parameters are located in the media.h header file. All request ioctl -commands, their respective function and parameters are specified in -:ref:`media-user-func`. - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. - -Command-specific error codes are listed in the individual command -descriptions. - -When an ioctl that takes an output or read/write parameter fails, the -parameter remains unmodified. diff --git a/Documentation/media/uapi/mediactl/request-func-poll.rst b/Documentation/media/uapi/mediactl/request-func-poll.rst deleted file mode 100644 index ebaf33e21873..000000000000 --- a/Documentation/media/uapi/mediactl/request-func-poll.rst +++ /dev/null @@ -1,101 +0,0 @@ -.. This file is dual-licensed: you can use it either under the terms -.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this -.. dual licensing only applies to this file, and not this project as a -.. whole. -.. -.. a) This file 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 file 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. -.. -.. Or, alternatively, -.. -.. b) Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections - -.. _request-func-poll: - -************** -request poll() -************** - -Name -==== - -request-poll - Wait for some event on a file descriptor - - -Synopsis -======== - -.. code-block:: c - - #include - - -.. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout ) - :name: request-poll - -Arguments -========= - -``ufds`` - List of file descriptor events to be watched - -``nfds`` - Number of file descriptor events at the \*ufds array - -``timeout`` - Timeout to wait for events - - -Description -=========== - -With the :c:func:`poll() ` function applications can wait -for a request to complete. - -On success :c:func:`poll() ` returns the number of file -descriptors that have been selected (that is, file descriptors for which the -``revents`` field of the respective struct :c:type:`pollfd` -is non-zero). Request file descriptor set the ``POLLPRI`` flag in ``revents`` -when the request was completed. When the function times out it returns -a value of zero, on failure it returns -1 and the ``errno`` variable is -set appropriately. - -Attempting to poll for a request that is not yet queued will -set the ``POLLERR`` flag in ``revents``. - - -Return Value -============ - -On success, :c:func:`poll() ` returns the number of -structures which have non-zero ``revents`` fields, or zero if the call -timed out. On error -1 is returned, and the ``errno`` variable is set -appropriately: - -``EBADF`` - One or more of the ``ufds`` members specify an invalid file - descriptor. - -``EFAULT`` - ``ufds`` references an inaccessible memory area. - -``EINTR`` - The call was interrupted by a signal. - -``EINVAL`` - The ``nfds`` value exceeds the ``RLIMIT_NOFILE`` value. Use - ``getrlimit()`` to obtain this value. diff --git a/Documentation/media/uapi/rc/keytable.c.rst b/Documentation/media/uapi/rc/keytable.c.rst deleted file mode 100644 index 46f98569e999..000000000000 --- a/Documentation/media/uapi/rc/keytable.c.rst +++ /dev/null @@ -1,183 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -file: uapi/v4l/keytable.c -========================= - -.. code-block:: c - - /* keytable.c - This program allows checking/replacing keys at IR - - Copyright (C) 2006-2009 Mauro Carvalho Chehab - - This program 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. - */ - - #include - #include - #include - #include - #include - #include - #include - #include - - #include "parse.h" - - void prtcode (int *codes) - { - struct parse_key *p; - - for (p=keynames;p->name!=NULL;p++) { - if (p->value == (unsigned)codes[1]) { - printf("scancode 0x%04x = %s (0x%02x)\\n", codes[0], p->name, codes[1]); - return; - } - } - - if (isprint (codes[1])) - printf("scancode %d = '%c' (0x%02x)\\n", codes[0], codes[1], codes[1]); - else - printf("scancode %d = 0x%02x\\n", codes[0], codes[1]); - } - - int parse_code(char *string) - { - struct parse_key *p; - - for (p=keynames;p->name!=NULL;p++) { - if (!strcasecmp(p->name, string)) { - return p->value; - } - } - return -1; - } - - int main (int argc, char *argv[]) - { - int fd; - unsigned int i, j; - int codes[2]; - - if (argc<2 || argc>4) { - printf ("usage: %s to get table; or\\n" - " %s \\n" - " %s n",*argv,*argv,*argv); - return -1; - } - - if ((fd = open(argv[1], O_RDONLY)) < 0) { - perror("Couldn't open input device"); - return(-1); - } - - if (argc==4) { - int value; - - value=parse_code(argv[3]); - - if (value==-1) { - value = strtol(argv[3], NULL, 0); - if (errno) - perror("value"); - } - - codes [0] = (unsigned) strtol(argv[2], NULL, 0); - codes [1] = (unsigned) value; - - if(ioctl(fd, EVIOCSKEYCODE, codes)) - perror ("EVIOCSKEYCODE"); - - if(ioctl(fd, EVIOCGKEYCODE, codes)==0) - prtcode(codes); - return 0; - } - - if (argc==3) { - FILE *fin; - int value; - char *scancode, *keycode, s[2048]; - - fin=fopen(argv[2],"r"); - if (fin==NULL) { - perror ("opening keycode file"); - return -1; - } - - /* Clears old table */ - for (j = 0; j < 256; j++) { - for (i = 0; i < 256; i++) { - codes[0] = (j << 8) | i; - codes[1] = KEY_RESERVED; - ioctl(fd, EVIOCSKEYCODE, codes); - } - } - - while (fgets(s,sizeof(s),fin)) { - scancode=strtok(s,"\\n\\t =:"); - if (!scancode) { - perror ("parsing input file scancode"); - return -1; - } - if (!strcasecmp(scancode, "scancode")) { - scancode = strtok(NULL,"\\n\\t =:"); - if (!scancode) { - perror ("parsing input file scancode"); - return -1; - } - } - - keycode=strtok(NULL,"\\n\\t =:("); - if (!keycode) { - perror ("parsing input file keycode"); - return -1; - } - - // printf ("parsing %s=%s:", scancode, keycode); - value=parse_code(keycode); - // printf ("\\tvalue=%d\\n",value); - - if (value==-1) { - value = strtol(keycode, NULL, 0); - if (errno) - perror("value"); - } - - codes [0] = (unsigned) strtol(scancode, NULL, 0); - codes [1] = (unsigned) value; - - // printf("\\t%04x=%04x\\n",codes[0], codes[1]); - if(ioctl(fd, EVIOCSKEYCODE, codes)) { - fprintf(stderr, "Setting scancode 0x%04x with 0x%04x via ",codes[0], codes[1]); - perror ("EVIOCSKEYCODE"); - } - - if(ioctl(fd, EVIOCGKEYCODE, codes)==0) - prtcode(codes); - } - return 0; - } - - /* Get scancode table */ - for (j = 0; j < 256; j++) { - for (i = 0; i < 256; i++) { - codes[0] = (j << 8) | i; - if (!ioctl(fd, EVIOCGKEYCODE, codes) && codes[1] != KEY_RESERVED) - prtcode(codes); - } - } - return 0; - } diff --git a/Documentation/media/uapi/rc/lirc-dev-intro.rst b/Documentation/media/uapi/rc/lirc-dev-intro.rst deleted file mode 100644 index b68c01693939..000000000000 --- a/Documentation/media/uapi/rc/lirc-dev-intro.rst +++ /dev/null @@ -1,171 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_dev_intro: - -************ -Introduction -************ - -LIRC stands for Linux Infrared Remote Control. The LIRC device interface is -a bi-directional interface for transporting raw IR and decoded scancodes -data between userspace and kernelspace. Fundamentally, it is just a chardev -(/dev/lircX, for X = 0, 1, 2, ...), with a number of standard struct -file_operations defined on it. With respect to transporting raw IR and -decoded scancodes to and fro, the essential fops are read, write and ioctl. - -It is also possible to attach a BPF program to a LIRC device for decoding -raw IR into scancodes. - -Example dmesg output upon a driver registering w/LIRC: - -.. code-block:: none - - $ dmesg |grep lirc_dev - rc rc0: lirc_dev: driver mceusb registered at minor = 0, raw IR receiver, raw IR transmitter - -What you should see for a chardev: - -.. code-block:: none - - $ ls -l /dev/lirc* - crw-rw---- 1 root root 248, 0 Jul 2 22:20 /dev/lirc0 - -Note that the package `v4l-utils `_ -contains tools for working with LIRC devices: - - - ir-ctl: can receive raw IR and transmit IR, as well as query LIRC - device features. - - - ir-keytable: can load keymaps; allows you to set IR kernel protocols; load - BPF IR decoders and test IR decoding. Some BPF IR decoders are also - provided. - -.. _lirc_modes: - -********** -LIRC modes -********** - -LIRC supports some modes of receiving and sending IR codes, as shown -on the following table. - -.. _lirc-mode-scancode: -.. _lirc-scancode-flag-toggle: -.. _lirc-scancode-flag-repeat: - -``LIRC_MODE_SCANCODE`` - - This mode is for both sending and receiving IR. - - For transmitting (aka sending), create a ``struct lirc_scancode`` with - the desired scancode set in the ``scancode`` member, :c:type:`rc_proto` - set to the :ref:`IR protocol `, and all other - members set to 0. Write this struct to the lirc device. - - For receiving, you read ``struct lirc_scancode`` from the LIRC device. - The ``scancode`` field is set to the received scancode and the - :ref:`IR protocol ` is set in - :c:type:`rc_proto`. If the scancode maps to a valid key code, this is set - in the ``keycode`` field, else it is set to ``KEY_RESERVED``. - - The ``flags`` can have ``LIRC_SCANCODE_FLAG_TOGGLE`` set if the toggle - bit is set in protocols that support it (e.g. rc-5 and rc-6), or - ``LIRC_SCANCODE_FLAG_REPEAT`` for when a repeat is received for protocols - that support it (e.g. nec). - - In the Sanyo and NEC protocol, if you hold a button on remote, rather than - repeating the entire scancode, the remote sends a shorter message with - no scancode, which just means button is held, a "repeat". When this is - received, the ``LIRC_SCANCODE_FLAG_REPEAT`` is set and the scancode and - keycode is repeated. - - With nec, there is no way to distinguish "button hold" from "repeatedly - pressing the same button". The rc-5 and rc-6 protocols have a toggle bit. - When a button is released and pressed again, the toggle bit is inverted. - If the toggle bit is set, the ``LIRC_SCANCODE_FLAG_TOGGLE`` is set. - - The ``timestamp`` field is filled with the time nanoseconds - (in ``CLOCK_MONOTONIC``) when the scancode was decoded. - -.. _lirc-mode-mode2: - -``LIRC_MODE_MODE2`` - - The driver returns a sequence of pulse and space codes to userspace, - as a series of u32 values. - - This mode is used only for IR receive. - - The upper 8 bits determine the packet type, and the lower 24 bits - the payload. Use ``LIRC_VALUE()`` macro to get the payload, and - the macro ``LIRC_MODE2()`` will give you the type, which - is one of: - - ``LIRC_MODE2_PULSE`` - - Signifies the presence of IR in microseconds. - - ``LIRC_MODE2_SPACE`` - - Signifies absence of IR in microseconds. - - ``LIRC_MODE2_FREQUENCY`` - - If measurement of the carrier frequency was enabled with - :ref:`lirc_set_measure_carrier_mode` then this packet gives you - the carrier frequency in Hertz. - - ``LIRC_MODE2_TIMEOUT`` - - If timeout reports are enabled with - :ref:`lirc_set_rec_timeout_reports`, when the timeout set with - :ref:`lirc_set_rec_timeout` expires due to no IR being detected, - this packet will be sent, with the number of microseconds with - no IR. - -.. _lirc-mode-pulse: - -``LIRC_MODE_PULSE`` - - In pulse mode, a sequence of pulse/space integer values are written to the - lirc device using :ref:`lirc-write`. - - The values are alternating pulse and space lengths, in microseconds. The - first and last entry must be a pulse, so there must be an odd number - of entries. - - This mode is used only for IR send. - -******************** -BPF based IR decoder -******************** - -The kernel has support for decoding the most common -:ref:`IR protocols `, but there -are many protocols which are not supported. To support these, it is possible -to load an BPF program which does the decoding. This can only be done on -LIRC devices which support reading raw IR. - -First, using the `bpf(2)`_ syscall with the ``BPF_LOAD_PROG`` argument, -program must be loaded of type ``BPF_PROG_TYPE_LIRC_MODE2``. Once attached -to the LIRC device, this program will be called for each pulse, space or -timeout event on the LIRC device. The context for the BPF program is a -pointer to a unsigned int, which is a :ref:`LIRC_MODE_MODE2 ` -value. When the program has decoded the scancode, it can be submitted using -the BPF functions ``bpf_rc_keydown()`` or ``bpf_rc_repeat()``. Mouse or pointer -movements can be reported using ``bpf_rc_pointer_rel()``. - -Once you have the file descriptor for the ``BPF_PROG_TYPE_LIRC_MODE2`` BPF -program, it can be attached to the LIRC device using the `bpf(2)`_ syscall. -The target must be the file descriptor for the LIRC device, and the -attach type must be ``BPF_LIRC_MODE2``. No more than 64 BPF programs can be -attached to a single LIRC device at a time. - -.. _bpf(2): http://man7.org/linux/man-pages/man2/bpf.2.html diff --git a/Documentation/media/uapi/rc/lirc-dev.rst b/Documentation/media/uapi/rc/lirc-dev.rst deleted file mode 100644 index 7058e0b2296a..000000000000 --- a/Documentation/media/uapi/rc/lirc-dev.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_dev: - -LIRC Device Interface -===================== - - -.. toctree:: - :maxdepth: 1 - - lirc-dev-intro - lirc-func - lirc-header diff --git a/Documentation/media/uapi/rc/lirc-func.rst b/Documentation/media/uapi/rc/lirc-func.rst deleted file mode 100644 index 25058369f724..000000000000 --- a/Documentation/media/uapi/rc/lirc-func.rst +++ /dev/null @@ -1,34 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_func: - -LIRC Function Reference -======================= - - -.. toctree:: - :maxdepth: 1 - - lirc-read - lirc-write - lirc-get-features - lirc-get-send-mode - lirc-get-rec-mode - lirc-get-rec-resolution - lirc-set-send-duty-cycle - lirc-get-timeout - lirc-set-rec-timeout - lirc-set-rec-carrier - lirc-set-rec-carrier-range - lirc-set-send-carrier - lirc-set-transmitter-mask - lirc-set-rec-timeout-reports - lirc-set-measure-carrier-mode - lirc-set-wideband-receiver diff --git a/Documentation/media/uapi/rc/lirc-get-features.rst b/Documentation/media/uapi/rc/lirc-get-features.rst deleted file mode 100644 index 1d590df8164a..000000000000 --- a/Documentation/media/uapi/rc/lirc-get-features.rst +++ /dev/null @@ -1,200 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_get_features: - -*********************** -ioctl LIRC_GET_FEATURES -*********************** - -Name -==== - -LIRC_GET_FEATURES - Get the underlying hardware device's features - -Synopsis -======== - -.. c:function:: int ioctl( int fd, LIRC_GET_FEATURES, __u32 *features) - :name: LIRC_GET_FEATURES - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``features`` - Bitmask with the LIRC features. - - -Description -=========== - - -Get the underlying hardware device's features. If a driver does not -announce support of certain features, calling of the corresponding ioctls -is undefined. - -LIRC features -============= - -.. _LIRC-CAN-REC-RAW: - -``LIRC_CAN_REC_RAW`` - - Unused. Kept just to avoid breaking uAPI. - -.. _LIRC-CAN-REC-PULSE: - -``LIRC_CAN_REC_PULSE`` - - Unused. Kept just to avoid breaking uAPI. - :ref:`LIRC_MODE_PULSE ` can only be used for transmitting. - -.. _LIRC-CAN-REC-MODE2: - -``LIRC_CAN_REC_MODE2`` - - This is raw IR driver for receiving. This means that - :ref:`LIRC_MODE_MODE2 ` is used. This also implies - that :ref:`LIRC_MODE_SCANCODE ` is also supported, - as long as the kernel is recent enough. Use the - :ref:`lirc_set_rec_mode` to switch modes. - -.. _LIRC-CAN-REC-LIRCCODE: - -``LIRC_CAN_REC_LIRCCODE`` - - Unused. Kept just to avoid breaking uAPI. - -.. _LIRC-CAN-REC-SCANCODE: - -``LIRC_CAN_REC_SCANCODE`` - - This is a scancode driver for receiving. This means that - :ref:`LIRC_MODE_SCANCODE ` is used. - -.. _LIRC-CAN-SET-SEND-CARRIER: - -``LIRC_CAN_SET_SEND_CARRIER`` - - The driver supports changing the modulation frequency via - :ref:`ioctl LIRC_SET_SEND_CARRIER `. - -.. _LIRC-CAN-SET-SEND-DUTY-CYCLE: - -``LIRC_CAN_SET_SEND_DUTY_CYCLE`` - - The driver supports changing the duty cycle using - :ref:`ioctl LIRC_SET_SEND_DUTY_CYCLE `. - -.. _LIRC-CAN-SET-TRANSMITTER-MASK: - -``LIRC_CAN_SET_TRANSMITTER_MASK`` - - The driver supports changing the active transmitter(s) using - :ref:`ioctl LIRC_SET_TRANSMITTER_MASK `. - -.. _LIRC-CAN-SET-REC-CARRIER: - -``LIRC_CAN_SET_REC_CARRIER`` - - The driver supports setting the receive carrier frequency using - :ref:`ioctl LIRC_SET_REC_CARRIER `. - -.. _LIRC-CAN-SET-REC-DUTY-CYCLE-RANGE: - -``LIRC_CAN_SET_REC_DUTY_CYCLE_RANGE`` - - Unused. Kept just to avoid breaking uAPI. - -.. _LIRC-CAN-SET-REC-CARRIER-RANGE: - -``LIRC_CAN_SET_REC_CARRIER_RANGE`` - - The driver supports - :ref:`ioctl LIRC_SET_REC_CARRIER_RANGE `. - -.. _LIRC-CAN-GET-REC-RESOLUTION: - -``LIRC_CAN_GET_REC_RESOLUTION`` - - The driver supports - :ref:`ioctl LIRC_GET_REC_RESOLUTION `. - -.. _LIRC-CAN-SET-REC-TIMEOUT: - -``LIRC_CAN_SET_REC_TIMEOUT`` - - The driver supports - :ref:`ioctl LIRC_SET_REC_TIMEOUT `. - -.. _LIRC-CAN-SET-REC-FILTER: - -``LIRC_CAN_SET_REC_FILTER`` - - Unused. Kept just to avoid breaking uAPI. - -.. _LIRC-CAN-MEASURE-CARRIER: - -``LIRC_CAN_MEASURE_CARRIER`` - - The driver supports measuring of the modulation frequency using - :ref:`ioctl LIRC_SET_MEASURE_CARRIER_MODE `. - -.. _LIRC-CAN-USE-WIDEBAND-RECEIVER: - -``LIRC_CAN_USE_WIDEBAND_RECEIVER`` - - The driver supports learning mode using - :ref:`ioctl LIRC_SET_WIDEBAND_RECEIVER `. - -.. _LIRC-CAN-NOTIFY-DECODE: - -``LIRC_CAN_NOTIFY_DECODE`` - - Unused. Kept just to avoid breaking uAPI. - -.. _LIRC-CAN-SEND-RAW: - -``LIRC_CAN_SEND_RAW`` - - Unused. Kept just to avoid breaking uAPI. - -.. _LIRC-CAN-SEND-PULSE: - -``LIRC_CAN_SEND_PULSE`` - - The driver supports sending (also called as IR blasting or IR TX) using - :ref:`LIRC_MODE_PULSE `. This implies that - :ref:`LIRC_MODE_SCANCODE ` is also supported for - transmit, as long as the kernel is recent enough. Use the - :ref:`lirc_set_send_mode` to switch modes. - -.. _LIRC-CAN-SEND-MODE2: - -``LIRC_CAN_SEND_MODE2`` - - Unused. Kept just to avoid breaking uAPI. - :ref:`LIRC_MODE_MODE2 ` can only be used for receiving. - -.. _LIRC-CAN-SEND-LIRCCODE: - -``LIRC_CAN_SEND_LIRCCODE`` - - Unused. Kept just to avoid breaking uAPI. - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/rc/lirc-get-rec-mode.rst b/Documentation/media/uapi/rc/lirc-get-rec-mode.rst deleted file mode 100644 index 0a3e02aca80e..000000000000 --- a/Documentation/media/uapi/rc/lirc-get-rec-mode.rst +++ /dev/null @@ -1,74 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_get_rec_mode: -.. _lirc_set_rec_mode: - -********************************************** -ioctls LIRC_GET_REC_MODE and LIRC_SET_REC_MODE -********************************************** - -Name -==== - -LIRC_GET_REC_MODE/LIRC_SET_REC_MODE - Get/set current receive mode. - -Synopsis -======== - -.. c:function:: int ioctl( int fd, LIRC_GET_REC_MODE, __u32 *mode) - :name: LIRC_GET_REC_MODE - -.. c:function:: int ioctl( int fd, LIRC_SET_REC_MODE, __u32 *mode) - :name: LIRC_SET_REC_MODE - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``mode`` - Mode used for receive. - -Description -=========== - -Get and set the current receive mode. Only -:ref:`LIRC_MODE_MODE2 ` and -:ref:`LIRC_MODE_SCANCODE ` are supported. -Use :ref:`lirc_get_features` to find out which modes the driver supports. - -Return Value -============ - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``ENODEV`` - - - Device not available. - - - .. row 2 - - - ``ENOTTY`` - - - Device does not support receiving. - - - .. row 3 - - - ``EINVAL`` - - - Invalid mode or invalid mode for this device. diff --git a/Documentation/media/uapi/rc/lirc-get-rec-resolution.rst b/Documentation/media/uapi/rc/lirc-get-rec-resolution.rst deleted file mode 100644 index f560b694ccf2..000000000000 --- a/Documentation/media/uapi/rc/lirc-get-rec-resolution.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_get_rec_resolution: - -***************************** -ioctl LIRC_GET_REC_RESOLUTION -***************************** - -Name -==== - -LIRC_GET_REC_RESOLUTION - Obtain the value of receive resolution, in microseconds. - -Synopsis -======== - -.. c:function:: int ioctl( int fd, LIRC_GET_REC_RESOLUTION, __u32 *microseconds) - :name: LIRC_GET_REC_RESOLUTION - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``microseconds`` - Resolution, in microseconds. - - -Description -=========== - -Some receivers have maximum resolution which is defined by internal -sample rate or data format limitations. E.g. it's common that -signals can only be reported in 50 microsecond steps. - -This ioctl returns the integer value with such resolution, with can be -used by userspace applications like lircd to automatically adjust the -tolerance value. - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/rc/lirc-get-send-mode.rst b/Documentation/media/uapi/rc/lirc-get-send-mode.rst deleted file mode 100644 index 4f440c697052..000000000000 --- a/Documentation/media/uapi/rc/lirc-get-send-mode.rst +++ /dev/null @@ -1,78 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_get_send_mode: -.. _lirc_set_send_mode: - -************************************************ -ioctls LIRC_GET_SEND_MODE and LIRC_SET_SEND_MODE -************************************************ - -Name -==== - -LIRC_GET_SEND_MODE/LIRC_SET_SEND_MODE - Get/set current transmit mode. - -Synopsis -======== - -.. c:function:: int ioctl( int fd, LIRC_GET_SEND_MODE, __u32 *mode ) - :name: LIRC_GET_SEND_MODE - -.. c:function:: int ioctl( int fd, LIRC_SET_SEND_MODE, __u32 *mode ) - :name: LIRC_SET_SEND_MODE - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``mode`` - The mode used for transmitting. - - -Description -=========== - -Get/set current transmit mode. - -Only :ref:`LIRC_MODE_PULSE ` and -:ref:`LIRC_MODE_SCANCODE ` are supported by for IR send, -depending on the driver. Use :ref:`lirc_get_features` to find out which -modes the driver supports. - -Return Value -============ - - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``ENODEV`` - - - Device not available. - - - .. row 2 - - - ``ENOTTY`` - - - Device does not support transmitting. - - - .. row 3 - - - ``EINVAL`` - - - Invalid mode or invalid mode for this device. diff --git a/Documentation/media/uapi/rc/lirc-get-timeout.rst b/Documentation/media/uapi/rc/lirc-get-timeout.rst deleted file mode 100644 index 1de214529f27..000000000000 --- a/Documentation/media/uapi/rc/lirc-get-timeout.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_get_min_timeout: -.. _lirc_get_max_timeout: - -**************************************************** -ioctls LIRC_GET_MIN_TIMEOUT and LIRC_GET_MAX_TIMEOUT -**************************************************** - -Name -==== - -LIRC_GET_MIN_TIMEOUT / LIRC_GET_MAX_TIMEOUT - Obtain the possible timeout -range for IR receive. - -Synopsis -======== - -.. c:function:: int ioctl( int fd, LIRC_GET_MIN_TIMEOUT, __u32 *timeout) - :name: LIRC_GET_MIN_TIMEOUT - -.. c:function:: int ioctl( int fd, LIRC_GET_MAX_TIMEOUT, __u32 *timeout) - :name: LIRC_GET_MAX_TIMEOUT - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``timeout`` - Timeout, in microseconds. - - -Description -=========== - -Some devices have internal timers that can be used to detect when -there's no IR activity for a long time. This can help lircd in -detecting that a IR signal is finished and can speed up the decoding -process. Returns an integer value with the minimum/maximum timeout -that can be set. - -.. note:: - - Some devices have a fixed timeout, in that case - both ioctls will return the same value even though the timeout - cannot be changed via :ref:`LIRC_SET_REC_TIMEOUT`. - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/rc/lirc-header.rst b/Documentation/media/uapi/rc/lirc-header.rst deleted file mode 100644 index c9b4f33e1031..000000000000 --- a/Documentation/media/uapi/rc/lirc-header.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_header: - -**************** -LIRC Header File -**************** - -.. kernel-include:: $BUILDDIR/lirc.h.rst - diff --git a/Documentation/media/uapi/rc/lirc-read.rst b/Documentation/media/uapi/rc/lirc-read.rst deleted file mode 100644 index 256e520bc27e..000000000000 --- a/Documentation/media/uapi/rc/lirc-read.rst +++ /dev/null @@ -1,76 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc-read: - -*********** -LIRC read() -*********** - -Name -==== - -lirc-read - Read from a LIRC device - - -Synopsis -======== - -.. code-block:: c - - #include - - -.. c:function:: ssize_t read( int fd, void *buf, size_t count ) - :name: lirc-read - - -Arguments -========= - -``fd`` - File descriptor returned by ``open()``. - -``buf`` - Buffer to be filled - -``count`` - Max number of bytes to read - -Description -=========== - -:ref:`read() ` attempts to read up to ``count`` bytes from file -descriptor ``fd`` into the buffer starting at ``buf``. If ``count`` is zero, -:ref:`read() ` returns zero and has no other results. If ``count`` -is greater than ``SSIZE_MAX``, the result is unspecified. - -The exact format of the data depends on what :ref:`lirc_modes` a driver -uses. Use :ref:`lirc_get_features` to get the supported mode, and use -:ref:`lirc_set_rec_mode` set the current active mode. - -The mode :ref:`LIRC_MODE_MODE2 ` is for raw IR, -in which packets containing an unsigned int value describing an IR signal are -read from the chardev. - -Alternatively, :ref:`LIRC_MODE_SCANCODE ` can be available, -in this mode scancodes which are either decoded by software decoders, or -by hardware decoders. The :c:type:`rc_proto` member is set to the -:ref:`IR protocol ` -used for transmission, and ``scancode`` to the decoded scancode, -and the ``keycode`` set to the keycode or ``KEY_RESERVED``. - - -Return Value -============ - -On success, the number of bytes read is returned. It is not an error if -this number is smaller than the number of bytes requested, or the amount -of data required for one frame. On error, -1 is returned, and the ``errno`` -variable is set appropriately. diff --git a/Documentation/media/uapi/rc/lirc-set-measure-carrier-mode.rst b/Documentation/media/uapi/rc/lirc-set-measure-carrier-mode.rst deleted file mode 100644 index c80acd85e369..000000000000 --- a/Documentation/media/uapi/rc/lirc-set-measure-carrier-mode.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_set_measure_carrier_mode: - -*********************************** -ioctl LIRC_SET_MEASURE_CARRIER_MODE -*********************************** - -Name -==== - -LIRC_SET_MEASURE_CARRIER_MODE - enable or disable measure mode - -Synopsis -======== - -.. c:function:: int ioctl( int fd, LIRC_SET_MEASURE_CARRIER_MODE, __u32 *enable ) - :name: LIRC_SET_MEASURE_CARRIER_MODE - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``enable`` - enable = 1 means enable measure mode, enable = 0 means disable measure - mode. - - -Description -=========== - -.. _lirc-mode2-frequency: - -Enable or disable measure mode. If enabled, from the next key -press on, the driver will send ``LIRC_MODE2_FREQUENCY`` packets. By -default this should be turned off. - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/rc/lirc-set-rec-carrier-range.rst b/Documentation/media/uapi/rc/lirc-set-rec-carrier-range.rst deleted file mode 100644 index 443681d5cc10..000000000000 --- a/Documentation/media/uapi/rc/lirc-set-rec-carrier-range.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_set_rec_carrier_range: - -******************************** -ioctl LIRC_SET_REC_CARRIER_RANGE -******************************** - -Name -==== - -LIRC_SET_REC_CARRIER_RANGE - Set lower bound of the carrier used to modulate -IR receive. - -Synopsis -======== - -.. c:function:: int ioctl( int fd, LIRC_SET_REC_CARRIER_RANGE, __u32 *frequency ) - :name: LIRC_SET_REC_CARRIER_RANGE - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``frequency`` - Frequency of the carrier that modulates PWM data, in Hz. - -Description -=========== - -This ioctl sets the upper range of carrier frequency that will be recognized -by the IR receiver. - -.. note:: - - To set a range use :ref:`LIRC_SET_REC_CARRIER_RANGE - ` with the lower bound first and later call - :ref:`LIRC_SET_REC_CARRIER ` with the upper bound. - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/rc/lirc-set-rec-carrier.rst b/Documentation/media/uapi/rc/lirc-set-rec-carrier.rst deleted file mode 100644 index cbe1e48b2a4a..000000000000 --- a/Documentation/media/uapi/rc/lirc-set-rec-carrier.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_set_rec_carrier: - -************************** -ioctl LIRC_SET_REC_CARRIER -************************** - -Name -==== - -LIRC_SET_REC_CARRIER - Set carrier used to modulate IR receive. - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, LIRC_SET_REC_CARRIER, __u32 *frequency ) - :name: LIRC_SET_REC_CARRIER - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``frequency`` - Frequency of the carrier that modulates PWM data, in Hz. - -Description -=========== - -Set receive carrier used to modulate IR PWM pulses and spaces. - -.. note:: - - If called together with :ref:`LIRC_SET_REC_CARRIER_RANGE`, this ioctl - sets the upper bound frequency that will be recognized by the device. - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/rc/lirc-set-rec-timeout-reports.rst b/Documentation/media/uapi/rc/lirc-set-rec-timeout-reports.rst deleted file mode 100644 index d06d69414c1e..000000000000 --- a/Documentation/media/uapi/rc/lirc-set-rec-timeout-reports.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_set_rec_timeout_reports: - -********************************** -ioctl LIRC_SET_REC_TIMEOUT_REPORTS -********************************** - -Name -==== - -LIRC_SET_REC_TIMEOUT_REPORTS - enable or disable timeout reports for IR receive - -Synopsis -======== - -.. c:function:: int ioctl( int fd, LIRC_SET_REC_TIMEOUT_REPORTS, __u32 *enable ) - :name: LIRC_SET_REC_TIMEOUT_REPORTS - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``enable`` - enable = 1 means enable timeout report, enable = 0 means disable timeout - reports. - - -Description -=========== - -.. _lirc-mode2-timeout: - -Enable or disable timeout reports for IR receive. By default, timeout reports -should be turned off. - -.. note:: - - This ioctl is only valid for :ref:`LIRC_MODE_MODE2 `. - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/rc/lirc-set-rec-timeout.rst b/Documentation/media/uapi/rc/lirc-set-rec-timeout.rst deleted file mode 100644 index 163ac6065737..000000000000 --- a/Documentation/media/uapi/rc/lirc-set-rec-timeout.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_set_rec_timeout: -.. _lirc_get_rec_timeout: - -*************************************************** -ioctl LIRC_GET_REC_TIMEOUT and LIRC_SET_REC_TIMEOUT -*************************************************** - -Name -==== - -LIRC_GET_REC_TIMEOUT/LIRC_SET_REC_TIMEOUT - Get/set the integer value for IR inactivity timeout. - -Synopsis -======== - -.. c:function:: int ioctl( int fd, LIRC_GET_REC_TIMEOUT, __u32 *timeout ) - :name: LIRC_GET_REC_TIMEOUT - -.. c:function:: int ioctl( int fd, LIRC_SET_REC_TIMEOUT, __u32 *timeout ) - :name: LIRC_SET_REC_TIMEOUT - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``timeout`` - Timeout, in microseconds. - - -Description -=========== - -Get and set the integer value for IR inactivity timeout. - -If supported by the hardware, setting it to 0 disables all hardware timeouts -and data should be reported as soon as possible. If the exact value -cannot be set, then the next possible value _greater_ than the -given value should be set. - -.. note:: - - The range of supported timeout is given by :ref:`LIRC_GET_MIN_TIMEOUT`. - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/rc/lirc-set-send-carrier.rst b/Documentation/media/uapi/rc/lirc-set-send-carrier.rst deleted file mode 100644 index cffc6c1e15cc..000000000000 --- a/Documentation/media/uapi/rc/lirc-set-send-carrier.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_set_send_carrier: - -*************************** -ioctl LIRC_SET_SEND_CARRIER -*************************** - -Name -==== - -LIRC_SET_SEND_CARRIER - Set send carrier used to modulate IR TX. - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, LIRC_SET_SEND_CARRIER, __u32 *frequency ) - :name: LIRC_SET_SEND_CARRIER - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``frequency`` - Frequency of the carrier to be modulated, in Hz. - -Description -=========== - -Set send carrier used to modulate IR PWM pulses and spaces. - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/rc/lirc-set-send-duty-cycle.rst b/Documentation/media/uapi/rc/lirc-set-send-duty-cycle.rst deleted file mode 100644 index 08ab3d1a96cd..000000000000 --- a/Documentation/media/uapi/rc/lirc-set-send-duty-cycle.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_set_send_duty_cycle: - -****************************** -ioctl LIRC_SET_SEND_DUTY_CYCLE -****************************** - -Name -==== - -LIRC_SET_SEND_DUTY_CYCLE - Set the duty cycle of the carrier signal for -IR transmit. - -Synopsis -======== - -.. c:function:: int ioctl( int fd, LIRC_SET_SEND_DUTY_CYCLE, __u32 *duty_cycle) - :name: LIRC_SET_SEND_DUTY_CYCLE - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``duty_cycle`` - Duty cicle, describing the pulse width in percent (from 1 to 99) of - the total cycle. Values 0 and 100 are reserved. - - -Description -=========== - -Get/set the duty cycle of the carrier signal for IR transmit. - -Currently, no special meaning is defined for 0 or 100, but this -could be used to switch off carrier generation in the future, so -these values should be reserved. - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/rc/lirc-set-transmitter-mask.rst b/Documentation/media/uapi/rc/lirc-set-transmitter-mask.rst deleted file mode 100644 index 889a739eaf0d..000000000000 --- a/Documentation/media/uapi/rc/lirc-set-transmitter-mask.rst +++ /dev/null @@ -1,58 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_set_transmitter_mask: - -******************************* -ioctl LIRC_SET_TRANSMITTER_MASK -******************************* - -Name -==== - -LIRC_SET_TRANSMITTER_MASK - Enables send codes on a given set of transmitters - -Synopsis -======== - -.. c:function:: int ioctl( int fd, LIRC_SET_TRANSMITTER_MASK, __u32 *mask ) - :name: LIRC_SET_TRANSMITTER_MASK - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``mask`` - Mask with channels to enable tx. Channel 0 is the least significant bit. - - -Description -=========== - -Some IR TX devices have multiple output channels, in such case, -:ref:`LIRC_CAN_SET_TRANSMITTER_MASK ` is -returned via :ref:`LIRC_GET_FEATURES` and this ioctl sets what channels will -send IR codes. - -This ioctl enables the given set of transmitters. The first transmitter is -encoded by the least significant bit and so on. - -When an invalid bit mask is given, i.e. a bit is set, even though the device -does not have so many transitters, then this ioctl returns the number of -available transitters and does nothing otherwise. - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/rc/lirc-set-wideband-receiver.rst b/Documentation/media/uapi/rc/lirc-set-wideband-receiver.rst deleted file mode 100644 index 592715452fce..000000000000 --- a/Documentation/media/uapi/rc/lirc-set-wideband-receiver.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_set_wideband_receiver: - -******************************** -ioctl LIRC_SET_WIDEBAND_RECEIVER -******************************** - -Name -==== - -LIRC_SET_WIDEBAND_RECEIVER - enable wide band receiver. - -Synopsis -======== - -.. c:function:: int ioctl( int fd, LIRC_SET_WIDEBAND_RECEIVER, __u32 *enable ) - :name: LIRC_SET_WIDEBAND_RECEIVER - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``enable`` - enable = 1 means enable wideband receiver, enable = 0 means disable - wideband receiver. - - -Description -=========== - -Some receivers are equipped with special wide band receiver which is -intended to be used to learn output of existing remote. This ioctl -allows enabling or disabling it. - -This might be useful of receivers that have otherwise narrow band receiver -that prevents them to be used with some remotes. Wide band receiver might -also be more precise. On the other hand its disadvantage it usually -reduced range of reception. - -.. note:: - - Wide band receiver might be implictly enabled if you enable - carrier reports. In that case it will be disabled as soon as you disable - carrier reports. Trying to disable wide band receiver while carrier - reports are active will do nothing. - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/rc/lirc-write.rst b/Documentation/media/uapi/rc/lirc-write.rst deleted file mode 100644 index eafe13203ea3..000000000000 --- a/Documentation/media/uapi/rc/lirc-write.rst +++ /dev/null @@ -1,82 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc-write: - -************ -LIRC write() -************ - -Name -==== - -lirc-write - Write to a LIRC device - - -Synopsis -======== - -.. code-block:: c - - #include - - -.. c:function:: ssize_t write( int fd, void *buf, size_t count ) - :name: lirc-write - -Arguments -========= - -``fd`` - File descriptor returned by ``open()``. - -``buf`` - Buffer with data to be written - -``count`` - Number of bytes at the buffer - -Description -=========== - -:ref:`write() ` writes up to ``count`` bytes to the device -referenced by the file descriptor ``fd`` from the buffer starting at -``buf``. - -The exact format of the data depends on what mode a driver is in, use -:ref:`lirc_get_features` to get the supported modes and use -:ref:`lirc_set_send_mode` set the mode. - -When in :ref:`LIRC_MODE_PULSE ` mode, the data written to -the chardev is a pulse/space sequence of integer values. Pulses and spaces -are only marked implicitly by their position. The data must start and end -with a pulse, therefore, the data must always include an uneven number of -samples. The write function blocks until the data has been transmitted -by the hardware. If more data is provided than the hardware can send, the -driver returns ``EINVAL``. - -When in :ref:`LIRC_MODE_SCANCODE ` mode, one -``struct lirc_scancode`` must be written to the chardev at a time, else -``EINVAL`` is returned. Set the desired scancode in the ``scancode`` member, -and the :ref:`IR protocol ` in the -:c:type:`rc_proto`: member. All other members must be -set to 0, else ``EINVAL`` is returned. If there is no protocol encoder -for the protocol or the scancode is not valid for the specified protocol, -``EINVAL`` is returned. The write function blocks until the scancode -is transmitted by the hardware. - - -Return Value -============ - -On success, the number of bytes written is returned. It is not an error if -this number is smaller than the number of bytes requested, or the amount -of data required for one frame. On error, -1 is returned, and the ``errno`` -variable is set appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/rc/rc-intro.rst b/Documentation/media/uapi/rc/rc-intro.rst deleted file mode 100644 index 37c5f90c76e7..000000000000 --- a/Documentation/media/uapi/rc/rc-intro.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _Remote_controllers_Intro: - -************ -Introduction -************ - -Currently, most analog and digital devices have a Infrared input for -remote controllers. Each manufacturer has their own type of control. It -is not rare for the same manufacturer to ship different types of -controls, depending on the device. - -A Remote Controller interface is mapped as a normal evdev/input -interface, just like a keyboard or a mouse. So, it uses all ioctls -already defined for any other input devices. - -However, remove controllers are more flexible than a normal input -device, as the IR receiver (and/or transmitter) can be used in -conjunction with a wide variety of different IR remotes. - -In order to allow flexibility, the Remote Controller subsystem allows -controlling the RC-specific attributes via -:ref:`the sysfs class nodes `. diff --git a/Documentation/media/uapi/rc/rc-protos.rst b/Documentation/media/uapi/rc/rc-protos.rst deleted file mode 100644 index b250ebe301d5..000000000000 --- a/Documentation/media/uapi/rc/rc-protos.rst +++ /dev/null @@ -1,456 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _Remote_controllers_Protocols: - -***************************************** -Remote Controller Protocols and Scancodes -***************************************** - -IR is encoded as a series of pulses and spaces, using a protocol. These -protocols can encode e.g. an address (which device should respond) and a -command: what it should do. The values for these are not always consistent -across different devices for a given protocol. - -Therefore out the output of the IR decoder is a scancode; a single u32 -value. Using keymap tables this can be mapped to linux key codes. - -Other things can be encoded too. Some IR protocols encode a toggle bit; this -is to distinguish whether the same button is being held down, or has been -released and pressed again. If has been released and pressed again, the -toggle bit will invert from one IR message to the next. - -Some remotes have a pointer-type device which can used to control the -mouse; some air conditioning systems can have their target temperature -target set in IR. - -The following are the protocols the kernel knows about and also lists -how scancodes are encoded for each protocol. - -rc-5 (RC_PROTO_RC5) -------------------- - -This IR protocol uses manchester encoding to encode 14 bits. There is a -detailed description here https://www.sbprojects.net/knowledge/ir/rc5.php. - -The scancode encoding is *not* consistent with the lirc daemon (lircd) rc5 -protocol, or the manchester BPF decoder. - -.. flat-table:: rc5 bits scancode mapping - :widths: 1 1 2 - - * - rc-5 bit - - - scancode bit - - - description - - * - 1 - - - none - - - Start bit, always set - - * - 1 - - - 6 (inverted) - - - 2nd start bit in rc5, re-used as 6th command bit - - * - 1 - - - none - - - Toggle bit - - * - 5 - - - 8 to 13 - - - Address - - * - 6 - - - 0 to 5 - - - Command - -There is a variant of rc5 called either rc5x or extended rc5 -where there the second stop bit is the 6th commmand bit, but inverted. -This is done so it the scancodes and encoding is compatible with existing -schemes. This bit is stored in bit 6 of the scancode, inverted. This is -done to keep it compatible with plain rc-5 where there are two start bits. - -rc-5-sz (RC_PROTO_RC5_SZ) -------------------------- -This is much like rc-5 but one bit longer. The scancode is encoded -differently. - -.. flat-table:: rc-5-sz bits scancode mapping - :widths: 1 1 2 - - * - rc-5-sz bits - - - scancode bit - - - description - - * - 1 - - - none - - - Start bit, always set - - * - 1 - - - 13 - - - Address bit - - * - 1 - - - none - - - Toggle bit - - * - 6 - - - 6 to 11 - - - Address - - * - 6 - - - 0 to 5 - - - Command - -rc-5x-20 (RC_PROTO_RC5X_20) ---------------------------- - -This rc-5 extended to encoded 20 bits. The is a 3555 microseconds space -after the 8th bit. - -.. flat-table:: rc-5x-20 bits scancode mapping - :widths: 1 1 2 - - * - rc-5-sz bits - - - scancode bit - - - description - - * - 1 - - - none - - - Start bit, always set - - * - 1 - - - 14 - - - Address bit - - * - 1 - - - none - - - Toggle bit - - * - 5 - - - 16 to 20 - - - Address - - * - 6 - - - 8 to 13 - - - Address - - * - 6 - - - 0 to 5 - - - Command - - -jvc (RC_PROTO_JVC) ------------------- - -The jvc protocol is much like nec, without the inverted values. It is -described here https://www.sbprojects.net/knowledge/ir/jvc.php. - -The scancode is a 16 bits value, where the address is the lower 8 bits -and the command the higher 8 bits; this is reversed from IR order. - -sony-12 (RC_PROTO_SONY12) -------------------------- - -The sony protocol is a pulse-width encoding. There are three variants, -which just differ in number of bits and scancode encoding. - -.. flat-table:: sony-12 bits scancode mapping - :widths: 1 1 2 - - * - sony-12 bits - - - scancode bit - - - description - - * - 5 - - - 16 to 20 - - - device - - * - 7 - - - 0 to 6 - - - function - -sony-15 (RC_PROTO_SONY15) -------------------------- - -The sony protocol is a pulse-width encoding. There are three variants, -which just differ in number of bits and scancode encoding. - -.. flat-table:: sony-12 bits scancode mapping - :widths: 1 1 2 - - * - sony-12 bits - - - scancode bit - - - description - - * - 8 - - - 16 to 23 - - - device - - * - 7 - - - 0 to 6 - - - function - -sony-20 (RC_PROTO_SONY20) -------------------------- - -The sony protocol is a pulse-width encoding. There are three variants, -which just differ in number of bits and scancode encoding. - -.. flat-table:: sony-20 bits scancode mapping - :widths: 1 1 2 - - * - sony-20 bits - - - scancode bit - - - description - - * - 5 - - - 16 to 20 - - - device - - * - 7 - - - 0 to 7 - - - device - - * - 8 - - - 8 to 15 - - - extended bits - -nec (RC_PROTO_NEC) ------------------- - -The nec protocol encodes an 8 bit address and an 8 bit command. It is -described here https://www.sbprojects.net/knowledge/ir/nec.php. Note -that the protocol sends least significant bit first. - -As a check, the nec protocol sends the address and command twice; the -second time it is inverted. This is done for verification. - -A plain nec IR message has 16 bits; the high 8 bits are the address -and the low 8 bits are the command. - -nec-x (RC_PROTO_NECX) ---------------------- - -Extended nec has a 16 bit address and a 8 bit command. This is encoded -as a 24 bit value as you would expect, with the lower 8 bits the command -and the upper 16 bits the address. - -nec-32 (RC_PROTO_NEC32) ------------------------ - -nec-32 does not send an inverted address or an inverted command; the -entire message, all 32 bits, are used. - -For this to be decoded correctly, the second 8 bits must not be the -inverted value of the first, and also the last 8 bits must not be the -inverted value of the third 8 bit value. - -The scancode has a somewhat unusual encoding. - -.. flat-table:: nec-32 bits scancode mapping - - * - nec-32 bits - - - scancode bit - - * - First 8 bits - - - 16 to 23 - - * - Second 8 bits - - - 24 to 31 - - * - Third 8 bits - - - 0 to 7 - - * - Fourth 8 bits - - - 8 to 15 - -sanyo (RC_PROTO_SANYO) ----------------------- - -The sanyo protocol is like the nec protocol, but with 13 bits address -rather than 8 bits. Both the address and the command are followed by -their inverted versions, but these are not present in the scancodes. - -Bis 8 to 20 of the scancode is the 13 bits address, and the lower 8 -bits are the command. - -mcir2-kbd (RC_PROTO_MCIR2_KBD) ------------------------------- - -This protocol is generated by the Microsoft MCE keyboard for keyboard -events. Refer to the ir-mce_kbd-decoder.c to see how it is encoded. - -mcir2-mse (RC_PROTO_MCIR2_MSE) ------------------------------- - -This protocol is generated by the Microsoft MCE keyboard for pointer -events. Refer to the ir-mce_kbd-decoder.c to see how it is encoded. - -rc-6-0 (RC_PROTO_RC6_0) ------------------------ - -This is the rc-6 in mode 0. rc-6 is described here -https://www.sbprojects.net/knowledge/ir/rc6.php. -The scancode is the exact 16 bits as in the protocol. There is also a -toggle bit. - -rc-6-6a-20 (RC_PROTO_RC6_6A_20) -------------------------------- - -This is the rc-6 in mode 6a, 20 bits. rc-6 is described here -https://www.sbprojects.net/knowledge/ir/rc6.php. -The scancode is the exact 20 bits -as in the protocol. There is also a toggle bit. - -rc-6-6a-24 (RC_PROTO_RC6_6A_24) -------------------------------- - -This is the rc-6 in mode 6a, 24 bits. rc-6 is described here -https://www.sbprojects.net/knowledge/ir/rc6.php. -The scancode is the exact 24 bits -as in the protocol. There is also a toggle bit. - -rc-6-6a-32 (RC_PROTO_RC6_6A_32) -------------------------------- - -This is the rc-6 in mode 6a, 32 bits. rc-6 is described here -https://www.sbprojects.net/knowledge/ir/rc6.php. -The upper 16 bits are the vendor, -and the lower 16 bits are the vendor-specific bits. This protocol is -for the non-Microsoft MCE variant (vendor != 0x800f). - - -rc-6-mce (RC_PROTO_RC6_MCE) ---------------------------- - -This is the rc-6 in mode 6a, 32 bits. The upper 16 bits are the vendor, -and the lower 16 bits are the vendor-specific bits. This protocol is -for the Microsoft MCE variant (vendor = 0x800f). The toggle bit in the -protocol itself is ignored, and the 16th bit should be takes as the toggle -bit. - -sharp (RC_PROTO_SHARP) ----------------------- - -This is a protocol used by Sharp VCRs, is described here -https://www.sbprojects.net/knowledge/ir/sharp.php. There is a very long -(40ms) space between the normal and inverted values, and some IR receivers -cannot decode this. - -There is a 5 bit address and a 8 bit command. In the scancode the address is -in bits 8 to 12, and the command in bits 0 to 7. - -xmp (RC_PROTO_XMP) ------------------- - -This protocol has several versions and only version 1 is supported. Refer -to the decoder (ir-xmp-decoder.c) to see how it is encoded. - - -cec (RC_PROTO_CEC) ------------------- - -This is not an IR protocol, this is a protocol over CEC. The CEC -infrastructure uses rc-core for handling CEC commands, so that they -can easily be remapped. - -imon (RC_PROTO_IMON) --------------------- - -This protocol is used by Antec Veris/SoundGraph iMON remotes. - -The protocol -describes both button presses and pointer movements. The protocol encodes -31 bits, and the scancode is simply the 31 bits with the top bit always 0. - -rc-mm-12 (RC_PROTO_RCMM12) --------------------------- - -The rc-mm protocol is described here -https://www.sbprojects.net/knowledge/ir/rcmm.php. The scancode is simply -the 12 bits. - -rc-mm-24 (RC_PROTO_RCMM24) --------------------------- - -The rc-mm protocol is described here -https://www.sbprojects.net/knowledge/ir/rcmm.php. The scancode is simply -the 24 bits. - -rc-mm-32 (RC_PROTO_RCMM32) --------------------------- - -The rc-mm protocol is described here -https://www.sbprojects.net/knowledge/ir/rcmm.php. The scancode is simply -the 32 bits. - -xbox-dvd (RC_PROTO_XBOX_DVD) ----------------------------- - -This protocol is used by XBox DVD Remote, which was made for the original -XBox. There is no in-kernel decoder or encoder for this protocol. The usb -device decodes the protocol. There is a BPF decoder available in v4l-utils. diff --git a/Documentation/media/uapi/rc/rc-sysfs-nodes.rst b/Documentation/media/uapi/rc/rc-sysfs-nodes.rst deleted file mode 100644 index b8e8319e3317..000000000000 --- a/Documentation/media/uapi/rc/rc-sysfs-nodes.rst +++ /dev/null @@ -1,151 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _remote_controllers_sysfs_nodes: - -******************************* -Remote Controller's sysfs nodes -******************************* - -As defined at ``Documentation/ABI/testing/sysfs-class-rc``, those are -the sysfs nodes that control the Remote Controllers: - - -.. _sys_class_rc: - -/sys/class/rc/ -============== - -The ``/sys/class/rc/`` class sub-directory belongs to the Remote -Controller core and provides a sysfs interface for configuring infrared -remote controller receivers. - - -.. _sys_class_rc_rcN: - -/sys/class/rc/rcN/ -================== - -A ``/sys/class/rc/rcN`` directory is created for each remote control -receiver device where N is the number of the receiver. - - -.. _sys_class_rc_rcN_protocols: - -/sys/class/rc/rcN/protocols -=========================== - -Reading this file returns a list of available protocols, something like:: - - rc5 [rc6] nec jvc [sony] - -Enabled protocols are shown in [] brackets. - -Writing "+proto" will add a protocol to the list of enabled protocols. - -Writing "-proto" will remove a protocol from the list of enabled -protocols. - -Writing "proto" will enable only "proto". - -Writing "none" will disable all protocols. - -Write fails with ``EINVAL`` if an invalid protocol combination or unknown -protocol name is used. - - -.. _sys_class_rc_rcN_filter: - -/sys/class/rc/rcN/filter -======================== - -Sets the scancode filter expected value. - -Use in combination with ``/sys/class/rc/rcN/filter_mask`` to set the -expected value of the bits set in the filter mask. If the hardware -supports it then scancodes which do not match the filter will be -ignored. Otherwise the write will fail with an error. - -This value may be reset to 0 if the current protocol is altered. - - -.. _sys_class_rc_rcN_filter_mask: - -/sys/class/rc/rcN/filter_mask -============================= - -Sets the scancode filter mask of bits to compare. Use in combination -with ``/sys/class/rc/rcN/filter`` to set the bits of the scancode which -should be compared against the expected value. A value of 0 disables the -filter to allow all valid scancodes to be processed. - -If the hardware supports it then scancodes which do not match the filter -will be ignored. Otherwise the write will fail with an error. - -This value may be reset to 0 if the current protocol is altered. - - -.. _sys_class_rc_rcN_wakeup_protocols: - -/sys/class/rc/rcN/wakeup_protocols -================================== - -Reading this file returns a list of available protocols to use for the -wakeup filter, something like:: - - rc-5 nec nec-x rc-6-0 rc-6-6a-24 [rc-6-6a-32] rc-6-mce - -Note that protocol variants are listed, so ``nec``, ``sony``, ``rc-5``, ``rc-6`` -have their different bit length encodings listed if available. - -Note that all protocol variants are listed. - -The enabled wakeup protocol is shown in [] brackets. - -Only one protocol can be selected at a time. - -Writing "proto" will use "proto" for wakeup events. - -Writing "none" will disable wakeup. - -Write fails with ``EINVAL`` if an invalid protocol combination or unknown -protocol name is used, or if wakeup is not supported by the hardware. - - -.. _sys_class_rc_rcN_wakeup_filter: - -/sys/class/rc/rcN/wakeup_filter -=============================== - -Sets the scancode wakeup filter expected value. Use in combination with -``/sys/class/rc/rcN/wakeup_filter_mask`` to set the expected value of -the bits set in the wakeup filter mask to trigger a system wake event. - -If the hardware supports it and wakeup_filter_mask is not 0 then -scancodes which match the filter will wake the system from e.g. suspend -to RAM or power off. Otherwise the write will fail with an error. - -This value may be reset to 0 if the wakeup protocol is altered. - - -.. _sys_class_rc_rcN_wakeup_filter_mask: - -/sys/class/rc/rcN/wakeup_filter_mask -==================================== - -Sets the scancode wakeup filter mask of bits to compare. Use in -combination with ``/sys/class/rc/rcN/wakeup_filter`` to set the bits of -the scancode which should be compared against the expected value to -trigger a system wake event. - -If the hardware supports it and wakeup_filter_mask is not 0 then -scancodes which match the filter will wake the system from e.g. suspend -to RAM or power off. Otherwise the write will fail with an error. - -This value may be reset to 0 if the wakeup protocol is altered. diff --git a/Documentation/media/uapi/rc/rc-table-change.rst b/Documentation/media/uapi/rc/rc-table-change.rst deleted file mode 100644 index 4a2e601b89fb..000000000000 --- a/Documentation/media/uapi/rc/rc-table-change.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _Remote_controllers_table_change: - -******************************************* -Changing default Remote Controller mappings -******************************************* - -The event interface provides two ioctls to be used against the -/dev/input/event device, to allow changing the default keymapping. - -This program demonstrates how to replace the keymap tables. - - -.. toctree:: - :maxdepth: 1 - - keytable.c diff --git a/Documentation/media/uapi/rc/rc-tables.rst b/Documentation/media/uapi/rc/rc-tables.rst deleted file mode 100644 index 20d7c686922b..000000000000 --- a/Documentation/media/uapi/rc/rc-tables.rst +++ /dev/null @@ -1,766 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _Remote_controllers_tables: - -************************ -Remote controller tables -************************ - -Unfortunately, for several years, there was no effort to create uniform -IR keycodes for different devices. This caused the same IR keyname to be -mapped completely differently on different IR devices. This resulted -that the same IR keyname to be mapped completely different on different -IR's. Due to that, V4L2 API now specifies a standard for mapping Media -keys on IR. - -This standard should be used by both V4L/DVB drivers and userspace -applications - -The modules register the remote as keyboard within the linux input -layer. This means that the IR key strokes will look like normal keyboard -key strokes (if CONFIG_INPUT_KEYBOARD is enabled). Using the event -devices (CONFIG_INPUT_EVDEV) it is possible for applications to access -the remote via /dev/input/event devices. - - -.. _rc_standard_keymap: - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. flat-table:: IR default keymapping - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - - - .. row 1 - - - Key code - - - Meaning - - - Key examples on IR - - - .. row 2 - - - **Numeric keys** - - - .. row 3 - - - ``KEY_NUMERIC_0`` - - - Keyboard digit 0 - - - 0 - - - .. row 4 - - - ``KEY_NUMERIC_1`` - - - Keyboard digit 1 - - - 1 - - - .. row 5 - - - ``KEY_NUMERIC_2`` - - - Keyboard digit 2 - - - 2 - - - .. row 6 - - - ``KEY_NUMERIC_3`` - - - Keyboard digit 3 - - - 3 - - - .. row 7 - - - ``KEY_NUMERIC_4`` - - - Keyboard digit 4 - - - 4 - - - .. row 8 - - - ``KEY_NUMERIC_5`` - - - Keyboard digit 5 - - - 5 - - - .. row 9 - - - ``KEY_NUMERIC_6`` - - - Keyboard digit 6 - - - 6 - - - .. row 10 - - - ``KEY_NUMERIC_7`` - - - Keyboard digit 7 - - - 7 - - - .. row 11 - - - ``KEY_NUMERIC_8`` - - - Keyboard digit 8 - - - 8 - - - .. row 12 - - - ``KEY_NUMERIC_9`` - - - Keyboard digit 9 - - - 9 - - - .. row 13 - - - **Movie play control** - - - .. row 14 - - - ``KEY_FORWARD`` - - - Instantly advance in time - - - >> / FORWARD - - - .. row 15 - - - ``KEY_BACK`` - - - Instantly go back in time - - - <<< / BACK - - - .. row 16 - - - ``KEY_FASTFORWARD`` - - - Play movie faster - - - >>> / FORWARD - - - .. row 17 - - - ``KEY_REWIND`` - - - Play movie back - - - REWIND / BACKWARD - - - .. row 18 - - - ``KEY_NEXT`` - - - Select next chapter / sub-chapter / interval - - - NEXT / SKIP - - - .. row 19 - - - ``KEY_PREVIOUS`` - - - Select previous chapter / sub-chapter / interval - - - << / PREV / PREVIOUS - - - .. row 20 - - - ``KEY_AGAIN`` - - - Repeat the video or a video interval - - - REPEAT / LOOP / RECALL - - - .. row 21 - - - ``KEY_PAUSE`` - - - Pause stream - - - PAUSE / FREEZE - - - .. row 22 - - - ``KEY_PLAY`` - - - Play movie at the normal timeshift - - - NORMAL TIMESHIFT / LIVE / > - - - .. row 23 - - - ``KEY_PLAYPAUSE`` - - - Alternate between play and pause - - - PLAY / PAUSE - - - .. row 24 - - - ``KEY_STOP`` - - - Stop stream - - - STOP - - - .. row 25 - - - ``KEY_RECORD`` - - - Start/stop recording stream - - - CAPTURE / REC / RECORD/PAUSE - - - .. row 26 - - - ``KEY_CAMERA`` - - - Take a picture of the image - - - CAMERA ICON / CAPTURE / SNAPSHOT - - - .. row 27 - - - ``KEY_SHUFFLE`` - - - Enable shuffle mode - - - SHUFFLE - - - .. row 28 - - - ``KEY_TIME`` - - - Activate time shift mode - - - TIME SHIFT - - - .. row 29 - - - ``KEY_TITLE`` - - - Allow changing the chapter - - - CHAPTER - - - .. row 30 - - - ``KEY_SUBTITLE`` - - - Allow changing the subtitle - - - SUBTITLE - - - .. row 31 - - - **Image control** - - - .. row 32 - - - ``KEY_BRIGHTNESSDOWN`` - - - Decrease Brightness - - - BRIGHTNESS DECREASE - - - .. row 33 - - - ``KEY_BRIGHTNESSUP`` - - - Increase Brightness - - - BRIGHTNESS INCREASE - - - .. row 34 - - - ``KEY_ANGLE`` - - - Switch video camera angle (on videos with more than one angle - stored) - - - ANGLE / SWAP - - - .. row 35 - - - ``KEY_EPG`` - - - Open the Elecrowonic Play Guide (EPG) - - - EPG / GUIDE - - - .. row 36 - - - ``KEY_TEXT`` - - - Activate/change closed caption mode - - - CLOSED CAPTION/TELETEXT / DVD TEXT / TELETEXT / TTX - - - .. row 37 - - - **Audio control** - - - .. row 38 - - - ``KEY_AUDIO`` - - - Change audio source - - - AUDIO SOURCE / AUDIO / MUSIC - - - .. row 39 - - - ``KEY_MUTE`` - - - Mute/unmute audio - - - MUTE / DEMUTE / UNMUTE - - - .. row 40 - - - ``KEY_VOLUMEDOWN`` - - - Decrease volume - - - VOLUME- / VOLUME DOWN - - - .. row 41 - - - ``KEY_VOLUMEUP`` - - - Increase volume - - - VOLUME+ / VOLUME UP - - - .. row 42 - - - ``KEY_MODE`` - - - Change sound mode - - - MONO/STEREO - - - .. row 43 - - - ``KEY_LANGUAGE`` - - - Select Language - - - 1ST / 2ND LANGUAGE / DVD LANG / MTS/SAP / MTS SEL - - - .. row 44 - - - **Channel control** - - - .. row 45 - - - ``KEY_CHANNEL`` - - - Go to the next favorite channel - - - ALT / CHANNEL / CH SURFING / SURF / FAV - - - .. row 46 - - - ``KEY_CHANNELDOWN`` - - - Decrease channel sequentially - - - CHANNEL - / CHANNEL DOWN / DOWN - - - .. row 47 - - - ``KEY_CHANNELUP`` - - - Increase channel sequentially - - - CHANNEL + / CHANNEL UP / UP - - - .. row 48 - - - ``KEY_DIGITS`` - - - Use more than one digit for channel - - - PLUS / 100/ 1xx / xxx / -/-- / Single Double Triple Digit - - - .. row 49 - - - ``KEY_SEARCH`` - - - Start channel autoscan - - - SCAN / AUTOSCAN - - - .. row 50 - - - **Colored keys** - - - .. row 51 - - - ``KEY_BLUE`` - - - IR Blue key - - - BLUE - - - .. row 52 - - - ``KEY_GREEN`` - - - IR Green Key - - - GREEN - - - .. row 53 - - - ``KEY_RED`` - - - IR Red key - - - RED - - - .. row 54 - - - ``KEY_YELLOW`` - - - IR Yellow key - - - YELLOW - - - .. row 55 - - - **Media selection** - - - .. row 56 - - - ``KEY_CD`` - - - Change input source to Compact Disc - - - CD - - - .. row 57 - - - ``KEY_DVD`` - - - Change input to DVD - - - DVD / DVD MENU - - - .. row 58 - - - ``KEY_EJECTCLOSECD`` - - - Open/close the CD/DVD player - - - -> ) / CLOSE / OPEN - - - .. row 59 - - - ``KEY_MEDIA`` - - - Turn on/off Media application - - - PC/TV / TURN ON/OFF APP - - - .. row 60 - - - ``KEY_PC`` - - - Selects from TV to PC - - - PC - - - .. row 61 - - - ``KEY_RADIO`` - - - Put into AM/FM radio mode - - - RADIO / TV/FM / TV/RADIO / FM / FM/RADIO - - - .. row 62 - - - ``KEY_TV`` - - - Select tv mode - - - TV / LIVE TV - - - .. row 63 - - - ``KEY_TV2`` - - - Select Cable mode - - - AIR/CBL - - - .. row 64 - - - ``KEY_VCR`` - - - Select VCR mode - - - VCR MODE / DTR - - - .. row 65 - - - ``KEY_VIDEO`` - - - Alternate between input modes - - - SOURCE / SELECT / DISPLAY / SWITCH INPUTS / VIDEO - - - .. row 66 - - - **Power control** - - - .. row 67 - - - ``KEY_POWER`` - - - Turn on/off computer - - - SYSTEM POWER / COMPUTER POWER - - - .. row 68 - - - ``KEY_POWER2`` - - - Turn on/off application - - - TV ON/OFF / POWER - - - .. row 69 - - - ``KEY_SLEEP`` - - - Activate sleep timer - - - SLEEP / SLEEP TIMER - - - .. row 70 - - - ``KEY_SUSPEND`` - - - Put computer into suspend mode - - - STANDBY / SUSPEND - - - .. row 71 - - - **Window control** - - - .. row 72 - - - ``KEY_CLEAR`` - - - Stop stream and return to default input video/audio - - - CLEAR / RESET / BOSS KEY - - - .. row 73 - - - ``KEY_CYCLEWINDOWS`` - - - Minimize windows and move to the next one - - - ALT-TAB / MINIMIZE / DESKTOP - - - .. row 74 - - - ``KEY_FAVORITES`` - - - Open the favorites stream window - - - TV WALL / Favorites - - - .. row 75 - - - ``KEY_MENU`` - - - Call application menu - - - 2ND CONTROLS (USA: MENU) / DVD/MENU / SHOW/HIDE CTRL - - - .. row 76 - - - ``KEY_NEW`` - - - Open/Close Picture in Picture - - - PIP - - - .. row 77 - - - ``KEY_OK`` - - - Send a confirmation code to application - - - OK / ENTER / RETURN - - - .. row 78 - - - ``KEY_ASPECT_RATIO`` - - - Select screen aspect ratio - - - 4:3 16:9 SELECT - - - .. row 79 - - - ``KEY_FULL_SCREEN`` - - - Put device into zoom/full screen mode - - - ZOOM / FULL SCREEN / ZOOM+ / HIDE PANNEL / SWITCH - - - .. row 80 - - - **Navigation keys** - - - .. row 81 - - - ``KEY_ESC`` - - - Cancel current operation - - - CANCEL / BACK - - - .. row 82 - - - ``KEY_HELP`` - - - Open a Help window - - - HELP - - - .. row 83 - - - ``KEY_HOMEPAGE`` - - - Navigate to Homepage - - - HOME - - - .. row 84 - - - ``KEY_INFO`` - - - Open On Screen Display - - - DISPLAY INFORMATION / OSD - - - .. row 85 - - - ``KEY_WWW`` - - - Open the default browser - - - WEB - - - .. row 86 - - - ``KEY_UP`` - - - Up key - - - UP - - - .. row 87 - - - ``KEY_DOWN`` - - - Down key - - - DOWN - - - .. row 88 - - - ``KEY_LEFT`` - - - Left key - - - LEFT - - - .. row 89 - - - ``KEY_RIGHT`` - - - Right key - - - RIGHT - - - .. row 90 - - - **Miscellaneous keys** - - - .. row 91 - - - ``KEY_DOT`` - - - Return a dot - - - . - - - .. row 92 - - - ``KEY_FN`` - - - Select a function - - - FUNCTION - - -It should be noted that, sometimes, there some fundamental missing keys -at some cheaper IR's. Due to that, it is recommended to: - - -.. _rc_keymap_notes: - -.. flat-table:: Notes - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - On simpler IR's, without separate channel keys, you need to map UP - as ``KEY_CHANNELUP`` - - - .. row 2 - - - On simpler IR's, without separate channel keys, you need to map - DOWN as ``KEY_CHANNELDOWN`` - - - .. row 3 - - - On simpler IR's, without separate volume keys, you need to map - LEFT as ``KEY_VOLUMEDOWN`` - - - .. row 4 - - - On simpler IR's, without separate volume keys, you need to map - RIGHT as ``KEY_VOLUMEUP`` diff --git a/Documentation/media/uapi/rc/remote_controllers.rst b/Documentation/media/uapi/rc/remote_controllers.rst deleted file mode 100644 index 20e0f986df49..000000000000 --- a/Documentation/media/uapi/rc/remote_controllers.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. include:: - -.. _remote_controllers: - -################################ -Part III - Remote Controller API -################################ - -.. only:: html - - .. class:: toc-title - - Table of Contents - -.. toctree:: - :maxdepth: 5 - :numbered: - - rc-intro - rc-sysfs-nodes - rc-protos - rc-tables - rc-table-change - lirc-dev - - -********************** -Revision and Copyright -********************** - -Authors: - -- Carvalho Chehab, Mauro - - - Initial version. - -**Copyright** |copy| 2009-2016 : Mauro Carvalho Chehab - -**************** -Revision History -**************** - -:revision: 3.15 / 2014-02-06 (*mcc*) - -Added the interface description and the RC sysfs class description. - - -:revision: 1.0 / 2009-09-06 (*mcc*) - -Initial revision diff --git a/Documentation/media/uapi/v4l/app-pri.rst b/Documentation/media/uapi/v4l/app-pri.rst deleted file mode 100644 index c25c1271b4f6..000000000000 --- a/Documentation/media/uapi/v4l/app-pri.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _app-pri: - -******************** -Application Priority -******************** - -When multiple applications share a device it may be desirable to assign -them different priorities. Contrary to the traditional "rm -rf /" school -of thought, a video recording application could for example block other -applications from changing video controls or switching the current TV -channel. Another objective is to permit low priority applications -working in background, which can be preempted by user controlled -applications and automatically regain control of the device at a later -time. - -Since these features cannot be implemented entirely in user space V4L2 -defines the :ref:`VIDIOC_G_PRIORITY ` and -:ref:`VIDIOC_S_PRIORITY ` ioctls to request and -query the access priority associate with a file descriptor. Opening a -device assigns a medium priority, compatible with earlier versions of -V4L2 and drivers not supporting these ioctls. Applications requiring a -different priority will usually call :ref:`VIDIOC_S_PRIORITY -` after verifying the device with the -:ref:`VIDIOC_QUERYCAP` ioctl. - -Ioctls changing driver properties, such as -:ref:`VIDIOC_S_INPUT `, return an ``EBUSY`` error code -after another application obtained higher priority. diff --git a/Documentation/media/uapi/v4l/async.rst b/Documentation/media/uapi/v4l/async.rst deleted file mode 100644 index be9539313f60..000000000000 --- a/Documentation/media/uapi/v4l/async.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _async: - -**************** -Asynchronous I/O -**************** - -This method is not defined yet. diff --git a/Documentation/media/uapi/v4l/audio.rst b/Documentation/media/uapi/v4l/audio.rst deleted file mode 100644 index 4c7fdbc8a860..000000000000 --- a/Documentation/media/uapi/v4l/audio.rst +++ /dev/null @@ -1,104 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _audio: - -************************ -Audio Inputs and Outputs -************************ - -Audio inputs and outputs are physical connectors of a device. Video -capture devices have inputs, output devices have outputs, zero or more -each. Radio devices have no audio inputs or outputs. They have exactly -one tuner which in fact *is* an audio source, but this API associates -tuners with video inputs or outputs only, and radio devices have none of -these. [#f1]_ A connector on a TV card to loop back the received audio -signal to a sound card is not considered an audio output. - -Audio and video inputs and outputs are associated. Selecting a video -source also selects an audio source. This is most evident when the video -and audio source is a tuner. Further audio connectors can combine with -more than one video input or output. Assumed two composite video inputs -and two audio inputs exist, there may be up to four valid combinations. -The relation of video and audio connectors is defined in the -``audioset`` field of the respective struct -:c:type:`v4l2_input` or struct -:c:type:`v4l2_output`, where each bit represents the index -number, starting at zero, of one audio input or output. - -To learn about the number and attributes of the available inputs and -outputs applications can enumerate them with the -:ref:`VIDIOC_ENUMAUDIO` and -:ref:`VIDIOC_ENUMAUDOUT ` ioctl, respectively. -The struct :c:type:`v4l2_audio` returned by the -:ref:`VIDIOC_ENUMAUDIO` ioctl also contains signal -status information applicable when the current audio input is queried. - -The :ref:`VIDIOC_G_AUDIO ` and -:ref:`VIDIOC_G_AUDOUT ` ioctls report the current -audio input and output, respectively. - -.. note:: - - Note that, unlike :ref:`VIDIOC_G_INPUT ` and - :ref:`VIDIOC_G_OUTPUT ` these ioctls return a - structure as :ref:`VIDIOC_ENUMAUDIO` and - :ref:`VIDIOC_ENUMAUDOUT ` do, not just an index. - -To select an audio input and change its properties applications call the -:ref:`VIDIOC_S_AUDIO ` ioctl. To select an audio -output (which presently has no changeable properties) applications call -the :ref:`VIDIOC_S_AUDOUT ` ioctl. - -Drivers must implement all audio input ioctls when the device has -multiple selectable audio inputs, all audio output ioctls when the -device has multiple selectable audio outputs. When the device has any -audio inputs or outputs the driver must set the ``V4L2_CAP_AUDIO`` flag -in the struct :c:type:`v4l2_capability` returned by -the :ref:`VIDIOC_QUERYCAP` ioctl. - - -Example: Information about the current audio input -================================================== - -.. code-block:: c - - struct v4l2_audio audio; - - memset(&audio, 0, sizeof(audio)); - - if (-1 == ioctl(fd, VIDIOC_G_AUDIO, &audio)) { - perror("VIDIOC_G_AUDIO"); - exit(EXIT_FAILURE); - } - - printf("Current input: %s\\n", audio.name); - - -Example: Switching to the first audio input -=========================================== - -.. code-block:: c - - struct v4l2_audio audio; - - memset(&audio, 0, sizeof(audio)); /* clear audio.mode, audio.reserved */ - - audio.index = 0; - - if (-1 == ioctl(fd, VIDIOC_S_AUDIO, &audio)) { - perror("VIDIOC_S_AUDIO"); - exit(EXIT_FAILURE); - } - -.. [#f1] - Actually struct :c:type:`v4l2_audio` ought to have a - ``tuner`` field like struct :c:type:`v4l2_input`, not - only making the API more consistent but also permitting radio devices - with multiple tuners. diff --git a/Documentation/media/uapi/v4l/bayer.svg b/Documentation/media/uapi/v4l/bayer.svg deleted file mode 100644 index c5bf85103901..000000000000 --- a/Documentation/media/uapi/v4l/bayer.svg +++ /dev/null @@ -1,56 +0,0 @@ - - -image/svg+xmlB -G -G -R -BGGR -B -G -G -R -GBRG -B -G -G -R -RGGB -B -G -G -R -GRBG - diff --git a/Documentation/media/uapi/v4l/biblio.rst b/Documentation/media/uapi/v4l/biblio.rst deleted file mode 100644 index 8095f57d3d75..000000000000 --- a/Documentation/media/uapi/v4l/biblio.rst +++ /dev/null @@ -1,416 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -********** -References -********** - - -.. _cea608: - -CEA 608-E -========= - - -:title: CEA-608-E R-2014 "Line 21 Data Services" - -:author: Consumer Electronics Association (http://www.ce.org) - -.. _en300294: - -EN 300 294 -========== - - -:title: EN 300 294 "625-line television Wide Screen Signalling (WSS)" - -:author: European Telecommunication Standards Institute (http://www.etsi.org) - -.. _ets300231: - -ETS 300 231 -=========== - - -:title: ETS 300 231 "Specification of the domestic video Programme Delivery Control system (PDC)" - -:author: European Telecommunication Standards Institute (http://www.etsi.org) - -.. _ets300706: - -ETS 300 706 -=========== - - -:title: ETS 300 706 "Enhanced Teletext specification" - -:author: European Telecommunication Standards Institute (http://www.etsi.org) - -.. _mpeg2part1: - -ISO 13818-1 -=========== - - -:title: ITU-T Rec. H.222.0 | ISO/IEC 13818-1 "Information technology — Generic coding of moving pictures and associated audio information: Systems" - -:author: International Telecommunication Union (http://www.itu.ch), International Organisation for Standardisation (http://www.iso.ch) - -.. _mpeg2part2: - -ISO 13818-2 -=========== - - -:title: ITU-T Rec. H.262 | ISO/IEC 13818-2 "Information technology — Generic coding of moving pictures and associated audio information: Video" - -:author: International Telecommunication Union (http://www.itu.ch), International Organisation for Standardisation (http://www.iso.ch) - -.. _itu470: - -ITU BT.470 -========== - - -:title: ITU-R Recommendation BT.470-6 "Conventional Television Systems" - -:author: International Telecommunication Union (http://www.itu.ch) - -.. _itu601: - -ITU BT.601 -========== - - -:title: ITU-R Recommendation BT.601-5 "Studio Encoding Parameters of Digital Television for Standard 4:3 and Wide-Screen 16:9 Aspect Ratios" - -:author: International Telecommunication Union (http://www.itu.ch) - -.. _itu653: - -ITU BT.653 -========== - - -:title: ITU-R Recommendation BT.653-3 "Teletext systems" - -:author: International Telecommunication Union (http://www.itu.ch) - -.. _itu709: - -ITU BT.709 -========== - - -:title: ITU-R Recommendation BT.709-5 "Parameter values for the HDTV standards for production and international programme exchange" - -:author: International Telecommunication Union (http://www.itu.ch) - -.. _itu1119: - -ITU BT.1119 -=========== - - -:title: ITU-R Recommendation BT.1119 "625-line television Wide Screen Signalling (WSS)" - -:author: International Telecommunication Union (http://www.itu.ch) - -.. _h264: - -ITU-T Rec. H.264 Specification (04/2017 Edition) -================================================ - -:title: ITU-T Recommendation H.264 "Advanced Video Coding for Generic Audiovisual Services" - -:author: International Telecommunication Union (http://www.itu.ch) - -.. _hevc: - -ITU H.265/HEVC -============== - -:title: ITU-T Rec. H.265 | ISO/IEC 23008-2 "High Efficiency Video Coding" - -:author: International Telecommunication Union (http://www.itu.ch), International Organisation for Standardisation (http://www.iso.ch) - -.. _jfif: - -JFIF -==== - - -:title: JPEG File Interchange Format -:subtitle: Version 1.02 - -:author: Independent JPEG Group (http://www.ijg.org) - -.. _itu-t81: - -ITU-T.81 -======== - - -:title: ITU-T Recommendation T.81 "Information Technology — Digital Compression and Coding of Continous-Tone Still Images — Requirements and Guidelines" - -:author: International Telecommunication Union (http://www.itu.int) - -.. _w3c-jpeg-jfif: - -W3C JPEG JFIF -============= - - -:title: JPEG JFIF - -:author: The World Wide Web Consortium (http://www.w3.org) - -.. _smpte12m: - -SMPTE 12M -========= - - -:title: SMPTE 12M-1999 "Television, Audio and Film - Time and Control Code" - -:author: Society of Motion Picture and Television Engineers (http://www.smpte.org) - -.. _smpte170m: - -SMPTE 170M -========== - - -:title: SMPTE 170M-1999 "Television - Composite Analog Video Signal - NTSC for Studio Applications" - -:author: Society of Motion Picture and Television Engineers (http://www.smpte.org) - -.. _smpte240m: - -SMPTE 240M -========== - - -:title: SMPTE 240M-1999 "Television - Signal Parameters - 1125-Line High-Definition Production" - -:author: Society of Motion Picture and Television Engineers (http://www.smpte.org) - -.. _smpte431: - -SMPTE RP 431-2 -============== - - -:title: SMPTE RP 431-2:2011 "D-Cinema Quality - Reference Projector and Environment" - -:author: Society of Motion Picture and Television Engineers (http://www.smpte.org) - -.. _smpte2084: - -SMPTE ST 2084 -============= - - -:title: SMPTE ST 2084:2014 "High Dynamic Range Electro-Optical Transfer Function of Master Reference Displays" - -:author: Society of Motion Picture and Television Engineers (http://www.smpte.org) - -.. _srgb: - -sRGB -==== - - -:title: IEC 61966-2-1 ed1.0 "Multimedia systems and equipment - Colour measurement and management - Part 2-1: Colour management - Default RGB colour space - sRGB" - -:author: International Electrotechnical Commission (http://www.iec.ch) - -.. _sycc: - -sYCC -==== - - -:title: IEC 61966-2-1-am1 ed1.0 "Amendment 1 - Multimedia systems and equipment - Colour measurement and management - Part 2-1: Colour management - Default RGB colour space - sRGB" - -:author: International Electrotechnical Commission (http://www.iec.ch) - -.. _xvycc: - -xvYCC -===== - - -:title: IEC 61966-2-4 ed1.0 "Multimedia systems and equipment - Colour measurement and management - Part 2-4: Colour management - Extended-gamut YCC colour space for video applications - xvYCC" - -:author: International Electrotechnical Commission (http://www.iec.ch) - -.. _oprgb: - -opRGB -===== - - -:title: IEC 61966-2-5 "Multimedia systems and equipment - Colour measurement and management - Part 2-5: Colour management - Optional RGB colour space - opRGB" - -:author: International Electrotechnical Commission (http://www.iec.ch) - -.. _itu2020: - -ITU BT.2020 -=========== - - -:title: ITU-R Recommendation BT.2020 (08/2012) "Parameter values for ultra-high definition television systems for production and international programme exchange" - -:author: International Telecommunication Union (http://www.itu.ch) - -.. _tech3213: - -EBU Tech 3213 -============= - - -:title: E.B.U. Standard for Chromaticity Tolerances for Studio Monitors" - -:author: European Broadcast Union (http://www.ebu.ch) - -.. _iec62106: - -IEC 62106 -========= - - -:title: Specification of the radio data system (RDS) for VHF/FM sound broadcasting in the frequency range from 87,5 to 108,0 MHz - -:author: International Electrotechnical Commission (http://www.iec.ch) - -.. _nrsc4: - -NRSC-4-B -======== - - -:title: NRSC-4-B: United States RBDS Standard - -:author: National Radio Systems Committee (http://www.nrscstandards.org) - -.. _iso12232: - -ISO 12232:2006 -============== - - -:title: Photography — Digital still cameras — Determination of exposure index, ISO speed ratings, standard output sensitivity, and recommended exposure index - -:author: International Organization for Standardization (http://www.iso.org) - -.. _cea861: - -CEA-861-E -========= - - -:title: A DTV Profile for Uncompressed High Speed Digital Interfaces - -:author: Consumer Electronics Association (http://www.ce.org) - -.. _vesadmt: - -VESA DMT -======== - - -:title: VESA and Industry Standards and Guidelines for Computer Display Monitor Timing (DMT) - -:author: Video Electronics Standards Association (http://www.vesa.org) - -.. _vesaedid: - -EDID -==== - - -:title: VESA Enhanced Extended Display Identification Data Standard -:subtitle: Release A, Revision 2 - -:author: Video Electronics Standards Association (http://www.vesa.org) - -.. _hdcp: - -HDCP -==== - - -:title: High-bandwidth Digital Content Protection System -:subtitle: Revision 1.3 - -:author: Digital Content Protection LLC (http://www.digital-cp.com) - -.. _hdmi: - -HDMI -==== - - -:title: High-Definition Multimedia Interface -:subtitle: Specification Version 1.4a - -:author: HDMI Licensing LLC (http://www.hdmi.org) - -.. _hdmi2: - -HDMI2 -===== - -:title: High-Definition Multimedia Interface -:subtitle: Specification Version 2.0 - -:author: HDMI Licensing LLC (http://www.hdmi.org) - -.. _dp: - -DP -== - - -:title: VESA DisplayPort Standard -:subtitle: Version 1, Revision 2 - -:author: Video Electronics Standards Association (http://www.vesa.org) - -.. _poynton: - -poynton -======= - - -:title: Digital Video and HDTV, Algorithms and Interfaces - -:author: Charles Poynton - -.. _colimg: - -colimg -====== - - -:title: Color Imaging: Fundamentals and Applications - -:author: Erik Reinhard et al. - -.. _vp8: - -VP8 -=== - - -:title: RFC 6386: "VP8 Data Format and Decoding Guide" - -:author: J. Bankoski et al. diff --git a/Documentation/media/uapi/v4l/buffer.rst b/Documentation/media/uapi/v4l/buffer.rst deleted file mode 100644 index 3112300c2fa0..000000000000 --- a/Documentation/media/uapi/v4l/buffer.rst +++ /dev/null @@ -1,817 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _buffer: - -******* -Buffers -******* - -A buffer contains data exchanged by application and driver using one of -the Streaming I/O methods. In the multi-planar API, the data is held in -planes, while the buffer structure acts as a container for the planes. -Only pointers to buffers (planes) are exchanged, the data itself is not -copied. These pointers, together with meta-information like timestamps -or field parity, are stored in a struct :c:type:`v4l2_buffer`, -argument to the :ref:`VIDIOC_QUERYBUF`, -:ref:`VIDIOC_QBUF ` and -:ref:`VIDIOC_DQBUF ` ioctl. In the multi-planar API, -some plane-specific members of struct :c:type:`v4l2_buffer`, -such as pointers and sizes for each plane, are stored in struct -struct :c:type:`v4l2_plane` instead. In that case, struct -struct :c:type:`v4l2_buffer` contains an array of plane structures. - -Dequeued video buffers come with timestamps. The driver decides at which -part of the frame and with which clock the timestamp is taken. Please -see flags in the masks ``V4L2_BUF_FLAG_TIMESTAMP_MASK`` and -``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` in :ref:`buffer-flags`. These flags -are always valid and constant across all buffers during the whole video -stream. Changes in these flags may take place as a side effect of -:ref:`VIDIOC_S_INPUT ` or -:ref:`VIDIOC_S_OUTPUT ` however. The -``V4L2_BUF_FLAG_TIMESTAMP_COPY`` timestamp type which is used by e.g. on -mem-to-mem devices is an exception to the rule: the timestamp source -flags are copied from the OUTPUT video buffer to the CAPTURE video -buffer. - - -Interactions between formats, controls and buffers -================================================== - -V4L2 exposes parameters that influence the buffer size, or the way data is -laid out in the buffer. Those parameters are exposed through both formats and -controls. One example of such a control is the ``V4L2_CID_ROTATE`` control -that modifies the direction in which pixels are stored in the buffer, as well -as the buffer size when the selected format includes padding at the end of -lines. - -The set of information needed to interpret the content of a buffer (e.g. the -pixel format, the line stride, the tiling orientation or the rotation) is -collectively referred to in the rest of this section as the buffer layout. - -Controls that can modify the buffer layout shall set the -``V4L2_CTRL_FLAG_MODIFY_LAYOUT`` flag. - -Modifying formats or controls that influence the buffer size or layout require -the stream to be stopped. Any attempt at such a modification while the stream -is active shall cause the ioctl setting the format or the control to return -the ``EBUSY`` error code. In that case drivers shall also set the -``V4L2_CTRL_FLAG_GRABBED`` flag when calling -:c:func:`VIDIOC_QUERYCTRL` or :c:func:`VIDIOC_QUERY_EXT_CTRL` for such a -control while the stream is active. - -.. note:: - - The :c:func:`VIDIOC_S_SELECTION` ioctl can, depending on the hardware (for - instance if the device doesn't include a scaler), modify the format in - addition to the selection rectangle. Similarly, the - :c:func:`VIDIOC_S_INPUT`, :c:func:`VIDIOC_S_OUTPUT`, :c:func:`VIDIOC_S_STD` - and :c:func:`VIDIOC_S_DV_TIMINGS` ioctls can also modify the format and - selection rectangles. When those ioctls result in a buffer size or layout - change, drivers shall handle that condition as they would handle it in the - :c:func:`VIDIOC_S_FMT` ioctl in all cases described in this section. - -Controls that only influence the buffer layout can be modified at any time -when the stream is stopped. As they don't influence the buffer size, no -special handling is needed to synchronize those controls with buffer -allocation and the ``V4L2_CTRL_FLAG_GRABBED`` flag is cleared once the -stream is stopped. - -Formats and controls that influence the buffer size interact with buffer -allocation. The simplest way to handle this is for drivers to always require -buffers to be reallocated in order to change those formats or controls. In -that case, to perform such changes, userspace applications shall first stop -the video stream with the :c:func:`VIDIOC_STREAMOFF` ioctl if it is running -and free all buffers with the :c:func:`VIDIOC_REQBUFS` ioctl if they are -allocated. After freeing all buffers the ``V4L2_CTRL_FLAG_GRABBED`` flag -for controls is cleared. The format or controls can then be modified, and -buffers shall then be reallocated and the stream restarted. A typical ioctl -sequence is - - #. VIDIOC_STREAMOFF - #. VIDIOC_REQBUFS(0) - #. VIDIOC_S_EXT_CTRLS - #. VIDIOC_S_FMT - #. VIDIOC_REQBUFS(n) - #. VIDIOC_QBUF - #. VIDIOC_STREAMON - -The second :c:func:`VIDIOC_REQBUFS` call will take the new format and control -value into account to compute the buffer size to allocate. Applications can -also retrieve the size by calling the :c:func:`VIDIOC_G_FMT` ioctl if needed. - -.. note:: - - The API doesn't mandate the above order for control (3.) and format (4.) - changes. Format and controls can be set in a different order, or even - interleaved, depending on the device and use case. For instance some - controls might behave differently for different pixel formats, in which - case the format might need to be set first. - -When reallocation is required, any attempt to modify format or controls that -influences the buffer size while buffers are allocated shall cause the format -or control set ioctl to return the ``EBUSY`` error. Any attempt to queue a -buffer too small for the current format or controls shall cause the -:c:func:`VIDIOC_QBUF` ioctl to return a ``EINVAL`` error. - -Buffer reallocation is an expensive operation. To avoid that cost, drivers can -(and are encouraged to) allow format or controls that influence the buffer -size to be changed with buffers allocated. In that case, a typical ioctl -sequence to modify format and controls is - - #. VIDIOC_STREAMOFF - #. VIDIOC_S_EXT_CTRLS - #. VIDIOC_S_FMT - #. VIDIOC_QBUF - #. VIDIOC_STREAMON - -For this sequence to operate correctly, queued buffers need to be large enough -for the new format or controls. Drivers shall return a ``ENOSPC`` error in -response to format change (:c:func:`VIDIOC_S_FMT`) or control changes -(:c:func:`VIDIOC_S_CTRL` or :c:func:`VIDIOC_S_EXT_CTRLS`) if buffers too small -for the new format are currently queued. As a simplification, drivers are -allowed to return a ``EBUSY`` error from these ioctls if any buffer is -currently queued, without checking the queued buffers sizes. - -Additionally, drivers shall return a ``EINVAL`` error from the -:c:func:`VIDIOC_QBUF` ioctl if the buffer being queued is too small for the -current format or controls. Together, these requirements ensure that queued -buffers will always be large enough for the configured format and controls. - -Userspace applications can query the buffer size required for a given format -and controls by first setting the desired control values and then trying the -desired format. The :c:func:`VIDIOC_TRY_FMT` ioctl will return the required -buffer size. - - #. VIDIOC_S_EXT_CTRLS(x) - #. VIDIOC_TRY_FMT() - #. VIDIOC_S_EXT_CTRLS(y) - #. VIDIOC_TRY_FMT() - -The :c:func:`VIDIOC_CREATE_BUFS` ioctl can then be used to allocate buffers -based on the queried sizes (for instance by allocating a set of buffers large -enough for all the desired formats and controls, or by allocating separate set -of appropriately sized buffers for each use case). - - -.. c:type:: v4l2_buffer - -struct v4l2_buffer -================== - -.. tabularcolumns:: |p{2.8cm}|p{2.5cm}|p{1.6cm}|p{10.2cm}| - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_buffer - :header-rows: 0 - :stub-columns: 0 - :widths: 1 2 10 - - * - __u32 - - ``index`` - - Number of the buffer, set by the application except when calling - :ref:`VIDIOC_DQBUF `, then it is set by the - driver. This field can range from zero to the number of buffers - allocated with the :ref:`VIDIOC_REQBUFS` ioctl - (struct :c:type:`v4l2_requestbuffers` - ``count``), plus any buffers allocated with - :ref:`VIDIOC_CREATE_BUFS` minus one. - * - __u32 - - ``type`` - - Type of the buffer, same as struct - :c:type:`v4l2_format` ``type`` or struct - :c:type:`v4l2_requestbuffers` ``type``, set - by the application. See :c:type:`v4l2_buf_type` - * - __u32 - - ``bytesused`` - - The number of bytes occupied by the data in the buffer. It depends - on the negotiated data format and may change with each buffer for - compressed variable size data like JPEG images. Drivers must set - this field when ``type`` refers to a capture stream, applications - when it refers to an output stream. If the application sets this - to 0 for an output stream, then ``bytesused`` will be set to the - size of the buffer (see the ``length`` field of this struct) by - the driver. For multiplanar formats this field is ignored and the - ``planes`` pointer is used instead. - * - __u32 - - ``flags`` - - Flags set by the application or driver, see :ref:`buffer-flags`. - * - __u32 - - ``field`` - - Indicates the field order of the image in the buffer, see - :c:type:`v4l2_field`. This field is not used when the buffer - contains VBI data. Drivers must set it when ``type`` refers to a - capture stream, applications when it refers to an output stream. - * - struct timeval - - ``timestamp`` - - For capture streams this is time when the first data byte was - captured, as returned by the :c:func:`clock_gettime()` function - for the relevant clock id; see ``V4L2_BUF_FLAG_TIMESTAMP_*`` in - :ref:`buffer-flags`. For output streams the driver stores the - time at which the last data byte was actually sent out in the - ``timestamp`` field. This permits applications to monitor the - drift between the video and system clock. For output streams that - use ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` the application has to fill - in the timestamp which will be copied by the driver to the capture - stream. - * - struct :c:type:`v4l2_timecode` - - ``timecode`` - - When the ``V4L2_BUF_FLAG_TIMECODE`` flag is set in ``flags``, this - structure contains a frame timecode. In - :c:type:`V4L2_FIELD_ALTERNATE ` mode the top and - bottom field contain the same timecode. Timecodes are intended to - help video editing and are typically recorded on video tapes, but - also embedded in compressed formats like MPEG. This field is - independent of the ``timestamp`` and ``sequence`` fields. - * - __u32 - - ``sequence`` - - Set by the driver, counting the frames (not fields!) in sequence. - This field is set for both input and output devices. - * - :cspan:`2` - - In :c:type:`V4L2_FIELD_ALTERNATE ` mode the top and - bottom field have the same sequence number. The count starts at - zero and includes dropped or repeated frames. A dropped frame was - received by an input device but could not be stored due to lack of - free buffer space. A repeated frame was displayed again by an - output device because the application did not pass new data in - time. - - .. note:: - - This may count the frames received e.g. over USB, without - taking into account the frames dropped by the remote hardware due - to limited compression throughput or bus bandwidth. These devices - identify by not enumerating any video standards, see - :ref:`standard`. - - * - __u32 - - ``memory`` - - This field must be set by applications and/or drivers in - accordance with the selected I/O method. See :c:type:`v4l2_memory` - * - union { - - ``m`` - * - __u32 - - ``offset`` - - For the single-planar API and when ``memory`` is - ``V4L2_MEMORY_MMAP`` this is the offset of the buffer from the - start of the device memory. The value is returned by the driver - and apart of serving as parameter to the - :ref:`mmap() ` function not useful for applications. - See :ref:`mmap` for details - * - unsigned long - - ``userptr`` - - For the single-planar API and when ``memory`` is - ``V4L2_MEMORY_USERPTR`` this is a pointer to the buffer (casted to - unsigned long type) in virtual memory, set by the application. See - :ref:`userp` for details. - * - struct v4l2_plane - - ``*planes`` - - When using the multi-planar API, contains a userspace pointer to - an array of struct :c:type:`v4l2_plane`. The size of - the array should be put in the ``length`` field of this - struct :c:type:`v4l2_buffer` structure. - * - int - - ``fd`` - - For the single-plane API and when ``memory`` is - ``V4L2_MEMORY_DMABUF`` this is the file descriptor associated with - a DMABUF buffer. - * - } - - - * - __u32 - - ``length`` - - Size of the buffer (not the payload) in bytes for the - single-planar API. This is set by the driver based on the calls to - :ref:`VIDIOC_REQBUFS` and/or - :ref:`VIDIOC_CREATE_BUFS`. For the - multi-planar API the application sets this to the number of - elements in the ``planes`` array. The driver will fill in the - actual number of valid elements in that array. - * - __u32 - - ``reserved2`` - - A place holder for future extensions. Drivers and applications - must set this to 0. - * - __u32 - - ``request_fd`` - - The file descriptor of the request to queue the buffer to. If the flag - ``V4L2_BUF_FLAG_REQUEST_FD`` is set, then the buffer will be - queued to this request. If the flag is not set, then this field will - be ignored. - - The ``V4L2_BUF_FLAG_REQUEST_FD`` flag and this field are only used by - :ref:`ioctl VIDIOC_QBUF ` and ignored by other ioctls that - take a :c:type:`v4l2_buffer` as argument. - - Applications should not set ``V4L2_BUF_FLAG_REQUEST_FD`` for any ioctls - other than :ref:`VIDIOC_QBUF `. - - If the device does not support requests, then ``EBADR`` will be returned. - If requests are supported but an invalid request file descriptor is - given, then ``EINVAL`` will be returned. - - - -.. c:type:: v4l2_plane - -struct v4l2_plane -================= - -.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u32 - - ``bytesused`` - - The number of bytes occupied by data in the plane (its payload). - Drivers must set this field when ``type`` refers to a capture - stream, applications when it refers to an output stream. If the - application sets this to 0 for an output stream, then - ``bytesused`` will be set to the size of the plane (see the - ``length`` field of this struct) by the driver. - - .. note:: - - Note that the actual image data starts at ``data_offset`` - which may not be 0. - * - __u32 - - ``length`` - - Size in bytes of the plane (not its payload). This is set by the - driver based on the calls to - :ref:`VIDIOC_REQBUFS` and/or - :ref:`VIDIOC_CREATE_BUFS`. - * - union { - - ``m`` - * - __u32 - - ``mem_offset`` - - When the memory type in the containing struct - :c:type:`v4l2_buffer` is ``V4L2_MEMORY_MMAP``, this - is the value that should be passed to :ref:`mmap() `, - similar to the ``offset`` field in struct - :c:type:`v4l2_buffer`. - * - unsigned long - - ``userptr`` - - When the memory type in the containing struct - :c:type:`v4l2_buffer` is ``V4L2_MEMORY_USERPTR``, - this is a userspace pointer to the memory allocated for this plane - by an application. - * - int - - ``fd`` - - When the memory type in the containing struct - :c:type:`v4l2_buffer` is ``V4L2_MEMORY_DMABUF``, - this is a file descriptor associated with a DMABUF buffer, similar - to the ``fd`` field in struct :c:type:`v4l2_buffer`. - * - } - - - * - __u32 - - ``data_offset`` - - Offset in bytes to video data in the plane. Drivers must set this - field when ``type`` refers to a capture stream, applications when - it refers to an output stream. - - .. note:: - - That data_offset is included in ``bytesused``. So the - size of the image in the plane is ``bytesused``-``data_offset`` - at offset ``data_offset`` from the start of the plane. - * - __u32 - - ``reserved[11]`` - - Reserved for future use. Should be zeroed by drivers and - applications. - - - -.. c:type:: v4l2_buf_type - -enum v4l2_buf_type -================== - -.. cssclass:: longtable - -.. tabularcolumns:: |p{7.8cm}|p{0.6cm}|p{9.1cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 4 1 9 - - * - ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` - - 1 - - Buffer of a single-planar video capture stream, see - :ref:`capture`. - * - ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` - - 9 - - Buffer of a multi-planar video capture stream, see - :ref:`capture`. - * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` - - 2 - - Buffer of a single-planar video output stream, see - :ref:`output`. - * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` - - 10 - - Buffer of a multi-planar video output stream, see :ref:`output`. - * - ``V4L2_BUF_TYPE_VIDEO_OVERLAY`` - - 3 - - Buffer for video overlay, see :ref:`overlay`. - * - ``V4L2_BUF_TYPE_VBI_CAPTURE`` - - 4 - - Buffer of a raw VBI capture stream, see :ref:`raw-vbi`. - * - ``V4L2_BUF_TYPE_VBI_OUTPUT`` - - 5 - - Buffer of a raw VBI output stream, see :ref:`raw-vbi`. - * - ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` - - 6 - - Buffer of a sliced VBI capture stream, see :ref:`sliced`. - * - ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT`` - - 7 - - Buffer of a sliced VBI output stream, see :ref:`sliced`. - * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY`` - - 8 - - Buffer for video output overlay (OSD), see :ref:`osd`. - * - ``V4L2_BUF_TYPE_SDR_CAPTURE`` - - 11 - - Buffer for Software Defined Radio (SDR) capture stream, see - :ref:`sdr`. - * - ``V4L2_BUF_TYPE_SDR_OUTPUT`` - - 12 - - Buffer for Software Defined Radio (SDR) output stream, see - :ref:`sdr`. - * - ``V4L2_BUF_TYPE_META_CAPTURE`` - - 13 - - Buffer for metadata capture, see :ref:`metadata`. - * - ``V4L2_BUF_TYPE_META_OUTPUT`` - - 14 - - Buffer for metadata output, see :ref:`metadata`. - - - -.. _buffer-flags: - -Buffer Flags -============ - -.. raw:: latex - - \small - -.. tabularcolumns:: |p{7.0cm}|p{2.1cm}|p{8.4cm}| - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 4 - - * .. _`V4L2-BUF-FLAG-MAPPED`: - - - ``V4L2_BUF_FLAG_MAPPED`` - - 0x00000001 - - The buffer resides in device memory and has been mapped into the - application's address space, see :ref:`mmap` for details. - Drivers set or clear this flag when the - :ref:`VIDIOC_QUERYBUF`, - :ref:`VIDIOC_QBUF` or - :ref:`VIDIOC_DQBUF ` ioctl is called. Set by the - driver. - * .. _`V4L2-BUF-FLAG-QUEUED`: - - - ``V4L2_BUF_FLAG_QUEUED`` - - 0x00000002 - - Internally drivers maintain two buffer queues, an incoming and - outgoing queue. When this flag is set, the buffer is currently on - the incoming queue. It automatically moves to the outgoing queue - after the buffer has been filled (capture devices) or displayed - (output devices). Drivers set or clear this flag when the - ``VIDIOC_QUERYBUF`` ioctl is called. After (successful) calling - the ``VIDIOC_QBUF``\ ioctl it is always set and after - ``VIDIOC_DQBUF`` always cleared. - * .. _`V4L2-BUF-FLAG-DONE`: - - - ``V4L2_BUF_FLAG_DONE`` - - 0x00000004 - - When this flag is set, the buffer is currently on the outgoing - queue, ready to be dequeued from the driver. Drivers set or clear - this flag when the ``VIDIOC_QUERYBUF`` ioctl is called. After - calling the ``VIDIOC_QBUF`` or ``VIDIOC_DQBUF`` it is always - cleared. Of course a buffer cannot be on both queues at the same - time, the ``V4L2_BUF_FLAG_QUEUED`` and ``V4L2_BUF_FLAG_DONE`` flag - are mutually exclusive. They can be both cleared however, then the - buffer is in "dequeued" state, in the application domain so to - say. - * .. _`V4L2-BUF-FLAG-ERROR`: - - - ``V4L2_BUF_FLAG_ERROR`` - - 0x00000040 - - When this flag is set, the buffer has been dequeued successfully, - although the data might have been corrupted. This is recoverable, - streaming may continue as normal and the buffer may be reused - normally. Drivers set this flag when the ``VIDIOC_DQBUF`` ioctl is - called. - * .. _`V4L2-BUF-FLAG-IN-REQUEST`: - - - ``V4L2_BUF_FLAG_IN_REQUEST`` - - 0x00000080 - - This buffer is part of a request that hasn't been queued yet. - * .. _`V4L2-BUF-FLAG-KEYFRAME`: - - - ``V4L2_BUF_FLAG_KEYFRAME`` - - 0x00000008 - - Drivers set or clear this flag when calling the ``VIDIOC_DQBUF`` - ioctl. It may be set by video capture devices when the buffer - contains a compressed image which is a key frame (or field), i. e. - can be decompressed on its own. Also known as an I-frame. - Applications can set this bit when ``type`` refers to an output - stream. - * .. _`V4L2-BUF-FLAG-PFRAME`: - - - ``V4L2_BUF_FLAG_PFRAME`` - - 0x00000010 - - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags predicted frames - or fields which contain only differences to a previous key frame. - Applications can set this bit when ``type`` refers to an output - stream. - * .. _`V4L2-BUF-FLAG-BFRAME`: - - - ``V4L2_BUF_FLAG_BFRAME`` - - 0x00000020 - - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags a bi-directional - predicted frame or field which contains only the differences - between the current frame and both the preceding and following key - frames to specify its content. Applications can set this bit when - ``type`` refers to an output stream. - * .. _`V4L2-BUF-FLAG-TIMECODE`: - - - ``V4L2_BUF_FLAG_TIMECODE`` - - 0x00000100 - - The ``timecode`` field is valid. Drivers set or clear this flag - when the ``VIDIOC_DQBUF`` ioctl is called. Applications can set - this bit and the corresponding ``timecode`` structure when - ``type`` refers to an output stream. - * .. _`V4L2-BUF-FLAG-PREPARED`: - - - ``V4L2_BUF_FLAG_PREPARED`` - - 0x00000400 - - The buffer has been prepared for I/O and can be queued by the - application. Drivers set or clear this flag when the - :ref:`VIDIOC_QUERYBUF`, - :ref:`VIDIOC_PREPARE_BUF `, - :ref:`VIDIOC_QBUF` or - :ref:`VIDIOC_DQBUF ` ioctl is called. - * .. _`V4L2-BUF-FLAG-NO-CACHE-INVALIDATE`: - - - ``V4L2_BUF_FLAG_NO_CACHE_INVALIDATE`` - - 0x00000800 - - Caches do not have to be invalidated for this buffer. Typically - applications shall use this flag if the data captured in the - buffer is not going to be touched by the CPU, instead the buffer - will, probably, be passed on to a DMA-capable hardware unit for - further processing or output. - * .. _`V4L2-BUF-FLAG-NO-CACHE-CLEAN`: - - - ``V4L2_BUF_FLAG_NO_CACHE_CLEAN`` - - 0x00001000 - - Caches do not have to be cleaned for this buffer. Typically - applications shall use this flag for output buffers if the data in - this buffer has not been created by the CPU but by some - DMA-capable unit, in which case caches have not been used. - * .. _`V4L2-BUF-FLAG-M2M-HOLD-CAPTURE-BUF`: - - - ``V4L2_BUF_FLAG_M2M_HOLD_CAPTURE_BUF`` - - 0x00000200 - - Only valid if ``V4L2_BUF_CAP_SUPPORTS_M2M_HOLD_CAPTURE_BUF`` is - set. It is typically used with stateless decoders where multiple - output buffers each decode to a slice of the decoded frame. - Applications can set this flag when queueing the output buffer - to prevent the driver from dequeueing the capture buffer after - the output buffer has been decoded (i.e. the capture buffer is - 'held'). If the timestamp of this output buffer differs from that - of the previous output buffer, then that indicates the start of a - new frame and the previously held capture buffer is dequeued. - * .. _`V4L2-BUF-FLAG-LAST`: - - - ``V4L2_BUF_FLAG_LAST`` - - 0x00100000 - - Last buffer produced by the hardware. mem2mem codec drivers set - this flag on the capture queue for the last buffer when the - :ref:`VIDIOC_QUERYBUF` or - :ref:`VIDIOC_DQBUF ` ioctl is called. Due to - hardware limitations, the last buffer may be empty. In this case - the driver will set the ``bytesused`` field to 0, regardless of - the format. Any Any subsequent call to the - :ref:`VIDIOC_DQBUF ` ioctl will not block anymore, - but return an ``EPIPE`` error code. - * .. _`V4L2-BUF-FLAG-REQUEST-FD`: - - - ``V4L2_BUF_FLAG_REQUEST_FD`` - - 0x00800000 - - The ``request_fd`` field contains a valid file descriptor. - * .. _`V4L2-BUF-FLAG-TIMESTAMP-MASK`: - - - ``V4L2_BUF_FLAG_TIMESTAMP_MASK`` - - 0x0000e000 - - Mask for timestamp types below. To test the timestamp type, mask - out bits not belonging to timestamp type by performing a logical - and operation with buffer flags and timestamp mask. - * .. _`V4L2-BUF-FLAG-TIMESTAMP-UNKNOWN`: - - - ``V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN`` - - 0x00000000 - - Unknown timestamp type. This type is used by drivers before Linux - 3.9 and may be either monotonic (see below) or realtime (wall - clock). Monotonic clock has been favoured in embedded systems - whereas most of the drivers use the realtime clock. Either kinds - of timestamps are available in user space via - :c:func:`clock_gettime` using clock IDs ``CLOCK_MONOTONIC`` - and ``CLOCK_REALTIME``, respectively. - * .. _`V4L2-BUF-FLAG-TIMESTAMP-MONOTONIC`: - - - ``V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC`` - - 0x00002000 - - The buffer timestamp has been taken from the ``CLOCK_MONOTONIC`` - clock. To access the same clock outside V4L2, use - :c:func:`clock_gettime`. - * .. _`V4L2-BUF-FLAG-TIMESTAMP-COPY`: - - - ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` - - 0x00004000 - - The CAPTURE buffer timestamp has been taken from the corresponding - OUTPUT buffer. This flag applies only to mem2mem devices. - * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-MASK`: - - - ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` - - 0x00070000 - - Mask for timestamp sources below. The timestamp source defines the - point of time the timestamp is taken in relation to the frame. - Logical 'and' operation between the ``flags`` field and - ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` produces the value of the - timestamp source. Applications must set the timestamp source when - ``type`` refers to an output stream and - ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` is set. - * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-EOF`: - - - ``V4L2_BUF_FLAG_TSTAMP_SRC_EOF`` - - 0x00000000 - - End Of Frame. The buffer timestamp has been taken when the last - pixel of the frame has been received or the last pixel of the - frame has been transmitted. In practice, software generated - timestamps will typically be read from the clock a small amount of - time after the last pixel has been received or transmitten, - depending on the system and other activity in it. - * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-SOE`: - - - ``V4L2_BUF_FLAG_TSTAMP_SRC_SOE`` - - 0x00010000 - - Start Of Exposure. The buffer timestamp has been taken when the - exposure of the frame has begun. This is only valid for the - ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` buffer type. - -.. raw:: latex - - \normalsize - - -.. c:type:: v4l2_memory - -enum v4l2_memory -================ - -.. tabularcolumns:: |p{5.0cm}|p{0.8cm}|p{11.7cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 4 - - * - ``V4L2_MEMORY_MMAP`` - - 1 - - The buffer is used for :ref:`memory mapping ` I/O. - * - ``V4L2_MEMORY_USERPTR`` - - 2 - - The buffer is used for :ref:`user pointer ` I/O. - * - ``V4L2_MEMORY_OVERLAY`` - - 3 - - [to do] - * - ``V4L2_MEMORY_DMABUF`` - - 4 - - The buffer is used for :ref:`DMA shared buffer ` I/O. - - - -Timecodes -========= - -The :c:type:`v4l2_buffer_timecode` structure is designed to hold a -:ref:`smpte12m` or similar timecode. -(struct :c:type:`timeval` timestamps are stored in the struct -:c:type:`v4l2_buffer` ``timestamp`` field.) - - -.. c:type:: v4l2_timecode - -struct v4l2_timecode --------------------- - -.. tabularcolumns:: |p{1.4cm}|p{2.8cm}|p{12.3cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u32 - - ``type`` - - Frame rate the timecodes are based on, see :ref:`timecode-type`. - * - __u32 - - ``flags`` - - Timecode flags, see :ref:`timecode-flags`. - * - __u8 - - ``frames`` - - Frame count, 0 ... 23/24/29/49/59, depending on the type of - timecode. - * - __u8 - - ``seconds`` - - Seconds count, 0 ... 59. This is a binary, not BCD number. - * - __u8 - - ``minutes`` - - Minutes count, 0 ... 59. This is a binary, not BCD number. - * - __u8 - - ``hours`` - - Hours count, 0 ... 29. This is a binary, not BCD number. - * - __u8 - - ``userbits``\ [4] - - The "user group" bits from the timecode. - - - -.. _timecode-type: - -Timecode Types --------------- - -.. tabularcolumns:: |p{5.6cm}|p{0.8cm}|p{11.1cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 4 - - * - ``V4L2_TC_TYPE_24FPS`` - - 1 - - 24 frames per second, i. e. film. - * - ``V4L2_TC_TYPE_25FPS`` - - 2 - - 25 frames per second, i. e. PAL or SECAM video. - * - ``V4L2_TC_TYPE_30FPS`` - - 3 - - 30 frames per second, i. e. NTSC video. - * - ``V4L2_TC_TYPE_50FPS`` - - 4 - - - * - ``V4L2_TC_TYPE_60FPS`` - - 5 - - - - - -.. _timecode-flags: - -Timecode Flags --------------- - -.. tabularcolumns:: |p{6.6cm}|p{1.4cm}|p{9.5cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 4 - - * - ``V4L2_TC_FLAG_DROPFRAME`` - - 0x0001 - - Indicates "drop frame" semantics for counting frames in 29.97 fps - material. When set, frame numbers 0 and 1 at the start of each - minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the - count. - * - ``V4L2_TC_FLAG_COLORFRAME`` - - 0x0002 - - The "color frame" flag. - * - ``V4L2_TC_USERBITS_field`` - - 0x000C - - Field mask for the "binary group flags". - * - ``V4L2_TC_USERBITS_USERDEFINED`` - - 0x0000 - - Unspecified format. - * - ``V4L2_TC_USERBITS_8BITCHARS`` - - 0x0008 - - 8-bit ISO characters. diff --git a/Documentation/media/uapi/v4l/capture-example.rst b/Documentation/media/uapi/v4l/capture-example.rst deleted file mode 100644 index 130ca47ef796..000000000000 --- a/Documentation/media/uapi/v4l/capture-example.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _capture-example: - -********************* -Video Capture Example -********************* - - -.. toctree:: - :maxdepth: 1 - - capture.c diff --git a/Documentation/media/uapi/v4l/capture.c.rst b/Documentation/media/uapi/v4l/capture.c.rst deleted file mode 100644 index b4652c2351f2..000000000000 --- a/Documentation/media/uapi/v4l/capture.c.rst +++ /dev/null @@ -1,671 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -file: media/v4l/capture.c -========================= - -.. code-block:: c - - /* - * V4L2 video capture example - * - * This program can be used and distributed without restrictions. - * - * This program is provided with the V4L2 API - * see https://linuxtv.org/docs.php for more information - */ - - #include - #include - #include - #include - - #include /* getopt_long() */ - - #include /* low-level i/o */ - #include - #include - #include - #include - #include - #include - #include - - #include - - #define CLEAR(x) memset(&(x), 0, sizeof(x)) - - enum io_method { - IO_METHOD_READ, - IO_METHOD_MMAP, - IO_METHOD_USERPTR, - }; - - struct buffer { - void *start; - size_t length; - }; - - static char *dev_name; - static enum io_method io = IO_METHOD_MMAP; - static int fd = -1; - struct buffer *buffers; - static unsigned int n_buffers; - static int out_buf; - static int force_format; - static int frame_count = 70; - - static void errno_exit(const char *s) - { - fprintf(stderr, "%s error %d, %s\\n", s, errno, strerror(errno)); - exit(EXIT_FAILURE); - } - - static int xioctl(int fh, int request, void *arg) - { - int r; - - do { - r = ioctl(fh, request, arg); - } while (-1 == r && EINTR == errno); - - return r; - } - - static void process_image(const void *p, int size) - { - if (out_buf) - fwrite(p, size, 1, stdout); - - fflush(stderr); - fprintf(stderr, "."); - fflush(stdout); - } - - static int read_frame(void) - { - struct v4l2_buffer buf; - unsigned int i; - - switch (io) { - case IO_METHOD_READ: - if (-1 == read(fd, buffers[0].start, buffers[0].length)) { - switch (errno) { - case EAGAIN: - return 0; - - case EIO: - /* Could ignore EIO, see spec. */ - - /* fall through */ - - default: - errno_exit("read"); - } - } - - process_image(buffers[0].start, buffers[0].length); - break; - - case IO_METHOD_MMAP: - CLEAR(buf); - - buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - buf.memory = V4L2_MEMORY_MMAP; - - if (-1 == xioctl(fd, VIDIOC_DQBUF, &buf)) { - switch (errno) { - case EAGAIN: - return 0; - - case EIO: - /* Could ignore EIO, see spec. */ - - /* fall through */ - - default: - errno_exit("VIDIOC_DQBUF"); - } - } - - assert(buf.index < n_buffers); - - process_image(buffers[buf.index].start, buf.bytesused); - - if (-1 == xioctl(fd, VIDIOC_QBUF, &buf)) - errno_exit("VIDIOC_QBUF"); - break; - - case IO_METHOD_USERPTR: - CLEAR(buf); - - buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - buf.memory = V4L2_MEMORY_USERPTR; - - if (-1 == xioctl(fd, VIDIOC_DQBUF, &buf)) { - switch (errno) { - case EAGAIN: - return 0; - - case EIO: - /* Could ignore EIO, see spec. */ - - /* fall through */ - - default: - errno_exit("VIDIOC_DQBUF"); - } - } - - for (i = 0; i < n_buffers; ++i) - if (buf.m.userptr == (unsigned long)buffers[i].start - && buf.length == buffers[i].length) - break; - - assert(i < n_buffers); - - process_image((void *)buf.m.userptr, buf.bytesused); - - if (-1 == xioctl(fd, VIDIOC_QBUF, &buf)) - errno_exit("VIDIOC_QBUF"); - break; - } - - return 1; - } - - static void mainloop(void) - { - unsigned int count; - - count = frame_count; - - while (count-- > 0) { - for (;;) { - fd_set fds; - struct timeval tv; - int r; - - FD_ZERO(&fds); - FD_SET(fd, &fds); - - /* Timeout. */ - tv.tv_sec = 2; - tv.tv_usec = 0; - - r = select(fd + 1, &fds, NULL, NULL, &tv); - - if (-1 == r) { - if (EINTR == errno) - continue; - errno_exit("select"); - } - - if (0 == r) { - fprintf(stderr, "select timeout\\n"); - exit(EXIT_FAILURE); - } - - if (read_frame()) - break; - /* EAGAIN - continue select loop. */ - } - } - } - - static void stop_capturing(void) - { - enum v4l2_buf_type type; - - switch (io) { - case IO_METHOD_READ: - /* Nothing to do. */ - break; - - case IO_METHOD_MMAP: - case IO_METHOD_USERPTR: - type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - if (-1 == xioctl(fd, VIDIOC_STREAMOFF, &type)) - errno_exit("VIDIOC_STREAMOFF"); - break; - } - } - - static void start_capturing(void) - { - unsigned int i; - enum v4l2_buf_type type; - - switch (io) { - case IO_METHOD_READ: - /* Nothing to do. */ - break; - - case IO_METHOD_MMAP: - for (i = 0; i < n_buffers; ++i) { - struct v4l2_buffer buf; - - CLEAR(buf); - buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - buf.memory = V4L2_MEMORY_MMAP; - buf.index = i; - - if (-1 == xioctl(fd, VIDIOC_QBUF, &buf)) - errno_exit("VIDIOC_QBUF"); - } - type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - if (-1 == xioctl(fd, VIDIOC_STREAMON, &type)) - errno_exit("VIDIOC_STREAMON"); - break; - - case IO_METHOD_USERPTR: - for (i = 0; i < n_buffers; ++i) { - struct v4l2_buffer buf; - - CLEAR(buf); - buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - buf.memory = V4L2_MEMORY_USERPTR; - buf.index = i; - buf.m.userptr = (unsigned long)buffers[i].start; - buf.length = buffers[i].length; - - if (-1 == xioctl(fd, VIDIOC_QBUF, &buf)) - errno_exit("VIDIOC_QBUF"); - } - type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - if (-1 == xioctl(fd, VIDIOC_STREAMON, &type)) - errno_exit("VIDIOC_STREAMON"); - break; - } - } - - static void uninit_device(void) - { - unsigned int i; - - switch (io) { - case IO_METHOD_READ: - free(buffers[0].start); - break; - - case IO_METHOD_MMAP: - for (i = 0; i < n_buffers; ++i) - if (-1 == munmap(buffers[i].start, buffers[i].length)) - errno_exit("munmap"); - break; - - case IO_METHOD_USERPTR: - for (i = 0; i < n_buffers; ++i) - free(buffers[i].start); - break; - } - - free(buffers); - } - - static void init_read(unsigned int buffer_size) - { - buffers = calloc(1, sizeof(*buffers)); - - if (!buffers) { - fprintf(stderr, "Out of memory\\n"); - exit(EXIT_FAILURE); - } - - buffers[0].length = buffer_size; - buffers[0].start = malloc(buffer_size); - - if (!buffers[0].start) { - fprintf(stderr, "Out of memory\\n"); - exit(EXIT_FAILURE); - } - } - - static void init_mmap(void) - { - struct v4l2_requestbuffers req; - - CLEAR(req); - - req.count = 4; - req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - req.memory = V4L2_MEMORY_MMAP; - - if (-1 == xioctl(fd, VIDIOC_REQBUFS, &req)) { - if (EINVAL == errno) { - fprintf(stderr, "%s does not support " - "memory mappingn", dev_name); - exit(EXIT_FAILURE); - } else { - errno_exit("VIDIOC_REQBUFS"); - } - } - - if (req.count < 2) { - fprintf(stderr, "Insufficient buffer memory on %s\\n", - dev_name); - exit(EXIT_FAILURE); - } - - buffers = calloc(req.count, sizeof(*buffers)); - - if (!buffers) { - fprintf(stderr, "Out of memory\\n"); - exit(EXIT_FAILURE); - } - - for (n_buffers = 0; n_buffers < req.count; ++n_buffers) { - struct v4l2_buffer buf; - - CLEAR(buf); - - buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - buf.memory = V4L2_MEMORY_MMAP; - buf.index = n_buffers; - - if (-1 == xioctl(fd, VIDIOC_QUERYBUF, &buf)) - errno_exit("VIDIOC_QUERYBUF"); - - buffers[n_buffers].length = buf.length; - buffers[n_buffers].start = - mmap(NULL /* start anywhere */, - buf.length, - PROT_READ | PROT_WRITE /* required */, - MAP_SHARED /* recommended */, - fd, buf.m.offset); - - if (MAP_FAILED == buffers[n_buffers].start) - errno_exit("mmap"); - } - } - - static void init_userp(unsigned int buffer_size) - { - struct v4l2_requestbuffers req; - - CLEAR(req); - - req.count = 4; - req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - req.memory = V4L2_MEMORY_USERPTR; - - if (-1 == xioctl(fd, VIDIOC_REQBUFS, &req)) { - if (EINVAL == errno) { - fprintf(stderr, "%s does not support " - "user pointer i/on", dev_name); - exit(EXIT_FAILURE); - } else { - errno_exit("VIDIOC_REQBUFS"); - } - } - - buffers = calloc(4, sizeof(*buffers)); - - if (!buffers) { - fprintf(stderr, "Out of memory\\n"); - exit(EXIT_FAILURE); - } - - for (n_buffers = 0; n_buffers < 4; ++n_buffers) { - buffers[n_buffers].length = buffer_size; - buffers[n_buffers].start = malloc(buffer_size); - - if (!buffers[n_buffers].start) { - fprintf(stderr, "Out of memory\\n"); - exit(EXIT_FAILURE); - } - } - } - - static void init_device(void) - { - struct v4l2_capability cap; - struct v4l2_cropcap cropcap; - struct v4l2_crop crop; - struct v4l2_format fmt; - unsigned int min; - - if (-1 == xioctl(fd, VIDIOC_QUERYCAP, &cap)) { - if (EINVAL == errno) { - fprintf(stderr, "%s is no V4L2 device\\n", - dev_name); - exit(EXIT_FAILURE); - } else { - errno_exit("VIDIOC_QUERYCAP"); - } - } - - if (!(cap.capabilities & V4L2_CAP_VIDEO_CAPTURE)) { - fprintf(stderr, "%s is no video capture device\\n", - dev_name); - exit(EXIT_FAILURE); - } - - switch (io) { - case IO_METHOD_READ: - if (!(cap.capabilities & V4L2_CAP_READWRITE)) { - fprintf(stderr, "%s does not support read i/o\\n", - dev_name); - exit(EXIT_FAILURE); - } - break; - - case IO_METHOD_MMAP: - case IO_METHOD_USERPTR: - if (!(cap.capabilities & V4L2_CAP_STREAMING)) { - fprintf(stderr, "%s does not support streaming i/o\\n", - dev_name); - exit(EXIT_FAILURE); - } - break; - } - - - /* Select video input, video standard and tune here. */ - - - CLEAR(cropcap); - - cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - - if (0 == xioctl(fd, VIDIOC_CROPCAP, &cropcap)) { - crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - crop.c = cropcap.defrect; /* reset to default */ - - if (-1 == xioctl(fd, VIDIOC_S_CROP, &crop)) { - switch (errno) { - case EINVAL: - /* Cropping not supported. */ - break; - default: - /* Errors ignored. */ - break; - } - } - } else { - /* Errors ignored. */ - } - - - CLEAR(fmt); - - fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - if (force_format) { - fmt.fmt.pix.width = 640; - fmt.fmt.pix.height = 480; - fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV; - fmt.fmt.pix.field = V4L2_FIELD_INTERLACED; - - if (-1 == xioctl(fd, VIDIOC_S_FMT, &fmt)) - errno_exit("VIDIOC_S_FMT"); - - /* Note VIDIOC_S_FMT may change width and height. */ - } else { - /* Preserve original settings as set by v4l2-ctl for example */ - if (-1 == xioctl(fd, VIDIOC_G_FMT, &fmt)) - errno_exit("VIDIOC_G_FMT"); - } - - /* Buggy driver paranoia. */ - min = fmt.fmt.pix.width * 2; - if (fmt.fmt.pix.bytesperline < min) - fmt.fmt.pix.bytesperline = min; - min = fmt.fmt.pix.bytesperline * fmt.fmt.pix.height; - if (fmt.fmt.pix.sizeimage < min) - fmt.fmt.pix.sizeimage = min; - - switch (io) { - case IO_METHOD_READ: - init_read(fmt.fmt.pix.sizeimage); - break; - - case IO_METHOD_MMAP: - init_mmap(); - break; - - case IO_METHOD_USERPTR: - init_userp(fmt.fmt.pix.sizeimage); - break; - } - } - - static void close_device(void) - { - if (-1 == close(fd)) - errno_exit("close"); - - fd = -1; - } - - static void open_device(void) - { - struct stat st; - - if (-1 == stat(dev_name, &st)) { - fprintf(stderr, "Cannot identify '%s': %d, %s\\n", - dev_name, errno, strerror(errno)); - exit(EXIT_FAILURE); - } - - if (!S_ISCHR(st.st_mode)) { - fprintf(stderr, "%s is no devicen", dev_name); - exit(EXIT_FAILURE); - } - - fd = open(dev_name, O_RDWR /* required */ | O_NONBLOCK, 0); - - if (-1 == fd) { - fprintf(stderr, "Cannot open '%s': %d, %s\\n", - dev_name, errno, strerror(errno)); - exit(EXIT_FAILURE); - } - } - - static void usage(FILE *fp, int argc, char **argv) - { - fprintf(fp, - "Usage: %s [options]\\n\\n" - "Version 1.3\\n" - "Options:\\n" - "-d | --device name Video device name [%s]n" - "-h | --help Print this messagen" - "-m | --mmap Use memory mapped buffers [default]n" - "-r | --read Use read() callsn" - "-u | --userp Use application allocated buffersn" - "-o | --output Outputs stream to stdoutn" - "-f | --format Force format to 640x480 YUYVn" - "-c | --count Number of frames to grab [%i]n" - "", - argv[0], dev_name, frame_count); - } - - static const char short_options[] = "d:hmruofc:"; - - static const struct option - long_options[] = { - { "device", required_argument, NULL, 'd' }, - { "help", no_argument, NULL, 'h' }, - { "mmap", no_argument, NULL, 'm' }, - { "read", no_argument, NULL, 'r' }, - { "userp", no_argument, NULL, 'u' }, - { "output", no_argument, NULL, 'o' }, - { "format", no_argument, NULL, 'f' }, - { "count", required_argument, NULL, 'c' }, - { 0, 0, 0, 0 } - }; - - int main(int argc, char **argv) - { - dev_name = "/dev/video0"; - - for (;;) { - int idx; - int c; - - c = getopt_long(argc, argv, - short_options, long_options, &idx); - - if (-1 == c) - break; - - switch (c) { - case 0: /* getopt_long() flag */ - break; - - case 'd': - dev_name = optarg; - break; - - case 'h': - usage(stdout, argc, argv); - exit(EXIT_SUCCESS); - - case 'm': - io = IO_METHOD_MMAP; - break; - - case 'r': - io = IO_METHOD_READ; - break; - - case 'u': - io = IO_METHOD_USERPTR; - break; - - case 'o': - out_buf++; - break; - - case 'f': - force_format++; - break; - - case 'c': - errno = 0; - frame_count = strtol(optarg, NULL, 0); - if (errno) - errno_exit(optarg); - break; - - default: - usage(stderr, argc, argv); - exit(EXIT_FAILURE); - } - } - - open_device(); - init_device(); - start_capturing(); - mainloop(); - stop_capturing(); - uninit_device(); - close_device(); - fprintf(stderr, "\\n"); - return 0; - } diff --git a/Documentation/media/uapi/v4l/colorspaces-defs.rst b/Documentation/media/uapi/v4l/colorspaces-defs.rst deleted file mode 100644 index e122bbe3d799..000000000000 --- a/Documentation/media/uapi/v4l/colorspaces-defs.rst +++ /dev/null @@ -1,183 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -**************************** -Defining Colorspaces in V4L2 -**************************** - -In V4L2 colorspaces are defined by four values. The first is the -colorspace identifier (enum :c:type:`v4l2_colorspace`) -which defines the chromaticities, the default transfer function, the -default Y'CbCr encoding and the default quantization method. The second -is the transfer function identifier (enum -:c:type:`v4l2_xfer_func`) to specify non-standard -transfer functions. The third is the Y'CbCr encoding identifier (enum -:c:type:`v4l2_ycbcr_encoding`) to specify -non-standard Y'CbCr encodings and the fourth is the quantization -identifier (enum :c:type:`v4l2_quantization`) to -specify non-standard quantization methods. Most of the time only the -colorspace field of struct :c:type:`v4l2_pix_format` -or struct :c:type:`v4l2_pix_format_mplane` -needs to be filled in. - -.. _hsv-colorspace: - -On :ref:`HSV formats ` the *Hue* is defined as the angle on -the cylindrical color representation. Usually this angle is measured in -degrees, i.e. 0-360. When we map this angle value into 8 bits, there are -two basic ways to do it: Divide the angular value by 2 (0-179), or use the -whole range, 0-255, dividing the angular value by 1.41. The enum -:c:type:`v4l2_hsv_encoding` specifies which encoding is used. - -.. note:: The default R'G'B' quantization is full range for all - colorspaces except for BT.2020 which uses limited range R'G'B' - quantization. - -.. tabularcolumns:: |p{6.7cm}|p{10.8cm}| - -.. c:type:: v4l2_colorspace - -.. flat-table:: V4L2 Colorspaces - :header-rows: 1 - :stub-columns: 0 - - * - Identifier - - Details - * - ``V4L2_COLORSPACE_DEFAULT`` - - The default colorspace. This can be used by applications to let - the driver fill in the colorspace. - * - ``V4L2_COLORSPACE_SMPTE170M`` - - See :ref:`col-smpte-170m`. - * - ``V4L2_COLORSPACE_REC709`` - - See :ref:`col-rec709`. - * - ``V4L2_COLORSPACE_SRGB`` - - See :ref:`col-srgb`. - * - ``V4L2_COLORSPACE_OPRGB`` - - See :ref:`col-oprgb`. - * - ``V4L2_COLORSPACE_BT2020`` - - See :ref:`col-bt2020`. - * - ``V4L2_COLORSPACE_DCI_P3`` - - See :ref:`col-dcip3`. - * - ``V4L2_COLORSPACE_SMPTE240M`` - - See :ref:`col-smpte-240m`. - * - ``V4L2_COLORSPACE_470_SYSTEM_M`` - - See :ref:`col-sysm`. - * - ``V4L2_COLORSPACE_470_SYSTEM_BG`` - - See :ref:`col-sysbg`. - * - ``V4L2_COLORSPACE_JPEG`` - - See :ref:`col-jpeg`. - * - ``V4L2_COLORSPACE_RAW`` - - The raw colorspace. This is used for raw image capture where the - image is minimally processed and is using the internal colorspace - of the device. The software that processes an image using this - 'colorspace' will have to know the internals of the capture - device. - - - -.. c:type:: v4l2_xfer_func - -.. tabularcolumns:: |p{5.5cm}|p{12.0cm}| - -.. flat-table:: V4L2 Transfer Function - :header-rows: 1 - :stub-columns: 0 - - * - Identifier - - Details - * - ``V4L2_XFER_FUNC_DEFAULT`` - - Use the default transfer function as defined by the colorspace. - * - ``V4L2_XFER_FUNC_709`` - - Use the Rec. 709 transfer function. - * - ``V4L2_XFER_FUNC_SRGB`` - - Use the sRGB transfer function. - * - ``V4L2_XFER_FUNC_OPRGB`` - - Use the opRGB transfer function. - * - ``V4L2_XFER_FUNC_SMPTE240M`` - - Use the SMPTE 240M transfer function. - * - ``V4L2_XFER_FUNC_NONE`` - - Do not use a transfer function (i.e. use linear RGB values). - * - ``V4L2_XFER_FUNC_DCI_P3`` - - Use the DCI-P3 transfer function. - * - ``V4L2_XFER_FUNC_SMPTE2084`` - - Use the SMPTE 2084 transfer function. See :ref:`xf-smpte-2084`. - - - -.. c:type:: v4l2_ycbcr_encoding - -.. tabularcolumns:: |p{7.2cm}|p{10.3cm}| - -.. flat-table:: V4L2 Y'CbCr Encodings - :header-rows: 1 - :stub-columns: 0 - - * - Identifier - - Details - * - ``V4L2_YCBCR_ENC_DEFAULT`` - - Use the default Y'CbCr encoding as defined by the colorspace. - * - ``V4L2_YCBCR_ENC_601`` - - Use the BT.601 Y'CbCr encoding. - * - ``V4L2_YCBCR_ENC_709`` - - Use the Rec. 709 Y'CbCr encoding. - * - ``V4L2_YCBCR_ENC_XV601`` - - Use the extended gamut xvYCC BT.601 encoding. - * - ``V4L2_YCBCR_ENC_XV709`` - - Use the extended gamut xvYCC Rec. 709 encoding. - * - ``V4L2_YCBCR_ENC_BT2020`` - - Use the default non-constant luminance BT.2020 Y'CbCr encoding. - * - ``V4L2_YCBCR_ENC_BT2020_CONST_LUM`` - - Use the constant luminance BT.2020 Yc'CbcCrc encoding. - * - ``V4L2_YCBCR_ENC_SMPTE_240M`` - - Use the SMPTE 240M Y'CbCr encoding. - - - -.. c:type:: v4l2_hsv_encoding - -.. tabularcolumns:: |p{6.5cm}|p{11.0cm}| - -.. flat-table:: V4L2 HSV Encodings - :header-rows: 1 - :stub-columns: 0 - - * - Identifier - - Details - * - ``V4L2_HSV_ENC_180`` - - For the Hue, each LSB is two degrees. - * - ``V4L2_HSV_ENC_256`` - - For the Hue, the 360 degrees are mapped into 8 bits, i.e. each - LSB is roughly 1.41 degrees. - - - -.. c:type:: v4l2_quantization - -.. tabularcolumns:: |p{6.5cm}|p{11.0cm}| - -.. flat-table:: V4L2 Quantization Methods - :header-rows: 1 - :stub-columns: 0 - - * - Identifier - - Details - * - ``V4L2_QUANTIZATION_DEFAULT`` - - Use the default quantization encoding as defined by the - colorspace. This is always full range for R'G'B' (except for the - BT.2020 colorspace) and HSV. It is usually limited range for Y'CbCr. - * - ``V4L2_QUANTIZATION_FULL_RANGE`` - - Use the full range quantization encoding. I.e. the range [0…1] is - mapped to [0…255] (with possible clipping to [1…254] to avoid the - 0x00 and 0xff values). Cb and Cr are mapped from [-0.5…0.5] to - [0…255] (with possible clipping to [1…254] to avoid the 0x00 and - 0xff values). - * - ``V4L2_QUANTIZATION_LIM_RANGE`` - - Use the limited range quantization encoding. I.e. the range [0…1] - is mapped to [16…235]. Cb and Cr are mapped from [-0.5…0.5] to - [16…240]. diff --git a/Documentation/media/uapi/v4l/colorspaces-details.rst b/Documentation/media/uapi/v4l/colorspaces-details.rst deleted file mode 100644 index 8b0ba3668101..000000000000 --- a/Documentation/media/uapi/v4l/colorspaces-details.rst +++ /dev/null @@ -1,813 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -******************************** -Detailed Colorspace Descriptions -******************************** - - -.. _col-smpte-170m: - -Colorspace SMPTE 170M (V4L2_COLORSPACE_SMPTE170M) -================================================= - -The :ref:`smpte170m` standard defines the colorspace used by NTSC and -PAL and by SDTV in general. The default transfer function is -``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is -``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited -range. The chromaticities of the primary colors and the white reference -are: - - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. flat-table:: SMPTE 170M Chromaticities - :header-rows: 1 - :stub-columns: 0 - :widths: 1 1 2 - - * - Color - - x - - y - * - Red - - 0.630 - - 0.340 - * - Green - - 0.310 - - 0.595 - * - Blue - - 0.155 - - 0.070 - * - White Reference (D65) - - 0.3127 - - 0.3290 - - -The red, green and blue chromaticities are also often referred to as the -SMPTE C set, so this colorspace is sometimes called SMPTE C as well. - -The transfer function defined for SMPTE 170M is the same as the one -defined in Rec. 709. - -.. math:: - - L' = -1.099(-L)^{0.45} + 0.099 \text{, for } L \le-0.018 - - L' = 4.5L \text{, for } -0.018 < L < 0.018 - - L' = 1.099L^{0.45} - 0.099 \text{, for } L \ge 0.018 - -Inverse Transfer function: - -.. math:: - - L = -\left( \frac{L' - 0.099}{-1.099} \right) ^{\frac{1}{0.45}} \text{, for } L' \le -0.081 - - L = \frac{L'}{4.5} \text{, for } -0.081 < L' < 0.081 - - L = \left(\frac{L' + 0.099}{1.099}\right)^{\frac{1}{0.45} } \text{, for } L' \ge 0.081 - -The luminance (Y') and color difference (Cb and Cr) are obtained with -the following ``V4L2_YCBCR_ENC_601`` encoding: - -.. math:: - - Y' = 0.2990R' + 0.5870G' + 0.1140B' - - Cb = -0.1687R' - 0.3313G' + 0.5B' - - Cr = 0.5R' - 0.4187G' - 0.0813B' - -Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range -[-0.5…0.5]. This conversion to Y'CbCr is identical to the one defined in -the :ref:`itu601` standard and this colorspace is sometimes called -BT.601 as well, even though BT.601 does not mention any color primaries. - -The default quantization is limited range, but full range is possible -although rarely seen. - - -.. _col-rec709: - -Colorspace Rec. 709 (V4L2_COLORSPACE_REC709) -============================================ - -The :ref:`itu709` standard defines the colorspace used by HDTV in -general. The default transfer function is ``V4L2_XFER_FUNC_709``. The -default Y'CbCr encoding is ``V4L2_YCBCR_ENC_709``. The default Y'CbCr -quantization is limited range. The chromaticities of the primary colors -and the white reference are: - - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. flat-table:: Rec. 709 Chromaticities - :header-rows: 1 - :stub-columns: 0 - :widths: 1 1 2 - - * - Color - - x - - y - * - Red - - 0.640 - - 0.330 - * - Green - - 0.300 - - 0.600 - * - Blue - - 0.150 - - 0.060 - * - White Reference (D65) - - 0.3127 - - 0.3290 - - -The full name of this standard is Rec. ITU-R BT.709-5. - -Transfer function. Normally L is in the range [0…1], but for the -extended gamut xvYCC encoding values outside that range are allowed. - -.. math:: - - L' = -1.099(-L)^{0.45} + 0.099 \text{, for } L \le -0.018 - - L' = 4.5L \text{, for } -0.018 < L < 0.018 - - L' = 1.099L^{0.45} - 0.099 \text{, for } L \ge 0.018 - -Inverse Transfer function: - -.. math:: - - L = -\left( \frac{L' - 0.099}{-1.099} \right)^\frac{1}{0.45} \text{, for } L' \le -0.081 - - L = \frac{L'}{4.5}\text{, for } -0.081 < L' < 0.081 - - L = \left(\frac{L' + 0.099}{1.099}\right)^{\frac{1}{0.45} } \text{, for } L' \ge 0.081 - -The luminance (Y') and color difference (Cb and Cr) are obtained with -the following ``V4L2_YCBCR_ENC_709`` encoding: - -.. math:: - - Y' = 0.2126R' + 0.7152G' + 0.0722B' - - Cb = -0.1146R' - 0.3854G' + 0.5B' - - Cr = 0.5R' - 0.4542G' - 0.0458B' - -Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range -[-0.5…0.5]. - -The default quantization is limited range, but full range is possible -although rarely seen. - -The ``V4L2_YCBCR_ENC_709`` encoding described above is the default for -this colorspace, but it can be overridden with ``V4L2_YCBCR_ENC_601``, -in which case the BT.601 Y'CbCr encoding is used. - -Two additional extended gamut Y'CbCr encodings are also possible with -this colorspace: - -The xvYCC 709 encoding (``V4L2_YCBCR_ENC_XV709``, :ref:`xvycc`) is -similar to the Rec. 709 encoding, but it allows for R', G' and B' values -that are outside the range [0…1]. The resulting Y', Cb and Cr values are -scaled and offset according to the limited range formula: - -.. math:: - - Y' = \frac{219}{256} * (0.2126R' + 0.7152G' + 0.0722B') + \frac{16}{256} - - Cb = \frac{224}{256} * (-0.1146R' - 0.3854G' + 0.5B') - - Cr = \frac{224}{256} * (0.5R' - 0.4542G' - 0.0458B') - -The xvYCC 601 encoding (``V4L2_YCBCR_ENC_XV601``, :ref:`xvycc`) is -similar to the BT.601 encoding, but it allows for R', G' and B' values -that are outside the range [0…1]. The resulting Y', Cb and Cr values are -scaled and offset according to the limited range formula: - -.. math:: - - Y' = \frac{219}{256} * (0.2990R' + 0.5870G' + 0.1140B') + \frac{16}{256} - - Cb = \frac{224}{256} * (-0.1687R' - 0.3313G' + 0.5B') - - Cr = \frac{224}{256} * (0.5R' - 0.4187G' - 0.0813B') - -Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range -[-0.5…0.5] and quantized without further scaling or offsets. -The non-standard xvYCC 709 or xvYCC 601 encodings can be -used by selecting ``V4L2_YCBCR_ENC_XV709`` or ``V4L2_YCBCR_ENC_XV601``. -As seen by the xvYCC formulas these encodings always use limited range quantization, -there is no full range variant. The whole point of these extended gamut encodings -is that values outside the limited range are still valid, although they -map to R', G' and B' values outside the [0…1] range and are therefore outside -the Rec. 709 colorspace gamut. - - -.. _col-srgb: - -Colorspace sRGB (V4L2_COLORSPACE_SRGB) -====================================== - -The :ref:`srgb` standard defines the colorspace used by most webcams -and computer graphics. The default transfer function is -``V4L2_XFER_FUNC_SRGB``. The default Y'CbCr encoding is -``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited range. - -Note that the :ref:`sycc` standard specifies full range quantization, -however all current capture hardware supported by the kernel convert -R'G'B' to limited range Y'CbCr. So choosing full range as the default -would break how applications interpret the quantization range. - -The chromaticities of the primary colors and the white reference are: - - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. flat-table:: sRGB Chromaticities - :header-rows: 1 - :stub-columns: 0 - :widths: 1 1 2 - - * - Color - - x - - y - * - Red - - 0.640 - - 0.330 - * - Green - - 0.300 - - 0.600 - * - Blue - - 0.150 - - 0.060 - * - White Reference (D65) - - 0.3127 - - 0.3290 - - -These chromaticities are identical to the Rec. 709 colorspace. - -Transfer function. Note that negative values for L are only used by the -Y'CbCr conversion. - -.. math:: - - L' = -1.055(-L)^{\frac{1}{2.4} } + 0.055\text{, for }L < -0.0031308 - - L' = 12.92L\text{, for }-0.0031308 \le L \le 0.0031308 - - L' = 1.055L ^{\frac{1}{2.4} } - 0.055\text{, for }0.0031308 < L \le 1 - -Inverse Transfer function: - -.. math:: - - L = -((-L' + 0.055) / 1.055) ^{2.4}\text{, for }L' < -0.04045 - - L = L' / 12.92\text{, for }-0.04045 \le L' \le 0.04045 - - L = ((L' + 0.055) / 1.055) ^{2.4}\text{, for }L' > 0.04045 - -The luminance (Y') and color difference (Cb and Cr) are obtained with -the following ``V4L2_YCBCR_ENC_601`` encoding as defined by :ref:`sycc`: - -.. math:: - - Y' = 0.2990R' + 0.5870G' + 0.1140B' - - Cb = -0.1687R' - 0.3313G' + 0.5B' - - Cr = 0.5R' - 0.4187G' - 0.0813B' - -Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range -[-0.5…0.5]. This transform is identical to one defined in SMPTE -170M/BT.601. The Y'CbCr quantization is limited range. - - -.. _col-oprgb: - -Colorspace opRGB (V4L2_COLORSPACE_OPRGB) -=============================================== - -The :ref:`oprgb` standard defines the colorspace used by computer -graphics that use the opRGB colorspace. The default transfer function is -``V4L2_XFER_FUNC_OPRGB``. The default Y'CbCr encoding is -``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited -range. - -Note that the :ref:`oprgb` standard specifies full range quantization, -however all current capture hardware supported by the kernel convert -R'G'B' to limited range Y'CbCr. So choosing full range as the default -would break how applications interpret the quantization range. - -The chromaticities of the primary colors and the white reference are: - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. flat-table:: opRGB Chromaticities - :header-rows: 1 - :stub-columns: 0 - :widths: 1 1 2 - - * - Color - - x - - y - * - Red - - 0.6400 - - 0.3300 - * - Green - - 0.2100 - - 0.7100 - * - Blue - - 0.1500 - - 0.0600 - * - White Reference (D65) - - 0.3127 - - 0.3290 - - - -Transfer function: - -.. math:: - - L' = L ^{\frac{1}{2.19921875}} - -Inverse Transfer function: - -.. math:: - - L = L'^{(2.19921875)} - -The luminance (Y') and color difference (Cb and Cr) are obtained with -the following ``V4L2_YCBCR_ENC_601`` encoding: - -.. math:: - - Y' = 0.2990R' + 0.5870G' + 0.1140B' - - Cb = -0.1687R' - 0.3313G' + 0.5B' - - Cr = 0.5R' - 0.4187G' - 0.0813B' - -Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range -[-0.5…0.5]. This transform is identical to one defined in SMPTE -170M/BT.601. The Y'CbCr quantization is limited range. - - -.. _col-bt2020: - -Colorspace BT.2020 (V4L2_COLORSPACE_BT2020) -=========================================== - -The :ref:`itu2020` standard defines the colorspace used by Ultra-high -definition television (UHDTV). The default transfer function is -``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is -``V4L2_YCBCR_ENC_BT2020``. The default R'G'B' quantization is limited -range (!), and so is the default Y'CbCr quantization. The chromaticities -of the primary colors and the white reference are: - - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. flat-table:: BT.2020 Chromaticities - :header-rows: 1 - :stub-columns: 0 - :widths: 1 1 2 - - * - Color - - x - - y - * - Red - - 0.708 - - 0.292 - * - Green - - 0.170 - - 0.797 - * - Blue - - 0.131 - - 0.046 - * - White Reference (D65) - - 0.3127 - - 0.3290 - - - -Transfer function (same as Rec. 709): - -.. math:: - - L' = 4.5L\text{, for }0 \le L < 0.018 - - L' = 1.099L ^{0.45} - 0.099\text{, for } 0.018 \le L \le 1 - -Inverse Transfer function: - -.. math:: - - L = L' / 4.5\text{, for } L' < 0.081 - - L = \left( \frac{L' + 0.099}{1.099}\right) ^{\frac{1}{0.45} }\text{, for } L' \ge 0.081 - -Please note that while Rec. 709 is defined as the default transfer function -by the :ref:`itu2020` standard, in practice this colorspace is often used -with the :ref:`xf-smpte-2084`. In particular Ultra HD Blu-ray discs use -this combination. - -The luminance (Y') and color difference (Cb and Cr) are obtained with -the following ``V4L2_YCBCR_ENC_BT2020`` encoding: - -.. math:: - - Y' = 0.2627R' + 0.6780G' + 0.0593B' - - Cb = -0.1396R' - 0.3604G' + 0.5B' - - Cr = 0.5R' - 0.4598G' - 0.0402B' - -Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range -[-0.5…0.5]. The Y'CbCr quantization is limited range. - -There is also an alternate constant luminance R'G'B' to Yc'CbcCrc -(``V4L2_YCBCR_ENC_BT2020_CONST_LUM``) encoding: - -Luma: - -.. math:: - :nowrap: - - \begin{align*} - Yc' = (0.2627R + 0.6780G + 0.0593B)'& \\ - B' - Yc' \le 0:& \\ - &Cbc = (B' - Yc') / 1.9404 \\ - B' - Yc' > 0: & \\ - &Cbc = (B' - Yc') / 1.5816 \\ - R' - Yc' \le 0:& \\ - &Crc = (R' - Y') / 1.7184 \\ - R' - Yc' > 0:& \\ - &Crc = (R' - Y') / 0.9936 - \end{align*} - -Yc' is clamped to the range [0…1] and Cbc and Crc are clamped to the -range [-0.5…0.5]. The Yc'CbcCrc quantization is limited range. - - -.. _col-dcip3: - -Colorspace DCI-P3 (V4L2_COLORSPACE_DCI_P3) -========================================== - -The :ref:`smpte431` standard defines the colorspace used by cinema -projectors that use the DCI-P3 colorspace. The default transfer function -is ``V4L2_XFER_FUNC_DCI_P3``. The default Y'CbCr encoding is -``V4L2_YCBCR_ENC_709``. The default Y'CbCr quantization is limited range. - -.. note:: - - Note that this colorspace standard does not specify a - Y'CbCr encoding since it is not meant to be encoded to Y'CbCr. So this - default Y'CbCr encoding was picked because it is the HDTV encoding. - -The chromaticities of the primary colors and the white reference are: - - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. flat-table:: DCI-P3 Chromaticities - :header-rows: 1 - :stub-columns: 0 - :widths: 1 1 2 - - * - Color - - x - - y - * - Red - - 0.6800 - - 0.3200 - * - Green - - 0.2650 - - 0.6900 - * - Blue - - 0.1500 - - 0.0600 - * - White Reference - - 0.3140 - - 0.3510 - - - -Transfer function: - -.. math:: - - L' = L^{\frac{1}{2.6}} - -Inverse Transfer function: - -.. math:: - - L = L'^{(2.6)} - -Y'CbCr encoding is not specified. V4L2 defaults to Rec. 709. - - -.. _col-smpte-240m: - -Colorspace SMPTE 240M (V4L2_COLORSPACE_SMPTE240M) -================================================= - -The :ref:`smpte240m` standard was an interim standard used during the -early days of HDTV (1988-1998). It has been superseded by Rec. 709. The -default transfer function is ``V4L2_XFER_FUNC_SMPTE240M``. The default -Y'CbCr encoding is ``V4L2_YCBCR_ENC_SMPTE240M``. The default Y'CbCr -quantization is limited range. The chromaticities of the primary colors -and the white reference are: - - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. flat-table:: SMPTE 240M Chromaticities - :header-rows: 1 - :stub-columns: 0 - :widths: 1 1 2 - - * - Color - - x - - y - * - Red - - 0.630 - - 0.340 - * - Green - - 0.310 - - 0.595 - * - Blue - - 0.155 - - 0.070 - * - White Reference (D65) - - 0.3127 - - 0.3290 - - -These chromaticities are identical to the SMPTE 170M colorspace. - -Transfer function: - -.. math:: - - L' = 4L\text{, for } 0 \le L < 0.0228 - - L' = 1.1115L ^{0.45} - 0.1115\text{, for } 0.0228 \le L \le 1 - -Inverse Transfer function: - -.. math:: - - L = \frac{L'}{4}\text{, for } 0 \le L' < 0.0913 - - L = \left( \frac{L' + 0.1115}{1.1115}\right) ^{\frac{1}{0.45} }\text{, for } L' \ge 0.0913 - -The luminance (Y') and color difference (Cb and Cr) are obtained with -the following ``V4L2_YCBCR_ENC_SMPTE240M`` encoding: - -.. math:: - - Y' = 0.2122R' + 0.7013G' + 0.0865B' - - Cb = -0.1161R' - 0.3839G' + 0.5B' - - Cr = 0.5R' - 0.4451G' - 0.0549B' - -Y' is clamped to the range [0…1] and Cb and Cr are clamped to the -range [-0.5…0.5]. The Y'CbCr quantization is limited range. - - -.. _col-sysm: - -Colorspace NTSC 1953 (V4L2_COLORSPACE_470_SYSTEM_M) -=================================================== - -This standard defines the colorspace used by NTSC in 1953. In practice -this colorspace is obsolete and SMPTE 170M should be used instead. The -default transfer function is ``V4L2_XFER_FUNC_709``. The default Y'CbCr -encoding is ``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is -limited range. The chromaticities of the primary colors and the white -reference are: - - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. flat-table:: NTSC 1953 Chromaticities - :header-rows: 1 - :stub-columns: 0 - :widths: 1 1 2 - - * - Color - - x - - y - * - Red - - 0.67 - - 0.33 - * - Green - - 0.21 - - 0.71 - * - Blue - - 0.14 - - 0.08 - * - White Reference (C) - - 0.310 - - 0.316 - - -.. note:: - - This colorspace uses Illuminant C instead of D65 as the white - reference. To correctly convert an image in this colorspace to another - that uses D65 you need to apply a chromatic adaptation algorithm such as - the Bradford method. - -The transfer function was never properly defined for NTSC 1953. The Rec. -709 transfer function is recommended in the literature: - -.. math:: - - L' = 4.5L\text{, for } 0 \le L < 0.018 - - L' = 1.099L ^{0.45} - 0.099\text{, for } 0.018 \le L \le 1 - -Inverse Transfer function: - -.. math:: - - L = \frac{L'}{4.5} \text{, for } L' < 0.081 - - L = \left( \frac{L' + 0.099}{1.099}\right) ^{\frac{1}{0.45} }\text{, for } L' \ge 0.081 - -The luminance (Y') and color difference (Cb and Cr) are obtained with -the following ``V4L2_YCBCR_ENC_601`` encoding: - -.. math:: - - Y' = 0.2990R' + 0.5870G' + 0.1140B' - - Cb = -0.1687R' - 0.3313G' + 0.5B' - - Cr = 0.5R' - 0.4187G' - 0.0813B' - -Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range -[-0.5…0.5]. The Y'CbCr quantization is limited range. This transform is -identical to one defined in SMPTE 170M/BT.601. - - -.. _col-sysbg: - -Colorspace EBU Tech. 3213 (V4L2_COLORSPACE_470_SYSTEM_BG) -========================================================= - -The :ref:`tech3213` standard defines the colorspace used by PAL/SECAM -in 1975. In practice this colorspace is obsolete and SMPTE 170M should -be used instead. The default transfer function is -``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is -``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited -range. The chromaticities of the primary colors and the white reference -are: - - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. flat-table:: EBU Tech. 3213 Chromaticities - :header-rows: 1 - :stub-columns: 0 - :widths: 1 1 2 - - * - Color - - x - - y - * - Red - - 0.64 - - 0.33 - * - Green - - 0.29 - - 0.60 - * - Blue - - 0.15 - - 0.06 - * - White Reference (D65) - - 0.3127 - - 0.3290 - - - -The transfer function was never properly defined for this colorspace. -The Rec. 709 transfer function is recommended in the literature: - -.. math:: - - L' = 4.5L\text{, for } 0 \le L < 0.018 - - L' = 1.099L ^{0.45} - 0.099\text{, for } 0.018 \le L \le 1 - -Inverse Transfer function: - -.. math:: - - L = \frac{L'}{4.5} \text{, for } L' < 0.081 - - L = \left(\frac{L' + 0.099}{1.099} \right) ^{\frac{1}{0.45} }\text{, for } L' \ge 0.081 - -The luminance (Y') and color difference (Cb and Cr) are obtained with -the following ``V4L2_YCBCR_ENC_601`` encoding: - -.. math:: - - Y' = 0.2990R' + 0.5870G' + 0.1140B' - - Cb = -0.1687R' - 0.3313G' + 0.5B' - - Cr = 0.5R' - 0.4187G' - 0.0813B' - -Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range -[-0.5…0.5]. The Y'CbCr quantization is limited range. This transform is -identical to one defined in SMPTE 170M/BT.601. - - -.. _col-jpeg: - -Colorspace JPEG (V4L2_COLORSPACE_JPEG) -====================================== - -This colorspace defines the colorspace used by most (Motion-)JPEG -formats. The chromaticities of the primary colors and the white -reference are identical to sRGB. The transfer function use is -``V4L2_XFER_FUNC_SRGB``. The Y'CbCr encoding is ``V4L2_YCBCR_ENC_601`` -with full range quantization where Y' is scaled to [0…255] and Cb/Cr are -scaled to [-128…128] and then clipped to [-128…127]. - -.. note:: - - The JPEG standard does not actually store colorspace - information. So if something other than sRGB is used, then the driver - will have to set that information explicitly. Effectively - ``V4L2_COLORSPACE_JPEG`` can be considered to be an abbreviation for - ``V4L2_COLORSPACE_SRGB``, ``V4L2_YCBCR_ENC_601`` and - ``V4L2_QUANTIZATION_FULL_RANGE``. - -*************************************** -Detailed Transfer Function Descriptions -*************************************** - -.. _xf-smpte-2084: - -Transfer Function SMPTE 2084 (V4L2_XFER_FUNC_SMPTE2084) -======================================================= - -The :ref:`smpte2084` standard defines the transfer function used by -High Dynamic Range content. - -Constants: - m1 = (2610 / 4096) / 4 - - m2 = (2523 / 4096) * 128 - - c1 = 3424 / 4096 - - c2 = (2413 / 4096) * 32 - - c3 = (2392 / 4096) * 32 - -Transfer function: - L' = ((c1 + c2 * L\ :sup:`m1`) / (1 + c3 * L\ :sup:`m1`))\ :sup:`m2` - -Inverse Transfer function: - L = (max(L':sup:`1/m2` - c1, 0) / (c2 - c3 * - L'\ :sup:`1/m2`))\ :sup:`1/m1` - -Take care when converting between this transfer function and non-HDR transfer -functions: the linear RGB values [0…1] of HDR content map to a luminance range -of 0 to 10000 cd/m\ :sup:`2` whereas the linear RGB values of non-HDR (aka -Standard Dynamic Range or SDR) map to a luminance range of 0 to 100 cd/m\ :sup:`2`. - -To go from SDR to HDR you will have to divide L by 100 first. To go in the other -direction you will have to multiply L by 100. Of course, this clamps all -luminance values over 100 cd/m\ :sup:`2` to 100 cd/m\ :sup:`2`. - -There are better methods, see e.g. :ref:`colimg` for more in-depth information -about this. diff --git a/Documentation/media/uapi/v4l/colorspaces.rst b/Documentation/media/uapi/v4l/colorspaces.rst deleted file mode 100644 index 4f6c82fa057f..000000000000 --- a/Documentation/media/uapi/v4l/colorspaces.rst +++ /dev/null @@ -1,170 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _colorspaces: - -*********** -Colorspaces -*********** - -'Color' is a very complex concept and depends on physics, chemistry and -biology. Just because you have three numbers that describe the 'red', -'green' and 'blue' components of the color of a pixel does not mean that -you can accurately display that color. A colorspace defines what it -actually *means* to have an RGB value of e.g. (255, 0, 0). That is, -which color should be reproduced on the screen in a perfectly calibrated -environment. - -In order to do that we first need to have a good definition of color, -i.e. some way to uniquely and unambiguously define a color so that -someone else can reproduce it. Human color vision is trichromatic since -the human eye has color receptors that are sensitive to three different -wavelengths of light. Hence the need to use three numbers to describe -color. Be glad you are not a mantis shrimp as those are sensitive to 12 -different wavelengths, so instead of RGB we would be using the -ABCDEFGHIJKL colorspace... - -Color exists only in the eye and brain and is the result of how strongly -color receptors are stimulated. This is based on the Spectral Power -Distribution (SPD) which is a graph showing the intensity (radiant -power) of the light at wavelengths covering the visible spectrum as it -enters the eye. The science of colorimetry is about the relationship -between the SPD and color as perceived by the human brain. - -Since the human eye has only three color receptors it is perfectly -possible that different SPDs will result in the same stimulation of -those receptors and are perceived as the same color, even though the SPD -of the light is different. - -In the 1920s experiments were devised to determine the relationship -between SPDs and the perceived color and that resulted in the CIE 1931 -standard that defines spectral weighting functions that model the -perception of color. Specifically that standard defines functions that -can take an SPD and calculate the stimulus for each color receptor. -After some further mathematical transforms these stimuli are known as -the *CIE XYZ tristimulus* values and these X, Y and Z values describe a -color as perceived by a human unambiguously. These X, Y and Z values are -all in the range [0…1]. - -The Y value in the CIE XYZ colorspace corresponds to luminance. Often -the CIE XYZ colorspace is transformed to the normalized CIE xyY -colorspace: - - x = X / (X + Y + Z) - - y = Y / (X + Y + Z) - -The x and y values are the chromaticity coordinates and can be used to -define a color without the luminance component Y. It is very confusing -to have such similar names for these colorspaces. Just be aware that if -colors are specified with lower case 'x' and 'y', then the CIE xyY -colorspace is used. Upper case 'X' and 'Y' refer to the CIE XYZ -colorspace. Also, y has nothing to do with luminance. Together x and y -specify a color, and Y the luminance. That is really all you need to -remember from a practical point of view. At the end of this section you -will find reading resources that go into much more detail if you are -interested. - -A monitor or TV will reproduce colors by emitting light at three -different wavelengths, the combination of which will stimulate the color -receptors in the eye and thus cause the perception of color. -Historically these wavelengths were defined by the red, green and blue -phosphors used in the displays. These *color primaries* are part of what -defines a colorspace. - -Different display devices will have different primaries and some -primaries are more suitable for some display technologies than others. -This has resulted in a variety of colorspaces that are used for -different display technologies or uses. To define a colorspace you need -to define the three color primaries (these are typically defined as x, y -chromaticity coordinates from the CIE xyY colorspace) but also the white -reference: that is the color obtained when all three primaries are at -maximum power. This determines the relative power or energy of the -primaries. This is usually chosen to be close to daylight which has been -defined as the CIE D65 Illuminant. - -To recapitulate: the CIE XYZ colorspace uniquely identifies colors. -Other colorspaces are defined by three chromaticity coordinates defined -in the CIE xyY colorspace. Based on those a 3x3 matrix can be -constructed that transforms CIE XYZ colors to colors in the new -colorspace. - -Both the CIE XYZ and the RGB colorspace that are derived from the -specific chromaticity primaries are linear colorspaces. But neither the -eye, nor display technology is linear. Doubling the values of all -components in the linear colorspace will not be perceived as twice the -intensity of the color. So each colorspace also defines a transfer -function that takes a linear color component value and transforms it to -the non-linear component value, which is a closer match to the -non-linear performance of both the eye and displays. Linear component -values are denoted RGB, non-linear are denoted as R'G'B'. In general -colors used in graphics are all R'G'B', except in openGL which uses -linear RGB. Special care should be taken when dealing with openGL to -provide linear RGB colors or to use the built-in openGL support to apply -the inverse transfer function. - -The final piece that defines a colorspace is a function that transforms -non-linear R'G'B' to non-linear Y'CbCr. This function is determined by -the so-called luma coefficients. There may be multiple possible Y'CbCr -encodings allowed for the same colorspace. Many encodings of color -prefer to use luma (Y') and chroma (CbCr) instead of R'G'B'. Since the -human eye is more sensitive to differences in luminance than in color -this encoding allows one to reduce the amount of color information -compared to the luma data. Note that the luma (Y') is unrelated to the Y -in the CIE XYZ colorspace. Also note that Y'CbCr is often called YCbCr -or YUV even though these are strictly speaking wrong. - -Sometimes people confuse Y'CbCr as being a colorspace. This is not -correct, it is just an encoding of an R'G'B' color into luma and chroma -values. The underlying colorspace that is associated with the R'G'B' -color is also associated with the Y'CbCr color. - -The final step is how the RGB, R'G'B' or Y'CbCr values are quantized. -The CIE XYZ colorspace where X, Y and Z are in the range [0…1] describes -all colors that humans can perceive, but the transform to another -colorspace will produce colors that are outside the [0…1] range. Once -clamped to the [0…1] range those colors can no longer be reproduced in -that colorspace. This clamping is what reduces the extent or gamut of -the colorspace. How the range of [0…1] is translated to integer values -in the range of [0…255] (or higher, depending on the color depth) is -called the quantization. This is *not* part of the colorspace -definition. In practice RGB or R'G'B' values are full range, i.e. they -use the full [0…255] range. Y'CbCr values on the other hand are limited -range with Y' using [16…235] and Cb and Cr using [16…240]. - -Unfortunately, in some cases limited range RGB is also used where the -components use the range [16…235]. And full range Y'CbCr also exists -using the [0…255] range. - -In order to correctly interpret a color you need to know the -quantization range, whether it is R'G'B' or Y'CbCr, the used Y'CbCr -encoding and the colorspace. From that information you can calculate the -corresponding CIE XYZ color and map that again to whatever colorspace -your display device uses. - -The colorspace definition itself consists of the three chromaticity -primaries, the white reference chromaticity, a transfer function and the -luma coefficients needed to transform R'G'B' to Y'CbCr. While some -colorspace standards correctly define all four, quite often the -colorspace standard only defines some, and you have to rely on other -standards for the missing pieces. The fact that colorspaces are often a -mix of different standards also led to very confusing naming conventions -where the name of a standard was used to name a colorspace when in fact -that standard was part of various other colorspaces as well. - -If you want to read more about colors and colorspaces, then the -following resources are useful: :ref:`poynton` is a good practical -book for video engineers, :ref:`colimg` has a much broader scope and -describes many more aspects of color (physics, chemistry, biology, -etc.). The -`http://www.brucelindbloom.com `__ -website is an excellent resource, especially with respect to the -mathematics behind colorspace conversions. The wikipedia -`CIE 1931 colorspace `__ -article is also very useful. diff --git a/Documentation/media/uapi/v4l/common-defs.rst b/Documentation/media/uapi/v4l/common-defs.rst deleted file mode 100644 index 504c6c93c9b0..000000000000 --- a/Documentation/media/uapi/v4l/common-defs.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _common-defs: - -****************************************************** -Common definitions for V4L2 and V4L2 subdev interfaces -****************************************************** - - -.. toctree:: - :maxdepth: 1 - - selections-common diff --git a/Documentation/media/uapi/v4l/common.rst b/Documentation/media/uapi/v4l/common.rst deleted file mode 100644 index 5e87ae24e4b4..000000000000 --- a/Documentation/media/uapi/v4l/common.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _common: - -################### -Common API Elements -################### -Programming a V4L2 device consists of these steps: - -- Opening the device - -- Changing device properties, selecting a video and audio input, video - standard, picture brightness a. o. - -- Negotiating a data format - -- Negotiating an input/output method - -- The actual input/output loop - -- Closing the device - -In practice most steps are optional and can be executed out of order. It -depends on the V4L2 device type, you can read about the details in -:ref:`devices`. In this chapter we will discuss the basic concepts -applicable to all devices. - - -.. toctree:: - :maxdepth: 1 - - open - querycap - app-pri - video - audio - tuner - standard - dv-timings - control - extended-controls - ext-ctrls-camera - ext-ctrls-flash - ext-ctrls-image-source - ext-ctrls-image-process - ext-ctrls-codec - ext-ctrls-jpeg - ext-ctrls-dv - ext-ctrls-rf-tuner - ext-ctrls-fm-tx - ext-ctrls-fm-rx - ext-ctrls-detect - format - planar-apis - selection-api - crop - streaming-par diff --git a/Documentation/media/uapi/v4l/compat.rst b/Documentation/media/uapi/v4l/compat.rst deleted file mode 100644 index f35575a300b4..000000000000 --- a/Documentation/media/uapi/v4l/compat.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _compat: - -******* -Changes -******* - -The following chapters document the evolution of the V4L2 API, errata or -extensions. They are also intended to help application and driver -writers to port or update their code. - - -.. toctree:: - :maxdepth: 1 - - diff-v4l - hist-v4l2 diff --git a/Documentation/media/uapi/v4l/constraints.svg b/Documentation/media/uapi/v4l/constraints.svg deleted file mode 100644 index 08f9f8b0985e..000000000000 --- a/Documentation/media/uapi/v4l/constraints.svg +++ /dev/null @@ -1,37 +0,0 @@ - - -image/svg+xmlV4L2_SEL_FLAG_GE -ORIGINAL -V4L2_SEL_FLAG_LE - diff --git a/Documentation/media/uapi/v4l/control.rst b/Documentation/media/uapi/v4l/control.rst deleted file mode 100644 index ef62e088ff7a..000000000000 --- a/Documentation/media/uapi/v4l/control.rst +++ /dev/null @@ -1,512 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _control: - -************* -User Controls -************* - -Devices typically have a number of user-settable controls such as -brightness, saturation and so on, which would be presented to the user -on a graphical user interface. But, different devices will have -different controls available, and furthermore, the range of possible -values, and the default value will vary from device to device. The -control ioctls provide the information and a mechanism to create a nice -user interface for these controls that will work correctly with any -device. - -All controls are accessed using an ID value. V4L2 defines several IDs -for specific purposes. Drivers can also implement their own custom -controls using ``V4L2_CID_PRIVATE_BASE`` [#f1]_ and higher values. The -pre-defined control IDs have the prefix ``V4L2_CID_``, and are listed in -:ref:`control-id`. The ID is used when querying the attributes of a -control, and when getting or setting the current value. - -Generally applications should present controls to the user without -assumptions about their purpose. Each control comes with a name string -the user is supposed to understand. When the purpose is non-intuitive -the driver writer should provide a user manual, a user interface plug-in -or a driver specific panel application. Predefined IDs were introduced -to change a few controls programmatically, for example to mute a device -during a channel switch. - -Drivers may enumerate different controls after switching the current -video input or output, tuner or modulator, or audio input or output. -Different in the sense of other bounds, another default and current -value, step size or other menu items. A control with a certain *custom* -ID can also change name and type. - -If a control is not applicable to the current configuration of the -device (for example, it doesn't apply to the current video input) -drivers set the ``V4L2_CTRL_FLAG_INACTIVE`` flag. - -Control values are stored globally, they do not change when switching -except to stay within the reported bounds. They also do not change e. g. -when the device is opened or closed, when the tuner radio frequency is -changed or generally never without application request. - -V4L2 specifies an event mechanism to notify applications when controls -change value (see -:ref:`VIDIOC_SUBSCRIBE_EVENT`, event -``V4L2_EVENT_CTRL``), panel applications might want to make use of that -in order to always reflect the correct control value. - -All controls use machine endianness. - - -.. _control-id: - -Control IDs -=========== - -``V4L2_CID_BASE`` - First predefined ID, equal to ``V4L2_CID_BRIGHTNESS``. - -``V4L2_CID_USER_BASE`` - Synonym of ``V4L2_CID_BASE``. - -``V4L2_CID_BRIGHTNESS`` ``(integer)`` - Picture brightness, or more precisely, the black level. - -``V4L2_CID_CONTRAST`` ``(integer)`` - Picture contrast or luma gain. - -``V4L2_CID_SATURATION`` ``(integer)`` - Picture color saturation or chroma gain. - -``V4L2_CID_HUE`` ``(integer)`` - Hue or color balance. - -``V4L2_CID_AUDIO_VOLUME`` ``(integer)`` - Overall audio volume. Note some drivers also provide an OSS or ALSA - mixer interface. - -``V4L2_CID_AUDIO_BALANCE`` ``(integer)`` - Audio stereo balance. Minimum corresponds to all the way left, - maximum to right. - -``V4L2_CID_AUDIO_BASS`` ``(integer)`` - Audio bass adjustment. - -``V4L2_CID_AUDIO_TREBLE`` ``(integer)`` - Audio treble adjustment. - -``V4L2_CID_AUDIO_MUTE`` ``(boolean)`` - Mute audio, i. e. set the volume to zero, however without affecting - ``V4L2_CID_AUDIO_VOLUME``. Like ALSA drivers, V4L2 drivers must mute - at load time to avoid excessive noise. Actually the entire device - should be reset to a low power consumption state. - -``V4L2_CID_AUDIO_LOUDNESS`` ``(boolean)`` - Loudness mode (bass boost). - -``V4L2_CID_BLACK_LEVEL`` ``(integer)`` - Another name for brightness (not a synonym of - ``V4L2_CID_BRIGHTNESS``). This control is deprecated and should not - be used in new drivers and applications. - -``V4L2_CID_AUTO_WHITE_BALANCE`` ``(boolean)`` - Automatic white balance (cameras). - -``V4L2_CID_DO_WHITE_BALANCE`` ``(button)`` - This is an action control. When set (the value is ignored), the - device will do a white balance and then hold the current setting. - Contrast this with the boolean ``V4L2_CID_AUTO_WHITE_BALANCE``, - which, when activated, keeps adjusting the white balance. - -``V4L2_CID_RED_BALANCE`` ``(integer)`` - Red chroma balance. - -``V4L2_CID_BLUE_BALANCE`` ``(integer)`` - Blue chroma balance. - -``V4L2_CID_GAMMA`` ``(integer)`` - Gamma adjust. - -``V4L2_CID_WHITENESS`` ``(integer)`` - Whiteness for grey-scale devices. This is a synonym for - ``V4L2_CID_GAMMA``. This control is deprecated and should not be - used in new drivers and applications. - -``V4L2_CID_EXPOSURE`` ``(integer)`` - Exposure (cameras). [Unit?] - -``V4L2_CID_AUTOGAIN`` ``(boolean)`` - Automatic gain/exposure control. - -``V4L2_CID_GAIN`` ``(integer)`` - Gain control. - - Primarily used to control gain on e.g. TV tuners but also on - webcams. Most devices control only digital gain with this control - but on some this could include analogue gain as well. Devices that - recognise the difference between digital and analogue gain use - controls ``V4L2_CID_DIGITAL_GAIN`` and ``V4L2_CID_ANALOGUE_GAIN``. - -``V4L2_CID_HFLIP`` ``(boolean)`` - Mirror the picture horizontally. - -``V4L2_CID_VFLIP`` ``(boolean)`` - Mirror the picture vertically. - -.. _v4l2-power-line-frequency: - -``V4L2_CID_POWER_LINE_FREQUENCY`` ``(enum)`` - Enables a power line frequency filter to avoid flicker. Possible - values for ``enum v4l2_power_line_frequency`` are: - ``V4L2_CID_POWER_LINE_FREQUENCY_DISABLED`` (0), - ``V4L2_CID_POWER_LINE_FREQUENCY_50HZ`` (1), - ``V4L2_CID_POWER_LINE_FREQUENCY_60HZ`` (2) and - ``V4L2_CID_POWER_LINE_FREQUENCY_AUTO`` (3). - -``V4L2_CID_HUE_AUTO`` ``(boolean)`` - Enables automatic hue control by the device. The effect of setting - ``V4L2_CID_HUE`` while automatic hue control is enabled is - undefined, drivers should ignore such request. - -``V4L2_CID_WHITE_BALANCE_TEMPERATURE`` ``(integer)`` - This control specifies the white balance settings as a color - temperature in Kelvin. A driver should have a minimum of 2800 - (incandescent) to 6500 (daylight). For more information about color - temperature see - `Wikipedia `__. - -``V4L2_CID_SHARPNESS`` ``(integer)`` - Adjusts the sharpness filters in a camera. The minimum value - disables the filters, higher values give a sharper picture. - -``V4L2_CID_BACKLIGHT_COMPENSATION`` ``(integer)`` - Adjusts the backlight compensation in a camera. The minimum value - disables backlight compensation. - -``V4L2_CID_CHROMA_AGC`` ``(boolean)`` - Chroma automatic gain control. - -``V4L2_CID_CHROMA_GAIN`` ``(integer)`` - Adjusts the Chroma gain control (for use when chroma AGC is - disabled). - -``V4L2_CID_COLOR_KILLER`` ``(boolean)`` - Enable the color killer (i. e. force a black & white image in case - of a weak video signal). - -.. _v4l2-colorfx: - -``V4L2_CID_COLORFX`` ``(enum)`` - Selects a color effect. The following values are defined: - - - -.. tabularcolumns:: |p{5.5cm}|p{12cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 11 24 - - * - ``V4L2_COLORFX_NONE`` - - Color effect is disabled. - * - ``V4L2_COLORFX_ANTIQUE`` - - An aging (old photo) effect. - * - ``V4L2_COLORFX_ART_FREEZE`` - - Frost color effect. - * - ``V4L2_COLORFX_AQUA`` - - Water color, cool tone. - * - ``V4L2_COLORFX_BW`` - - Black and white. - * - ``V4L2_COLORFX_EMBOSS`` - - Emboss, the highlights and shadows replace light/dark boundaries - and low contrast areas are set to a gray background. - * - ``V4L2_COLORFX_GRASS_GREEN`` - - Grass green. - * - ``V4L2_COLORFX_NEGATIVE`` - - Negative. - * - ``V4L2_COLORFX_SEPIA`` - - Sepia tone. - * - ``V4L2_COLORFX_SKETCH`` - - Sketch. - * - ``V4L2_COLORFX_SKIN_WHITEN`` - - Skin whiten. - * - ``V4L2_COLORFX_SKY_BLUE`` - - Sky blue. - * - ``V4L2_COLORFX_SOLARIZATION`` - - Solarization, the image is partially reversed in tone, only color - values above or below a certain threshold are inverted. - * - ``V4L2_COLORFX_SILHOUETTE`` - - Silhouette (outline). - * - ``V4L2_COLORFX_VIVID`` - - Vivid colors. - * - ``V4L2_COLORFX_SET_CBCR`` - - The Cb and Cr chroma components are replaced by fixed coefficients - determined by ``V4L2_CID_COLORFX_CBCR`` control. - - - -``V4L2_CID_COLORFX_CBCR`` ``(integer)`` - Determines the Cb and Cr coefficients for ``V4L2_COLORFX_SET_CBCR`` - color effect. Bits [7:0] of the supplied 32 bit value are - interpreted as Cr component, bits [15:8] as Cb component and bits - [31:16] must be zero. - -``V4L2_CID_AUTOBRIGHTNESS`` ``(boolean)`` - Enable Automatic Brightness. - -``V4L2_CID_ROTATE`` ``(integer)`` - Rotates the image by specified angle. Common angles are 90, 270 and - 180. Rotating the image to 90 and 270 will reverse the height and - width of the display window. It is necessary to set the new height - and width of the picture using the - :ref:`VIDIOC_S_FMT ` ioctl according to the - rotation angle selected. - -``V4L2_CID_BG_COLOR`` ``(integer)`` - Sets the background color on the current output device. Background - color needs to be specified in the RGB24 format. The supplied 32 bit - value is interpreted as bits 0-7 Red color information, bits 8-15 - Green color information, bits 16-23 Blue color information and bits - 24-31 must be zero. - -``V4L2_CID_ILLUMINATORS_1 V4L2_CID_ILLUMINATORS_2`` ``(boolean)`` - Switch on or off the illuminator 1 or 2 of the device (usually a - microscope). - -``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE`` ``(integer)`` - This is a read-only control that can be read by the application and - used as a hint to determine the number of CAPTURE buffers to pass to - REQBUFS. The value is the minimum number of CAPTURE buffers that is - necessary for hardware to work. - -``V4L2_CID_MIN_BUFFERS_FOR_OUTPUT`` ``(integer)`` - This is a read-only control that can be read by the application and - used as a hint to determine the number of OUTPUT buffers to pass to - REQBUFS. The value is the minimum number of OUTPUT buffers that is - necessary for hardware to work. - -.. _v4l2-alpha-component: - -``V4L2_CID_ALPHA_COMPONENT`` ``(integer)`` - Sets the alpha color component. When a capture device (or capture - queue of a mem-to-mem device) produces a frame format that includes - an alpha component (e.g. - :ref:`packed RGB image formats `) and the alpha value - is not defined by the device or the mem-to-mem input data this - control lets you select the alpha component value of all pixels. - When an output device (or output queue of a mem-to-mem device) - consumes a frame format that doesn't include an alpha component and - the device supports alpha channel processing this control lets you - set the alpha component value of all pixels for further processing - in the device. - -``V4L2_CID_LASTP1`` - End of the predefined control IDs (currently - ``V4L2_CID_ALPHA_COMPONENT`` + 1). - -``V4L2_CID_PRIVATE_BASE`` - ID of the first custom (driver specific) control. Applications - depending on particular custom controls should check the driver name - and version, see :ref:`querycap`. - -Applications can enumerate the available controls with the -:ref:`VIDIOC_QUERYCTRL` and -:ref:`VIDIOC_QUERYMENU ` ioctls, get and set a -control value with the :ref:`VIDIOC_G_CTRL ` and -:ref:`VIDIOC_S_CTRL ` ioctls. Drivers must implement -``VIDIOC_QUERYCTRL``, ``VIDIOC_G_CTRL`` and ``VIDIOC_S_CTRL`` when the -device has one or more controls, ``VIDIOC_QUERYMENU`` when it has one or -more menu type controls. - - -.. _enum_all_controls: - -Example: Enumerating all controls -================================= - -.. code-block:: c - - struct v4l2_queryctrl queryctrl; - struct v4l2_querymenu querymenu; - - static void enumerate_menu(__u32 id) - { - printf(" Menu items:\\n"); - - memset(&querymenu, 0, sizeof(querymenu)); - querymenu.id = id; - - for (querymenu.index = queryctrl.minimum; - querymenu.index <= queryctrl.maximum; - querymenu.index++) { - if (0 == ioctl(fd, VIDIOC_QUERYMENU, &querymenu)) { - printf(" %s\\n", querymenu.name); - } - } - } - - memset(&queryctrl, 0, sizeof(queryctrl)); - - queryctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL; - while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) { - if (!(queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)) { - printf("Control %s\\n", queryctrl.name); - - if (queryctrl.type == V4L2_CTRL_TYPE_MENU) - enumerate_menu(queryctrl.id); - } - - queryctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; - } - if (errno != EINVAL) { - perror("VIDIOC_QUERYCTRL"); - exit(EXIT_FAILURE); - } - -Example: Enumerating all controls including compound controls -============================================================= - -.. code-block:: c - - struct v4l2_query_ext_ctrl query_ext_ctrl; - - memset(&query_ext_ctrl, 0, sizeof(query_ext_ctrl)); - - query_ext_ctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL | V4L2_CTRL_FLAG_NEXT_COMPOUND; - while (0 == ioctl(fd, VIDIOC_QUERY_EXT_CTRL, &query_ext_ctrl)) { - if (!(query_ext_ctrl.flags & V4L2_CTRL_FLAG_DISABLED)) { - printf("Control %s\\n", query_ext_ctrl.name); - - if (query_ext_ctrl.type == V4L2_CTRL_TYPE_MENU) - enumerate_menu(query_ext_ctrl.id); - } - - query_ext_ctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL | V4L2_CTRL_FLAG_NEXT_COMPOUND; - } - if (errno != EINVAL) { - perror("VIDIOC_QUERY_EXT_CTRL"); - exit(EXIT_FAILURE); - } - -Example: Enumerating all user controls (old style) -================================================== - -.. code-block:: c - - - memset(&queryctrl, 0, sizeof(queryctrl)); - - for (queryctrl.id = V4L2_CID_BASE; - queryctrl.id < V4L2_CID_LASTP1; - queryctrl.id++) { - if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) { - if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) - continue; - - printf("Control %s\\n", queryctrl.name); - - if (queryctrl.type == V4L2_CTRL_TYPE_MENU) - enumerate_menu(queryctrl.id); - } else { - if (errno == EINVAL) - continue; - - perror("VIDIOC_QUERYCTRL"); - exit(EXIT_FAILURE); - } - } - - for (queryctrl.id = V4L2_CID_PRIVATE_BASE;; - queryctrl.id++) { - if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) { - if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) - continue; - - printf("Control %s\\n", queryctrl.name); - - if (queryctrl.type == V4L2_CTRL_TYPE_MENU) - enumerate_menu(queryctrl.id); - } else { - if (errno == EINVAL) - break; - - perror("VIDIOC_QUERYCTRL"); - exit(EXIT_FAILURE); - } - } - - -Example: Changing controls -========================== - -.. code-block:: c - - struct v4l2_queryctrl queryctrl; - struct v4l2_control control; - - memset(&queryctrl, 0, sizeof(queryctrl)); - queryctrl.id = V4L2_CID_BRIGHTNESS; - - if (-1 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) { - if (errno != EINVAL) { - perror("VIDIOC_QUERYCTRL"); - exit(EXIT_FAILURE); - } else { - printf("V4L2_CID_BRIGHTNESS is not supportedn"); - } - } else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) { - printf("V4L2_CID_BRIGHTNESS is not supportedn"); - } else { - memset(&control, 0, sizeof (control)); - control.id = V4L2_CID_BRIGHTNESS; - control.value = queryctrl.default_value; - - if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)) { - perror("VIDIOC_S_CTRL"); - exit(EXIT_FAILURE); - } - } - - memset(&control, 0, sizeof(control)); - control.id = V4L2_CID_CONTRAST; - - if (0 == ioctl(fd, VIDIOC_G_CTRL, &control)) { - control.value += 1; - - /* The driver may clamp the value or return ERANGE, ignored here */ - - if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control) - && errno != ERANGE) { - perror("VIDIOC_S_CTRL"); - exit(EXIT_FAILURE); - } - /* Ignore if V4L2_CID_CONTRAST is unsupported */ - } else if (errno != EINVAL) { - perror("VIDIOC_G_CTRL"); - exit(EXIT_FAILURE); - } - - control.id = V4L2_CID_AUDIO_MUTE; - control.value = 1; /* silence */ - - /* Errors ignored */ - ioctl(fd, VIDIOC_S_CTRL, &control); - -.. [#f1] - The use of ``V4L2_CID_PRIVATE_BASE`` is problematic because different - drivers may use the same ``V4L2_CID_PRIVATE_BASE`` ID for different - controls. This makes it hard to programmatically set such controls - since the meaning of the control with that ID is driver dependent. In - order to resolve this drivers use unique IDs and the - ``V4L2_CID_PRIVATE_BASE`` IDs are mapped to those unique IDs by the - kernel. Consider these ``V4L2_CID_PRIVATE_BASE`` IDs as aliases to - the real IDs. - - Many applications today still use the ``V4L2_CID_PRIVATE_BASE`` IDs - instead of using :ref:`VIDIOC_QUERYCTRL` with - the ``V4L2_CTRL_FLAG_NEXT_CTRL`` flag to enumerate all IDs, so - support for ``V4L2_CID_PRIVATE_BASE`` is still around. diff --git a/Documentation/media/uapi/v4l/crop.rst b/Documentation/media/uapi/v4l/crop.rst deleted file mode 100644 index ada7c22e6291..000000000000 --- a/Documentation/media/uapi/v4l/crop.rst +++ /dev/null @@ -1,324 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _crop: - -***************************************************** -Image Cropping, Insertion and Scaling -- the CROP API -***************************************************** - -.. note:: - - The CROP API is mostly superseded by the newer :ref:`SELECTION API - `. The new API should be preferred in most cases, - with the exception of pixel aspect ratio detection, which is - implemented by :ref:`VIDIOC_CROPCAP ` and has no - equivalent in the SELECTION API. See :ref:`selection-vs-crop` for a - comparison of the two APIs. - -Some video capture devices can sample a subsection of the picture and -shrink or enlarge it to an image of arbitrary size. We call these -abilities cropping and scaling. Some video output devices can scale an -image up or down and insert it at an arbitrary scan line and horizontal -offset into a video signal. - -Applications can use the following API to select an area in the video -signal, query the default area and the hardware limits. - -.. note:: - - Despite their name, the :ref:`VIDIOC_CROPCAP `, - :ref:`VIDIOC_G_CROP ` and :ref:`VIDIOC_S_CROP - ` ioctls apply to input as well as output devices. - -Scaling requires a source and a target. On a video capture or overlay -device the source is the video signal, and the cropping ioctls determine -the area actually sampled. The target are images read by the application -or overlaid onto the graphics screen. Their size (and position for an -overlay) is negotiated with the :ref:`VIDIOC_G_FMT ` -and :ref:`VIDIOC_S_FMT ` ioctls. - -On a video output device the source are the images passed in by the -application, and their size is again negotiated with the -:ref:`VIDIOC_G_FMT ` and :ref:`VIDIOC_S_FMT ` -ioctls, or may be encoded in a compressed video stream. The target is -the video signal, and the cropping ioctls determine the area where the -images are inserted. - -Source and target rectangles are defined even if the device does not -support scaling or the :ref:`VIDIOC_G_CROP ` and -:ref:`VIDIOC_S_CROP ` ioctls. Their size (and position -where applicable) will be fixed in this case. - -.. note:: - - All capture and output devices that support the CROP or SELECTION - API will also support the :ref:`VIDIOC_CROPCAP ` - ioctl. - -Cropping Structures -=================== - - -.. _crop-scale: - -.. kernel-figure:: crop.svg - :alt: crop.svg - :align: center - - Image Cropping, Insertion and Scaling - - The cropping, insertion and scaling process - - - -For capture devices the coordinates of the top left corner, width and -height of the area which can be sampled is given by the ``bounds`` -substructure of the struct :c:type:`v4l2_cropcap` returned -by the :ref:`VIDIOC_CROPCAP ` ioctl. To support a wide -range of hardware this specification does not define an origin or units. -However by convention drivers should horizontally count unscaled samples -relative to 0H (the leading edge of the horizontal sync pulse, see -:ref:`vbi-hsync`). Vertically ITU-R line numbers of the first field -(see ITU R-525 line numbering for :ref:`525 lines ` and for -:ref:`625 lines `), multiplied by two if the driver -can capture both fields. - -The top left corner, width and height of the source rectangle, that is -the area actually sampled, is given by struct -:c:type:`v4l2_crop` using the same coordinate system as -struct :c:type:`v4l2_cropcap`. Applications can use the -:ref:`VIDIOC_G_CROP ` and :ref:`VIDIOC_S_CROP ` -ioctls to get and set this rectangle. It must lie completely within the -capture boundaries and the driver may further adjust the requested size -and/or position according to hardware limitations. - -Each capture device has a default source rectangle, given by the -``defrect`` substructure of struct -:c:type:`v4l2_cropcap`. The center of this rectangle -shall align with the center of the active picture area of the video -signal, and cover what the driver writer considers the complete picture. -Drivers shall reset the source rectangle to the default when the driver -is first loaded, but not later. - -For output devices these structures and ioctls are used accordingly, -defining the *target* rectangle where the images will be inserted into -the video signal. - - -Scaling Adjustments -=================== - -Video hardware can have various cropping, insertion and scaling -limitations. It may only scale up or down, support only discrete scaling -factors, or have different scaling abilities in horizontal and vertical -direction. Also it may not support scaling at all. At the same time the -struct :c:type:`v4l2_crop` rectangle may have to be aligned, -and both the source and target rectangles may have arbitrary upper and -lower size limits. In particular the maximum ``width`` and ``height`` in -struct :c:type:`v4l2_crop` may be smaller than the struct -:c:type:`v4l2_cropcap`. ``bounds`` area. Therefore, as -usual, drivers are expected to adjust the requested parameters and -return the actual values selected. - -Applications can change the source or the target rectangle first, as -they may prefer a particular image size or a certain area in the video -signal. If the driver has to adjust both to satisfy hardware -limitations, the last requested rectangle shall take priority, and the -driver should preferably adjust the opposite one. The -:ref:`VIDIOC_TRY_FMT ` ioctl however shall not change -the driver state and therefore only adjust the requested rectangle. - -Suppose scaling on a video capture device is restricted to a factor 1:1 -or 2:1 in either direction and the target image size must be a multiple -of 16 × 16 pixels. The source cropping rectangle is set to defaults, -which are also the upper limit in this example, of 640 × 400 pixels at -offset 0, 0. An application requests an image size of 300 × 225 pixels, -assuming video will be scaled down from the "full picture" accordingly. -The driver sets the image size to the closest possible values 304 × 224, -then chooses the cropping rectangle closest to the requested size, that -is 608 × 224 (224 × 2:1 would exceed the limit 400). The offset 0, 0 is -still valid, thus unmodified. Given the default cropping rectangle -reported by :ref:`VIDIOC_CROPCAP ` the application can -easily propose another offset to center the cropping rectangle. - -Now the application may insist on covering an area using a picture -aspect ratio closer to the original request, so it asks for a cropping -rectangle of 608 × 456 pixels. The present scaling factors limit -cropping to 640 × 384, so the driver returns the cropping size 608 × 384 -and adjusts the image size to closest possible 304 × 192. - - -Examples -======== - -Source and target rectangles shall remain unchanged across closing and -reopening a device, such that piping data into or out of a device will -work without special preparations. More advanced applications should -ensure the parameters are suitable before starting I/O. - -.. note:: - - On the next two examples, a video capture device is assumed; - change ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other types of device. - -Example: Resetting the cropping parameters -========================================== - -.. code-block:: c - - struct v4l2_cropcap cropcap; - struct v4l2_crop crop; - - memset (&cropcap, 0, sizeof (cropcap)); - cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - - if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) { - perror ("VIDIOC_CROPCAP"); - exit (EXIT_FAILURE); - } - - memset (&crop, 0, sizeof (crop)); - crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - crop.c = cropcap.defrect; - - /* Ignore if cropping is not supported (EINVAL). */ - - if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop) - && errno != EINVAL) { - perror ("VIDIOC_S_CROP"); - exit (EXIT_FAILURE); - } - - -Example: Simple downscaling -=========================== - -.. code-block:: c - - struct v4l2_cropcap cropcap; - struct v4l2_format format; - - reset_cropping_parameters (); - - /* Scale down to 1/4 size of full picture. */ - - memset (&format, 0, sizeof (format)); /* defaults */ - - format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - - format.fmt.pix.width = cropcap.defrect.width >> 1; - format.fmt.pix.height = cropcap.defrect.height >> 1; - format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV; - - if (-1 == ioctl (fd, VIDIOC_S_FMT, &format)) { - perror ("VIDIOC_S_FORMAT"); - exit (EXIT_FAILURE); - } - - /* We could check the actual image size now, the actual scaling factor - or if the driver can scale at all. */ - -Example: Selecting an output area -================================= - -.. note:: This example assumes an output device. - -.. code-block:: c - - struct v4l2_cropcap cropcap; - struct v4l2_crop crop; - - memset (&cropcap, 0, sizeof (cropcap)); - cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT; - - if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &cropcap)) { - perror ("VIDIOC_CROPCAP"); - exit (EXIT_FAILURE); - } - - memset (&crop, 0, sizeof (crop)); - - crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT; - crop.c = cropcap.defrect; - - /* Scale the width and height to 50 % of their original size - and center the output. */ - - crop.c.width /= 2; - crop.c.height /= 2; - crop.c.left += crop.c.width / 2; - crop.c.top += crop.c.height / 2; - - /* Ignore if cropping is not supported (EINVAL). */ - - if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop) - && errno != EINVAL) { - perror ("VIDIOC_S_CROP"); - exit (EXIT_FAILURE); - } - -Example: Current scaling factor and pixel aspect -================================================ - -.. note:: This example assumes a video capture device. - -.. code-block:: c - - struct v4l2_cropcap cropcap; - struct v4l2_crop crop; - struct v4l2_format format; - double hscale, vscale; - double aspect; - int dwidth, dheight; - - memset (&cropcap, 0, sizeof (cropcap)); - cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - - if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) { - perror ("VIDIOC_CROPCAP"); - exit (EXIT_FAILURE); - } - - memset (&crop, 0, sizeof (crop)); - crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - - if (-1 == ioctl (fd, VIDIOC_G_CROP, &crop)) { - if (errno != EINVAL) { - perror ("VIDIOC_G_CROP"); - exit (EXIT_FAILURE); - } - - /* Cropping not supported. */ - crop.c = cropcap.defrect; - } - - memset (&format, 0, sizeof (format)); - format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - - if (-1 == ioctl (fd, VIDIOC_G_FMT, &format)) { - perror ("VIDIOC_G_FMT"); - exit (EXIT_FAILURE); - } - - /* The scaling applied by the driver. */ - - hscale = format.fmt.pix.width / (double) crop.c.width; - vscale = format.fmt.pix.height / (double) crop.c.height; - - aspect = cropcap.pixelaspect.numerator / - (double) cropcap.pixelaspect.denominator; - aspect = aspect * hscale / vscale; - - /* Devices following ITU-R BT.601 do not capture - square pixels. For playback on a computer monitor - we should scale the images to this size. */ - - dwidth = format.fmt.pix.width / aspect; - dheight = format.fmt.pix.height; diff --git a/Documentation/media/uapi/v4l/crop.svg b/Documentation/media/uapi/v4l/crop.svg deleted file mode 100644 index 32d72598d135..000000000000 --- a/Documentation/media/uapi/v4l/crop.svg +++ /dev/null @@ -1,290 +0,0 @@ - - -image/svg+xmlv4l2_cropcap.bounds -v4l2_cropcap.defrect -v4l2_crop.c -v4l2_format - - diff --git a/Documentation/media/uapi/v4l/depth-formats.rst b/Documentation/media/uapi/v4l/depth-formats.rst deleted file mode 100644 index 1bfd0b82cb85..000000000000 --- a/Documentation/media/uapi/v4l/depth-formats.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _depth-formats: - -************* -Depth Formats -************* - -Depth data provides distance to points, mapped onto the image plane - - -.. toctree:: - :maxdepth: 1 - - pixfmt-inzi - pixfmt-z16 - pixfmt-cnf4 diff --git a/Documentation/media/uapi/v4l/dev-capture.rst b/Documentation/media/uapi/v4l/dev-capture.rst deleted file mode 100644 index 134e22b32338..000000000000 --- a/Documentation/media/uapi/v4l/dev-capture.rst +++ /dev/null @@ -1,111 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _capture: - -*********************** -Video Capture Interface -*********************** - -Video capture devices sample an analog video signal and store the -digitized images in memory. Today nearly all devices can capture at full -25 or 30 frames/second. With this interface applications can control the -capture process and move images from the driver into user space. - -Conventionally V4L2 video capture devices are accessed through character -device special files named ``/dev/video`` and ``/dev/video0`` to -``/dev/video63`` with major number 81 and minor numbers 0 to 63. -``/dev/video`` is typically a symbolic link to the preferred video -device. - -.. note:: The same device file names are used for video output devices. - - -Querying Capabilities -===================== - -Devices supporting the video capture interface set the -``V4L2_CAP_VIDEO_CAPTURE`` or ``V4L2_CAP_VIDEO_CAPTURE_MPLANE`` flag in -the ``capabilities`` field of struct -:c:type:`v4l2_capability` returned by the -:ref:`VIDIOC_QUERYCAP` ioctl. As secondary device -functions they may also support the :ref:`video overlay ` -(``V4L2_CAP_VIDEO_OVERLAY``) and the :ref:`raw VBI capture ` -(``V4L2_CAP_VBI_CAPTURE``) interface. At least one of the read/write or -streaming I/O methods must be supported. Tuners and audio inputs are -optional. - - -Supplemental Functions -====================== - -Video capture devices shall support :ref:`audio input