diff options
Diffstat (limited to 'Documentation/media')
43 files changed, 4697 insertions, 1589 deletions
diff --git a/Documentation/media/conf.py b/Documentation/media/conf.py deleted file mode 100644 index 1f194fcd2cae..000000000000 --- a/Documentation/media/conf.py +++ /dev/null @@ -1,12 +0,0 @@ -# -*- coding: utf-8; mode: python -*- - -# SPDX-License-Identifier: GPL-2.0 - -project = 'Linux Media Subsystem Documentation' - -tags.add("subproject") - -latex_documents = [ - ('index', 'media.tex', 'Linux Media Subsystem Documentation', - 'The kernel development community', 'manual'), -] diff --git a/Documentation/media/kapi/csi2.rst b/Documentation/media/kapi/csi2.rst index a7e75e2eba85..030a5c41ec75 100644 --- a/Documentation/media/kapi/csi2.rst +++ b/Documentation/media/kapi/csi2.rst @@ -49,9 +49,13 @@ where The transmitter drivers must, if possible, configure the CSI-2 transmitter to *LP-11 mode* whenever the transmitter is powered on but -not active. Some transmitters do this automatically but some have to -be explicitly programmed to do so, and some are unable to do so -altogether due to hardware constraints. +not active, and maintain *LP-11 mode* until stream on. Only at stream +on should the transmitter activate the clock on the clock lane and +transition to *HS mode*. + +Some transmitters do this automatically but some have to be explicitly +programmed to do so, and some are unable to do so altogether due to +hardware constraints. Stopping the transmitter ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -72,3 +76,10 @@ the transmitter up by using the :c:type:`v4l2_subdev_core_ops`->s_power() callback. This may take place either indirectly by using :c:func:`v4l2_pipeline_pm_use` or directly. + +Formats +------- + +The media bus pixel codes document parallel formats. Should the pixel data be +transported over a serial bus, the media bus pixel code that describes a +parallel format that transfers a sample on a single clock cycle is used. diff --git a/Documentation/media/kapi/dtv-core.rst b/Documentation/media/kapi/dtv-core.rst index ac005b46f23e..82c5b85ed9b1 100644 --- a/Documentation/media/kapi/dtv-core.rst +++ b/Documentation/media/kapi/dtv-core.rst @@ -11,12 +11,12 @@ Digital TV devices are implemented by several different drivers: - Frontend drivers that are usually implemented as two separate drivers: - - A tuner driver that implements the logic with commands the part of the - hardware with is responsible to tune into a digital TV transponder or + - A tuner driver that implements the logic which commands the part of + the hardware responsible for tuning into a digital TV transponder or physical channel. The output of a tuner is usually a baseband or Intermediate Frequency (IF) signal; - - A demodulator driver (a.k.a "demod") that implements the logic with + - A demodulator driver (a.k.a "demod") that implements the logic which commands the digital TV decoding hardware. The output of a demod is a digital stream, with multiple audio, video and data channels typically multiplexed using MPEG Transport Stream [#f1]_. diff --git a/Documentation/media/kapi/v4l2-controls.rst b/Documentation/media/kapi/v4l2-controls.rst index 64ab99abf0b6..ebe2a55908be 100644 --- a/Documentation/media/kapi/v4l2-controls.rst +++ b/Documentation/media/kapi/v4l2-controls.rst @@ -26,8 +26,9 @@ The control framework was created in order to implement all the rules of the V4L2 specification with respect to controls in a central place. And to make life as easy as possible for the driver developer. -Note that the control framework relies on the presence of a struct v4l2_device -for V4L2 drivers and struct v4l2_subdev for sub-device drivers. +Note that the control framework relies on the presence of a struct +:c:type:`v4l2_device` for V4L2 drivers and struct :c:type:`v4l2_subdev` for +sub-device drivers. Objects in the framework @@ -35,12 +36,13 @@ Objects in the framework There are two main objects: -The v4l2_ctrl object describes the control properties and keeps track of the -control's value (both the current value and the proposed new value). +The :c:type:`v4l2_ctrl` object describes the control properties and keeps +track of the control's value (both the current value and the proposed new +value). -v4l2_ctrl_handler is the object that keeps track of controls. It maintains a -list of v4l2_ctrl objects that it owns and another list of references to -controls, possibly to controls owned by other handlers. +:c:type:`v4l2_ctrl_handler` is the object that keeps track of controls. It +maintains a list of v4l2_ctrl objects that it owns and another list of +references to controls, possibly to controls owned by other handlers. Basic usage for V4L2 and sub-device drivers @@ -48,21 +50,39 @@ Basic usage for V4L2 and sub-device drivers 1) Prepare the driver: +.. code-block:: c + + #include <media/v4l2-ctrls.h> + 1.1) Add the handler to your driver's top-level struct: -.. code-block:: none +For V4L2 drivers: + +.. code-block:: c struct foo_dev { ... + struct v4l2_device v4l2_dev; + ... struct v4l2_ctrl_handler ctrl_handler; ... }; - struct foo_dev *foo; +For sub-device drivers: + +.. code-block:: c + + struct foo_dev { + ... + struct v4l2_subdev sd; + ... + struct v4l2_ctrl_handler ctrl_handler; + ... + }; 1.2) Initialize the handler: -.. code-block:: none +.. code-block:: c v4l2_ctrl_handler_init(&foo->ctrl_handler, nr_of_controls); @@ -72,72 +92,48 @@ information. It is a hint only. 1.3) Hook the control handler into the driver: -1.3.1) For V4L2 drivers do this: +For V4L2 drivers: -.. code-block:: none - - struct foo_dev { - ... - struct v4l2_device v4l2_dev; - ... - struct v4l2_ctrl_handler ctrl_handler; - ... - }; +.. code-block:: c foo->v4l2_dev.ctrl_handler = &foo->ctrl_handler; -Where foo->v4l2_dev is of type struct v4l2_device. - -Finally, remove all control functions from your v4l2_ioctl_ops (if any): -vidioc_queryctrl, vidioc_query_ext_ctrl, vidioc_querymenu, vidioc_g_ctrl, -vidioc_s_ctrl, vidioc_g_ext_ctrls, vidioc_try_ext_ctrls and vidioc_s_ext_ctrls. -Those are now no longer needed. - -1.3.2) For sub-device drivers do this: - -.. code-block:: none +For sub-device drivers: - struct foo_dev { - ... - struct v4l2_subdev sd; - ... - struct v4l2_ctrl_handler ctrl_handler; - ... - }; +.. code-block:: c foo->sd.ctrl_handler = &foo->ctrl_handler; -Where foo->sd is of type struct v4l2_subdev. - 1.4) Clean up the handler at the end: -.. code-block:: none +.. code-block:: c v4l2_ctrl_handler_free(&foo->ctrl_handler); 2) Add controls: -You add non-menu controls by calling v4l2_ctrl_new_std: +You add non-menu controls by calling :c:func:`v4l2_ctrl_new_std`: -.. code-block:: none +.. code-block:: c struct v4l2_ctrl *v4l2_ctrl_new_std(struct v4l2_ctrl_handler *hdl, const struct v4l2_ctrl_ops *ops, u32 id, s32 min, s32 max, u32 step, s32 def); -Menu and integer menu controls are added by calling v4l2_ctrl_new_std_menu: +Menu and integer menu controls are added by calling +:c:func:`v4l2_ctrl_new_std_menu`: -.. code-block:: none +.. code-block:: c struct v4l2_ctrl *v4l2_ctrl_new_std_menu(struct v4l2_ctrl_handler *hdl, const struct v4l2_ctrl_ops *ops, u32 id, s32 max, s32 skip_mask, s32 def); Menu controls with a driver specific menu are added by calling -v4l2_ctrl_new_std_menu_items: +:c:func:`v4l2_ctrl_new_std_menu_items`: -.. code-block:: none +.. code-block:: c struct v4l2_ctrl *v4l2_ctrl_new_std_menu_items( struct v4l2_ctrl_handler *hdl, @@ -145,17 +141,18 @@ v4l2_ctrl_new_std_menu_items: s32 skip_mask, s32 def, const char * const *qmenu); Integer menu controls with a driver specific menu can be added by calling -v4l2_ctrl_new_int_menu: +:c:func:`v4l2_ctrl_new_int_menu`: -.. code-block:: none +.. code-block:: c struct v4l2_ctrl *v4l2_ctrl_new_int_menu(struct v4l2_ctrl_handler *hdl, const struct v4l2_ctrl_ops *ops, u32 id, s32 max, s32 def, const s64 *qmenu_int); -These functions are typically called right after the v4l2_ctrl_handler_init: +These functions are typically called right after the +:c:func:`v4l2_ctrl_handler_init`: -.. code-block:: none +.. code-block:: c static const s64 exp_bias_qmenu[] = { -2, -1, 0, 1, 2 @@ -192,33 +189,34 @@ These functions are typically called right after the v4l2_ctrl_handler_init: return err; } -The v4l2_ctrl_new_std function returns the v4l2_ctrl pointer to the new -control, but if you do not need to access the pointer outside the control ops, -then there is no need to store it. - -The v4l2_ctrl_new_std function will fill in most fields based on the control -ID except for the min, max, step and default values. These are passed in the -last four arguments. These values are driver specific while control attributes -like type, name, flags are all global. The control's current value will be set -to the default value. - -The v4l2_ctrl_new_std_menu function is very similar but it is used for menu -controls. There is no min argument since that is always 0 for menu controls, -and instead of a step there is a skip_mask argument: if bit X is 1, then menu -item X is skipped. - -The v4l2_ctrl_new_int_menu function creates a new standard integer menu -control with driver-specific items in the menu. It differs from -v4l2_ctrl_new_std_menu in that it doesn't have the mask argument and takes -as the last argument an array of signed 64-bit integers that form an exact -menu item list. - -The v4l2_ctrl_new_std_menu_items function is very similar to -v4l2_ctrl_new_std_menu but takes an extra parameter qmenu, which is the driver -specific menu for an otherwise standard menu control. A good example for this -control is the test pattern control for capture/display/sensors devices that -have the capability to generate test patterns. These test patterns are hardware -specific, so the contents of the menu will vary from device to device. +The :c:func:`v4l2_ctrl_new_std` function returns the v4l2_ctrl pointer to +the new control, but if you do not need to access the pointer outside the +control ops, then there is no need to store it. + +The :c:func:`v4l2_ctrl_new_std` function will fill in most fields based on +the control ID except for the min, max, step and default values. These are +passed in the last four arguments. These values are driver specific while +control attributes like type, name, flags are all global. The control's +current value will be set to the default value. + +The :c:func:`v4l2_ctrl_new_std_menu` function is very similar but it is +used for menu controls. There is no min argument since that is always 0 for +menu controls, and instead of a step there is a skip_mask argument: if bit +X is 1, then menu item X is skipped. + +The :c:func:`v4l2_ctrl_new_int_menu` function creates a new standard +integer menu control with driver-specific items in the menu. It differs +from v4l2_ctrl_new_std_menu in that it doesn't have the mask argument and +takes as the last argument an array of signed 64-bit integers that form an +exact menu item list. + +The :c:func:`v4l2_ctrl_new_std_menu_items` function is very similar to +v4l2_ctrl_new_std_menu but takes an extra parameter qmenu, which is the +driver specific menu for an otherwise standard menu control. A good example +for this control is the test pattern control for capture/display/sensors +devices that have the capability to generate test patterns. These test +patterns are hardware specific, so the contents of the menu will vary from +device to device. Note that if something fails, the function will return NULL or an error and set ctrl_handler->error to the error code. If ctrl_handler->error was already @@ -233,7 +231,7 @@ a bit faster that way. 3) Optionally force initial control setup: -.. code-block:: none +.. code-block:: c v4l2_ctrl_handler_setup(&foo->ctrl_handler); @@ -242,9 +240,9 @@ initializes the hardware to the default control values. It is recommended that you do this as this ensures that both the internal data structures and the hardware are in sync. -4) Finally: implement the v4l2_ctrl_ops +4) Finally: implement the :c:type:`v4l2_ctrl_ops` -.. code-block:: none +.. code-block:: c static const struct v4l2_ctrl_ops foo_ctrl_ops = { .s_ctrl = foo_s_ctrl, @@ -252,7 +250,7 @@ the hardware are in sync. Usually all you need is s_ctrl: -.. code-block:: none +.. code-block:: c static int foo_s_ctrl(struct v4l2_ctrl *ctrl) { @@ -305,7 +303,7 @@ Accessing Control Values The following union is used inside the control framework to access control values: -.. code-block:: none +.. code-block:: c union v4l2_ctrl_ptr { s32 *p_s32; @@ -317,7 +315,7 @@ values: The v4l2_ctrl struct contains these fields that can be used to access both current and new values: -.. code-block:: none +.. code-block:: c s32 val; struct { @@ -330,7 +328,7 @@ current and new values: If the control has a simple s32 type type, then: -.. code-block:: none +.. code-block:: c &ctrl->val == ctrl->p_new.p_s32 &ctrl->cur.val == ctrl->p_cur.p_s32 @@ -354,7 +352,7 @@ exception is for controls that return a volatile register such as a signal strength read-out that changes continuously. In that case you will need to implement g_volatile_ctrl like this: -.. code-block:: none +.. code-block:: c static int foo_g_volatile_ctrl(struct v4l2_ctrl *ctrl) { @@ -372,7 +370,7 @@ changes. To mark a control as volatile you have to set V4L2_CTRL_FLAG_VOLATILE: -.. code-block:: none +.. code-block:: c ctrl = v4l2_ctrl_new_std(&sd->ctrl_handler, ...); if (ctrl) @@ -393,7 +391,7 @@ not to introduce deadlocks. Outside of the control ops you have to go through to helper functions to get or set a single control value safely in your driver: -.. code-block:: none +.. code-block:: c s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl); int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val); @@ -404,7 +402,7 @@ will result in a deadlock since these helpers lock the handler as well. You can also take the handler lock yourself: -.. code-block:: none +.. code-block:: c mutex_lock(&state->ctrl_handler.lock); pr_info("String value is '%s'\n", ctrl1->p_cur.p_char); @@ -417,7 +415,7 @@ Menu Controls The v4l2_ctrl struct contains this union: -.. code-block:: none +.. code-block:: c union { u32 step; @@ -445,7 +443,7 @@ Custom Controls Driver specific controls can be created using v4l2_ctrl_new_custom(): -.. code-block:: none +.. code-block:: c static const struct v4l2_ctrl_config ctrl_filter = { .ops = &ctrl_custom_ops, @@ -499,7 +497,7 @@ By default all controls are independent from the others. But in more complex scenarios you can get dependencies from one control to another. In that case you need to 'cluster' them: -.. code-block:: none +.. code-block:: c struct foo { struct v4l2_ctrl_handler ctrl_handler; @@ -523,7 +521,7 @@ composite control. Similar to how a 'struct' works in C. So when s_ctrl is called with V4L2_CID_AUDIO_VOLUME as argument, you should set all two controls belonging to the audio_cluster: -.. code-block:: none +.. code-block:: c static int foo_s_ctrl(struct v4l2_ctrl *ctrl) { @@ -545,7 +543,7 @@ all two controls belonging to the audio_cluster: In the example above the following are equivalent for the VOLUME case: -.. code-block:: none +.. code-block:: c ctrl == ctrl->cluster[AUDIO_CL_VOLUME] == state->audio_cluster[AUDIO_CL_VOLUME] ctrl->cluster[AUDIO_CL_MUTE] == state->audio_cluster[AUDIO_CL_MUTE] @@ -553,7 +551,7 @@ In the example above the following are equivalent for the VOLUME case: In practice using cluster arrays like this becomes very tiresome. So instead the following equivalent method is used: -.. code-block:: none +.. code-block:: c struct { /* audio cluster */ @@ -565,7 +563,7 @@ The anonymous struct is used to clearly 'cluster' these two control pointers, but it serves no other purpose. The effect is the same as creating an array with two control pointers. So you can just do: -.. code-block:: none +.. code-block:: c state->volume = v4l2_ctrl_new_std(&state->ctrl_handler, ...); state->mute = v4l2_ctrl_new_std(&state->ctrl_handler, ...); @@ -621,7 +619,7 @@ changing that control affects the control flags of the manual controls. In order to simplify this a special variation of v4l2_ctrl_cluster was introduced: -.. code-block:: none +.. code-block:: c void v4l2_ctrl_auto_cluster(unsigned ncontrols, struct v4l2_ctrl **controls, u8 manual_val, bool set_volatile); @@ -676,7 +674,7 @@ of another handler (e.g. for a video device node), then you should first add the controls to the first handler, add the other controls to the second handler and finally add the first handler to the second. For example: -.. code-block:: none +.. code-block:: c v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_VOLUME, ...); v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...); @@ -690,7 +688,7 @@ all controls. Or you can add specific controls to a handler: -.. code-block:: none +.. code-block:: c volume = v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_AUDIO_VOLUME, ...); v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_BRIGHTNESS, ...); @@ -699,7 +697,7 @@ Or you can add specific controls to a handler: What you should not do is make two identical controls for two handlers. For example: -.. code-block:: none +.. code-block:: c v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...); v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_AUDIO_MUTE, ...); @@ -720,7 +718,7 @@ not own. For example, if you have to find a volume control from a subdev. You can do that by calling v4l2_ctrl_find: -.. code-block:: none +.. code-block:: c struct v4l2_ctrl *volume; @@ -729,7 +727,7 @@ You can do that by calling v4l2_ctrl_find: Since v4l2_ctrl_find will lock the handler you have to be careful where you use it. For example, this is not a good idea: -.. code-block:: none +.. code-block:: c struct v4l2_ctrl_handler ctrl_handler; @@ -738,7 +736,7 @@ use it. For example, this is not a good idea: ...and in video_ops.s_ctrl: -.. code-block:: none +.. code-block:: c case V4L2_CID_BRIGHTNESS: contrast = v4l2_find_ctrl(&ctrl_handler, V4L2_CID_CONTRAST); @@ -760,7 +758,7 @@ not when it is used in consumer-level hardware. In that case you want to keep those low-level controls local to the subdev. You can do this by simply setting the 'is_private' flag of the control to 1: -.. code-block:: none +.. code-block:: c static const struct v4l2_ctrl_config ctrl_private = { .ops = &ctrl_custom_ops, @@ -797,7 +795,7 @@ Sometimes the platform or bridge driver needs to be notified when a control from a sub-device driver changes. You can set a notify callback by calling this function: -.. code-block:: none +.. code-block:: c void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl, void (*notify)(struct v4l2_ctrl *ctrl, void *priv), void *priv); diff --git a/Documentation/media/kapi/v4l2-dev.rst b/Documentation/media/kapi/v4l2-dev.rst index b359f1804bbe..4c5a15c53dbf 100644 --- a/Documentation/media/kapi/v4l2-dev.rst +++ b/Documentation/media/kapi/v4l2-dev.rst @@ -288,6 +288,7 @@ Mask Description 0x08 Log the read and write file operations and the VIDIOC_QBUF and VIDIOC_DQBUF ioctls. 0x10 Log the poll file operation. +0x20 Log error and messages in the control operations. ===== ================================================================ Video device cleanup diff --git a/Documentation/media/uapi/cec/cec-api.rst b/Documentation/media/uapi/cec/cec-api.rst index b614bf81aa20..0780ba07995a 100644 --- a/Documentation/media/uapi/cec/cec-api.rst +++ b/Documentation/media/uapi/cec/cec-api.rst @@ -39,7 +39,7 @@ Revision and Copyright ********************** Authors: -- Verkuil, Hans <hans.verkuil@cisco.com> +- Verkuil, Hans <hverkuil-cisco@xs4all.nl> - Initial version. diff --git a/Documentation/media/uapi/cec/cec-ioc-g-mode.rst b/Documentation/media/uapi/cec/cec-ioc-g-mode.rst index c53bb5f73f0d..d0902f356d65 100644 --- a/Documentation/media/uapi/cec/cec-ioc-g-mode.rst +++ b/Documentation/media/uapi/cec/cec-ioc-g-mode.rst @@ -294,7 +294,8 @@ EINVAL The requested mode is invalid. EPERM - Monitor mode is requested without having root permissions + 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 index c3a685ff05cb..4137903d672e 100644 --- a/Documentation/media/uapi/cec/cec-ioc-receive.rst +++ b/Documentation/media/uapi/cec/cec-ioc-receive.rst @@ -223,6 +223,18 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). result of the :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`, and once via :ref:`ioctl CEC_RECEIVE <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 <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}| @@ -358,7 +370,8 @@ ENOTTY EPERM The CEC adapter is not configured, i.e. :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>` - has never been called. + 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 <CEC_ADAP_S_LOG_ADDRS>` diff --git a/Documentation/media/uapi/mediactl/media-ioc-enum-links.rst b/Documentation/media/uapi/mediactl/media-ioc-enum-links.rst index a982f16e55a4..b827ebc398f8 100644 --- a/Documentation/media/uapi/mediactl/media-ioc-enum-links.rst +++ b/Documentation/media/uapi/mediactl/media-ioc-enum-links.rst @@ -84,6 +84,11 @@ returned during the enumeration process. - 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 @@ -135,7 +140,7 @@ returned during the enumeration process. - Link flags, see :ref:`media-link-flag` for more details. * - __u32 - - ``reserved[4]`` + - ``reserved[2]`` - Reserved for future extensions. Drivers and applications must set the array to zero. diff --git a/Documentation/media/uapi/rc/lirc-dev-intro.rst b/Documentation/media/uapi/rc/lirc-dev-intro.rst index 1a901d8e1797..b68c01693939 100644 --- a/Documentation/media/uapi/rc/lirc-dev-intro.rst +++ b/Documentation/media/uapi/rc/lirc-dev-intro.rst @@ -20,6 +20,9 @@ data between userspace and kernelspace. Fundamentally, it is just a chardev 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 @@ -34,6 +37,16 @@ What you should see for a chardev: $ ls -l /dev/lirc* crw-rw---- 1 root root 248, 0 Jul 2 22:20 /dev/lirc0 +Note that the package `v4l-utils <https://git.linuxtv.org/v4l-utils.git/>`_ +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: ********** @@ -53,11 +66,12 @@ on the following table. For transmitting (aka sending), create a ``struct lirc_scancode`` with the desired scancode set in the ``scancode`` member, :c:type:`rc_proto` - set the IR protocol, and all other members set to 0. Write this struct to - the lirc device. + set to the :ref:`IR protocol <Remote_controllers_Protocols>`, 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, - with ``scancode`` set to the received scancode and the IR protocol + 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 <Remote_controllers_Protocols>` 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``. @@ -129,12 +143,29 @@ on the following table. This mode is used only for IR send. - -************************** -Remote Controller protocol -************************** - -An enum :c:type:`rc_proto` in the :ref:`lirc_header` lists all the -supported IR protocols: - -.. kernel-doc:: include/uapi/linux/lirc.h +******************** +BPF based IR decoder +******************** + +The kernel has support for decoding the most common +:ref:`IR protocols <Remote_controllers_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 <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-read.rst b/Documentation/media/uapi/rc/lirc-read.rst index a8fedfaaf0ab..256e520bc27e 100644 --- a/Documentation/media/uapi/rc/lirc-read.rst +++ b/Documentation/media/uapi/rc/lirc-read.rst @@ -62,7 +62,8 @@ read from the chardev. Alternatively, :ref:`LIRC_MODE_SCANCODE <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 -protocol used for transmission, and ``scancode`` to the decoded scancode, +:ref:`IR protocol <Remote_controllers_Protocols>` +used for transmission, and ``scancode`` to the decoded scancode, and the ``keycode`` set to the keycode or ``KEY_RESERVED``. diff --git a/Documentation/media/uapi/rc/lirc-write.rst b/Documentation/media/uapi/rc/lirc-write.rst index 6adf5ddbac99..eafe13203ea3 100644 --- a/Documentation/media/uapi/rc/lirc-write.rst +++ b/Documentation/media/uapi/rc/lirc-write.rst @@ -64,7 +64,8 @@ driver returns ``EINVAL``. When in :ref:`LIRC_MODE_SCANCODE <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 protocol in the :c:type:`rc_proto`: member. All other members must be +and the :ref:`IR protocol <Remote_controllers_Protocols>` 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 diff --git a/Documentation/media/uapi/rc/rc-protos.rst b/Documentation/media/uapi/rc/rc-protos.rst new file mode 100644 index 000000000000..b250ebe301d5 --- /dev/null +++ b/Documentation/media/uapi/rc/rc-protos.rst @@ -0,0 +1,456 @@ +.. 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-tables.rst b/Documentation/media/uapi/rc/rc-tables.rst index 177ac44fa0fa..20d7c686922b 100644 --- a/Documentation/media/uapi/rc/rc-tables.rst +++ b/Documentation/media/uapi/rc/rc-tables.rst @@ -54,7 +54,7 @@ the remote via /dev/input/event devices. - .. row 3 - - ``KEY_0`` + - ``KEY_NUMERIC_0`` - Keyboard digit 0 @@ -62,7 +62,7 @@ the remote via /dev/input/event devices. - .. row 4 - - ``KEY_1`` + - ``KEY_NUMERIC_1`` - Keyboard digit 1 @@ -70,7 +70,7 @@ the remote via /dev/input/event devices. - .. row 5 - - ``KEY_2`` + - ``KEY_NUMERIC_2`` - Keyboard digit 2 @@ -78,7 +78,7 @@ the remote via /dev/input/event devices. - .. row 6 - - ``KEY_3`` + - ``KEY_NUMERIC_3`` - Keyboard digit 3 @@ -86,7 +86,7 @@ the remote via /dev/input/event devices. - .. row 7 - - ``KEY_4`` + - ``KEY_NUMERIC_4`` - Keyboard digit 4 @@ -94,7 +94,7 @@ the remote via /dev/input/event devices. - .. row 8 - - ``KEY_5`` + - ``KEY_NUMERIC_5`` - Keyboard digit 5 @@ -102,7 +102,7 @@ the remote via /dev/input/event devices. - .. row 9 - - ``KEY_6`` + - ``KEY_NUMERIC_6`` - Keyboard digit 6 @@ -110,7 +110,7 @@ the remote via /dev/input/event devices. - .. row 10 - - ``KEY_7`` + - ``KEY_NUMERIC_7`` - Keyboard digit 7 @@ -118,7 +118,7 @@ the remote via /dev/input/event devices. - .. row 11 - - ``KEY_8`` + - ``KEY_NUMERIC_8`` - Keyboard digit 8 @@ -126,7 +126,7 @@ the remote via /dev/input/event devices. - .. row 12 - - ``KEY_9`` + - ``KEY_NUMERIC_9`` - Keyboard digit 9 @@ -196,7 +196,7 @@ the remote via /dev/input/event devices. - ``KEY_PAUSE`` - - Pause sroweam + - Pause stream - PAUSE / FREEZE @@ -220,7 +220,7 @@ the remote via /dev/input/event devices. - ``KEY_STOP`` - - Stop sroweam + - Stop stream - STOP @@ -228,7 +228,7 @@ the remote via /dev/input/event devices. - ``KEY_RECORD`` - - Start/stop recording sroweam + - Start/stop recording stream - CAPTURE / REC / RECORD/PAUSE @@ -577,7 +577,7 @@ the remote via /dev/input/event devices. - ``KEY_CLEAR`` - - Stop sroweam and return to default input video/audio + - Stop stream and return to default input video/audio - CLEAR / RESET / BOSS KEY @@ -593,7 +593,7 @@ the remote via /dev/input/event devices. - ``KEY_FAVORITES`` - - Open the favorites sroweam window + - Open the favorites stream window - TV WALL / Favorites diff --git a/Documentation/media/uapi/rc/remote_controllers.rst b/Documentation/media/uapi/rc/remote_controllers.rst index 3051f7abe11d..20e0f986df49 100644 --- a/Documentation/media/uapi/rc/remote_controllers.rst +++ b/Documentation/media/uapi/rc/remote_controllers.rst @@ -27,6 +27,7 @@ Part III - Remote Controller API rc-intro rc-sysfs-nodes + rc-protos rc-tables rc-table-change lirc-dev diff --git a/Documentation/media/uapi/v4l/biblio.rst b/Documentation/media/uapi/v4l/biblio.rst index ec33768c055e..ad2ff258afa8 100644 --- a/Documentation/media/uapi/v4l/biblio.rst +++ b/Documentation/media/uapi/v4l/biblio.rst @@ -122,6 +122,15 @@ ITU BT.1119 :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) + .. _jfif: JFIF @@ -386,3 +395,13 @@ 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/control.rst b/Documentation/media/uapi/v4l/control.rst index 71417bba028c..ef62e088ff7a 100644 --- a/Documentation/media/uapi/v4l/control.rst +++ b/Documentation/media/uapi/v4l/control.rst @@ -295,7 +295,7 @@ Control IDs Sets the alpha color component. When a capture device (or capture queue of a mem-to-mem device) produces a frame format that includes an alpha component (e.g. - :ref:`packed RGB image formats <rgb-formats>`) and the alpha value + :ref:`packed RGB image formats <pixfmt-rgb>`) 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) diff --git a/Documentation/media/uapi/v4l/dev-decoder.rst b/Documentation/media/uapi/v4l/dev-decoder.rst new file mode 100644 index 000000000000..606b54947e10 --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-decoder.rst @@ -0,0 +1,1101 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _decoder: + +************************************************* +Memory-to-Memory Stateful Video Decoder Interface +************************************************* + +A stateful video decoder takes complete chunks of the bytestream (e.g. Annex-B +H.264/HEVC stream, raw VP8/9 stream) and decodes them into raw video frames in +display order. The decoder is expected not to require any additional information +from the client to process these buffers. + +Performing software parsing, processing etc. of the stream in the driver in +order to support this interface is strongly discouraged. In case such +operations are needed, use of the Stateless Video Decoder Interface (in +development) is strongly advised. + +Conventions and Notations Used in This Document +=============================================== + +1. The general V4L2 API rules apply if not specified in this document + otherwise. + +2. The meaning of words "must", "may", "should", etc. is as per `RFC + 2119 <https://tools.ietf.org/html/rfc2119>`_. + +3. All steps not marked "optional" are required. + +4. :c:func:`VIDIOC_G_EXT_CTRLS` and :c:func:`VIDIOC_S_EXT_CTRLS` may be used + interchangeably with :c:func:`VIDIOC_G_CTRL` and :c:func:`VIDIOC_S_CTRL`, + unless specified otherwise. + +5. Single-planar API (see :ref:`planar-apis`) and applicable structures may be + used interchangeably with multi-planar API, unless specified otherwise, + depending on decoder capabilities and following the general V4L2 guidelines. + +6. i = [a..b]: sequence of integers from a to b, inclusive, i.e. i = + [0..2]: i = 0, 1, 2. + +7. Given an ``OUTPUT`` buffer A, then A’ represents a buffer on the ``CAPTURE`` + queue containing data that resulted from processing buffer A. + +.. _decoder-glossary: + +Glossary +======== + +CAPTURE + the destination buffer queue; for decoders, the queue of buffers containing + decoded frames; for encoders, the queue of buffers containing an encoded + bytestream; ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or + ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``; data is captured from the hardware + into ``CAPTURE`` buffers. + +client + the application communicating with the decoder or encoder implementing + this interface. + +coded format + encoded/compressed video bytestream format (e.g. H.264, VP8, etc.); see + also: raw format. + +coded height + height for given coded resolution. + +coded resolution + stream resolution in pixels aligned to codec and hardware requirements; + typically visible resolution rounded up to full macroblocks; + see also: visible resolution. + +coded width + width for given coded resolution. + +decode order + the order in which frames are decoded; may differ from display order if the + coded format includes a feature of frame reordering; for decoders, + ``OUTPUT`` buffers must be queued by the client in decode order; for + encoders ``CAPTURE`` buffers must be returned by the encoder in decode order. + +destination + data resulting from the decode process; see ``CAPTURE``. + +display order + the order in which frames must be displayed; for encoders, ``OUTPUT`` + buffers must be queued by the client in display order; for decoders, + ``CAPTURE`` buffers must be returned by the decoder in display order. + +DPB + Decoded Picture Buffer; an H.264/HEVC term for a buffer that stores a decoded + raw frame available for reference in further decoding steps. + +EOS + end of stream. + +IDR + Instantaneous Decoder Refresh; a type of a keyframe in an H.264/HEVC-encoded + stream, which clears the list of earlier reference frames (DPBs). + +keyframe + an encoded frame that does not reference frames decoded earlier, i.e. + can be decoded fully on its own. + +macroblock + a processing unit in image and video compression formats based on linear + block transforms (e.g. H.264, VP8, VP9); codec-specific, but for most of + popular codecs the size is 16x16 samples (pixels). + +OUTPUT + the source buffer queue; for decoders, the queue of buffers containing + an encoded bytestream; for encoders, the queue of buffers containing raw + frames; ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or + ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``; the hardware is fed with data + from ``OUTPUT`` buffers. + +PPS + Picture Parameter Set; a type of metadata entity in an H.264/HEVC bytestream. + +raw format + uncompressed format containing raw pixel data (e.g. YUV, RGB formats). + +resume point + a point in the bytestream from which decoding may start/continue, without + any previous state/data present, e.g.: a keyframe (VP8/VP9) or + SPS/PPS/IDR sequence (H.264/HEVC); a resume point is required to start decode + of a new stream, or to resume decoding after a seek. + +source + data fed to the decoder or encoder; see ``OUTPUT``. + +source height + height in pixels for given source resolution; relevant to encoders only. + +source resolution + resolution in pixels of source frames being source to the encoder and + subject to further cropping to the bounds of visible resolution; relevant to + encoders only. + +source width + width in pixels for given source resolution; relevant to encoders only. + +SPS + Sequence Parameter Set; a type of metadata entity in an H.264/HEVC bytestream. + +stream metadata + additional (non-visual) information contained inside encoded bytestream; + for example: coded resolution, visible resolution, codec profile. + +visible height + height for given visible resolution; display height. + +visible resolution + stream resolution of the visible picture, in pixels, to be used for + display purposes; must be smaller or equal to coded resolution; + display resolution. + +visible width + width for given visible resolution; display width. + +State Machine +============= + +.. kernel-render:: DOT + :alt: DOT digraph of decoder state machine + :caption: Decoder State Machine + + digraph decoder_state_machine { + node [shape = doublecircle, label="Decoding"] Decoding; + + node [shape = circle, label="Initialization"] Initialization; + node [shape = circle, label="Capture\nsetup"] CaptureSetup; + node [shape = circle, label="Dynamic\nResolution\nChange"] ResChange; + node [shape = circle, label="Stopped"] Stopped; + node [shape = circle, label="Drain"] Drain; + node [shape = circle, label="Seek"] Seek; + node [shape = circle, label="End of Stream"] EoS; + + node [shape = point]; qi + qi -> Initialization [ label = "open()" ]; + + Initialization -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ]; + + CaptureSetup -> Stopped [ label = "CAPTURE\nbuffers\nready" ]; + + Decoding -> ResChange [ label = "Stream\nresolution\nchange" ]; + Decoding -> Drain [ label = "V4L2_DEC_CMD_STOP" ]; + Decoding -> EoS [ label = "EoS mark\nin the stream" ]; + Decoding -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ]; + Decoding -> Stopped [ label = "VIDIOC_STREAMOFF(CAPTURE)" ]; + Decoding -> Decoding; + + ResChange -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ]; + ResChange -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ]; + + EoS -> Drain [ label = "Implicit\ndrain" ]; + + Drain -> Stopped [ label = "All CAPTURE\nbuffers dequeued\nor\nVIDIOC_STREAMOFF(CAPTURE)" ]; + Drain -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ]; + + Seek -> Decoding [ label = "VIDIOC_STREAMON(OUTPUT)" ]; + Seek -> Initialization [ label = "VIDIOC_REQBUFS(OUTPUT, 0)" ]; + + Stopped -> Decoding [ label = "V4L2_DEC_CMD_START\nor\nVIDIOC_STREAMON(CAPTURE)" ]; + Stopped -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ]; + } + +Querying Capabilities +===================== + +1. To enumerate the set of coded formats supported by the decoder, the + client may call :c:func:`VIDIOC_ENUM_FMT` on ``OUTPUT``. + + * The full set of supported formats will be returned, regardless of the + format set on ``CAPTURE``. + * Check the flags field of :c:type:`v4l2_fmtdesc` for more information + about the decoder's capabilities with respect to each coded format. + In particular whether or not the decoder has a full-fledged bytestream + parser and if the decoder supports dynamic resolution changes. + +2. To enumerate the set of supported raw formats, the client may call + :c:func:`VIDIOC_ENUM_FMT` on ``CAPTURE``. + + * Only the formats supported for the format currently active on ``OUTPUT`` + will be returned. + + * In order to enumerate raw formats supported by a given coded format, + the client must first set that coded format on ``OUTPUT`` and then + enumerate formats on ``CAPTURE``. + +3. The client may use :c:func:`VIDIOC_ENUM_FRAMESIZES` to detect supported + resolutions for a given format, passing desired pixel format in + :c:type:`v4l2_frmsizeenum` ``pixel_format``. + + * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a coded pixel + format will include all possible coded resolutions supported by the + decoder for given coded pixel format. + + * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a raw pixel format + will include all possible frame buffer resolutions supported by the + decoder for given raw pixel format and the coded format currently set on + ``OUTPUT``. + +4. Supported profiles and levels for the coded format currently set on + ``OUTPUT``, if applicable, may be queried using their respective controls + via :c:func:`VIDIOC_QUERYCTRL`. + +Initialization +============== + +1. Set the coded format on ``OUTPUT`` via :c:func:`VIDIOC_S_FMT` + + * **Required fields:** + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. + + ``pixelformat`` + a coded pixel format. + + ``width``, ``height`` + coded resolution of the stream; required only if it cannot be parsed + from the stream for the given coded format; otherwise the decoder will + use this resolution as a placeholder resolution that will likely change + as soon as it can parse the actual coded resolution from the stream. + + ``sizeimage`` + desired size of ``OUTPUT`` buffers; the decoder may adjust it to + match hardware requirements. + + other fields + follow standard semantics. + + * **Return fields:** + + ``sizeimage`` + adjusted size of ``OUTPUT`` buffers. + + * The ``CAPTURE`` format will be updated with an appropriate frame buffer + resolution instantly based on the width and height returned by + :c:func:`VIDIOC_S_FMT`. + However, for coded formats that include stream resolution information, + after the decoder is done parsing the information from the stream, it will + update the ``CAPTURE`` format with new values and signal a source change + event, regardless of whether they match the values set by the client or + not. + + .. important:: + + Changing the ``OUTPUT`` format may change the currently set ``CAPTURE`` + format. How the new ``CAPTURE`` format is determined is up to the decoder + and the client must ensure it matches its needs afterwards. + +2. Allocate source (bytestream) buffers via :c:func:`VIDIOC_REQBUFS` on + ``OUTPUT``. + + * **Required fields:** + + ``count`` + requested number of buffers to allocate; greater than zero. + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. + + ``memory`` + follows standard semantics. + + * **Return fields:** + + ``count`` + the actual number of buffers allocated. + + .. warning:: + + The actual number of allocated buffers may differ from the ``count`` + given. The client must check the updated value of ``count`` after the + call returns. + + Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``OUTPUT`` queue can be + used to have more control over buffer allocation. + + * **Required fields:** + + ``count`` + requested number of buffers to allocate; greater than zero. + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. + + ``memory`` + follows standard semantics. + + ``format`` + follows standard semantics. + + * **Return fields:** + + ``count`` + adjusted to the number of allocated buffers. + + .. warning:: + + The actual number of allocated buffers may differ from the ``count`` + given. The client must check the updated value of ``count`` after the + call returns. + +3. Start streaming on the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`. + +4. **This step only applies to coded formats that contain resolution information + in the stream.** Continue queuing/dequeuing bytestream buffers to/from the + ``OUTPUT`` queue via :c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`. The + buffers will be processed and returned to the client in order, until + required metadata to configure the ``CAPTURE`` queue are found. This is + indicated by the decoder sending a ``V4L2_EVENT_SOURCE_CHANGE`` event with + ``changes`` set to ``V4L2_EVENT_SRC_CH_RESOLUTION``. + + * It is not an error if the first buffer does not contain enough data for + this to occur. Processing of the buffers will continue as long as more + data is needed. + + * If data in a buffer that triggers the event is required to decode the + first frame, it will not be returned to the client, until the + initialization sequence completes and the frame is decoded. + + * If the client has not set the coded resolution of the stream on its own, + calling :c:func:`VIDIOC_G_FMT`, :c:func:`VIDIOC_S_FMT`, + :c:func:`VIDIOC_TRY_FMT` or :c:func:`VIDIOC_REQBUFS` on the ``CAPTURE`` + queue will not return the real values for the stream until a + ``V4L2_EVENT_SOURCE_CHANGE`` event with ``changes`` set to + ``V4L2_EVENT_SRC_CH_RESOLUTION`` is signaled. + + .. important:: + + Any client query issued after the decoder queues the event will return + values applying to the just parsed stream, including queue formats, + selection rectangles and controls. + + .. note:: + + A client capable of acquiring stream parameters from the bytestream on + its own may attempt to set the width and height of the ``OUTPUT`` format + to non-zero values matching the coded size of the stream, skip this step + and continue with the `Capture Setup` sequence. However, it must not + rely on any driver queries regarding stream parameters, such as + selection rectangles and controls, since the decoder has not parsed them + from the stream yet. If the values configured by the client do not match + those parsed by the decoder, a `Dynamic Resolution Change` will be + triggered to reconfigure them. + + .. note:: + + No decoded frames are produced during this phase. + +5. Continue with the `Capture Setup` sequence. + +Capture Setup +============= + +1. Call :c:func:`VIDIOC_G_FMT` on the ``CAPTURE`` queue to get format for the + destination buffers parsed/decoded from the bytestream. + + * **Required fields:** + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``. + + * **Return fields:** + + ``width``, ``height`` + frame buffer resolution for the decoded frames. + + ``pixelformat`` + pixel format for decoded frames. + + ``num_planes`` (for _MPLANE ``type`` only) + number of planes for pixelformat. + + ``sizeimage``, ``bytesperline`` + as per standard semantics; matching frame buffer format. + + .. note:: + + The value of ``pixelformat`` may be any pixel format supported by the + decoder for the current stream. The decoder should choose a + preferred/optimal format for the default configuration. For example, a + YUV format may be preferred over an RGB format if an additional + conversion step would be required for the latter. + +2. **Optional.** Acquire the visible resolution via + :c:func:`VIDIOC_G_SELECTION`. + + * **Required fields:** + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``. + + ``target`` + set to ``V4L2_SEL_TGT_COMPOSE``. + + * **Return fields:** + + ``r.left``, ``r.top``, ``r.width``, ``r.height`` + the visible rectangle; it must fit within the frame buffer resolution + returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``. + + * The following selection targets are supported on ``CAPTURE``: + + ``V4L2_SEL_TGT_CROP_BOUNDS`` + corresponds to the coded resolution of the stream. + + ``V4L2_SEL_TGT_CROP_DEFAULT`` + the rectangle covering the part of the ``CAPTURE`` buffer that + contains meaningful picture data (visible area); width and height + will be equal to the visible resolution of the stream. + + ``V4L2_SEL_TGT_CROP`` + the rectangle within the coded resolution to be output to + ``CAPTURE``; defaults to ``V4L2_SEL_TGT_CROP_DEFAULT``; read-only on + hardware without additional compose/scaling capabilities. + + ``V4L2_SEL_TGT_COMPOSE_BOUNDS`` + the maximum rectangle within a ``CAPTURE`` buffer, which the cropped + frame can be composed into; equal to ``V4L2_SEL_TGT_CROP`` if the + hardware does not support compose/scaling. + + ``V4L2_SEL_TGT_COMPOSE_DEFAULT`` + equal to ``V4L2_SEL_TGT_CROP``. + + ``V4L2_SEL_TGT_COMPOSE`` + the rectangle inside a ``CAPTURE`` buffer into which the cropped + frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``; + read-only on hardware without additional compose/scaling capabilities. + + ``V4L2_SEL_TGT_COMPOSE_PADDED`` + the rectangle inside a ``CAPTURE`` buffer which is overwritten by the + hardware; equal to ``V4L2_SEL_TGT_COMPOSE`` if the hardware does not + write padding pixels. + + .. warning:: + + The values are guaranteed to be meaningful only after the decoder + successfully parses the stream metadata. The client must not rely on the + query before that happens. + +3. **Optional.** Enumerate ``CAPTURE`` formats via :c:func:`VIDIOC_ENUM_FMT` on + the ``CAPTURE`` queue. Once the stream information is parsed and known, the + client may use this ioctl to discover which raw formats are supported for + given stream and select one of them via :c:func:`VIDIOC_S_FMT`. + + .. important:: + + The decoder will return only formats supported for the currently + established coded format, as per the ``OUTPUT`` format and/or stream + metadata parsed in this initialization sequence, even if more formats + may be supported by the decoder in general. In other words, the set + returned will be a subset of the initial query mentioned in the + `Querying Capabilities` section. + + For example, a decoder may support YUV and RGB formats for resolutions + 1920x1088 and lower, but only YUV for higher resolutions (due to + hardware limitations). After parsing a resolution of 1920x1088 or lower, + :c:func:`VIDIOC_ENUM_FMT` may return a set of YUV and RGB pixel formats, + but after parsing resolution higher than 1920x1088, the decoder will not + return RGB, unsupported for this resolution. + + However, subsequent resolution change event triggered after + discovering a resolution change within the same stream may switch + the stream into a lower resolution and :c:func:`VIDIOC_ENUM_FMT` + would return RGB formats again in that case. + +4. **Optional.** Set the ``CAPTURE`` format via :c:func:`VIDIOC_S_FMT` on the + ``CAPTURE`` queue. The client may choose a different format than + selected/suggested by the decoder in :c:func:`VIDIOC_G_FMT`. + + * **Required fields:** + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``. + + ``pixelformat`` + a raw pixel format. + + ``width``, ``height`` + frame buffer resolution of the decoded stream; typically unchanged from + what was returned with :c:func:`VIDIOC_G_FMT`, but it may be different + if the hardware supports composition and/or scaling. + + * Setting the ``CAPTURE`` format will reset the compose selection rectangles + to their default values, based on the new resolution, as described in the + previous step. + +5. **Optional.** Set the compose rectangle via :c:func:`VIDIOC_S_SELECTION` on + the ``CAPTURE`` queue if it is desired and if the decoder has compose and/or + scaling capabilities. + + * **Required fields:** + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``. + + ``target`` + set to ``V4L2_SEL_TGT_COMPOSE``. + + ``r.left``, ``r.top``, ``r.width``, ``r.height`` + the rectangle inside a ``CAPTURE`` buffer into which the cropped + frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``; + read-only on hardware without additional compose/scaling capabilities. + + * **Return fields:** + + ``r.left``, ``r.top``, ``r.width``, ``r.height`` + the visible rectangle; it must fit within the frame buffer resolution + returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``. + + .. warning:: + + The decoder may adjust the compose rectangle to the nearest + supported one to meet codec and hardware requirements. The client needs + to check the adjusted rectangle returned by :c:func:`VIDIOC_S_SELECTION`. + +6. If all the following conditions are met, the client may resume the decoding + instantly: + + * ``sizeimage`` of the new format (determined in previous steps) is less + than or equal to the size of currently allocated buffers, + + * the number of buffers currently allocated is greater than or equal to the + minimum number of buffers acquired in previous steps. To fulfill this + requirement, the client may use :c:func:`VIDIOC_CREATE_BUFS` to add new + buffers. + + In that case, the remaining steps do not apply and the client may resume + the decoding by one of the following actions: + + * if the ``CAPTURE`` queue is streaming, call :c:func:`VIDIOC_DECODER_CMD` + with the ``V4L2_DEC_CMD_START`` command, + + * if the ``CAPTURE`` queue is not streaming, call :c:func:`VIDIOC_STREAMON` + on the ``CAPTURE`` queue. + + However, if the client intends to change the buffer set, to lower + memory usage or for any other reasons, it may be achieved by following + the steps below. + +7. **If the** ``CAPTURE`` **queue is streaming,** keep queuing and dequeuing + buffers on the ``CAPTURE`` queue until a buffer marked with the + ``V4L2_BUF_FLAG_LAST`` flag is dequeued. + +8. **If the** ``CAPTURE`` **queue is streaming,** call :c:func:`VIDIOC_STREAMOFF` + on the ``CAPTURE`` queue to stop streaming. + + .. warning:: + + The ``OUTPUT`` queue must remain streaming. Calling + :c:func:`VIDIOC_STREAMOFF` on it would abort the sequence and trigger a + seek. + +9. **If the** ``CAPTURE`` **queue has buffers allocated,** free the ``CAPTURE`` + buffers using :c:func:`VIDIOC_REQBUFS`. + + * **Required fields:** + + ``count`` + set to 0. + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``. + + ``memory`` + follows standard semantics. + +10. Allocate ``CAPTURE`` buffers via :c:func:`VIDIOC_REQBUFS` on the + ``CAPTURE`` queue. + + * **Required fields:** + + ``count`` + requested number of buffers to allocate; greater than zero. + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``. + + ``memory`` + follows standard semantics. + + * **Return fields:** + + ``count`` + actual number of buffers allocated. + + .. warning:: + + The actual number of allocated buffers may differ from the ``count`` + given. The client must check the updated value of ``count`` after the + call returns. + + .. note:: + + To allocate more than the minimum number of buffers (for pipeline + depth), the client may query the ``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE`` + control to get the minimum number of buffers required, and pass the + obtained value plus the number of additional buffers needed in the + ``count`` field to :c:func:`VIDIOC_REQBUFS`. + + Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``CAPTURE`` queue can be + used to have more control over buffer allocation. For example, by + allocating buffers larger than the current ``CAPTURE`` format, future + resolution changes can be accommodated. + + * **Required fields:** + + ``count`` + requested number of buffers to allocate; greater than zero. + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``. + + ``memory`` + follows standard semantics. + + ``format`` + a format representing the maximum framebuffer resolution to be + accommodated by newly allocated buffers. + + * **Return fields:** + + ``count`` + adjusted to the number of allocated buffers. + + .. warning:: + + The actual number of allocated buffers may differ from the ``count`` + given. The client must check the updated value of ``count`` after the + call returns. + + .. note:: + + To allocate buffers for a format different than parsed from the stream + metadata, the client must proceed as follows, before the metadata + parsing is initiated: + + * set width and height of the ``OUTPUT`` format to desired coded resolution to + let the decoder configure the ``CAPTURE`` format appropriately, + + * query the ``CAPTURE`` format using :c:func:`VIDIOC_G_FMT` and save it + until this step. + + The format obtained in the query may be then used with + :c:func:`VIDIOC_CREATE_BUFS` in this step to allocate the buffers. + +11. Call :c:func:`VIDIOC_STREAMON` on the ``CAPTURE`` queue to start decoding + frames. + +Decoding +======== + +This state is reached after the `Capture Setup` sequence finishes successfully. +In this state, the client queues and dequeues buffers to both queues via +:c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`, following the standard +semantics. + +The content of the source ``OUTPUT`` buffers depends on the active coded pixel +format and may be affected by codec-specific extended controls, as stated in +the documentation of each format. + +Both queues operate independently, following the standard behavior of V4L2 +buffer queues and memory-to-memory devices. In addition, the order of decoded +frames dequeued from the ``CAPTURE`` queue may differ from the order of queuing +coded frames to the ``OUTPUT`` queue, due to properties of the selected coded +format, e.g. frame reordering. + +The client must not assume any direct relationship between ``CAPTURE`` +and ``OUTPUT`` buffers and any specific timing of buffers becoming +available to dequeue. Specifically: + +* a buffer queued to ``OUTPUT`` may result in no buffers being produced + on ``CAPTURE`` (e.g. if it does not contain encoded data, or if only + metadata syntax structures are present in it), + +* a buffer queued to ``OUTPUT`` may result in more than one buffer produced + on ``CAPTURE`` (if the encoded data contained more than one frame, or if + returning a decoded frame allowed the decoder to return a frame that + preceded it in decode, but succeeded it in the display order), + +* a buffer queued to ``OUTPUT`` may result in a buffer being produced on + ``CAPTURE`` later into decode process, and/or after processing further + ``OUTPUT`` buffers, or be returned out of order, e.g. if display + reordering is used, + +* buffers may become available on the ``CAPTURE`` queue without additional + buffers queued to ``OUTPUT`` (e.g. during drain or ``EOS``), because of the + ``OUTPUT`` buffers queued in the past whose decoding results are only + available at later time, due to specifics of the decoding process. + +.. note:: + + To allow matching decoded ``CAPTURE`` buffers with ``OUTPUT`` buffers they + originated from, the client can set the ``timestamp`` field of the + :c:type:`v4l2_buffer` struct when queuing an ``OUTPUT`` buffer. The + ``CAPTURE`` buffer(s), which resulted from decoding that ``OUTPUT`` buffer + will have their ``timestamp`` field set to the same value when dequeued. + + In addition to the straightforward case of one ``OUTPUT`` buffer producing + one ``CAPTURE`` buffer, the following cases are defined: + + * one ``OUTPUT`` buffer generates multiple ``CAPTURE`` buffers: the same + ``OUTPUT`` timestamp will be copied to multiple ``CAPTURE`` buffers. + + * multiple ``OUTPUT`` buffers generate one ``CAPTURE`` buffer: timestamp of + the ``OUTPUT`` buffer queued first will be copied. + + * the decoding order differs from the display order (i.e. the ``CAPTURE`` + buffers are out-of-order compared to the ``OUTPUT`` buffers): ``CAPTURE`` + timestamps will not retain the order of ``OUTPUT`` timestamps. + +During the decoding, the decoder may initiate one of the special sequences, as +listed below. The sequences will result in the decoder returning all the +``CAPTURE`` buffers that originated from all the ``OUTPUT`` buffers processed +before the sequence started. Last of the buffers will have the +``V4L2_BUF_FLAG_LAST`` flag set. To determine the sequence to follow, the client +must check if there is any pending event and: + +* if a ``V4L2_EVENT_SOURCE_CHANGE`` event with ``changes`` set to + ``V4L2_EVENT_SRC_CH_RESOLUTION`` is pending, the `Dynamic Resolution + Change` sequence needs to be followed, + +* if a ``V4L2_EVENT_EOS`` event is pending, the `End of Stream` sequence needs + to be followed. + +Some of the sequences can be intermixed with each other and need to be handled +as they happen. The exact operation is documented for each sequence. + +Should a decoding error occur, it will be reported to the client with the level +of details depending on the decoder capabilities. Specifically: + +* the CAPTURE buffer that contains the results of the failed decode operation + will be returned with the V4L2_BUF_FLAG_ERROR flag set, + +* if the decoder is able to precisely report the OUTPUT buffer that triggered + the error, such buffer will be returned with the V4L2_BUF_FLAG_ERROR flag + set. + +In case of a fatal failure that does not allow the decoding to continue, any +further operations on corresponding decoder file handle will return the -EIO +error code. The client may close the file handle and open a new one, or +alternatively reinitialize the instance by stopping streaming on both queues, +releasing all buffers and performing the Initialization sequence again. + +Seek +==== + +Seek is controlled by the ``OUTPUT`` queue, as it is the source of coded data. +The seek does not require any specific operation on the ``CAPTURE`` queue, but +it may be affected as per normal decoder operation. + +1. Stop the ``OUTPUT`` queue to begin the seek sequence via + :c:func:`VIDIOC_STREAMOFF`. + + * **Required fields:** + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. + + * The decoder will drop all the pending ``OUTPUT`` buffers and they must be + treated as returned to the client (following standard semantics). + +2. Restart the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON` + + * **Required fields:** + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. + + * The decoder will start accepting new source bytestream buffers after the + call returns. + +3. Start queuing buffers containing coded data after the seek to the ``OUTPUT`` + queue until a suitable resume point is found. + + .. note:: + + There is no requirement to begin queuing coded data starting exactly + from a resume point (e.g. SPS or a keyframe). Any queued ``OUTPUT`` + buffers will be processed and returned to the client until a suitable + resume point is found. While looking for a resume point, the decoder + should not produce any decoded frames into ``CAPTURE`` buffers. + + Some hardware is known to mishandle seeks to a non-resume point. Such an + operation may result in an unspecified number of corrupted decoded frames + being made available on the ``CAPTURE`` queue. Drivers must ensure that + no fatal decoding errors or crashes occur, and implement any necessary + handling and workarounds for hardware issues related to seek operations. + + .. warning:: + + In case of the H.264/HEVC codec, the client must take care not to seek + over a change of SPS/PPS. Even though the target frame could be a + keyframe, the stale SPS/PPS inside decoder state would lead to undefined + results when decoding. Although the decoder must handle that case without + a crash or a fatal decode error, the client must not expect a sensible + decode output. + + If the hardware can detect such corrupted decoded frames, then + corresponding buffers will be returned to the client with the + V4L2_BUF_FLAG_ERROR set. See the `Decoding` section for further + description of decode error reporting. + +4. After a resume point is found, the decoder will start returning ``CAPTURE`` + buffers containing decoded frames. + +.. important:: + + A seek may result in the `Dynamic Resolution Change` sequence being + initiated, due to the seek target having decoding parameters different from + the part of the stream decoded before the seek. The sequence must be handled + as per normal decoder operation. + +.. warning:: + + It is not specified when the ``CAPTURE`` queue starts producing buffers + containing decoded data from the ``OUTPUT`` buffers queued after the seek, + as it operates independently from the ``OUTPUT`` queue. + + The decoder may return a number of remaining ``CAPTURE`` buffers containing + decoded frames originating from the ``OUTPUT`` buffers queued before the + seek sequence is performed. + + The ``VIDIOC_STREAMOFF`` operation discards any remaining queued + ``OUTPUT`` buffers, which means that not all of the ``OUTPUT`` buffers + queued before the seek sequence may have matching ``CAPTURE`` buffers + produced. For example, given the sequence of operations on the + ``OUTPUT`` queue: + + QBUF(A), QBUF(B), STREAMOFF(), STREAMON(), QBUF(G), QBUF(H), + + any of the following results on the ``CAPTURE`` queue is allowed: + + {A’, B’, G’, H’}, {A’, G’, H’}, {G’, H’}. + + To determine the CAPTURE buffer containing the first decoded frame after the + seek, the client may observe the timestamps to match the CAPTURE and OUTPUT + buffers or use V4L2_DEC_CMD_STOP and V4L2_DEC_CMD_START to drain the + decoder. + +.. note:: + + To achieve instantaneous seek, the client may restart streaming on the + ``CAPTURE`` queue too to discard decoded, but not yet dequeued buffers. + +Dynamic Resolution Change +========================= + +Streams that include resolution metadata in the bytestream may require switching +to a different resolution during the decoding. + +.. note:: + + Not all decoders can detect resolution changes. Those that do set the + ``V4L2_FMT_FLAG_DYN_RESOLUTION`` flag for the coded format when + :c:func:`VIDIOC_ENUM_FMT` is called. + +The sequence starts when the decoder detects a coded frame with one or more of +the following parameters different from those previously established (and +reflected by corresponding queries): + +* coded resolution (``OUTPUT`` width and height), + +* visible resolution (selection rectangles), + +* the minimum number of buffers needed for decoding. + +Whenever that happens, the decoder must proceed as follows: + +1. After encountering a resolution change in the stream, the decoder sends a + ``V4L2_EVENT_SOURCE_CHANGE`` event with ``changes`` set to + ``V4L2_EVENT_SRC_CH_RESOLUTION``. + + .. important:: + + Any client query issued after the decoder queues the event will return + values applying to the stream after the resolution change, including + queue formats, selection rectangles and controls. + +2. The decoder will then process and decode all remaining buffers from before + the resolution change point. + + * The last buffer from before the change must be marked with the + ``V4L2_BUF_FLAG_LAST`` flag, similarly to the `Drain` sequence above. + + .. warning:: + + The last buffer may be empty (with :c:type:`v4l2_buffer` ``bytesused`` + = 0) and in that case it must be ignored by the client, as it does not + contain a decoded frame. + + .. note:: + + Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer marked + with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from + :c:func:`VIDIOC_DQBUF`. + +The client must continue the sequence as described below to continue the +decoding process. + +1. Dequeue the source change event. + + .. important:: + + A source change triggers an implicit decoder drain, similar to the + explicit `Drain` sequence. The decoder is stopped after it completes. + The decoding process must be resumed with either a pair of calls to + :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the + ``CAPTURE`` queue, or a call to :c:func:`VIDIOC_DECODER_CMD` with the + ``V4L2_DEC_CMD_START`` command. + +2. Continue with the `Capture Setup` sequence. + +.. note:: + + During the resolution change sequence, the ``OUTPUT`` queue must remain + streaming. Calling :c:func:`VIDIOC_STREAMOFF` on the ``OUTPUT`` queue would + abort the sequence and initiate a seek. + + In principle, the ``OUTPUT`` queue operates separately from the ``CAPTURE`` + queue and this remains true for the duration of the entire resolution change + sequence as well. + + The client should, for best performance and simplicity, keep queuing/dequeuing + buffers to/from the ``OUTPUT`` queue even while processing this sequence. + +Drain +===== + +To ensure that all queued ``OUTPUT`` buffers have been processed and related +``CAPTURE`` buffers are given to the client, the client must follow the drain +sequence described below. After the drain sequence ends, the client has +received all decoded frames for all ``OUTPUT`` buffers queued before the +sequence was started. + +1. Begin drain by issuing :c:func:`VIDIOC_DECODER_CMD`. + + * **Required fields:** + + ``cmd`` + set to ``V4L2_DEC_CMD_STOP``. + + ``flags`` + set to 0. + + ``pts`` + set to 0. + + .. warning:: + + The sequence can be only initiated if both ``OUTPUT`` and ``CAPTURE`` + queues are streaming. For compatibility reasons, the call to + :c:func:`VIDIOC_DECODER_CMD` will not fail even if any of the queues is + not streaming, but at the same time it will not initiate the `Drain` + sequence and so the steps described below would not be applicable. + +2. Any ``OUTPUT`` buffers queued by the client before the + :c:func:`VIDIOC_DECODER_CMD` was issued will be processed and decoded as + normal. The client must continue to handle both queues independently, + similarly to normal decode operation. This includes: + + * handling any operations triggered as a result of processing those buffers, + such as the `Dynamic Resolution Change` sequence, before continuing with + the drain sequence, + + * queuing and dequeuing ``CAPTURE`` buffers, until a buffer marked with the + ``V4L2_BUF_FLAG_LAST`` flag is dequeued, + + .. warning:: + + The last buffer may be empty (with :c:type:`v4l2_buffer` + ``bytesused`` = 0) and in that case it must be ignored by the client, + as it does not contain a decoded frame. + + .. note:: + + Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer + marked with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from + :c:func:`VIDIOC_DQBUF`. + + * dequeuing processed ``OUTPUT`` buffers, until all the buffers queued + before the ``V4L2_DEC_CMD_STOP`` command are dequeued, + + * dequeuing the ``V4L2_EVENT_EOS`` event, if the client subscribed to it. + + .. note:: + + For backwards compatibility, the decoder will signal a ``V4L2_EVENT_EOS`` + event when the last frame has been decoded and all frames are ready to be + dequeued. It is a deprecated behavior and the client must not rely on it. + The ``V4L2_BUF_FLAG_LAST`` buffer flag should be used instead. + +3. Once all the ``OUTPUT`` buffers queued before the ``V4L2_DEC_CMD_STOP`` call + are dequeued and the last ``CAPTURE`` buffer is dequeued, the decoder is + stopped and it will accept, but not process, any newly queued ``OUTPUT`` + buffers until the client issues any of the following operations: + + * ``V4L2_DEC_CMD_START`` - the decoder will not be reset and will resume + operation normally, with all the state from before the drain, + + * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the + ``CAPTURE`` queue - the decoder will resume the operation normally, + however any ``CAPTURE`` buffers still in the queue will be returned to the + client, + + * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the + ``OUTPUT`` queue - any pending source buffers will be returned to the + client and the `Seek` sequence will be triggered. + +.. note:: + + Once the drain sequence is initiated, the client needs to drive it to + completion, as described by the steps above, unless it aborts the process by + issuing :c:func:`VIDIOC_STREAMOFF` on any of the ``OUTPUT`` or ``CAPTURE`` + queues. The client is not allowed to issue ``V4L2_DEC_CMD_START`` or + ``V4L2_DEC_CMD_STOP`` again while the drain sequence is in progress and they + will fail with -EBUSY error code if attempted. + + Although mandatory, the availability of decoder commands may be queried + using :c:func:`VIDIOC_TRY_DECODER_CMD`. + +End of Stream +============= + +If the decoder encounters an end of stream marking in the stream, the decoder +will initiate the `Drain` sequence, which the client must handle as described +above, skipping the initial :c:func:`VIDIOC_DECODER_CMD`. + +Commit Points +============= + +Setting formats and allocating buffers trigger changes in the behavior of the +decoder. + +1. Setting the format on the ``OUTPUT`` queue may change the set of formats + supported/advertised on the ``CAPTURE`` queue. In particular, it also means + that the ``CAPTURE`` format may be reset and the client must not rely on the + previously set format being preserved. + +2. Enumerating formats on the ``CAPTURE`` queue always returns only formats + supported for the current ``OUTPUT`` format. + +3. Setting the format on the ``CAPTURE`` queue does not change the list of + formats available on the ``OUTPUT`` queue. An attempt to set a ``CAPTURE`` + format that is not supported for the currently selected ``OUTPUT`` format + will result in the decoder adjusting the requested ``CAPTURE`` format to a + supported one. + +4. Enumerating formats on the ``OUTPUT`` queue always returns the full set of + supported coded formats, irrespectively of the current ``CAPTURE`` format. + +5. While buffers are allocated on any of the ``OUTPUT`` or ``CAPTURE`` queues, + the client must not change the format on the ``OUTPUT`` queue. Drivers will + return the -EBUSY error code for any such format change attempt. + +To summarize, setting formats and allocation must always start with the +``OUTPUT`` queue and the ``OUTPUT`` queue is the master that governs the +set of supported formats for the ``CAPTURE`` queue. diff --git a/Documentation/media/uapi/v4l/dev-mem2mem.rst b/Documentation/media/uapi/v4l/dev-mem2mem.rst index 67a980818dc8..caa05f5f6380 100644 --- a/Documentation/media/uapi/v4l/dev-mem2mem.rst +++ b/Documentation/media/uapi/v4l/dev-mem2mem.rst @@ -39,4 +39,10 @@ file handle is visible through another file handle). One of the most common memory-to-memory device is the codec. Codecs are more complicated than most and require additional setup for their codec parameters. This is done through codec controls. -See :ref:`mpeg-controls`. +See :ref:`mpeg-controls`. More details on how to use codec memory-to-memory +devices are given in the following sections. + +.. toctree:: + :maxdepth: 1 + + dev-decoder diff --git a/Documentation/media/uapi/v4l/ext-ctrls-codec.rst b/Documentation/media/uapi/v4l/ext-ctrls-codec.rst index 4a8446203085..bc5dd8e76567 100644 --- a/Documentation/media/uapi/v4l/ext-ctrls-codec.rst +++ b/Documentation/media/uapi/v4l/ext-ctrls-codec.rst @@ -759,6 +759,32 @@ enum v4l2_mpeg_video_h264_level - +.. _v4l2-mpeg-video-mpeg2-level: + +``V4L2_CID_MPEG_VIDEO_MPEG2_LEVEL`` + (enum) + +enum v4l2_mpeg_video_mpeg2_level - + The level information for the MPEG2 elementary stream. Applicable to + MPEG2 codecs. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_MPEG2_LEVEL_LOW`` + - Low Level (LL) + * - ``V4L2_MPEG_VIDEO_MPEG2_LEVEL_MAIN`` + - Main Level (ML) + * - ``V4L2_MPEG_VIDEO_MPEG2_LEVEL_HIGH_1440`` + - High-1440 Level (H-14) + * - ``V4L2_MPEG_VIDEO_MPEG2_LEVEL_HIGH`` + - High Level (HL) + + + .. _v4l2-mpeg-video-mpeg4-level: ``V4L2_CID_MPEG_VIDEO_MPEG4_LEVEL`` @@ -845,6 +871,36 @@ enum v4l2_mpeg_video_h264_profile - +.. _v4l2-mpeg-video-mpeg2-profile: + +``V4L2_CID_MPEG_VIDEO_MPEG2_PROFILE`` + (enum) + +enum v4l2_mpeg_video_mpeg2_profile - + The profile information for MPEG2. Applicable to MPEG2 codecs. + Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_MPEG2_PROFILE_SIMPLE`` + - Simple profile (SP) + * - ``V4L2_MPEG_VIDEO_MPEG2_PROFILE_MAIN`` + - Main profile (MP) + * - ``V4L2_MPEG_VIDEO_MPEG2_PROFILE_SNR_SCALABLE`` + - SNR Scalable profile (SNR) + * - ``V4L2_MPEG_VIDEO_MPEG2_PROFILE_SPATIALLY_SCALABLE`` + - Spatially Scalable profile (Spt) + * - ``V4L2_MPEG_VIDEO_MPEG2_PROFILE_HIGH`` + - High profile (HP) + * - ``V4L2_MPEG_VIDEO_MPEG2_PROFILE_MULTIVIEW`` + - Multi-view profile (MVP) + + + .. _v4l2-mpeg-video-mpeg4-profile: ``V4L2_CID_MPEG_VIDEO_MPEG4_PROFILE`` @@ -1395,6 +1451,654 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - - Layer number +.. _v4l2-mpeg-h264: + +``V4L2_CID_MPEG_VIDEO_H264_SPS (struct)`` + Specifies the sequence parameter set (as extracted from the + bitstream) for the associated H264 slice data. This includes the + necessary parameters for configuring a stateless hardware decoding + pipeline for H264. The bitstream parameters are defined according + to :ref:`h264`, section 7.4.2.1.1 "Sequence Parameter Set Data + Semantics". For further documentation, refer to the above + specification, unless there is an explicit comment stating + otherwise. + + .. note:: + + This compound control is not yet part of the public kernel API and + it is expected to change. + +.. c:type:: v4l2_ctrl_h264_sps + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_h264_sps + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``profile_idc`` + - + * - __u8 + - ``constraint_set_flags`` + - See :ref:`Sequence Parameter Set Constraints Set Flags <h264_sps_constraints_set_flags>` + * - __u8 + - ``level_idc`` + - + * - __u8 + - ``seq_parameter_set_id`` + - + * - __u8 + - ``chroma_format_idc`` + - + * - __u8 + - ``bit_depth_luma_minus8`` + - + * - __u8 + - ``bit_depth_chroma_minus8`` + - + * - __u8 + - ``log2_max_frame_num_minus4`` + - + * - __u8 + - ``pic_order_cnt_type`` + - + * - __u8 + - ``log2_max_pic_order_cnt_lsb_minus4`` + - + * - __u8 + - ``max_num_ref_frames`` + - + * - __u8 + - ``num_ref_frames_in_pic_order_cnt_cycle`` + - + * - __s32 + - ``offset_for_ref_frame[255]`` + - + * - __s32 + - ``offset_for_non_ref_pic`` + - + * - __s32 + - ``offset_for_top_to_bottom_field`` + - + * - __u16 + - ``pic_width_in_mbs_minus1`` + - + * - __u16 + - ``pic_height_in_map_units_minus1`` + - + * - __u32 + - ``flags`` + - See :ref:`Sequence Parameter Set Flags <h264_sps_flags>` + +.. _h264_sps_constraints_set_flags: + +``Sequence Parameter Set Constraints Set Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_SPS_CONSTRAINT_SET0_FLAG`` + - 0x00000001 + - + * - ``V4L2_H264_SPS_CONSTRAINT_SET1_FLAG`` + - 0x00000002 + - + * - ``V4L2_H264_SPS_CONSTRAINT_SET2_FLAG`` + - 0x00000004 + - + * - ``V4L2_H264_SPS_CONSTRAINT_SET3_FLAG`` + - 0x00000008 + - + * - ``V4L2_H264_SPS_CONSTRAINT_SET4_FLAG`` + - 0x00000010 + - + * - ``V4L2_H264_SPS_CONSTRAINT_SET5_FLAG`` + - 0x00000020 + - + +.. _h264_sps_flags: + +``Sequence Parameter Set Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_SPS_FLAG_SEPARATE_COLOUR_PLANE`` + - 0x00000001 + - + * - ``V4L2_H264_SPS_FLAG_QPPRIME_Y_ZERO_TRANSFORM_BYPASS`` + - 0x00000002 + - + * - ``V4L2_H264_SPS_FLAG_DELTA_PIC_ORDER_ALWAYS_ZERO`` + - 0x00000004 + - + * - ``V4L2_H264_SPS_FLAG_GAPS_IN_FRAME_NUM_VALUE_ALLOWED`` + - 0x00000008 + - + * - ``V4L2_H264_SPS_FLAG_FRAME_MBS_ONLY`` + - 0x00000010 + - + * - ``V4L2_H264_SPS_FLAG_MB_ADAPTIVE_FRAME_FIELD`` + - 0x00000020 + - + * - ``V4L2_H264_SPS_FLAG_DIRECT_8X8_INFERENCE`` + - 0x00000040 + - + +``V4L2_CID_MPEG_VIDEO_H264_PPS (struct)`` + Specifies the picture parameter set (as extracted from the + bitstream) for the associated H264 slice data. This includes the + necessary parameters for configuring a stateless hardware decoding + pipeline for H264. The bitstream parameters are defined according + to :ref:`h264`, section 7.4.2.2 "Picture Parameter Set RBSP + Semantics". For further documentation, refer to the above + specification, unless there is an explicit comment stating + otherwise. + + .. note:: + + This compound control is not yet part of the public kernel API and + it is expected to change. + +.. c:type:: v4l2_ctrl_h264_pps + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_h264_pps + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``pic_parameter_set_id`` + - + * - __u8 + - ``seq_parameter_set_id`` + - + * - __u8 + - ``num_slice_groups_minus1`` + - + * - __u8 + - ``num_ref_idx_l0_default_active_minus1`` + - + * - __u8 + - ``num_ref_idx_l1_default_active_minus1`` + - + * - __u8 + - ``weighted_bipred_idc`` + - + * - __s8 + - ``pic_init_qp_minus26`` + - + * - __s8 + - ``pic_init_qs_minus26`` + - + * - __s8 + - ``chroma_qp_index_offset`` + - + * - __s8 + - ``second_chroma_qp_index_offset`` + - + * - __u16 + - ``flags`` + - See :ref:`Picture Parameter Set Flags <h264_pps_flags>` + +.. _h264_pps_flags: + +``Picture Parameter Set Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_PPS_FLAG_ENTROPY_CODING_MODE`` + - 0x00000001 + - + * - ``V4L2_H264_PPS_FLAG_BOTTOM_FIELD_PIC_ORDER_IN_FRAME_PRESENT`` + - 0x00000002 + - + * - ``V4L2_H264_PPS_FLAG_WEIGHTED_PRED`` + - 0x00000004 + - + * - ``V4L2_H264_PPS_FLAG_DEBLOCKING_FILTER_CONTROL_PRESENT`` + - 0x00000008 + - + * - ``V4L2_H264_PPS_FLAG_CONSTRAINED_INTRA_PRED`` + - 0x00000010 + - + * - ``V4L2_H264_PPS_FLAG_REDUNDANT_PIC_CNT_PRESENT`` + - 0x00000020 + - + * - ``V4L2_H264_PPS_FLAG_TRANSFORM_8X8_MODE`` + - 0x00000040 + - + * - ``V4L2_H264_PPS_FLAG_PIC_SCALING_MATRIX_PRESENT`` + - 0x00000080 + - + +``V4L2_CID_MPEG_VIDEO_H264_SCALING_MATRIX (struct)`` + Specifies the scaling matrix (as extracted from the bitstream) for + the associated H264 slice data. The bitstream parameters are + defined according to :ref:`h264`, section 7.4.2.1.1.1 "Scaling + List Semantics". For further documentation, refer to the above + specification, unless there is an explicit comment stating + otherwise. + + .. note:: + + This compound control is not yet part of the public kernel API and + it is expected to change. + +.. c:type:: v4l2_ctrl_h264_scaling_matrix + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_h264_scaling_matrix + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``scaling_list_4x4[6][16]`` + - + * - __u8 + - ``scaling_list_8x8[6][64]`` + - + +``V4L2_CID_MPEG_VIDEO_H264_SLICE_PARAMS (struct)`` + Specifies the slice parameters (as extracted from the bitstream) + for the associated H264 slice data. This includes the necessary + parameters for configuring a stateless hardware decoding pipeline + for H264. The bitstream parameters are defined according to + :ref:`h264`, section 7.4.3 "Slice Header Semantics". For further + documentation, refer to the above specification, unless there is + an explicit comment stating otherwise. + + .. note:: + + This compound control is not yet part of the public kernel API + and it is expected to change. + + This structure is expected to be passed as an array, with one + entry for each slice included in the bitstream buffer. + +.. c:type:: v4l2_ctrl_h264_slice_params + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_h264_slice_params + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``size`` + - + * - __u32 + - ``start_byte_offset`` + Offset (in bytes) from the beginning of the OUTPUT buffer to the start + of the slice. If the slice starts with a start code, then this is the + offset to such start code. When operating in slice-based decoding mode + (see :c:type:`v4l2_mpeg_video_h264_decode_mode`), this field should + be set to 0. When operating in frame-based decoding mode, this field + should be 0 for the first slice. + * - __u32 + - ``header_bit_size`` + - + * - __u16 + - ``first_mb_in_slice`` + - + * - __u8 + - ``slice_type`` + - + * - __u8 + - ``pic_parameter_set_id`` + - + * - __u8 + - ``colour_plane_id`` + - + * - __u8 + - ``redundant_pic_cnt`` + - + * - __u16 + - ``frame_num`` + - + * - __u16 + - ``idr_pic_id`` + - + * - __u16 + - ``pic_order_cnt_lsb`` + - + * - __s32 + - ``delta_pic_order_cnt_bottom`` + - + * - __s32 + - ``delta_pic_order_cnt0`` + - + * - __s32 + - ``delta_pic_order_cnt1`` + - + * - struct :c:type:`v4l2_h264_pred_weight_table` + - ``pred_weight_table`` + - + * - __u32 + - ``dec_ref_pic_marking_bit_size`` + - + * - __u32 + - ``pic_order_cnt_bit_size`` + - + * - __u8 + - ``cabac_init_idc`` + - + * - __s8 + - ``slice_qp_delta`` + - + * - __s8 + - ``slice_qs_delta`` + - + * - __u8 + - ``disable_deblocking_filter_idc`` + - + * - __s8 + - ``slice_alpha_c0_offset_div2`` + - + * - __s8 + - ``slice_beta_offset_div2`` + - + * - __u8 + - ``num_ref_idx_l0_active_minus1`` + - + * - __u8 + - ``num_ref_idx_l1_active_minus1`` + - + * - __u32 + - ``slice_group_change_cycle`` + - + * - __u8 + - ``ref_pic_list0[32]`` + - Reference picture list after applying the per-slice modifications + * - __u8 + - ``ref_pic_list1[32]`` + - Reference picture list after applying the per-slice modifications + * - __u32 + - ``flags`` + - See :ref:`Slice Parameter Flags <h264_slice_flags>` + +.. _h264_slice_flags: + +``Slice Parameter Set Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_SLICE_FLAG_FIELD_PIC`` + - 0x00000001 + - + * - ``V4L2_H264_SLICE_FLAG_BOTTOM_FIELD`` + - 0x00000002 + - + * - ``V4L2_H264_SLICE_FLAG_DIRECT_SPATIAL_MV_PRED`` + - 0x00000004 + - + * - ``V4L2_H264_SLICE_FLAG_SP_FOR_SWITCH`` + - 0x00000008 + - + +``Prediction Weight Table`` + + The bitstream parameters are defined according to :ref:`h264`, + section 7.4.3.2 "Prediction Weight Table Semantics". For further + documentation, refer to the above specification, unless there is + an explicit comment stating otherwise. + +.. c:type:: v4l2_h264_pred_weight_table + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_h264_pred_weight_table + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u16 + - ``luma_log2_weight_denom`` + - + * - __u16 + - ``chroma_log2_weight_denom`` + - + * - struct :c:type:`v4l2_h264_weight_factors` + - ``weight_factors[2]`` + - The weight factors at index 0 are the weight factors for the reference + list 0, the one at index 1 for the reference list 1. + +.. c:type:: v4l2_h264_weight_factors + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_h264_weight_factors + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __s16 + - ``luma_weight[32]`` + - + * - __s16 + - ``luma_offset[32]`` + - + * - __s16 + - ``chroma_weight[32][2]`` + - + * - __s16 + - ``chroma_offset[32][2]`` + - + +``V4L2_CID_MPEG_VIDEO_H264_DECODE_PARAMS (struct)`` + Specifies the decode parameters (as extracted from the bitstream) + for the associated H264 slice data. This includes the necessary + parameters for configuring a stateless hardware decoding pipeline + for H264. The bitstream parameters are defined according to + :ref:`h264`. For further documentation, refer to the above + specification, unless there is an explicit comment stating + otherwise. + + .. note:: + + This compound control is not yet part of the public kernel API and + it is expected to change. + +.. c:type:: v4l2_ctrl_h264_decode_params + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_h264_decode_params + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - struct :c:type:`v4l2_h264_dpb_entry` + - ``dpb[16]`` + - + * - __u16 + - ``num_slices`` + - Number of slices needed to decode the current frame/field. When + operating in slice-based decoding mode (see + :c:type:`v4l2_mpeg_video_h264_decode_mode`), this field + should always be set to one. + * - __u16 + - ``nal_ref_idc`` + - NAL reference ID value coming from the NAL Unit header + * - __s32 + - ``top_field_order_cnt`` + - Picture Order Count for the coded top field + * - __s32 + - ``bottom_field_order_cnt`` + - Picture Order Count for the coded bottom field + * - __u32 + - ``flags`` + - See :ref:`Decode Parameters Flags <h264_decode_params_flags>` + +.. _h264_decode_params_flags: + +``Decode Parameters Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_DECODE_PARAM_FLAG_IDR_PIC`` + - 0x00000001 + - That picture is an IDR picture + +.. c:type:: v4l2_h264_dpb_entry + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_h264_dpb_entry + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u64 + - ``reference_ts`` + - Timestamp of the V4L2 capture buffer to use as reference, used + with B-coded and P-coded frames. The timestamp refers to the + ``timestamp`` field in struct :c:type:`v4l2_buffer`. Use the + :c:func:`v4l2_timeval_to_ns()` function to convert the struct + :c:type:`timeval` in struct :c:type:`v4l2_buffer` to a __u64. + * - __u16 + - ``frame_num`` + - + * - __u16 + - ``pic_num`` + - + * - __s32 + - ``top_field_order_cnt`` + - + * - __s32 + - ``bottom_field_order_cnt`` + - + * - __u32 + - ``flags`` + - See :ref:`DPB Entry Flags <h264_dpb_flags>` + +.. _h264_dpb_flags: + +``DPB Entries Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_DPB_ENTRY_FLAG_VALID`` + - 0x00000001 + - The DPB entry is valid and should be considered + * - ``V4L2_H264_DPB_ENTRY_FLAG_ACTIVE`` + - 0x00000002 + - The DPB entry is currently being used as a reference frame + * - ``V4L2_H264_DPB_ENTRY_FLAG_LONG_TERM`` + - 0x00000004 + - The DPB entry is a long term reference frame + +``V4L2_CID_MPEG_VIDEO_H264_DECODE_MODE (enum)`` + Specifies the decoding mode to use. Currently exposes slice-based and + frame-based decoding but new modes might be added later on. + This control is used as a modifier for V4L2_PIX_FMT_H264_SLICE + pixel format. Applications that support V4L2_PIX_FMT_H264_SLICE + are required to set this control in order to specify the decoding mode + that is expected for the buffer. + Drivers may expose a single or multiple decoding modes, depending + on what they can support. + + .. note:: + + This menu control is not yet part of the public kernel API and + it is expected to change. + +.. c:type:: v4l2_mpeg_video_h264_decode_mode + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_MPEG_VIDEO_H264_DECODE_MODE_SLICE_BASED`` + - 0 + - Decoding is done at the slice granularity. + In this mode, ``num_slices`` field in struct + :c:type:`v4l2_ctrl_h264_decode_params` should be set to 1, + and ``start_byte_offset`` in struct + :c:type:`v4l2_ctrl_h264_slice_params` should be set to 0. + The OUTPUT buffer must contain a single slice. + * - ``V4L2_MPEG_VIDEO_H264_DECODE_MODE_FRAME_BASED`` + - 1 + - Decoding is done at the frame granularity. + In this mode, ``num_slices`` field in struct + :c:type:`v4l2_ctrl_h264_decode_params` should be set to the number + of slices in the frame, and ``start_byte_offset`` in struct + :c:type:`v4l2_ctrl_h264_slice_params` should be set accordingly + for each slice. For the first slice, ``start_byte_offset`` should + be zero. + The OUTPUT buffer must contain all slices needed to decode the + frame. The OUTPUT buffer must also contain both fields. + +``V4L2_CID_MPEG_VIDEO_H264_START_CODE (enum)`` + Specifies the H264 slice start code expected for each slice. + This control is used as a modifier for V4L2_PIX_FMT_H264_SLICE + pixel format. Applications that support V4L2_PIX_FMT_H264_SLICE + are required to set this control in order to specify the start code + that is expected for the buffer. + Drivers may expose a single or multiple start codes, depending + on what they can support. + + .. note:: + + This menu control is not yet part of the public kernel API and + it is expected to change. + +.. c:type:: v4l2_mpeg_video_h264_start_code + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_MPEG_VIDEO_H264_START_CODE_NONE`` + - 0 + - Selecting this value specifies that H264 slices are passed + to the driver without any start code. + * - ``V4L2_MPEG_VIDEO_H264_START_CODE_ANNEX_B`` + - 1 + - Selecting this value specifies that H264 slices are expected + to be prefixed by Annex B start codes. According to :ref:`h264` + valid start codes can be 3-bytes 0x000001 or 4-bytes 0x00000001. .. _v4l2-mpeg-mpeg2: @@ -1609,6 +2313,329 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - Quantization parameter for a P frame for FWHT. Valid range: from 1 to 31. +.. _v4l2-mpeg-vp8: + +``V4L2_CID_MPEG_VIDEO_VP8_FRAME_HEADER (struct)`` + Specifies the frame parameters for the associated VP8 parsed frame data. + This includes the necessary parameters for + configuring a stateless hardware decoding pipeline for VP8. + The bitstream parameters are defined according to :ref:`vp8`. + + .. note:: + + This compound control is not yet part of the public kernel API and + it is expected to change. + +.. c:type:: v4l2_ctrl_vp8_frame_header + +.. cssclass:: longtable + +.. tabularcolumns:: |p{5.8cm}|p{4.8cm}|p{6.6cm}| + +.. flat-table:: struct v4l2_ctrl_vp8_frame_header + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - struct :c:type:`v4l2_vp8_segment_header` + - ``segment_header`` + - Structure with segment-based adjustments metadata. + * - struct :c:type:`v4l2_vp8_loopfilter_header` + - ``loopfilter_header`` + - Structure with loop filter level adjustments metadata. + * - struct :c:type:`v4l2_vp8_quantization_header` + - ``quant_header`` + - Structure with VP8 dequantization indices metadata. + * - struct :c:type:`v4l2_vp8_entropy_header` + - ``entropy_header`` + - Structure with VP8 entropy coder probabilities metadata. + * - struct :c:type:`v4l2_vp8_entropy_coder_state` + - ``coder_state`` + - Structure with VP8 entropy coder state. + * - __u16 + - ``width`` + - The width of the frame. Must be set for all frames. + * - __u16 + - ``height`` + - The height of the frame. Must be set for all frames. + * - __u8 + - ``horizontal_scale`` + - Horizontal scaling factor. + * - __u8 + - ``vertical_scaling factor`` + - Vertical scale. + * - __u8 + - ``version`` + - Bitstream version. + * - __u8 + - ``prob_skip_false`` + - Indicates the probability that the macroblock is not skipped. + * - __u8 + - ``prob_intra`` + - Indicates the probability that a macroblock is intra-predicted. + * - __u8 + - ``prob_last`` + - Indicates the probability that the last reference frame is used + for inter-prediction + * - __u8 + - ``prob_gf`` + - Indicates the probability that the golden reference frame is used + for inter-prediction + * - __u8 + - ``num_dct_parts`` + - Number of DCT coefficients partitions. Must be one of: 1, 2, 4, or 8. + * - __u32 + - ``first_part_size`` + - Size of the first partition, i.e. the control partition. + * - __u32 + - ``first_part_header_bits`` + - Size in bits of the first partition header portion. + * - __u32 + - ``dct_part_sizes[8]`` + - DCT coefficients sizes. + * - __u64 + - ``last_frame_ts`` + - Timestamp for the V4L2 capture buffer to use as last reference frame, used + with inter-coded frames. The timestamp refers to the ``timestamp`` field in + struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` + function to convert the struct :c:type:`timeval` in struct + :c:type:`v4l2_buffer` to a __u64. + * - __u64 + - ``golden_frame_ts`` + - Timestamp for the V4L2 capture buffer to use as last reference frame, used + with inter-coded frames. The timestamp refers to the ``timestamp`` field in + struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` + function to convert the struct :c:type:`timeval` in struct + :c:type:`v4l2_buffer` to a __u64. + * - __u64 + - ``alt_frame_ts`` + - Timestamp for the V4L2 capture buffer to use as alternate reference frame, used + with inter-coded frames. The timestamp refers to the ``timestamp`` field in + struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()` + function to convert the struct :c:type:`timeval` in struct + :c:type:`v4l2_buffer` to a __u64. + * - __u64 + - ``flags`` + - See :ref:`Frame Header Flags <vp8_frame_header_flags>` + +.. _vp8_frame_header_flags: + +``Frame Header Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP8_FRAME_HEADER_FLAG_KEY_FRAME`` + - 0x01 + - Indicates if the frame is a key frame. + * - ``V4L2_VP8_FRAME_HEADER_FLAG_EXPERIMENTAL`` + - 0x02 + - Experimental bitstream. + * - ``V4L2_VP8_FRAME_HEADER_FLAG_SHOW_FRAME`` + - 0x04 + - Show frame flag, indicates if the frame is for display. + * - ``V4L2_VP8_FRAME_HEADER_FLAG_MB_NO_SKIP_COEFF`` + - 0x08 + - Enable/disable skipping of macroblocks with no non-zero coefficients. + * - ``V4L2_VP8_FRAME_HEADER_FLAG_SIGN_BIAS_GOLDEN`` + - 0x10 + - Sign of motion vectors when the golden frame is referenced. + * - ``V4L2_VP8_FRAME_HEADER_FLAG_SIGN_BIAS_ALT`` + - 0x20 + - Sign of motion vectors when the alt frame is referenced. + +.. c:type:: v4l2_vp8_entropy_coder_state + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| + +.. flat-table:: struct v4l2_vp8_entropy_coder_state + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``range`` + - + * - __u8 + - ``value`` + - + * - __u8 + - ``bit_count`` + - + * - __u8 + - ``padding`` + - Applications and drivers must set this to zero. + +.. c:type:: v4l2_vp8_segment_header + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| + +.. flat-table:: struct v4l2_vp8_segment_header + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __s8 + - ``quant_update[4]`` + - Signed quantizer value update. + * - __s8 + - ``lf_update[4]`` + - Signed loop filter level value update. + * - __u8 + - ``segment_probs[3]`` + - Segment probabilities. + * - __u8 + - ``padding`` + - Applications and drivers must set this to zero. + * - __u32 + - ``flags`` + - See :ref:`Segment Header Flags <vp8_segment_header_flags>` + +.. _vp8_segment_header_flags: + +``Segment Header Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP8_SEGMENT_HEADER_FLAG_ENABLED`` + - 0x01 + - Enable/disable segment-based adjustments. + * - ``V4L2_VP8_SEGMENT_HEADER_FLAG_UPDATE_MAP`` + - 0x02 + - Indicates if the macroblock segmentation map is updated in this frame. + * - ``V4L2_VP8_SEGMENT_HEADER_FLAG_UPDATE_FEATURE_DATA`` + - 0x04 + - Indicates if the segment feature data is updated in this frame. + * - ``V4L2_VP8_SEGMENT_HEADER_FLAG_DELTA_VALUE_MODE`` + - 0x08 + - If is set, the segment feature data mode is delta-value. + If cleared, it's absolute-value. + +.. c:type:: v4l2_vp8_loopfilter_header + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| + +.. flat-table:: struct v4l2_vp8_loopfilter_header + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __s8 + - ``ref_frm_delta[4]`` + - Reference adjustment (signed) delta value. + * - __s8 + - ``mb_mode_delta[4]`` + - Macroblock prediction mode adjustment (signed) delta value. + * - __u8 + - ``sharpness_level`` + - Sharpness level + * - __u8 + - ``level`` + - Filter level + * - __u16 + - ``padding`` + - Applications and drivers must set this to zero. + * - __u32 + - ``flags`` + - See :ref:`Loopfilter Header Flags <vp8_loopfilter_header_flags>` + +.. _vp8_loopfilter_header_flags: + +``Loopfilter Header Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP8_LF_HEADER_ADJ_ENABLE`` + - 0x01 + - Enable/disable macroblock-level loop filter adjustment. + * - ``V4L2_VP8_LF_HEADER_DELTA_UPDATE`` + - 0x02 + - Indicates if the delta values used in an adjustment are updated. + * - ``V4L2_VP8_LF_FILTER_TYPE_SIMPLE`` + - 0x04 + - If set, indicates the filter type is simple. + If cleared, the filter type is normal. + +.. c:type:: v4l2_vp8_quantization_header + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| + +.. flat-table:: struct v4l2_vp8_quantization_header + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``y_ac_qi`` + - Luma AC coefficient table index. + * - __s8 + - ``y_dc_delta`` + - Luma DC delta vaue. + * - __s8 + - ``y2_dc_delta`` + - Y2 block DC delta value. + * - __s8 + - ``y2_ac_delta`` + - Y2 block AC delta value. + * - __s8 + - ``uv_dc_delta`` + - Chroma DC delta value. + * - __s8 + - ``uv_ac_delta`` + - Chroma AC delta value. + * - __u16 + - ``padding`` + - Applications and drivers must set this to zero. + +.. c:type:: v4l2_vp8_entropy_header + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| + +.. flat-table:: struct v4l2_vp8_entropy_header + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``coeff_probs[4][8][3][11]`` + - Coefficient update probabilities. + * - __u8 + - ``y_mode_probs[4]`` + - Luma mode update probabilities. + * - __u8 + - ``uv_mode_probs[3]`` + - Chroma mode update probabilities. + * - __u8 + - ``mv_probs[2][19]`` + - MV decoding update probabilities. + * - __u8 + - ``padding[3]`` + - Applications and drivers must set this to zero. + .. raw:: latex \normalsize diff --git a/Documentation/media/uapi/v4l/extended-controls.rst b/Documentation/media/uapi/v4l/extended-controls.rst index 24274b398e63..655362483730 100644 --- a/Documentation/media/uapi/v4l/extended-controls.rst +++ b/Documentation/media/uapi/v4l/extended-controls.rst @@ -85,20 +85,17 @@ be able to see such compound controls. In other words, these controls with compound types should only be used programmatically. Since such compound controls need to expose more information about -themselves than is possible with -:ref:`VIDIOC_QUERYCTRL` the -:ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>` ioctl was added. In -particular, this ioctl gives the dimensions of the N-dimensional array -if this control consists of more than one element. +themselves than is possible with :ref:`VIDIOC_QUERYCTRL <VIDIOC_QUERYCTRL>` +the :ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>` ioctl was added. In +particular, this ioctl gives the dimensions of the N-dimensional array if +this control consists of more than one element. .. note:: #. It is important to realize that due to the flexibility of controls it is necessary to check whether the control you want to set actually is supported in the driver and what the valid range of values is. So use - the :ref:`VIDIOC_QUERYCTRL` (or :ref:`VIDIOC_QUERY_EXT_CTRL - <VIDIOC_QUERYCTRL>`) and :ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>` - ioctls to check this. + :ref:`VIDIOC_QUERYCTRL` to check this. #. It is possible that some of the menu indices in a control of type ``V4L2_CTRL_TYPE_MENU`` may not be supported (``VIDIOC_QUERYMENU`` @@ -144,7 +141,7 @@ control class is found: while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &qctrl)) { if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4L2_CTRL_CLASS_MPEG) break; - /* ... */ + /* ... */ qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; } diff --git a/Documentation/media/uapi/v4l/field-order.rst b/Documentation/media/uapi/v4l/field-order.rst index d640e922a974..c422bebe4314 100644 --- a/Documentation/media/uapi/v4l/field-order.rst +++ b/Documentation/media/uapi/v4l/field-order.rst @@ -51,6 +51,11 @@ determined by the video standard. Hence the distinction between temporal and spatial order of fields. The diagrams below should make this clearer. +In V4L it is assumed that all video cameras transmit fields on the media +bus in the same order they were captured, so if the top field was +captured first (is the older field), the top field is also transmitted +first on the bus. + All video capture and output devices must report the current field order. Some drivers may permit the selection of a different order, to this end applications initialize the ``field`` field of struct @@ -101,10 +106,10 @@ enum v4l2_field * - ``V4L2_FIELD_INTERLACED`` - 4 - Images contain both fields, interleaved line by line. The temporal - order of the fields (whether the top or bottom field is first - transmitted) depends on the current video standard. M/NTSC - transmits the bottom field first, all other standards the top - field first. + order of the fields (whether the top or bottom field is older) + depends on the current video standard. In M/NTSC the bottom + field is the older field. In all other standards the top field + is the older field. * - ``V4L2_FIELD_SEQ_TB`` - 5 - Images contain both fields, the top field lines are stored first @@ -135,11 +140,11 @@ enum v4l2_field * - ``V4L2_FIELD_INTERLACED_TB`` - 8 - Images contain both fields, interleaved line by line, top field - first. The top field is transmitted first. + first. The top field is the older field. * - ``V4L2_FIELD_INTERLACED_BT`` - 9 - Images contain both fields, interleaved line by line, top field - first. The bottom field is transmitted first. + first. The bottom field is the older field. diff --git a/Documentation/media/uapi/v4l/hist-v4l2.rst b/Documentation/media/uapi/v4l/hist-v4l2.rst index 7d8e9efbeb1e..9e097f34cb74 100644 --- a/Documentation/media/uapi/v4l/hist-v4l2.rst +++ b/Documentation/media/uapi/v4l/hist-v4l2.rst @@ -900,7 +900,7 @@ V4L2 in Linux 2.6.19 :ref:`VIDIOC_ENUM_FRAMEINTERVALS` were added. -3. A new pixel format ``V4L2_PIX_FMT_RGB444`` (:ref:`rgb-formats`) was +3. A new pixel format ``V4L2_PIX_FMT_RGB444`` (:ref:`pixfmt-rgb`) was added. diff --git a/Documentation/media/uapi/v4l/pixfmt-bayer.rst b/Documentation/media/uapi/v4l/pixfmt-bayer.rst new file mode 100644 index 000000000000..cfa2f4e3e114 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-bayer.rst @@ -0,0 +1,38 @@ +.. 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 + +.. _pixfmt-bayer: + +***************** +Raw Bayer Formats +***************** + +Description +=========== + +The raw Bayer formats are used by image sensors before much if any processing is +performed on the image. The formats contain green, red and blue components, with +alternating lines of red and green, and blue and green pixels in different +orders. See also `the Wikipedia article on Bayer filter +<https://en.wikipedia.org/wiki/Bayer_filter>`__. + + +.. toctree:: + :maxdepth: 1 + + pixfmt-srggb8 + pixfmt-srggb10 + pixfmt-srggb10p + pixfmt-srggb10alaw8 + pixfmt-srggb10dpcm8 + pixfmt-srggb10-ipu3 + pixfmt-srggb12 + pixfmt-srggb12p + pixfmt-srggb14p + pixfmt-srggb16 diff --git a/Documentation/media/uapi/v4l/pixfmt-compressed.rst b/Documentation/media/uapi/v4l/pixfmt-compressed.rst index 6c961cfb74da..292fdc116c77 100644 --- a/Documentation/media/uapi/v4l/pixfmt-compressed.rst +++ b/Documentation/media/uapi/v4l/pixfmt-compressed.rst @@ -41,7 +41,12 @@ Compressed Formats - ``V4L2_PIX_FMT_H264`` - 'H264' - - H264 video elementary stream with start codes. + - H264 Access Unit. + The decoder expects one Access Unit per buffer. + The encoder generates one Access Unit per buffer. + If :ref:`VIDIOC_ENUM_FMT` reports ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM`` + then the decoder has no requirements since it can parse all the + information from the raw bytestream. * .. _V4L2-PIX-FMT-H264-NO-SC: - ``V4L2_PIX_FMT_H264_NO_SC`` @@ -52,6 +57,34 @@ Compressed Formats - ``V4L2_PIX_FMT_H264_MVC`` - 'M264' - H264 MVC video elementary stream. + * .. _V4L2-PIX-FMT-H264-SLICE: + + - ``V4L2_PIX_FMT_H264_SLICE`` + - 'S264' + - H264 parsed slice data, without the start code and as + extracted from the H264 bitstream. This format is adapted for + stateless video decoders that implement an H264 pipeline + (using the :ref:`mem2mem` and :ref:`media-request-api`). + This pixelformat has two modifiers that must be set at least once + through the ``V4L2_CID_MPEG_VIDEO_H264_DECODE_MODE`` + and ``V4L2_CID_MPEG_VIDEO_H264_START_CODE`` controls. + In addition, metadata associated with the frame to decode are + required to be passed through the ``V4L2_CID_MPEG_VIDEO_H264_SPS``, + ``V4L2_CID_MPEG_VIDEO_H264_PPS``, + ``V4L2_CID_MPEG_VIDEO_H264_SCALING_MATRIX``, + ``V4L2_CID_MPEG_VIDEO_H264_SLICE_PARAMS`` and + ``V4L2_CID_MPEG_VIDEO_H264_DECODE_PARAMS`` controls. See the + :ref:`associated Codec Control IDs <v4l2-mpeg-h264>`. Exactly + one output and one capture buffer must be provided for use + with this pixel format. The output buffer must contain the + appropriate number of macroblocks to decode a full + corresponding frame to the matching capture buffer. + + .. note:: + + This format is not yet part of the public kernel API and it + is expected to change. + * .. _V4L2-PIX-FMT-H263: - ``V4L2_PIX_FMT_H263`` @@ -61,12 +94,20 @@ Compressed Formats - ``V4L2_PIX_FMT_MPEG1`` - 'MPG1' - - MPEG1 video elementary stream. + - MPEG1 Picture. Each buffer starts with a Picture header, followed + by other headers as needed and ending with the Picture data. + If :ref:`VIDIOC_ENUM_FMT` reports ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM`` + then the decoder has no requirements since it can parse all the + information from the raw bytestream. * .. _V4L2-PIX-FMT-MPEG2: - ``V4L2_PIX_FMT_MPEG2`` - 'MPG2' - - MPEG2 video elementary stream. + - MPEG2 Picture. Each buffer starts with a Picture header, followed + by other headers as needed and ending with the Picture data. + If :ref:`VIDIOC_ENUM_FMT` reports ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM`` + then the decoder has no requirements since it can parse all the + information from the raw bytestream. * .. _V4L2-PIX-FMT-MPEG2-SLICE: - ``V4L2_PIX_FMT_MPEG2_SLICE`` @@ -107,17 +148,46 @@ Compressed Formats - ``V4L2_PIX_FMT_VP8`` - 'VP80' - - VP8 video elementary stream. + - VP8 compressed video frame. The encoder generates one + compressed frame per buffer, and the decoder requires one + compressed frame per buffer. + * .. _V4L2-PIX-FMT-VP8-FRAME: + + - ``V4L2_PIX_FMT_VP8_FRAME`` + - 'VP8F' + - VP8 parsed frame, as extracted from the container. + This format is adapted for stateless video decoders that implement a + VP8 pipeline (using the :ref:`mem2mem` and :ref:`media-request-api`). + Metadata associated with the frame to decode is required to be passed + through the ``V4L2_CID_MPEG_VIDEO_VP8_FRAME_HEADER`` control. + See the :ref:`associated Codec Control IDs <v4l2-mpeg-vp8>`. + Exactly one output and one capture buffer must be provided for use with + this pixel format. The output buffer must contain the appropriate number + of macroblocks to decode a full corresponding frame to the matching + capture buffer. + + .. note:: + + This format is not yet part of the public kernel API and it + is expected to change. + * .. _V4L2-PIX-FMT-VP9: - ``V4L2_PIX_FMT_VP9`` - 'VP90' - - VP9 video elementary stream. + - VP9 compressed video frame. The encoder generates one + compressed frame per buffer, and the decoder requires one + compressed frame per buffer. * .. _V4L2-PIX-FMT-HEVC: - ``V4L2_PIX_FMT_HEVC`` - 'HEVC' - - HEVC/H.265 video elementary stream. + - HEVC/H.265 Access Unit. + The decoder expects one Access Unit per buffer. + The encoder generates one Access Unit per buffer. + If :ref:`VIDIOC_ENUM_FMT` reports ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM`` + then the decoder has no requirements since it can parse all the + information from the raw bytestream. * .. _V4L2-PIX-FMT-FWHT: - ``V4L2_PIX_FMT_FWHT`` @@ -125,6 +195,8 @@ Compressed Formats - Video elementary stream using a codec based on the Fast Walsh Hadamard Transform. This codec is implemented by the vicodec ('Virtual Codec') driver. See the codec-fwht.h header for more details. + :ref:`VIDIOC_ENUM_FMT` reports ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM`` + since the decoder can parse all the information from the raw bytestream. * .. _V4L2-PIX-FMT-FWHT-STATELESS: - ``V4L2_PIX_FMT_FWHT_STATELESS`` diff --git a/Documentation/media/uapi/v4l/pixfmt-packed-rgb.rst b/Documentation/media/uapi/v4l/pixfmt-packed-rgb.rst deleted file mode 100644 index 738bb14c0ee2..000000000000 --- a/Documentation/media/uapi/v4l/pixfmt-packed-rgb.rst +++ /dev/null @@ -1,1306 +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 - -.. _packed-rgb: - -****************** -Packed RGB formats -****************** - -Description -=========== - -These formats are designed to match the pixel formats of typical PC -graphics frame buffers. They occupy 8, 16, 24 or 32 bits per pixel. -These are all packed-pixel formats, meaning all the data for a pixel lie -next to each other in memory. - -.. raw:: latex - - \begingroup - \tiny - \setlength{\tabcolsep}{2pt} - -.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| - - -.. _rgb-formats: - -.. flat-table:: Packed RGB Image Formats - :header-rows: 2 - :stub-columns: 0 - - * - Identifier - - Code - - :cspan:`7` Byte 0 in memory - - :cspan:`7` Byte 1 - - :cspan:`7` Byte 2 - - :cspan:`7` Byte 3 - * - - - - - 7 - - 6 - - 5 - - 4 - - 3 - - 2 - - 1 - - 0 - - - 7 - - 6 - - 5 - - 4 - - 3 - - 2 - - 1 - - 0 - - - 7 - - 6 - - 5 - - 4 - - 3 - - 2 - - 1 - - 0 - - - 7 - - 6 - - 5 - - 4 - - 3 - - 2 - - 1 - - 0 - * .. _V4L2-PIX-FMT-RGB332: - - - ``V4L2_PIX_FMT_RGB332`` - - 'RGB1' - - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - b\ :sub:`1` - - b\ :sub:`0` - - - * .. _V4L2-PIX-FMT-ARGB444: - - - ``V4L2_PIX_FMT_ARGB444`` - - 'AR12' - - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - * .. _V4L2-PIX-FMT-XRGB444: - - - ``V4L2_PIX_FMT_XRGB444`` - - 'XR12' - - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - - - - - - - - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - * .. _V4L2-PIX-FMT-RGBA444: - - - ``V4L2_PIX_FMT_RGBA444`` - - 'RA12' - - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` - - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - * .. _V4L2-PIX-FMT-RGBX444: - - - ``V4L2_PIX_FMT_RGBX444`` - - 'RX12' - - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - - - - - - - - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - * .. _V4L2-PIX-FMT-ABGR444: - - - ``V4L2_PIX_FMT_ABGR444`` - - 'AB12' - - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - * .. _V4L2-PIX-FMT-XBGR444: - - - ``V4L2_PIX_FMT_XBGR444`` - - 'XB12' - - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - - - - - - - - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - * .. _V4L2-PIX-FMT-BGRA444: - - - ``V4L2_PIX_FMT_BGRA444`` - - 'BA12' - - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` - - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - * .. _V4L2-PIX-FMT-BGRX444: - - - ``V4L2_PIX_FMT_BGRX444`` - - 'BX12' - - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - - - - - - - - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - * .. _V4L2-PIX-FMT-ARGB555: - - - ``V4L2_PIX_FMT_ARGB555`` - - 'AR15' - - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - a - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - g\ :sub:`4` - - g\ :sub:`3` - - - * .. _V4L2-PIX-FMT-XRGB555: - - - ``V4L2_PIX_FMT_XRGB555`` - - 'XR15' - - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - g\ :sub:`4` - - g\ :sub:`3` - - - * .. _V4L2-PIX-FMT-RGBA555: - - - ``V4L2_PIX_FMT_RGBA555`` - - 'RA15' - - - g\ :sub:`1` - - g\ :sub:`0` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - a - - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - - * .. _V4L2-PIX-FMT-RGBX555: - - - ``V4L2_PIX_FMT_RGBX555`` - - 'RX15' - - - g\ :sub:`1` - - g\ :sub:`0` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - - * .. _V4L2-PIX-FMT-ABGR555: - - - ``V4L2_PIX_FMT_ABGR555`` - - 'AB15' - - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - a - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - g\ :sub:`4` - - g\ :sub:`3` - - - * .. _V4L2-PIX-FMT-XBGR555: - - - ``V4L2_PIX_FMT_XBGR555`` - - 'XB15' - - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - g\ :sub:`4` - - g\ :sub:`3` - - - * .. _V4L2-PIX-FMT-BGRA555: - - - ``V4L2_PIX_FMT_BGRA555`` - - 'BA15' - - - g\ :sub:`1` - - g\ :sub:`0` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - a - - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - - * .. _V4L2-PIX-FMT-BGRX555: - - - ``V4L2_PIX_FMT_BGRX555`` - - 'BX15' - - - g\ :sub:`1` - - g\ :sub:`0` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - - * .. _V4L2-PIX-FMT-RGB565: - - - ``V4L2_PIX_FMT_RGB565`` - - 'RGBP' - - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - - * .. _V4L2-PIX-FMT-ARGB555X: - - - ``V4L2_PIX_FMT_ARGB555X`` - - 'AR15' | (1 << 31) - - - a - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - g\ :sub:`4` - - g\ :sub:`3` - - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - * .. _V4L2-PIX-FMT-XRGB555X: - - - ``V4L2_PIX_FMT_XRGB555X`` - - 'XR15' | (1 << 31) - - - - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - g\ :sub:`4` - - g\ :sub:`3` - - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - * .. _V4L2-PIX-FMT-RGB565X: - - - ``V4L2_PIX_FMT_RGB565X`` - - 'RGBR' - - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - * .. _V4L2-PIX-FMT-BGR24: - - - ``V4L2_PIX_FMT_BGR24`` - - 'BGR3' - - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - * .. _V4L2-PIX-FMT-RGB24: - - - ``V4L2_PIX_FMT_RGB24`` - - 'RGB3' - - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - * .. _V4L2-PIX-FMT-BGR666: - - - ``V4L2_PIX_FMT_BGR666`` - - 'BGRH' - - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - g\ :sub:`5` - - g\ :sub:`4` - - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - - r\ :sub:`1` - - r\ :sub:`0` - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - * .. _V4L2-PIX-FMT-ABGR32: - - - ``V4L2_PIX_FMT_ABGR32`` - - 'AR24' - - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - a\ :sub:`7` - - a\ :sub:`6` - - a\ :sub:`5` - - a\ :sub:`4` - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` - * .. _V4L2-PIX-FMT-XBGR32: - - - ``V4L2_PIX_FMT_XBGR32`` - - 'XR24' - - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - - - - - - - - - - - - - - - - * .. _V4L2-PIX-FMT-BGRA32: - - - ``V4L2_PIX_FMT_BGRA32`` - - 'RA24' - - - a\ :sub:`7` - - a\ :sub:`6` - - a\ :sub:`5` - - a\ :sub:`4` - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` - - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - * .. _V4L2-PIX-FMT-BGRX32: - - - ``V4L2_PIX_FMT_BGRX32`` - - 'RX24' - - - - - - - - - - - - - - - - - - - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - * .. _V4L2-PIX-FMT-RGBA32: - - - ``V4L2_PIX_FMT_RGBA32`` - - 'AB24' - - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - a\ :sub:`7` - - a\ :sub:`6` - - a\ :sub:`5` - - a\ :sub:`4` - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` - * .. _V4L2-PIX-FMT-RGBX32: - - - ``V4L2_PIX_FMT_RGBX32`` - - 'XB24' - - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - - - - - - - - - - - - - - - - * .. _V4L2-PIX-FMT-ARGB32: - - - ``V4L2_PIX_FMT_ARGB32`` - - 'BA24' - - - a\ :sub:`7` - - a\ :sub:`6` - - a\ :sub:`5` - - a\ :sub:`4` - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` - - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - * .. _V4L2-PIX-FMT-XRGB32: - - - ``V4L2_PIX_FMT_XRGB32`` - - 'BX24' - - - - - - - - - - - - - - - - - - - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - -.. raw:: latex - - \endgroup - -.. note:: Bit 7 is the most significant bit. - -The usage and value of the alpha bits (a) in the ARGB and ABGR formats -(collectively referred to as alpha formats) depend on the device type -and hardware operation. :ref:`Capture <capture>` devices (including -capture queues of mem-to-mem devices) fill the alpha component in -memory. When the device outputs an alpha channel the alpha component -will have a meaningful value. Otherwise, when the device doesn't output -an alpha channel but can set the alpha bit to a user-configurable value, -the :ref:`V4L2_CID_ALPHA_COMPONENT <v4l2-alpha-component>` control -is used to specify that alpha value, and the alpha component of all -pixels will be set to the value specified by that control. Otherwise a -corresponding format without an alpha component (XRGB or XBGR) must be -used instead of an alpha format. - -:ref:`Output <output>` devices (including output queues of mem-to-mem -devices and :ref:`video output overlay <osd>` devices) read the alpha -component from memory. When the device processes the alpha channel the -alpha component must be filled with meaningful values by applications. -Otherwise a corresponding format without an alpha component (XRGB or -XBGR) must be used instead of an alpha format. - -The XRGB and XBGR formats contain undefined bits (-). Applications, -devices and drivers must ignore those bits, for both -:ref:`capture` and :ref:`output` devices. - -**Byte Order.** -Each cell is one byte. - - -.. raw:: latex - - \small - -.. tabularcolumns:: |p{3.1cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}| - -.. flat-table:: RGB byte order - :header-rows: 0 - :stub-columns: 0 - :widths: 11 3 3 3 3 3 3 3 3 3 3 3 3 - - * - start + 0: - - B\ :sub:`00` - - G\ :sub:`00` - - R\ :sub:`00` - - B\ :sub:`01` - - G\ :sub:`01` - - R\ :sub:`01` - - B\ :sub:`02` - - G\ :sub:`02` - - R\ :sub:`02` - - B\ :sub:`03` - - G\ :sub:`03` - - R\ :sub:`03` - * - start + 12: - - B\ :sub:`10` - - G\ :sub:`10` - - R\ :sub:`10` - - B\ :sub:`11` - - G\ :sub:`11` - - R\ :sub:`11` - - B\ :sub:`12` - - G\ :sub:`12` - - R\ :sub:`12` - - B\ :sub:`13` - - G\ :sub:`13` - - R\ :sub:`13` - * - start + 24: - - B\ :sub:`20` - - G\ :sub:`20` - - R\ :sub:`20` - - B\ :sub:`21` - - G\ :sub:`21` - - R\ :sub:`21` - - B\ :sub:`22` - - G\ :sub:`22` - - R\ :sub:`22` - - B\ :sub:`23` - - G\ :sub:`23` - - R\ :sub:`23` - * - start + 36: - - B\ :sub:`30` - - G\ :sub:`30` - - R\ :sub:`30` - - B\ :sub:`31` - - G\ :sub:`31` - - R\ :sub:`31` - - B\ :sub:`32` - - G\ :sub:`32` - - R\ :sub:`32` - - B\ :sub:`33` - - G\ :sub:`33` - - R\ :sub:`33` - -.. raw:: latex - - \normalsize - -Formats defined in :ref:`rgb-formats-deprecated` are deprecated and -must not be used by new drivers. They are documented here for reference. -The meaning of their alpha bits ``(a)`` are ill-defined and interpreted as in -either the corresponding ARGB or XRGB format, depending on the driver. - - -.. raw:: latex - - \begingroup - \tiny - \setlength{\tabcolsep}{2pt} - -.. tabularcolumns:: |p{2.6cm}|p{0.70cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| - -.. _rgb-formats-deprecated: - -.. flat-table:: Deprecated Packed RGB Image Formats - :header-rows: 2 - :stub-columns: 0 - - * - Identifier - - Code - - :cspan:`7` Byte 0 in memory - - - :cspan:`7` Byte 1 - - - :cspan:`7` Byte 2 - - - :cspan:`7` Byte 3 - * - - - - - 7 - - 6 - - 5 - - 4 - - 3 - - 2 - - 1 - - 0 - - - 7 - - 6 - - 5 - - 4 - - 3 - - 2 - - 1 - - 0 - - - 7 - - 6 - - 5 - - 4 - - 3 - - 2 - - 1 - - 0 - - - 7 - - 6 - - 5 - - 4 - - 3 - - 2 - - 1 - - 0 - * .. _V4L2-PIX-FMT-RGB444: - - - ``V4L2_PIX_FMT_RGB444`` - - 'R444' - - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - * .. _V4L2-PIX-FMT-RGB555: - - - ``V4L2_PIX_FMT_RGB555`` - - 'RGBO' - - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - a - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - g\ :sub:`4` - - g\ :sub:`3` - - - * .. _V4L2-PIX-FMT-RGB555X: - - - ``V4L2_PIX_FMT_RGB555X`` - - 'RGBQ' - - - a - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - g\ :sub:`4` - - g\ :sub:`3` - - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - * .. _V4L2-PIX-FMT-BGR32: - - - ``V4L2_PIX_FMT_BGR32`` - - 'BGR4' - - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - a\ :sub:`7` - - a\ :sub:`6` - - a\ :sub:`5` - - a\ :sub:`4` - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` - * .. _V4L2-PIX-FMT-RGB32: - - - ``V4L2_PIX_FMT_RGB32`` - - 'RGB4' - - - a\ :sub:`7` - - a\ :sub:`6` - - a\ :sub:`5` - - a\ :sub:`4` - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` - - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` - - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - - b\ :sub:`7` - - b\ :sub:`6` - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - -.. raw:: latex - - \endgroup - -A test utility to determine which RGB formats a driver actually supports -is available from the LinuxTV v4l-dvb repository. See -`https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access -instructions. diff --git a/Documentation/media/uapi/v4l/pixfmt-rgb.rst b/Documentation/media/uapi/v4l/pixfmt-rgb.rst index 48ab80024835..4ce305cc45da 100644 --- a/Documentation/media/uapi/v4l/pixfmt-rgb.rst +++ b/Documentation/media/uapi/v4l/pixfmt-rgb.rst @@ -13,18 +13,1292 @@ RGB Formats *********** +Description +=========== -.. toctree:: - :maxdepth: 1 - - pixfmt-packed-rgb - pixfmt-srggb8 - pixfmt-srggb10 - pixfmt-srggb10p - pixfmt-srggb10alaw8 - pixfmt-srggb10dpcm8 - pixfmt-srggb10-ipu3 - pixfmt-srggb12 - pixfmt-srggb12p - pixfmt-srggb14p - pixfmt-srggb16 +These formats are designed to match the pixel formats of typical PC +graphics frame buffers. They occupy 8, 16, 24 or 32 bits per pixel. +These are all packed-pixel formats, meaning all the data for a pixel lie +next to each other in memory. + +.. raw:: latex + + \begingroup + \tiny + \setlength{\tabcolsep}{2pt} + +.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| + + +.. flat-table:: RGB Image Formats + :header-rows: 2 + :stub-columns: 0 + + * - Identifier + - Code + - :cspan:`7` Byte 0 in memory + - :cspan:`7` Byte 1 + - :cspan:`7` Byte 2 + - :cspan:`7` Byte 3 + * - + - + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + * .. _V4L2-PIX-FMT-RGB332: + + - ``V4L2_PIX_FMT_RGB332`` + - 'RGB1' + + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`1` + - b\ :sub:`0` + - + * .. _V4L2-PIX-FMT-ARGB444: + + - ``V4L2_PIX_FMT_ARGB444`` + - 'AR12' + + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - + * .. _V4L2-PIX-FMT-XRGB444: + + - ``V4L2_PIX_FMT_XRGB444`` + - 'XR12' + + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - + - + - + - + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - + * .. _V4L2-PIX-FMT-RGBA444: + + - ``V4L2_PIX_FMT_RGBA444`` + - 'RA12' + + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - + * .. _V4L2-PIX-FMT-RGBX444: + + - ``V4L2_PIX_FMT_RGBX444`` + - 'RX12' + + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - + - + - + - + + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - + * .. _V4L2-PIX-FMT-ABGR444: + + - ``V4L2_PIX_FMT_ABGR444`` + - 'AB12' + + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - + * .. _V4L2-PIX-FMT-XBGR444: + + - ``V4L2_PIX_FMT_XBGR444`` + - 'XB12' + + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - + - + - + - + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - + * .. _V4L2-PIX-FMT-BGRA444: + + - ``V4L2_PIX_FMT_BGRA444`` + - 'BA12' + + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - + * .. _V4L2-PIX-FMT-BGRX444: + + - ``V4L2_PIX_FMT_BGRX444`` + - 'BX12' + + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - + - + - + - + + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - + * .. _V4L2-PIX-FMT-ARGB555: + + - ``V4L2_PIX_FMT_ARGB555`` + - 'AR15' + + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - a + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + - + * .. _V4L2-PIX-FMT-XRGB555: + + - ``V4L2_PIX_FMT_XRGB555`` + - 'XR15' + + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + - + * .. _V4L2-PIX-FMT-RGBA555: + + - ``V4L2_PIX_FMT_RGBA555`` + - 'RA15' + + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - a + + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - + * .. _V4L2-PIX-FMT-RGBX555: + + - ``V4L2_PIX_FMT_RGBX555`` + - 'RX15' + + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - + + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - + * .. _V4L2-PIX-FMT-ABGR555: + + - ``V4L2_PIX_FMT_ABGR555`` + - 'AB15' + + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - a + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + - + * .. _V4L2-PIX-FMT-XBGR555: + + - ``V4L2_PIX_FMT_XBGR555`` + - 'XB15' + + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + - + * .. _V4L2-PIX-FMT-BGRA555: + + - ``V4L2_PIX_FMT_BGRA555`` + - 'BA15' + + - g\ :sub:`1` + - g\ :sub:`0` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - a + + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - + * .. _V4L2-PIX-FMT-BGRX555: + + - ``V4L2_PIX_FMT_BGRX555`` + - 'BX15' + + - g\ :sub:`1` + - g\ :sub:`0` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - + + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - + * .. _V4L2-PIX-FMT-RGB565: + + - ``V4L2_PIX_FMT_RGB565`` + - 'RGBP' + + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - + * .. _V4L2-PIX-FMT-ARGB555X: + + - ``V4L2_PIX_FMT_ARGB555X`` + - 'AR15' | (1 << 31) + + - a + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - + * .. _V4L2-PIX-FMT-XRGB555X: + + - ``V4L2_PIX_FMT_XRGB555X`` + - 'XR15' | (1 << 31) + + - + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - + * .. _V4L2-PIX-FMT-RGB565X: + + - ``V4L2_PIX_FMT_RGB565X`` + - 'RGBR' + + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - + * .. _V4L2-PIX-FMT-BGR24: + + - ``V4L2_PIX_FMT_BGR24`` + - 'BGR3' + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - + * .. _V4L2-PIX-FMT-RGB24: + + - ``V4L2_PIX_FMT_RGB24`` + - 'RGB3' + + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - + * .. _V4L2-PIX-FMT-BGR666: + + - ``V4L2_PIX_FMT_BGR666`` + - 'BGRH' + + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - g\ :sub:`5` + - g\ :sub:`4` + + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + + - r\ :sub:`1` + - r\ :sub:`0` + - + - + - + - + - + - + + - + - + - + - + - + - + - + - + * .. _V4L2-PIX-FMT-ABGR32: + + - ``V4L2_PIX_FMT_ABGR32`` + - 'AR24' + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - a\ :sub:`7` + - a\ :sub:`6` + - a\ :sub:`5` + - a\ :sub:`4` + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + * .. _V4L2-PIX-FMT-XBGR32: + + - ``V4L2_PIX_FMT_XBGR32`` + - 'XR24' + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - + - + - + - + - + - + - + - + * .. _V4L2-PIX-FMT-BGRA32: + + - ``V4L2_PIX_FMT_BGRA32`` + - 'RA24' + + - a\ :sub:`7` + - a\ :sub:`6` + - a\ :sub:`5` + - a\ :sub:`4` + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + * .. _V4L2-PIX-FMT-BGRX32: + + - ``V4L2_PIX_FMT_BGRX32`` + - 'RX24' + + - + - + - + - + - + - + - + - + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + * .. _V4L2-PIX-FMT-RGBA32: + + - ``V4L2_PIX_FMT_RGBA32`` + - 'AB24' + + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - a\ :sub:`7` + - a\ :sub:`6` + - a\ :sub:`5` + - a\ :sub:`4` + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + * .. _V4L2-PIX-FMT-RGBX32: + + - ``V4L2_PIX_FMT_RGBX32`` + - 'XB24' + + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - + - + - + - + - + - + - + - + * .. _V4L2-PIX-FMT-ARGB32: + + - ``V4L2_PIX_FMT_ARGB32`` + - 'BA24' + + - a\ :sub:`7` + - a\ :sub:`6` + - a\ :sub:`5` + - a\ :sub:`4` + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + * .. _V4L2-PIX-FMT-XRGB32: + + - ``V4L2_PIX_FMT_XRGB32`` + - 'BX24' + + - + - + - + - + - + - + - + - + + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + +.. raw:: latex + + \endgroup + +.. note:: Bit 7 is the most significant bit. + +The usage and value of the alpha bits (a) in the ARGB and ABGR formats +(collectively referred to as alpha formats) depend on the device type +and hardware operation. :ref:`Capture <capture>` devices (including +capture queues of mem-to-mem devices) fill the alpha component in +memory. When the device outputs an alpha channel the alpha component +will have a meaningful value. Otherwise, when the device doesn't output +an alpha channel but can set the alpha bit to a user-configurable value, +the :ref:`V4L2_CID_ALPHA_COMPONENT <v4l2-alpha-component>` control +is used to specify that alpha value, and the alpha component of all +pixels will be set to the value specified by that control. Otherwise a +corresponding format without an alpha component (XRGB or XBGR) must be +used instead of an alpha format. + +:ref:`Output <output>` devices (including output queues of mem-to-mem +devices and :ref:`video output overlay <osd>` devices) read the alpha +component from memory. When the device processes the alpha channel the +alpha component must be filled with meaningful values by applications. +Otherwise a corresponding format without an alpha component (XRGB or +XBGR) must be used instead of an alpha format. + +The XRGB and XBGR formats contain undefined bits (-). Applications, +devices and drivers must ignore those bits, for both +:ref:`capture` and :ref:`output` devices. + +**Byte Order.** +Each cell is one byte. + + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{3.1cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}| + +.. flat-table:: RGB byte order + :header-rows: 0 + :stub-columns: 0 + :widths: 11 3 3 3 3 3 3 3 3 3 3 3 3 + + * - start + 0: + - B\ :sub:`00` + - G\ :sub:`00` + - R\ :sub:`00` + - B\ :sub:`01` + - G\ :sub:`01` + - R\ :sub:`01` + - B\ :sub:`02` + - G\ :sub:`02` + - R\ :sub:`02` + - B\ :sub:`03` + - G\ :sub:`03` + - R\ :sub:`03` + * - start + 12: + - B\ :sub:`10` + - G\ :sub:`10` + - R\ :sub:`10` + - B\ :sub:`11` + - G\ :sub:`11` + - R\ :sub:`11` + - B\ :sub:`12` + - G\ :sub:`12` + - R\ :sub:`12` + - B\ :sub:`13` + - G\ :sub:`13` + - R\ :sub:`13` + * - start + 24: + - B\ :sub:`20` + - G\ :sub:`20` + - R\ :sub:`20` + - B\ :sub:`21` + - G\ :sub:`21` + - R\ :sub:`21` + - B\ :sub:`22` + - G\ :sub:`22` + - R\ :sub:`22` + - B\ :sub:`23` + - G\ :sub:`23` + - R\ :sub:`23` + * - start + 36: + - B\ :sub:`30` + - G\ :sub:`30` + - R\ :sub:`30` + - B\ :sub:`31` + - G\ :sub:`31` + - R\ :sub:`31` + - B\ :sub:`32` + - G\ :sub:`32` + - R\ :sub:`32` + - B\ :sub:`33` + - G\ :sub:`33` + - R\ :sub:`33` + +.. raw:: latex + + \normalsize + +Formats defined in :ref:`pixfmt-rgb-deprecated` are deprecated and +must not be used by new drivers. They are documented here for reference. +The meaning of their alpha bits ``(a)`` are ill-defined and interpreted as in +either the corresponding ARGB or XRGB format, depending on the driver. + + +.. raw:: latex + + \begingroup + \tiny + \setlength{\tabcolsep}{2pt} + +.. tabularcolumns:: |p{2.6cm}|p{0.70cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| + +.. _pixfmt-rgb-deprecated: + +.. flat-table:: Deprecated Packed RGB Image Formats + :header-rows: 2 + :stub-columns: 0 + + * - Identifier + - Code + - :cspan:`7` Byte 0 in memory + + - :cspan:`7` Byte 1 + + - :cspan:`7` Byte 2 + + - :cspan:`7` Byte 3 + * - + - + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + * .. _V4L2-PIX-FMT-RGB444: + + - ``V4L2_PIX_FMT_RGB444`` + - 'R444' + + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - + * .. _V4L2-PIX-FMT-RGB555: + + - ``V4L2_PIX_FMT_RGB555`` + - 'RGBO' + + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - a + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + - + * .. _V4L2-PIX-FMT-RGB555X: + + - ``V4L2_PIX_FMT_RGB555X`` + - 'RGBQ' + + - a + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - + * .. _V4L2-PIX-FMT-BGR32: + + - ``V4L2_PIX_FMT_BGR32`` + - 'BGR4' + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - a\ :sub:`7` + - a\ :sub:`6` + - a\ :sub:`5` + - a\ :sub:`4` + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + * .. _V4L2-PIX-FMT-RGB32: + + - ``V4L2_PIX_FMT_RGB32`` + - 'RGB4' + + - a\ :sub:`7` + - a\ :sub:`6` + - a\ :sub:`5` + - a\ :sub:`4` + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + +.. raw:: latex + + \endgroup + +A test utility to determine which RGB formats a driver actually supports +is available from the LinuxTV v4l-dvb repository. See +`https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access +instructions. diff --git a/Documentation/media/uapi/v4l/pixfmt-v4l2-mplane.rst b/Documentation/media/uapi/v4l/pixfmt-v4l2-mplane.rst index 5688c816e334..db43dda5aafb 100644 --- a/Documentation/media/uapi/v4l/pixfmt-v4l2-mplane.rst +++ b/Documentation/media/uapi/v4l/pixfmt-v4l2-mplane.rst @@ -31,7 +31,20 @@ describing all planes of that format. * - __u32 - ``sizeimage`` - - Maximum size in bytes required for image data in this plane. + - Maximum size in bytes required for image data in this plane, + set by the driver. When the image consists of variable length + compressed data this is the number of bytes required by the + codec to support the worst-case compression scenario. + + The driver will set the value for uncompressed images. + + Clients are allowed to set the sizeimage field for variable length + compressed data flagged with ``V4L2_FMT_FLAG_COMPRESSED`` at + :ref:`VIDIOC_ENUM_FMT`, but the driver may ignore it and set the + value itself, or it may modify the provided value based on + alignment requirements or minimum/maximum size requirements. + If the client wants to leave this to the driver, then it should + set sizeimage to 0. * - __u32 - ``bytesperline`` - Distance in bytes between the leftmost pixels in two adjacent diff --git a/Documentation/media/uapi/v4l/pixfmt-v4l2.rst b/Documentation/media/uapi/v4l/pixfmt-v4l2.rst index 71eebfc6d853..a8321c348bf8 100644 --- a/Documentation/media/uapi/v4l/pixfmt-v4l2.rst +++ b/Documentation/media/uapi/v4l/pixfmt-v4l2.rst @@ -39,12 +39,17 @@ Single-planar format structure to a multiple of the scale factor of any smaller planes. For example when the image format is YUV 4:2:0, ``width`` and ``height`` must be multiples of two. + + For compressed formats that contain the resolution information encoded + inside the stream, when fed to a stateful mem2mem decoder, the fields + may be zero to rely on the decoder to detect the right values. For more + details see :ref:`decoder` and format descriptions. * - __u32 - ``pixelformat`` - The pixel format or type of compression, set by the application. This is a little endian :ref:`four character code <v4l2-fourcc>`. V4L2 defines standard - RGB formats in :ref:`rgb-formats`, YUV formats in + RGB formats in :ref:`pixfmt-rgb`, YUV formats in :ref:`yuv-formats`, and reserved codes in :ref:`reserved-formats` * - __u32 @@ -89,7 +94,18 @@ Single-planar format structure - Size in bytes of the buffer to hold a complete image, set by the driver. Usually this is ``bytesperline`` times ``height``. When the image consists of variable length compressed data this is the - maximum number of bytes required to hold an image. + number of bytes required by the codec to support the worst-case + compression scenario. + + The driver will set the value for uncompressed images. + + Clients are allowed to set the sizeimage field for variable length + compressed data flagged with ``V4L2_FMT_FLAG_COMPRESSED`` at + :ref:`VIDIOC_ENUM_FMT`, but the driver may ignore it and set the + value itself, or it may modify the provided value based on + alignment requirements or minimum/maximum size requirements. + If the client wants to leave this to the driver, then it should + set sizeimage to 0. * - __u32 - ``colorspace`` - Image colorspace, from enum :c:type:`v4l2_colorspace`. diff --git a/Documentation/media/uapi/v4l/pixfmt.rst b/Documentation/media/uapi/v4l/pixfmt.rst index 29be001796db..a7d4cd43a298 100644 --- a/Documentation/media/uapi/v4l/pixfmt.rst +++ b/Documentation/media/uapi/v4l/pixfmt.rst @@ -31,6 +31,7 @@ see also :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`.) pixfmt-intro pixfmt-indexed pixfmt-rgb + pixfmt-bayer yuv-formats hsv-formats depth-formats diff --git a/Documentation/media/uapi/v4l/subdev-formats.rst b/Documentation/media/uapi/v4l/subdev-formats.rst index ab1a48a5ae80..15e11f27b4c8 100644 --- a/Documentation/media/uapi/v4l/subdev-formats.rst +++ b/Documentation/media/uapi/v4l/subdev-formats.rst @@ -85,6 +85,14 @@ formats in memory (a raw Bayer image won't be magically converted to JPEG just by storing it to memory), there is no one-to-one correspondence between them. +The media bus pixel codes document parallel formats. Should the pixel data be +transported over a serial bus, the media bus pixel code that describes a +parallel format that transfers a sample on a single clock cycle is used. For +instance, both MEDIA_BUS_FMT_BGR888_1X24 and MEDIA_BUS_FMT_BGR888_3X8 are used +on parallel busses for transferring an 8 bits per sample BGR data, whereas on +serial busses the data in this format is only referred to using +MEDIA_BUS_FMT_BGR888_1X24. This is because there is effectively only a single +way to transport that format on the serial busses. Packed RGB Formats ^^^^^^^^^^^^^^^^^^ @@ -1305,6 +1313,113 @@ The following tables list existing packed RGB formats. - g\ :sub:`6` - g\ :sub:`5` - g\ :sub:`4` + * .. _MEDIA-BUS-FMT-RGB888-3X8: + + - MEDIA_BUS_FMT_RGB888_3X8 + - 0x101c + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + * - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + * - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` * .. _MEDIA-BUS-FMT-ARGB888-1X32: - MEDIA_BUS_FMT_ARGB888_1X32 diff --git a/Documentation/media/uapi/v4l/v4l2.rst b/Documentation/media/uapi/v4l/v4l2.rst index 004ec00db6bd..97015b9b40b8 100644 --- a/Documentation/media/uapi/v4l/v4l2.rst +++ b/Documentation/media/uapi/v4l/v4l2.rst @@ -60,6 +60,10 @@ Authors, in alphabetical order: - Original author of the V4L2 API and documentation. +- Figa, Tomasz <tfiga@chromium.org> + + - Documented the memory-to-memory decoder interface. + - H Schimek, Michael <mschimek@gmx.at> - Original author of the V4L2 API and documentation. @@ -68,6 +72,10 @@ Authors, in alphabetical order: - Documented the Digital Video timings API. +- Osciak, Pawel <posciak@chromium.org> + + - Documented the memory-to-memory decoder interface. + - Osciak, Pawel <pawel@osciak.com> - Designed and documented the multi-planar API. @@ -92,7 +100,7 @@ Authors, in alphabetical order: - Designed and documented the VIDIOC_LOG_STATUS ioctl, the extended control ioctls, major parts of the sliced VBI API, the MPEG encoder and decoder APIs and the DV Timings API. -**Copyright** |copy| 1999-2016: Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab, Pawel Osciak, Sakari Ailus & Antti Palosaari. +**Copyright** |copy| 1999-2018: Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab, Pawel Osciak, Sakari Ailus & Antti Palosaari, Tomasz Figa Except when explicitly stated as GPL, programming examples within this part can be used and distributed without restrictions. diff --git a/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst b/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst index ccf83b05afa7..57f0066f4cff 100644 --- a/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst +++ b/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst @@ -56,14 +56,16 @@ The ``cmd`` field must contain the command code. Some commands use the A :ref:`write() <func-write>` or :ref:`VIDIOC_STREAMON` call sends an implicit START command to the decoder if it has not been -started yet. +started yet. Applies to both queues of mem2mem decoders. A :ref:`close() <func-close>` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` call of a streaming file descriptor sends an implicit immediate STOP -command to the decoder, and all buffered data is discarded. +command to the decoder, and all buffered data is discarded. Applies to both +queues of mem2mem decoders. -These ioctls are optional, not all drivers may support them. They were -introduced in Linux 3.3. +In principle, these ioctls are optional, not all drivers may support them. They were +introduced in Linux 3.3. They are, however, mandatory for stateful mem2mem decoders +(as further documented in :ref:`decoder`). .. tabularcolumns:: |p{1.1cm}|p{2.4cm}|p{1.2cm}|p{1.6cm}|p{10.6cm}| @@ -167,26 +169,32 @@ introduced in Linux 3.3. ``V4L2_DEC_CMD_RESUME`` for that. This command has one flag: ``V4L2_DEC_CMD_START_MUTE_AUDIO``. If set, then audio will be muted when playing back at a non-standard speed. + + For a device implementing the :ref:`decoder`, once the drain sequence + is initiated with the ``V4L2_DEC_CMD_STOP`` command, it must be driven + to completion before this command can be invoked. Any attempt to + invoke the command while the drain sequence is in progress will trigger + an ``EBUSY`` error code. The command may be also used to restart the + decoder in case of an implicit stop initiated by the decoder itself, + without the ``V4L2_DEC_CMD_STOP`` being called explicitly. See + :ref:`decoder` for more details. * - ``V4L2_DEC_CMD_STOP`` - 1 - Stop the decoder. When the decoder is already stopped, this command does nothing. This command has two flags: if ``V4L2_DEC_CMD_STOP_TO_BLACK`` is set, then the decoder will set the picture to black after it stopped decoding. Otherwise the last - image will repeat. mem2mem decoders will stop producing new frames - altogether. They will send a ``V4L2_EVENT_EOS`` event when the - last frame has been decoded and all frames are ready to be - dequeued and will set the ``V4L2_BUF_FLAG_LAST`` buffer flag on - the last buffer of the capture queue to indicate there will be no - new buffers produced to dequeue. This buffer may be empty, - indicated by the driver setting the ``bytesused`` field to 0. Once - the ``V4L2_BUF_FLAG_LAST`` flag was set, the - :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore, - but return an ``EPIPE`` error code. If + image will repeat. If ``V4L2_DEC_CMD_STOP_IMMEDIATELY`` is set, then the decoder stops immediately (ignoring the ``pts`` value), otherwise it will keep decoding until timestamp >= pts or until the last of the pending data from its internal buffers was decoded. + + For a device implementing the :ref:`decoder`, the command will initiate + the drain sequence as documented in :ref:`decoder`. No flags or other + arguments are accepted in this case. Any attempt to invoke the command + again before the sequence completes will trigger an ``EBUSY`` error + code. * - ``V4L2_DEC_CMD_PAUSE`` - 2 - Pause the decoder. When the decoder has not been started yet, the @@ -209,6 +217,11 @@ 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 <gen-errors>` chapter. +EBUSY + A drain sequence of a device implementing the :ref:`decoder` is still in + progress. It is not allowed to issue another decoder command until it + completes. + EINVAL The ``cmd`` field is invalid. diff --git a/Documentation/media/uapi/v4l/vidioc-dqevent.rst b/Documentation/media/uapi/v4l/vidioc-dqevent.rst index dea9c0cc00ab..42659a3d1705 100644 --- a/Documentation/media/uapi/v4l/vidioc-dqevent.rst +++ b/Documentation/media/uapi/v4l/vidioc-dqevent.rst @@ -389,14 +389,19 @@ call. decoder. Applications will have to query the new resolution (if any, the signal may also have been lost). + For stateful decoders follow the guidelines in :ref:`decoder`. + Video Capture devices have to query the new timings using + :ref:`VIDIOC_QUERY_DV_TIMINGS` or + :ref:`VIDIOC_QUERYSTD <VIDIOC_QUERYSTD>`. + *Important*: even if the new video timings appear identical to the old ones, receiving this event indicates that there was an issue with the video signal and you must stop and restart streaming (:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` followed by :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`). The reason is - that many devices are not able to recover from a temporary loss of - signal and so restarting streaming I/O is required in order for the - hardware to synchronize to the video signal. + that many Video Capture devices are not able to recover from a temporary + loss of signal and so restarting streaming I/O is required in order for + the hardware to synchronize to the video signal. Return Value diff --git a/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst b/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst index 822d6730e7d2..399ef1062bac 100644 --- a/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst +++ b/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst @@ -127,6 +127,22 @@ one until ``EINVAL`` is returned. - This format is not native to the device but emulated through software (usually libv4l2), where possible try to use a native format instead for better performance. + * - ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM`` + - 0x0004 + - The hardware decoder for this compressed bytestream format (aka coded + format) is capable of parsing a continuous bytestream. Applications do + not need to parse the bytestream themselves to find the boundaries + between frames/fields. This flag can only be used in combination with + the ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to compressed + formats only. This flag is valid for stateful decoders only. + * - ``V4L2_FMT_FLAG_DYN_RESOLUTION`` + - 0x0008 + - Dynamic resolution switching is supported by the device for this + compressed bytestream format (aka coded format). It will notify the user + via the event ``V4L2_EVENT_SOURCE_CHANGE`` when changes in the video + parameters are detected. This flag can only be used in combination + with the ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to + compressed formats only. It is also only applies to stateful codecs. Return Value diff --git a/Documentation/media/uapi/v4l/vidioc-qbuf.rst b/Documentation/media/uapi/v4l/vidioc-qbuf.rst index dbf7b445a27b..407302d80684 100644 --- a/Documentation/media/uapi/v4l/vidioc-qbuf.rst +++ b/Documentation/media/uapi/v4l/vidioc-qbuf.rst @@ -139,6 +139,14 @@ may continue as normal, but should be aware that data in the dequeued buffer might be corrupted. When using the multi-planar API, the planes array must be passed in as well. +If the application sets the ``memory`` field to ``V4L2_MEMORY_DMABUF`` to +dequeue a :ref:`DMABUF <dmabuf>` buffer, the driver fills the ``m.fd`` field +with a file descriptor numerically the same as the one given to ``VIDIOC_QBUF`` +when the buffer was enqueued. No new file descriptor is created at dequeue time +and the value is only for the application convenience. When the multi-planar +API is used the ``m.fd`` fields of the passed array of struct +:c:type:`v4l2_plane` are filled instead. + By default ``VIDIOC_DQBUF`` blocks when no buffer is in the outgoing queue. When the ``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>` function, ``VIDIOC_DQBUF`` returns diff --git a/Documentation/media/uapi/v4l/vidioc-queryctrl.rst b/Documentation/media/uapi/v4l/vidioc-queryctrl.rst index f824162d0ea9..a3d56ffbf4cc 100644 --- a/Documentation/media/uapi/v4l/vidioc-queryctrl.rst +++ b/Documentation/media/uapi/v4l/vidioc-queryctrl.rst @@ -39,8 +39,8 @@ Arguments File descriptor returned by :ref:`open() <func-open>`. ``argp`` - Pointer to struct :c:type:`v4l2_queryctl`, :c:type:`v4l2_query_ext_ctrl` - or :c:type`v4l2_querymenu` (depending on the ioctl). + Pointer to struct :c:type:`v4l2_queryctrl`, :c:type:`v4l2_query_ext_ctrl` + or :c:type:`v4l2_querymenu` (depending on the ioctl). Description @@ -443,6 +443,36 @@ See also the examples in :ref:`control`. - n/a - A struct :c:type:`v4l2_ctrl_mpeg2_quantization`, containing MPEG-2 quantization matrices for stateless video decoders. + * - ``V4L2_CTRL_TYPE_H264_SPS`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_h264_sps`, containing H264 + sequence parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_H264_PPS`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_h264_pps`, containing H264 + picture parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_H264_SCALING_MATRIX`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_h264_scaling_matrix`, containing H264 + scaling matrices for stateless video decoders. + * - ``V4L2_CTRL_TYPE_H264_SLICE_PARAMS`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_h264_slice_params`, containing H264 + slice parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_H264_DECODE_PARAMS`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_h264_decode_params`, containing H264 + decode parameters for stateless video decoders. .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| diff --git a/Documentation/media/v4l-drivers/imx7.rst b/Documentation/media/v4l-drivers/imx7.rst index fe411f65c01c..1e442c97da47 100644 --- a/Documentation/media/v4l-drivers/imx7.rst +++ b/Documentation/media/v4l-drivers/imx7.rst @@ -41,7 +41,7 @@ data from MIPI CSI-2 camera sensor. It has one source pad, corresponding to the virtual channel 0. This module is compliant to previous version of Samsung D-phy, and supports two D-PHY Rx Data lanes. -csi_mux +csi-mux ------- This is the video multiplexer. It has two sink pads to select from either camera @@ -56,7 +56,7 @@ can interface directly with Parallel and MIPI CSI-2 buses. It has 256 x 64 FIFO to store received image pixel data and embedded DMA controllers to transfer data from the FIFO through AHB bus. -This entity has one sink pad that receives from the csi_mux entity and a single +This entity has one sink pad that receives from the csi-mux entity and a single source pad that routes video frames directly to memory buffers. This pad is routed to a capture device node. @@ -81,14 +81,14 @@ an output of 800x600, and BGGR 10 bit bayer format: # Setup links media-ctl -l "'ov2680 1-0036':0 -> 'imx7-mipi-csis.0':0[1]" - media-ctl -l "'imx7-mipi-csis.0':1 -> 'csi_mux':1[1]" - media-ctl -l "'csi_mux':2 -> 'csi':0[1]" + media-ctl -l "'imx7-mipi-csis.0':1 -> 'csi-mux':1[1]" + media-ctl -l "'csi-mux':2 -> 'csi':0[1]" media-ctl -l "'csi':1 -> 'csi capture':0[1]" # Configure pads for pipeline media-ctl -V "'ov2680 1-0036':0 [fmt:SBGGR10_1X10/800x600 field:none]" - media-ctl -V "'csi_mux':1 [fmt:SBGGR10_1X10/800x600 field:none]" - media-ctl -V "'csi_mux':2 [fmt:SBGGR10_1X10/800x600 field:none]" + media-ctl -V "'csi-mux':1 [fmt:SBGGR10_1X10/800x600 field:none]" + media-ctl -V "'csi-mux':2 [fmt:SBGGR10_1X10/800x600 field:none]" media-ctl -V "'imx7-mipi-csis.0':0 [fmt:SBGGR10_1X10/800x600 field:none]" media-ctl -V "'csi':0 [fmt:SBGGR10_1X10/800x600 field:none]" @@ -97,64 +97,63 @@ the resolutions supported by the sensor. .. code-block:: none - root@imx7s-warp:~# media-ctl -p - Media controller API version 4.17.0 - - Media device information - ------------------------ - driver imx-media - model imx-media - serial - bus info - hw revision 0x0 - driver version 4.17.0 - - Device topology - - entity 1: csi (2 pads, 2 links) - type V4L2 subdev subtype Unknown flags 0 - device node name /dev/v4l-subdev0 - pad0: Sink - [fmt:SBGGR10_1X10/800x600 field:none] - <- "csi_mux":2 [ENABLED] - pad1: Source - [fmt:SBGGR10_1X10/800x600 field:none] - -> "csi capture":0 [ENABLED] - - - entity 4: csi capture (1 pad, 1 link) - type Node subtype V4L flags 0 - device node name /dev/video0 - pad0: Sink - <- "csi":1 [ENABLED] - - - entity 10: csi_mux (3 pads, 2 links) - type V4L2 subdev subtype Unknown flags 0 - device node name /dev/v4l-subdev1 - pad0: Sink - [fmt:unknown/0x0] - pad1: Sink - [fmt:unknown/800x600 field:none] - <- "imx7-mipi-csis.0":1 [ENABLED] - pad2: Source - [fmt:unknown/800x600 field:none] - -> "csi":0 [ENABLED] - - - entity 14: imx7-mipi-csis.0 (2 pads, 2 links) - type V4L2 subdev subtype Unknown flags 0 - device node name /dev/v4l-subdev2 - pad0: Sink - [fmt:SBGGR10_1X10/800x600 field:none] - <- "ov2680 1-0036":0 [ENABLED] - pad1: Source - [fmt:SBGGR10_1X10/800x600 field:none] - -> "csi_mux":1 [ENABLED] - - - entity 17: ov2680 1-0036 (1 pad, 1 link) - type V4L2 subdev subtype Sensor flags 0 - device node name /dev/v4l-subdev3 - pad0: Source - [fmt:SBGGR10_1X10/800x600 field:none] - -> "imx7-mipi-csis.0":0 [ENABLED] - + # media-ctl -p + Media controller API version 5.2.0 + + Media device information + ------------------------ + driver imx7-csi + model imx-media + serial + bus info + hw revision 0x0 + driver version 5.2.0 + + Device topology + - entity 1: csi (2 pads, 2 links) + type V4L2 subdev subtype Unknown flags 0 + device node name /dev/v4l-subdev0 + pad0: Sink + [fmt:SBGGR10_1X10/800x600 field:none colorspace:srgb xfer:srgb ycbcr:601 quantization:full-range] + <- "csi-mux":2 [ENABLED] + pad1: Source + [fmt:SBGGR10_1X10/800x600 field:none colorspace:srgb xfer:srgb ycbcr:601 quantization:full-range] + -> "csi capture":0 [ENABLED] + + - entity 4: csi capture (1 pad, 1 link) + type Node subtype V4L flags 0 + device node name /dev/video0 + pad0: Sink + <- "csi":1 [ENABLED] + + - entity 10: csi-mux (3 pads, 2 links) + type V4L2 subdev subtype Unknown flags 0 + device node name /dev/v4l-subdev1 + pad0: Sink + [fmt:Y8_1X8/1x1 field:none] + pad1: Sink + [fmt:SBGGR10_1X10/800x600 field:none] + <- "imx7-mipi-csis.0":1 [ENABLED] + pad2: Source + [fmt:SBGGR10_1X10/800x600 field:none] + -> "csi":0 [ENABLED] + + - entity 14: imx7-mipi-csis.0 (2 pads, 2 links) + type V4L2 subdev subtype Unknown flags 0 + device node name /dev/v4l-subdev2 + pad0: Sink + [fmt:SBGGR10_1X10/800x600 field:none] + <- "ov2680 1-0036":0 [ENABLED] + pad1: Source + [fmt:SBGGR10_1X10/800x600 field:none] + -> "csi-mux":1 [ENABLED] + + - entity 17: ov2680 1-0036 (1 pad, 1 link) + type V4L2 subdev subtype Sensor flags 0 + device node name /dev/v4l-subdev3 + pad0: Source + [fmt:SBGGR10_1X10/800x600@1/30 field:none colorspace:srgb] + -> "imx7-mipi-csis.0":0 [ENABLED] References ---------- diff --git a/Documentation/media/v4l-drivers/index.rst b/Documentation/media/v4l-drivers/index.rst index 33a055907258..c4c78a28654c 100644 --- a/Documentation/media/v4l-drivers/index.rst +++ b/Documentation/media/v4l-drivers/index.rst @@ -64,5 +64,6 @@ For more details see the file COPYING in the source distribution of Linux. si476x soc-camera uvcvideo + vimc vivid zr364xx diff --git a/Documentation/media/v4l-drivers/vimc.dot b/Documentation/media/v4l-drivers/vimc.dot new file mode 100644 index 000000000000..57863a13fa39 --- /dev/null +++ b/Documentation/media/v4l-drivers/vimc.dot @@ -0,0 +1,22 @@ +# SPDX-License-Identifier: GPL-2.0 + +digraph board { + rankdir=TB + n00000001 [label="{{} | Sensor A\n/dev/v4l-subdev0 | {<port0> 0}}", shape=Mrecord, style=filled, fillcolor=green] + n00000001:port0 -> n00000005:port0 [style=bold] + n00000001:port0 -> n0000000b [style=bold] + n00000003 [label="{{} | Sensor B\n/dev/v4l-subdev1 | {<port0> 0}}", shape=Mrecord, style=filled, fillcolor=green] + n00000003:port0 -> n00000008:port0 [style=bold] + n00000003:port0 -> n0000000f [style=bold] + n00000005 [label="{{<port0> 0} | Debayer A\n/dev/v4l-subdev2 | {<port1> 1}}", shape=Mrecord, style=filled, fillcolor=green] + n00000005:port1 -> n00000017:port0 + n00000008 [label="{{<port0> 0} | Debayer B\n/dev/v4l-subdev3 | {<port1> 1}}", shape=Mrecord, style=filled, fillcolor=green] + n00000008:port1 -> n00000017:port0 [style=dashed] + n0000000b [label="Raw Capture 0\n/dev/video0", shape=box, style=filled, fillcolor=yellow] + n0000000f [label="Raw Capture 1\n/dev/video1", shape=box, style=filled, fillcolor=yellow] + n00000013 [label="RGB/YUV Input\n/dev/video2", shape=box, style=filled, fillcolor=yellow] + n00000013 -> n00000017:port0 [style=dashed] + n00000017 [label="{{<port0> 0} | Scaler\n/dev/v4l-subdev4 | {<port1> 1}}", shape=Mrecord, style=filled, fillcolor=green] + n00000017:port1 -> n0000001a [style=bold] + n0000001a [label="RGB/YUV Capture\n/dev/video3", shape=box, style=filled, fillcolor=yellow] +} diff --git a/Documentation/media/v4l-drivers/vimc.rst b/Documentation/media/v4l-drivers/vimc.rst new file mode 100644 index 000000000000..406417680db5 --- /dev/null +++ b/Documentation/media/v4l-drivers/vimc.rst @@ -0,0 +1,109 @@ +.. SPDX-License-Identifier: GPL-2.0 + +The Virtual Media Controller Driver (vimc) +========================================== + +The vimc driver emulates complex video hardware using the V4L2 API and the Media +API. It has a capture device and three subdevices: sensor, debayer and scaler. + +Topology +-------- + +The topology is hardcoded, although you could modify it in vimc-core and +recompile the driver to achieve your own topology. This is the default topology: + +.. _vimc_topology_graph: + +.. kernel-figure:: vimc.dot + :alt: Diagram of the default media pipeline topology + :align: center + + Media pipeline graph on vimc + +Configuring the topology +~~~~~~~~~~~~~~~~~~~~~~~~ + +Each subdevice will come with its default configuration (pixelformat, height, +width, ...). One needs to configure the topology in order to match the +configuration on each linked subdevice to stream frames through the pipeline. +If the configuration doesn't match, the stream will fail. The ``v4l-utils`` +package is a bundle of user-space applications, that comes with ``media-ctl`` and +``v4l2-ctl`` that can be used to configure the vimc configuration. This sequence +of commands fits for the default topology: + +.. code-block:: bash + + media-ctl -d platform:vimc -V '"Sensor A":0[fmt:SBGGR8_1X8/640x480]' + media-ctl -d platform:vimc -V '"Debayer A":0[fmt:SBGGR8_1X8/640x480]' + media-ctl -d platform:vimc -V '"Sensor B":0[fmt:SBGGR8_1X8/640x480]' + media-ctl -d platform:vimc -V '"Debayer B":0[fmt:SBGGR8_1X8/640x480]' + v4l2-ctl -z platform:vimc -d "RGB/YUV Capture" -v width=1920,height=1440 + v4l2-ctl -z platform:vimc -d "Raw Capture 0" -v pixelformat=BA81 + v4l2-ctl -z platform:vimc -d "Raw Capture 1" -v pixelformat=BA81 + +Subdevices +---------- + +Subdevices define the behavior of an entity in the topology. Depending on the +subdevice, the entity can have multiple pads of type source or sink. + +vimc-sensor: + Generates images in several formats using video test pattern generator. + Exposes: + + * 1 Pad source + +vimc-debayer: + Transforms images in bayer format into a non-bayer format. + Exposes: + + * 1 Pad sink + * 1 Pad source + +vimc-scaler: + Scale up the image by a factor of 3. E.g.: a 640x480 image becomes a + 1920x1440 image. (this value can be configured, see at + `Module options`_). + Exposes: + + * 1 Pad sink + * 1 Pad source + +vimc-capture: + Exposes node /dev/videoX to allow userspace to capture the stream. + Exposes: + + * 1 Pad sink + * 1 Pad source + +Module options +--------------- + +Vimc has a few module parameters to configure the driver. You should pass +those arguments to each subdevice, not to the vimc module. For example:: + + vimc_subdevice.param=value + +* ``vimc_scaler.sca_mult=<unsigned int>`` + + Image size multiplier factor to be used to multiply both width and + 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). + +* ``vimc_debayer.deb_mean_win_size=<unsigned int>`` + + Window size to calculate the mean. Note: the window size needs to be an + odd number, as the main pixel stays in the center of the window, + otherwise the next odd number is considered (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 diff --git a/Documentation/media/v4l-drivers/vivid.rst b/Documentation/media/v4l-drivers/vivid.rst index edb6f33e029c..7082fec4075d 100644 --- a/Documentation/media/v4l-drivers/vivid.rst +++ b/Documentation/media/v4l-drivers/vivid.rst @@ -941,6 +941,11 @@ Digital Video Controls affects the reported colorspace since DVI_D outputs will always use sRGB. +- Display Present: + + sets the presence of a "display" on the HDMI output. This affects + the tx_edid_present, tx_hotplug and tx_rxsense controls. + FM Radio Receiver Controls ~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/media/videodev2.h.rst.exceptions b/Documentation/media/videodev2.h.rst.exceptions index 64d348e67df9..adeb6b7a15cb 100644 --- a/Documentation/media/videodev2.h.rst.exceptions +++ b/Documentation/media/videodev2.h.rst.exceptions @@ -136,6 +136,11 @@ replace symbol V4L2_CTRL_TYPE_U32 :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_U8 :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_MPEG2_SLICE_PARAMS :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_MPEG2_QUANTIZATION :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_H264_SPS :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_H264_PPS :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_H264_SCALING_MATRIX :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_H264_SLICE_PARAMS :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_H264_DECODE_PARAMS :c:type:`v4l2_ctrl_type` # V4L2 capability defines replace define V4L2_CAP_VIDEO_CAPTURE device-capabilities @@ -175,15 +180,17 @@ replace define V4L2_PIX_FMT_FLAG_PREMUL_ALPHA reserved-formats # V4L2 format flags replace define V4L2_FMT_FLAG_COMPRESSED fmtdesc-flags replace define V4L2_FMT_FLAG_EMULATED fmtdesc-flags +replace define V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM fmtdesc-flags +replace define V4L2_FMT_FLAG_DYN_RESOLUTION fmtdesc-flags -# V4L2 tymecode types +# V4L2 timecode types replace define V4L2_TC_TYPE_24FPS timecode-type replace define V4L2_TC_TYPE_25FPS timecode-type replace define V4L2_TC_TYPE_30FPS timecode-type replace define V4L2_TC_TYPE_50FPS timecode-type replace define V4L2_TC_TYPE_60FPS timecode-type -# V4L2 tymecode flags +# V4L2 timecode flags replace define V4L2_TC_FLAG_DROPFRAME timecode-flags replace define V4L2_TC_FLAG_COLORFRAME timecode-flags replace define V4L2_TC_USERBITS_field timecode-flags |