diff options
Diffstat (limited to 'Documentation')
166 files changed, 7135 insertions, 5142 deletions
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 index a10a4de3e5fe..c4a4497c249a 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 +++ b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 @@ -109,30 +109,6 @@ Description: When counting down the counter start from preset value and fire event when reach 0. -What: /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available -KernelVersion: 4.12 -Contact: benjamin.gaignard@st.com -Description: - Reading returns the list possible quadrature modes. - -What: /sys/bus/iio/devices/iio:deviceX/in_count0_quadrature_mode -KernelVersion: 4.12 -Contact: benjamin.gaignard@st.com -Description: - Configure the device counter quadrature modes: - - channel_A: - Encoder A input servers as the count input and B as - the UP/DOWN direction control input. - - channel_B: - Encoder B input serves as the count input and A as - the UP/DOWN direction control input. - - quadrature: - Encoder A and B inputs are mixed to get direction - and count with a scale of 0.25. - What: /sys/bus/iio/devices/iio:deviceX/in_count_enable_mode_available KernelVersion: 4.12 Contact: benjamin.gaignard@st.com diff --git a/Documentation/admin-guide/bootconfig.rst b/Documentation/admin-guide/bootconfig.rst index a22024f9175e..9b90efcc3a35 100644 --- a/Documentation/admin-guide/bootconfig.rst +++ b/Documentation/admin-guide/bootconfig.rst @@ -137,15 +137,24 @@ Boot Kernel With a Boot Config ============================== Since the boot configuration file is loaded with initrd, it will be added -to the end of the initrd (initramfs) image file with size, checksum and -12-byte magic word as below. +to the end of the initrd (initramfs) image file with padding, size, +checksum and 12-byte magic word as below. -[initrd][bootconfig][size(u32)][checksum(u32)][#BOOTCONFIG\n] +[initrd][bootconfig][padding][size(le32)][checksum(le32)][#BOOTCONFIG\n] + +The size and checksum fields are unsigned 32bit little endian value. + +When the boot configuration is added to the initrd image, the total +file size is aligned to 4 bytes. To fill the gap, null characters +(``\0``) will be added. Thus the ``size`` is the length of the bootconfig +file + padding bytes. The Linux kernel decodes the last part of the initrd image in memory to get the boot configuration data. Because of this "piggyback" method, there is no need to change or -update the boot loader and the kernel image itself. +update the boot loader and the kernel image itself as long as the boot +loader passes the correct initrd file size. If by any chance, the boot +loader passes a longer size, the kernel feils to find the bootconfig data. To do this operation, Linux kernel provides "bootconfig" command under tools/bootconfig, which allows admin to apply or delete the config file @@ -176,7 +185,8 @@ up to 512 key-value pairs. If keys contains 3 words in average, it can contain 256 key-value pairs. In most cases, the number of config items will be under 100 entries and smaller than 8KB, so it would be enough. If the node number exceeds 1024, parser returns an error even if the file -size is smaller than 32KB. +size is smaller than 32KB. (Note that this maximum size is not including +the padding null characters.) Anyway, since bootconfig command verifies it when appending a boot config to initrd image, user can notice it before boot. diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 526d65d8573a..a7d60d847584 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -2858,6 +2858,8 @@ mds=off [X86] tsx_async_abort=off [X86] kvm.nx_huge_pages=off [X86] + no_entry_flush [PPC] + no_uaccess_flush [PPC] Exceptions: This does not have any effect on @@ -3186,6 +3188,8 @@ noefi Disable EFI runtime services support. + no_entry_flush [PPC] Don't flush the L1-D cache when entering the kernel. + noexec [IA-64] noexec [X86] @@ -3235,6 +3239,9 @@ nospec_store_bypass_disable [HW] Disable all mitigations for the Speculative Store Bypass vulnerability + no_uaccess_flush + [PPC] Don't flush the L1-D cache after accessing user data. + noxsave [BUGS=X86] Disables x86 extended register state save and restore using xsave. The kernel will fallback to enabling legacy floating-point and sse state. @@ -3368,6 +3375,8 @@ nosep [BUGS=X86-32] Disables x86 SYSENTER/SYSEXIT support. + nosgx [X86-64,SGX] Disables Intel SGX kernel support. + nosmp [SMP] Tells an SMP kernel to act as a UP kernel, and disable the IO APIC. legacy for "maxcpus=0". diff --git a/Documentation/admin-guide/media/rkisp1.rst b/Documentation/admin-guide/media/rkisp1.rst index 42e37ed255f6..2267e4fb475e 100644 --- a/Documentation/admin-guide/media/rkisp1.rst +++ b/Documentation/admin-guide/media/rkisp1.rst @@ -86,7 +86,7 @@ the driver through the rkisp_params node to improve image quality during a video stream. The buffer format is defined by struct :c:type:`rkisp1_stat_buffer`, and userspace should set -:ref:`V4L2_META_FMT_RK_ISP1_STAT_3A <v4l2-meta-fmt-stat-rkisp1>` as the +:ref:`V4L2_META_FMT_RK_ISP1_STAT_3A <v4l2-meta-fmt-rk-isp1-stat-3a>` as the dataformat. .. _rkisp1_params: @@ -100,7 +100,7 @@ and others. The buffer format is defined by struct :c:type:`rkisp1_params_cfg`, and userspace should set -:ref:`V4L2_META_FMT_RK_ISP1_PARAMS <v4l2-meta-fmt-params-rkisp1>` as the +:ref:`V4L2_META_FMT_RK_ISP1_PARAMS <v4l2-meta-fmt-rk-isp1-params>` as the dataformat. diff --git a/Documentation/dev-tools/kunit/faq.rst b/Documentation/dev-tools/kunit/faq.rst index 1628862e7024..8d5029ad210a 100644 --- a/Documentation/dev-tools/kunit/faq.rst +++ b/Documentation/dev-tools/kunit/faq.rst @@ -90,7 +90,7 @@ things to try. re-run kunit_tool. 5. Try to run ``make ARCH=um defconfig`` before running ``kunit.py run``. This may help clean up any residual config items which could be causing problems. -6. Finally, try running KUnit outside UML. KUnit and KUnit tests can run be +6. Finally, try running KUnit outside UML. KUnit and KUnit tests can be built into any kernel, or can be built as a module and loaded at runtime. Doing so should allow you to determine if UML is causing the issue you're seeing. When tests are built-in, they will execute when the kernel boots, and diff --git a/Documentation/dev-tools/kunit/style.rst b/Documentation/dev-tools/kunit/style.rst index da1d6f0ed6bc..8dbcdc552606 100644 --- a/Documentation/dev-tools/kunit/style.rst +++ b/Documentation/dev-tools/kunit/style.rst @@ -175,17 +175,17 @@ An example Kconfig entry: .. code-block:: none - config FOO_KUNIT_TEST - tristate "KUnit test for foo" if !KUNIT_ALL_TESTS - depends on KUNIT - default KUNIT_ALL_TESTS - help - This builds unit tests for foo. + config FOO_KUNIT_TEST + tristate "KUnit test for foo" if !KUNIT_ALL_TESTS + depends on KUNIT + default KUNIT_ALL_TESTS + help + This builds unit tests for foo. - For more information on KUnit and unit tests in general, please refer - to the KUnit documentation in Documentation/dev-tools/kunit + For more information on KUnit and unit tests in general, please refer + to the KUnit documentation in Documentation/dev-tools/kunit/. - If unsure, say N + If unsure, say N. Test File and Module Names diff --git a/Documentation/dev-tools/kunit/usage.rst b/Documentation/dev-tools/kunit/usage.rst index 62142a47488c..9c28c518e6a3 100644 --- a/Documentation/dev-tools/kunit/usage.rst +++ b/Documentation/dev-tools/kunit/usage.rst @@ -92,7 +92,7 @@ behavior of a function called ``add``; the first parameter is always of type the second parameter, in this case, is what the value is expected to be; the last value is what the value actually is. If ``add`` passes all of these expectations, the test case, ``add_test_basic`` will pass; if any one of these -expectations fail, the test case will fail. +expectations fails, the test case will fail. It is important to understand that a test case *fails* when any expectation is violated; however, the test will continue running, potentially trying other @@ -202,7 +202,7 @@ Example: kunit_test_suite(example_test_suite); In the above example the test suite, ``example_test_suite``, would run the test -cases ``example_test_foo``, ``example_test_bar``, and ``example_test_baz``, +cases ``example_test_foo``, ``example_test_bar``, and ``example_test_baz``; each would have ``example_test_init`` called immediately before it and would have ``example_test_exit`` called immediately after it. ``kunit_test_suite(example_test_suite)`` registers the test suite with the @@ -229,7 +229,7 @@ through some sort of indirection where a function is exposed as part of an API such that the definition of that function can be changed without affecting the rest of the code base. In the kernel this primarily comes from two constructs, classes, structs that contain function pointers that are provided by the -implementer, and architecture specific functions which have definitions selected +implementer, and architecture-specific functions which have definitions selected at compile time. Classes @@ -459,7 +459,7 @@ KUnit on non-UML architectures By default KUnit uses UML as a way to provide dependencies for code under test. Under most circumstances KUnit's usage of UML should be treated as an implementation detail of how KUnit works under the hood. Nevertheless, there -are instances where being able to run architecture specific code or test +are instances where being able to run architecture-specific code or test against real hardware is desirable. For these reasons KUnit supports running on other architectures. @@ -599,7 +599,7 @@ writing normal KUnit tests. One special caveat is that you have to reset hardware state in between test cases; if this is not possible, you may only be able to run one test case per invocation. -.. TODO(brendanhiggins@google.com): Add an actual example of an architecture +.. TODO(brendanhiggins@google.com): Add an actual example of an architecture- dependent KUnit test. KUnit debugfs representation diff --git a/Documentation/devicetree/bindings/auxdisplay/modtronix,lcd2s.yaml b/Documentation/devicetree/bindings/auxdisplay/modtronix,lcd2s.yaml new file mode 100644 index 000000000000..a1d55a2634a5 --- /dev/null +++ b/Documentation/devicetree/bindings/auxdisplay/modtronix,lcd2s.yaml @@ -0,0 +1,58 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/auxdisplay/modtronix,lcd2s.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Modtronix engineering LCD2S Character LCD Display + +maintainers: + - Lars Poeschel <poeschel@lemonage.de> + +description: + The LCD2S is a Character LCD Display manufactured by Modtronix Engineering. + The display supports a serial I2C and SPI interface. The driver currently + only supports the I2C interface. + +properties: + compatible: + const: modtronix,lcd2s + + reg: + maxItems: 1 + description: + I2C bus address of the display. + + display-height-chars: + description: Height of the display, in character cells. + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 1 + maximum: 4 + + display-width-chars: + description: Width of the display, in character cells. + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 16 + maximum: 20 + +required: + - compatible + - reg + - display-height-chars + - display-width-chars + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + lcd2s: auxdisplay@28 { + compatible = "modtronix,lcd2s"; + reg = <0x28>; + display-height-chars = <4>; + display-width-chars = <20>; + }; + }; diff --git a/Documentation/devicetree/bindings/crypto/intel,keembay-ocs-aes.yaml b/Documentation/devicetree/bindings/crypto/intel,keembay-ocs-aes.yaml new file mode 100644 index 000000000000..ee2c099981b2 --- /dev/null +++ b/Documentation/devicetree/bindings/crypto/intel,keembay-ocs-aes.yaml @@ -0,0 +1,45 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/crypto/intel,keembay-ocs-aes.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Intel Keem Bay OCS AES Device Tree Bindings + +maintainers: + - Daniele Alessandrelli <daniele.alessandrelli@intel.com> + +description: + The Intel Keem Bay Offload and Crypto Subsystem (OCS) AES engine provides + hardware-accelerated AES/SM4 encryption/decryption. + +properties: + compatible: + const: intel,keembay-ocs-aes + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - clocks + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + crypto@30008000 { + compatible = "intel,keembay-ocs-aes"; + reg = <0x30008000 0x1000>; + interrupts = <GIC_SPI 114 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&scmi_clk 95>; + }; diff --git a/Documentation/devicetree/bindings/display/brcm,bcm2711-hdmi.yaml b/Documentation/devicetree/bindings/display/brcm,bcm2711-hdmi.yaml index 03a76729d26c..7ce06f9f9f8e 100644 --- a/Documentation/devicetree/bindings/display/brcm,bcm2711-hdmi.yaml +++ b/Documentation/devicetree/bindings/display/brcm,bcm2711-hdmi.yaml @@ -76,6 +76,12 @@ properties: resets: maxItems: 1 + wifi-2.4ghz-coexistence: + type: boolean + description: > + Should the pixel frequencies in the WiFi frequencies range be + avoided? + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/display/bridge/analogix,anx7625.yaml b/Documentation/devicetree/bindings/display/bridge/analogix,anx7625.yaml new file mode 100644 index 000000000000..60585a4fc22b --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/analogix,anx7625.yaml @@ -0,0 +1,95 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2019 Analogix Semiconductor, Inc. +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/display/bridge/analogix,anx7625.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Analogix ANX7625 SlimPort (4K Mobile HD Transmitter) + +maintainers: + - Xin Ji <xji@analogixsemi.com> + +description: | + The ANX7625 is an ultra-low power 4K Mobile HD Transmitter + designed for portable devices. + +properties: + compatible: + items: + - const: analogix,anx7625 + + reg: + maxItems: 1 + + interrupts: + description: used for interrupt pin B8. + maxItems: 1 + + enable-gpios: + description: used for power on chip control, POWER_EN pin D2. + maxItems: 1 + + reset-gpios: + description: used for reset chip control, RESET_N pin B7. + maxItems: 1 + + ports: + type: object + + properties: + port@0: + type: object + description: + Video port for MIPI DSI input. + + port@1: + type: object + description: + Video port for panel or connector. + + required: + - port@0 + - port@1 + +required: + - compatible + - reg + - ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + encoder@58 { + compatible = "analogix,anx7625"; + reg = <0x58>; + enable-gpios = <&pio 45 GPIO_ACTIVE_HIGH>; + reset-gpios = <&pio 73 GPIO_ACTIVE_HIGH>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + mipi2dp_bridge_in: port@0 { + reg = <0>; + anx7625_in: endpoint { + remote-endpoint = <&mipi_dsi>; + }; + }; + + mipi2dp_bridge_out: port@1 { + reg = <1>; + anx7625_out: endpoint { + remote-endpoint = <&panel_in>; + }; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/bridge/intel,keembay-dsi.yaml b/Documentation/devicetree/bindings/display/bridge/intel,keembay-dsi.yaml new file mode 100644 index 000000000000..ab5be2625224 --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/intel,keembay-dsi.yaml @@ -0,0 +1,101 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/bridge/intel,keembay-dsi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Devicetree bindings for Intel Keem Bay mipi dsi controller + +maintainers: + - Anitha Chrisanthus <anitha.chrisanthus@intel.com> + - Edmond J Dea <edmund.j.dea@intel.com> + +properties: + compatible: + const: intel,keembay-dsi + + reg: + items: + - description: MIPI registers range + + reg-names: + items: + - const: mipi + + clocks: + items: + - description: MIPI DSI clock + - description: MIPI DSI econfig clock + - description: MIPI DSI config clock + + clock-names: + items: + - const: clk_mipi + - const: clk_mipi_ecfg + - const: clk_mipi_cfg + + ports: + type: object + + properties: + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + port@0: + type: object + description: MIPI DSI input port. + + port@1: + type: object + description: DSI output port. + + required: + - port@0 + - port@1 + + additionalProperties: false + +required: + - compatible + - reg + - reg-names + - clocks + - clock-names + - ports + +additionalProperties: false + +examples: + - | + mipi-dsi@20900000 { + compatible = "intel,keembay-dsi"; + reg = <0x20900000 0x4000>; + reg-names = "mipi"; + clocks = <&scmi_clk 0x86>, + <&scmi_clk 0x88>, + <&scmi_clk 0x89>; + clock-names = "clk_mipi", "clk_mipi_ecfg", + "clk_mipi_cfg"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + dsi_in: endpoint { + remote-endpoint = <&disp_out>; + }; + }; + + port@1 { + reg = <1>; + dsi_out: endpoint { + remote-endpoint = <&adv7535_input>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/bridge/lontium,lt9611.yaml b/Documentation/devicetree/bindings/display/bridge/lontium,lt9611.yaml index d60208359234..7a1c89b995e2 100644 --- a/Documentation/devicetree/bindings/display/bridge/lontium,lt9611.yaml +++ b/Documentation/devicetree/bindings/display/bridge/lontium,lt9611.yaml @@ -4,18 +4,19 @@ $id: http://devicetree.org/schemas/display/bridge/lontium,lt9611.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Lontium LT9611 2 Port MIPI to HDMI Bridge +title: Lontium LT9611(UXC) 2 Port MIPI to HDMI Bridge maintainers: - Vinod Koul <vkoul@kernel.org> description: | - The LT9611 is a bridge device which converts DSI to HDMI + The LT9611 and LT9611UXC are bridge devices which convert DSI to HDMI properties: compatible: enum: - lontium,lt9611 + - lontium,lt9611uxc reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/display/bridge/sii902x.txt b/Documentation/devicetree/bindings/display/bridge/sii902x.txt index 0d1db3f9da84..02c21b584741 100644 --- a/Documentation/devicetree/bindings/display/bridge/sii902x.txt +++ b/Documentation/devicetree/bindings/display/bridge/sii902x.txt @@ -8,6 +8,8 @@ Optional properties: - interrupts: describe the interrupt line used to inform the host about hotplug events. - reset-gpios: OF device-tree gpio specification for RST_N pin. + - iovcc-supply: I/O Supply Voltage (1.8V or 3.3V) + - cvcc12-supply: Digital Core Supply Voltage (1.2V) HDMI audio properties: - #sound-dai-cells: <0> or <1>. <0> if only i2s or spdif pin @@ -54,6 +56,8 @@ Example: compatible = "sil,sii9022"; reg = <0x39>; reset-gpios = <&pioA 1 0>; + iovcc-supply = <&v3v3_hdmi>; + cvcc12-supply = <&v1v2_hdmi>; #sound-dai-cells = <0>; sil,i2s-data-lanes = < 0 1 2 >; diff --git a/Documentation/devicetree/bindings/display/intel,keembay-display.yaml b/Documentation/devicetree/bindings/display/intel,keembay-display.yaml new file mode 100644 index 000000000000..0a697d45c2ad --- /dev/null +++ b/Documentation/devicetree/bindings/display/intel,keembay-display.yaml @@ -0,0 +1,72 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/intel,keembay-display.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Devicetree bindings for Intel Keem Bay display controller + +maintainers: + - Anitha Chrisanthus <anitha.chrisanthus@intel.com> + - Edmond J Dea <edmund.j.dea@intel.com> + +properties: + compatible: + const: intel,keembay-display + + reg: + items: + - description: LCD registers range + + reg-names: + items: + - const: lcd + + clocks: + items: + - description: LCD controller clock + - description: pll0 clock + + clock-names: + items: + - const: clk_lcd + - const: clk_pll0 + + interrupts: + maxItems: 1 + + port: + type: object + description: Display output node to DSI. + +required: + - compatible + - reg + - reg-names + - clocks + - clock-names + - interrupts + - port + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + display@20930000 { + compatible = "intel,keembay-display"; + reg = <0x20930000 0x3000>; + reg-names = "lcd"; + interrupts = <GIC_SPI 33 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&scmi_clk 0x83>, + <&scmi_clk 0x0>; + clock-names = "clk_lcd", "clk_pll0"; + + port { + disp_out: endpoint { + remote-endpoint = <&dsi_in>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/intel,keembay-msscam.yaml b/Documentation/devicetree/bindings/display/intel,keembay-msscam.yaml new file mode 100644 index 000000000000..40caa6118809 --- /dev/null +++ b/Documentation/devicetree/bindings/display/intel,keembay-msscam.yaml @@ -0,0 +1,43 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/intel,keembay-msscam.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Devicetree bindings for Intel Keem Bay MSSCAM + +maintainers: + - Anitha Chrisanthus <anitha.chrisanthus@intel.com> + - Edmond J Dea <edmund.j.dea@intel.com> + +description: | + MSSCAM controls local clocks in the display subsystem namely LCD clocks and + MIPI DSI clocks. It also configures the interconnect between LCD and + MIPI DSI. + +properties: + compatible: + items: + - const: intel,keembay-msscam + - const: syscon + + reg: + maxItems: 1 + + reg-io-width: + const: 4 + +required: + - compatible + - reg + - reg-io-width + +additionalProperties: false + +examples: + - | + msscam:msscam@20910000 { + compatible = "intel,keembay-msscam", "syscon"; + reg = <0x20910000 0x30>; + reg-io-width = <4>; + }; diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,disp.txt b/Documentation/devicetree/bindings/display/mediatek/mediatek,disp.txt index 121220745d46..33977e15bebd 100644 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,disp.txt +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,disp.txt @@ -43,7 +43,7 @@ Required properties (all function blocks): "mediatek,<chip>-dpi" - DPI controller, see mediatek,dpi.txt "mediatek,<chip>-disp-mutex" - display mutex "mediatek,<chip>-disp-od" - overdrive - the supported chips are mt2701, mt7623, mt2712 and mt8173. + the supported chips are mt2701, mt7623, mt2712, mt8167 and mt8173. - reg: Physical base address and length of the function block register space - interrupts: The interrupt signal from the function block (required, except for merge and split function blocks). @@ -59,7 +59,7 @@ Required properties (DMA function blocks): "mediatek,<chip>-disp-ovl" "mediatek,<chip>-disp-rdma" "mediatek,<chip>-disp-wdma" - the supported chips are mt2701 and mt8173. + the supported chips are mt2701, mt8167 and mt8173. - larb: Should contain a phandle pointing to the local arbiter device as defined in Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.txt - iommus: Should point to the respective IOMMU block with master port as diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,dpi.txt b/Documentation/devicetree/bindings/display/mediatek/mediatek,dpi.txt deleted file mode 100644 index dc1ebd13cc88..000000000000 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,dpi.txt +++ /dev/null @@ -1,42 +0,0 @@ -Mediatek DPI Device -=================== - -The Mediatek DPI function block is a sink of the display subsystem and -provides 8-bit RGB/YUV444 or 8/10/10-bit YUV422 pixel data on a parallel -output bus. - -Required properties: -- compatible: "mediatek,<chip>-dpi" - the supported chips are mt2701, mt7623, mt8173 and mt8183. -- reg: Physical base address and length of the controller's registers -- interrupts: The interrupt signal from the function block. -- clocks: device clocks - See Documentation/devicetree/bindings/clock/clock-bindings.txt for details. -- clock-names: must contain "pixel", "engine", and "pll" -- port: Output port node with endpoint definitions as described in - Documentation/devicetree/bindings/graph.txt. This port should be connected - to the input port of an attached HDMI or LVDS encoder chip. - -Optional properties: -- pinctrl-names: Contain "default" and "sleep". - -Example: - -dpi0: dpi@1401d000 { - compatible = "mediatek,mt8173-dpi"; - reg = <0 0x1401d000 0 0x1000>; - interrupts = <GIC_SPI 194 IRQ_TYPE_LEVEL_LOW>; - clocks = <&mmsys CLK_MM_DPI_PIXEL>, - <&mmsys CLK_MM_DPI_ENGINE>, - <&apmixedsys CLK_APMIXED_TVDPLL>; - clock-names = "pixel", "engine", "pll"; - pinctrl-names = "default", "sleep"; - pinctrl-0 = <&dpi_pin_func>; - pinctrl-1 = <&dpi_pin_idle>; - - port { - dpi0_out: endpoint { - remote-endpoint = <&hdmi0_in>; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,dpi.yaml b/Documentation/devicetree/bindings/display/mediatek/mediatek,dpi.yaml new file mode 100644 index 000000000000..6cdb734c91a9 --- /dev/null +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,dpi.yaml @@ -0,0 +1,98 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/mediatek/mediatek,dpi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: mediatek DPI Controller Device Tree Bindings + +maintainers: + - CK Hu <ck.hu@mediatek.com> + - Jitao shi <jitao.shi@mediatek.com> + +description: | + The Mediatek DPI function block is a sink of the display subsystem and + provides 8-bit RGB/YUV444 or 8/10/10-bit YUV422 pixel data on a parallel + output bus. + +properties: + compatible: + enum: + - mediatek,mt2701-dpi + - mediatek,mt7623-dpi + - mediatek,mt8173-dpi + - mediatek,mt8183-dpi + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: Pixel Clock + - description: Engine Clock + - description: DPI PLL + + clock-names: + items: + - const: pixel + - const: engine + - const: pll + + pinctrl-0: true + pinctrl-1: true + + pinctrl-names: + items: + - const: default + - const: sleep + + port: + type: object + description: + Output port node with endpoint definitions as described in + Documentation/devicetree/bindings/graph.txt. This port should be connected + to the input port of an attached HDMI or LVDS encoder chip. + + properties: + endpoint: + type: object + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - port + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/mt8173-clk.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + dpi0: dpi@1401d000 { + compatible = "mediatek,mt8173-dpi"; + reg = <0x1401d000 0x1000>; + interrupts = <GIC_SPI 194 IRQ_TYPE_LEVEL_LOW>; + clocks = <&mmsys CLK_MM_DPI_PIXEL>, + <&mmsys CLK_MM_DPI_ENGINE>, + <&apmixedsys CLK_APMIXED_TVDPLL>; + clock-names = "pixel", "engine", "pll"; + pinctrl-names = "default", "sleep"; + pinctrl-0 = <&dpi_pin_func>; + pinctrl-1 = <&dpi_pin_idle>; + + port { + dpi0_out: endpoint { + remote-endpoint = <&hdmi0_in>; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/msm/gpu.txt b/Documentation/devicetree/bindings/display/msm/gpu.txt index 1af0ff102b50..090dcb3fc34d 100644 --- a/Documentation/devicetree/bindings/display/msm/gpu.txt +++ b/Documentation/devicetree/bindings/display/msm/gpu.txt @@ -39,6 +39,10 @@ Required properties: a4xx Snapdragon SoCs. See Documentation/devicetree/bindings/sram/qcom,ocmem.yaml. +Optional properties: +- #cooling-cells: The value must be 2. For details, please refer + Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml. + Example 3xx/4xx: / { @@ -61,6 +65,7 @@ Example 3xx/4xx: power-domains = <&mmcc OXILICX_GDSC>; operating-points-v2 = <&gpu_opp_table>; iommus = <&gpu_iommu 0>; + #cooling-cells = <2>; }; gpu_sram: ocmem@fdd00000 { @@ -98,6 +103,8 @@ Example a6xx (with GMU): reg = <0x5000000 0x40000>, <0x509e000 0x10>; reg-names = "kgsl_3d0_reg_memory", "cx_mem"; + #cooling-cells = <2>; + /* * Look ma, no clocks! The GPU clocks and power are * controlled entirely by the GMU diff --git a/Documentation/devicetree/bindings/display/panel/abt,y030xx067a.yaml b/Documentation/devicetree/bindings/display/panel/abt,y030xx067a.yaml new file mode 100644 index 000000000000..91cb4c3e0198 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/abt,y030xx067a.yaml @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/abt,y030xx067a.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Asia Better Technology 3.0" (320x480 pixels) 24-bit IPS LCD panel + +description: | + The panel must obey the rules for a SPI slave device as specified in + spi/spi-controller.yaml + +maintainers: + - Paul Cercueil <paul@crapouillou.net> + +allOf: + - $ref: panel-common.yaml# + +properties: + compatible: + const: abt,y030xx067a + + backlight: true + port: true + power-supply: true + reg: true + reset-gpios: true + +required: + - compatible + - reg + - power-supply + - reset-gpios + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + spi { + #address-cells = <1>; + #size-cells = <0>; + + panel@0 { + compatible = "abt,y030xx067a"; + reg = <0>; + + spi-max-frequency = <3125000>; + + reset-gpios = <&gpe 2 GPIO_ACTIVE_LOW>; + + backlight = <&backlight>; + power-supply = <&vcc>; + + port { + panel_input: endpoint { + remote-endpoint = <&panel_output>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/panel/novatek,nt36672a.yaml b/Documentation/devicetree/bindings/display/panel/novatek,nt36672a.yaml new file mode 100644 index 000000000000..d2170de6b723 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/novatek,nt36672a.yaml @@ -0,0 +1,87 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/novatek,nt36672a.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Novatek NT36672A based DSI display Panels + +maintainers: + - Sumit Semwal <sumit.semwal@linaro.org> + +description: | + The nt36672a IC from Novatek is a generic DSI Panel IC used to drive dsi + panels. + Right now, support is added only for a Tianma FHD+ LCD display panel with a + resolution of 1080x2246. It is a video mode DSI panel. + +allOf: + - $ref: panel-common.yaml# + +properties: + compatible: + items: + - enum: + - tianma,fhd-video + - const: novatek,nt36672a + description: This indicates the panel manufacturer of the panel that is + in turn using the NT36672A panel driver. This compatible string + determines how the NT36672A panel driver is configured for the indicated + panel. The novatek,nt36672a compatible shall always be provided as a fallback. + + reset-gpios: + description: phandle of gpio for reset line - This should be 8mA, gpio + can be configured using mux, pinctrl, pinctrl-names (active high) + + vddio-supply: + description: phandle of the regulator that provides the supply voltage + Power IC supply + + vddpos-supply: + description: phandle of the positive boost supply regulator + + vddneg-supply: + description: phandle of the negative boost supply regulator + + reg: true + port: true + +required: + - compatible + - reg + - vddi0-supply + - vddpos-supply + - vddneg-supply + - reset-gpios + - port + +unevaluatedProperties: false + +examples: + - |+ + #include <dt-bindings/gpio/gpio.h> + + dsi0 { + #address-cells = <1>; + #size-cells = <0>; + + panel@0 { + compatible = "tianma,fhd-video", "novatek,nt36672a"; + reg = <0>; + vddi0-supply = <&vreg_l14a_1p88>; + vddpos-supply = <&lab>; + vddneg-supply = <&ibb>; + + reset-gpios = <&tlmm 6 GPIO_ACTIVE_HIGH>; + + #address-cells = <1>; + #size-cells = <0>; + port { + tianma_nt36672a_in_0: endpoint { + remote-endpoint = <&dsi0_out>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml b/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml index c0dd9fa29f1d..72e4b6d4d5e1 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml @@ -47,6 +47,12 @@ properties: - panasonic,vvx10f004b00 # Panasonic 10" WUXGA TFT LCD panel - panasonic,vvx10f034n00 + # Samsung s6e3fc2x01 1080x2340 AMOLED panel + - samsung,s6e3fc2x01 + # Samsung sofef00 1080x2280 AMOLED panel + - samsung,sofef00 + # Shangai Top Display Optoelectronics 7" TL070WSH30 1024x600 TFT LCD panel + - tdo,tl070wsh30 reg: maxItems: 1 @@ -54,6 +60,7 @@ properties: backlight: true enable-gpios: true + reset-gpios: true port: true power-supply: true diff --git a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml index edb53ab0d9eb..f9750b0b6708 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml @@ -282,6 +282,8 @@ properties: - vxt,vl050-8048nt-c01 # Winstar Display Corporation 3.5" QVGA (320x240) TFT LCD panel - winstar,wf35ltiacd + # Yes Optoelectronics YTC700TLAG-05-201C 7" TFT LCD panel + - yes-optoelectronics,ytc700tlag-05-201c backlight: true enable-gpios: true diff --git a/Documentation/devicetree/bindings/display/ti/ti,am65x-dss.yaml b/Documentation/devicetree/bindings/display/ti/ti,am65x-dss.yaml index 4f9185462ed3..4dc30738ee57 100644 --- a/Documentation/devicetree/bindings/display/ti/ti,am65x-dss.yaml +++ b/Documentation/devicetree/bindings/display/ti/ti,am65x-dss.yaml @@ -55,6 +55,14 @@ properties: - const: vp1 - const: vp2 + assigned-clocks: + minItems: 1 + maxItems: 3 + + assigned-clock-parents: + minItems: 1 + maxItems: 3 + interrupts: maxItems: 1 @@ -62,6 +70,9 @@ properties: maxItems: 1 description: phandle to the associated power domain + dma-coherent: + type: boolean + ports: type: object description: diff --git a/Documentation/devicetree/bindings/display/ti/ti,j721e-dss.yaml b/Documentation/devicetree/bindings/display/ti/ti,j721e-dss.yaml index 173730d56334..c9a947d55fa4 100644 --- a/Documentation/devicetree/bindings/display/ti/ti,j721e-dss.yaml +++ b/Documentation/devicetree/bindings/display/ti/ti,j721e-dss.yaml @@ -77,6 +77,14 @@ properties: - const: vp3 - const: vp4 + assigned-clocks: + minItems: 1 + maxItems: 5 + + assigned-clock-parents: + minItems: 1 + maxItems: 5 + interrupts: items: - description: common_m DSS Master common @@ -95,6 +103,9 @@ properties: maxItems: 1 description: phandle to the associated power domain + dma-coherent: + type: boolean + ports: type: object description: diff --git a/Documentation/devicetree/bindings/edac/aspeed-sdram-edac.txt b/Documentation/devicetree/bindings/edac/aspeed-sdram-edac.txt index 6a0f3d90d682..8ca9e0a049d8 100644 --- a/Documentation/devicetree/bindings/edac/aspeed-sdram-edac.txt +++ b/Documentation/devicetree/bindings/edac/aspeed-sdram-edac.txt @@ -1,6 +1,6 @@ -Aspeed AST2500 SoC EDAC node +Aspeed BMC SoC EDAC node -The Aspeed AST2500 SoC supports DDR3 and DDR4 memory with and without ECC (error +The Aspeed BMC SoC supports DDR3 and DDR4 memory with and without ECC (error correction check). The memory controller supports SECDED (single bit error correction, double bit @@ -11,7 +11,10 @@ Note, the bootloader must configure ECC mode in the memory controller. Required properties: -- compatible: should be "aspeed,ast2500-sdram-edac" +- compatible: should be one of + - "aspeed,ast2400-sdram-edac" + - "aspeed,ast2500-sdram-edac" + - "aspeed,ast2600-sdram-edac" - reg: sdram controller register set should be <0x1e6e0000 0x174> - interrupts: should be AVIC interrupt #0 diff --git a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-video-engine.yaml b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-video-engine.yaml index 4cc1a670c986..2f7058f7760c 100644 --- a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-video-engine.yaml +++ b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-video-engine.yaml @@ -18,6 +18,8 @@ properties: - allwinner,sun7i-a20-video-engine - allwinner,sun8i-a33-video-engine - allwinner,sun8i-h3-video-engine + - allwinner,sun8i-v3s-video-engine + - allwinner,sun8i-r40-video-engine - allwinner,sun50i-a64-video-engine - allwinner,sun50i-h5-video-engine - allwinner,sun50i-h6-video-engine diff --git a/Documentation/devicetree/bindings/media/amlogic,axg-ge2d.yaml b/Documentation/devicetree/bindings/media/amlogic,axg-ge2d.yaml new file mode 100644 index 000000000000..bee93bd84771 --- /dev/null +++ b/Documentation/devicetree/bindings/media/amlogic,axg-ge2d.yaml @@ -0,0 +1,47 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2020 BayLibre, SAS +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/media/amlogic,axg-ge2d.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Amlogic GE2D Acceleration Unit + +maintainers: + - Neil Armstrong <narmstrong@baylibre.com> + +properties: + compatible: + enum: + - amlogic,axg-ge2d + + interrupts: + minItems: 1 + + reg: + minItems: 1 + + resets: + maxItems: 1 + + clocks: + minItems: 1 + +required: + - compatible + - reg + - interrupts + - clocks + - resets + +additionalProperties: false + +examples: + - | + ge2d: ge2d@ff940000 { + compatible = "amlogic,axg-ge2d"; + reg = <0xff940000 0x10000>; + interrupts = <150>; + clocks = <&clk_ge2d>; + resets = <&reset_ge2d>; + }; diff --git a/Documentation/devicetree/bindings/media/coda.txt b/Documentation/devicetree/bindings/media/coda.txt deleted file mode 100644 index 90eb74cc1993..000000000000 --- a/Documentation/devicetree/bindings/media/coda.txt +++ /dev/null @@ -1,31 +0,0 @@ -Chips&Media Coda multi-standard codec IP -======================================== - -Coda codec IPs are present in i.MX SoCs in various versions, -called VPU (Video Processing Unit). - -Required properties: -- compatible : should be "fsl,<chip>-src" for i.MX SoCs: - (a) "fsl,imx27-vpu" for CodaDx6 present in i.MX27 - (b) "fsl,imx51-vpu" for CodaHx4 present in i.MX51 - (c) "fsl,imx53-vpu" for CODA7541 present in i.MX53 - (d) "fsl,imx6q-vpu" for CODA960 present in i.MX6q -- reg: should be register base and length as documented in the - SoC reference manual -- interrupts : Should contain the VPU interrupt. For CODA960, - a second interrupt is needed for the MJPEG unit. -- clocks : Should contain the ahb and per clocks, in the order - determined by the clock-names property. -- clock-names : Should be "ahb", "per" -- iram : phandle pointing to the SRAM device node - -Example: - -vpu: vpu@63ff4000 { - compatible = "fsl,imx53-vpu"; - reg = <0x63ff4000 0x1000>; - interrupts = <9>; - clocks = <&clks 63>, <&clks 63>; - clock-names = "ahb", "per"; - iram = <&ocram>; -}; diff --git a/Documentation/devicetree/bindings/media/coda.yaml b/Documentation/devicetree/bindings/media/coda.yaml new file mode 100644 index 000000000000..7bac0057faf7 --- /dev/null +++ b/Documentation/devicetree/bindings/media/coda.yaml @@ -0,0 +1,108 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/coda.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Chips&Media Coda multi-standard codec IP + +maintainers: + - Philipp Zabel <p.zabel@pengutronix.de> + +description: |- + Coda codec IPs are present in i.MX SoCs in various versions, + called VPU (Video Processing Unit). + +properties: + compatible: + oneOf: + - items: + - const: fsl,imx27-vpu + - const: cnm,codadx6 + - items: + - const: fsl,imx51-vpu + - const: cnm,codahx4 + - items: + - const: fsl,imx53-vpu + - const: cnm,coda7541 + - items: + - enum: + - fsl,imx6dl-vpu + - fsl,imx6q-vpu + - const: cnm,coda960 + + reg: + maxItems: 1 + + clocks: + items: + - description: PER clock + - description: AHB interface clock + + clock-names: + items: + - const: per + - const: ahb + + resets: + maxItems: 1 + + iram: + $ref: /schemas/types.yaml#/definitions/phandle + description: phandle pointing to the SRAM device node + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + +allOf: + - if: + properties: + compatible: + contains: + const: cnm,coda960 + then: + properties: + interrupts: + items: + - description: BIT processor interrupt + - description: JPEG unit interrupt + + interrupt-names: + items: + - const: bit + - const: jpeg + else: + properties: + interrupts: + items: + - description: BIT processor interrupt + + - if: + properties: + compatible: + contains: + enum: + - fsl,imx6dl-vpu + - fsl,imx6q-vpu + then: + properties: + power-domains: + $ref: /schemas/types.yaml#/definitions/phandle + description: phandle pointing to the PU power domain + maxItems: 1 + +examples: + - | + vpu: video-codec@63ff4000 { + compatible = "fsl,imx53-vpu", "cnm,coda7541"; + reg = <0x63ff4000 0x1000>; + interrupts = <9>; + clocks = <&clks 63>, <&clks 63>; + clock-names = "per", "ahb"; + iram = <&ocram>; + }; diff --git a/Documentation/devicetree/bindings/media/i2c/adv7604.txt b/Documentation/devicetree/bindings/media/i2c/adv7604.txt deleted file mode 100644 index b3e688b77a38..000000000000 --- a/Documentation/devicetree/bindings/media/i2c/adv7604.txt +++ /dev/null @@ -1,88 +0,0 @@ -* Analog Devices ADV7604/11/12 video decoder with HDMI receiver - -The ADV7604 and ADV7611/12 are multiformat video decoders with an integrated -HDMI receiver. The ADV7604 has four multiplexed HDMI inputs and one analog -input, and the ADV7611 has one HDMI input and no analog input. The 7612 is -similar to the 7611 but has 2 HDMI inputs. - -These device tree bindings support the ADV7611/12 only at the moment. - -Required Properties: - - - compatible: Must contain one of the following - - "adi,adv7611" for the ADV7611 - - "adi,adv7612" for the ADV7612 - - - reg: I2C slave addresses - The ADV76xx has up to thirteen 256-byte maps that can be accessed via the - main I2C ports. Each map has it own I2C address and acts as a standard - slave device on the I2C bus. The main address is mandatory, others are - optional and revert to defaults if not specified. - - - hpd-gpios: References to the GPIOs that control the HDMI hot-plug - detection pins, one per HDMI input. The active flag indicates the GPIO - level that enables hot-plug detection. - -The device node must contain one 'port' child node per device input and output -port, in accordance with the video interface bindings defined in -Documentation/devicetree/bindings/media/video-interfaces.txt. The port nodes -are numbered as follows. - - Port ADV7611 ADV7612 ------------------------------------------------------------- - HDMI 0 0, 1 - Digital output 1 2 - -The digital output port node must contain at least one endpoint. - -Optional Properties: - - - reset-gpios: Reference to the GPIO connected to the device's reset pin. - - default-input: Select which input is selected after reset. - - reg-names : Names of maps with programmable addresses. - It can contain any map needing a non-default address. - Possible maps names are : - "main", "avlink", "cec", "infoframe", "esdp", "dpp", "afe", - "rep", "edid", "hdmi", "test", "cp", "vdp" - -Optional Endpoint Properties: - - The following three properties are defined in video-interfaces.txt and are - valid for source endpoints only. - - - hsync-active: Horizontal synchronization polarity. Defaults to active low. - - vsync-active: Vertical synchronization polarity. Defaults to active low. - - pclk-sample: Pixel clock polarity. Defaults to output on the falling edge. - - If none of hsync-active, vsync-active and pclk-sample is specified the - endpoint will use embedded BT.656 synchronization. - -Example: - - hdmi_receiver@4c { - compatible = "adi,adv7611"; - /* - * The edid page will be accessible @ 0x66 on the I2C bus. All - * other maps will retain their default addresses. - */ - reg = <0x4c>, <0x66>; - reg-names = "main", "edid"; - - reset-gpios = <&ioexp 0 GPIO_ACTIVE_LOW>; - hpd-gpios = <&ioexp 2 GPIO_ACTIVE_HIGH>; - - #address-cells = <1>; - #size-cells = <0>; - - default-input = <0>; - - port@0 { - reg = <0>; - }; - port@1 { - reg = <1>; - hdmi_in: endpoint { - remote-endpoint = <&ccdc_in>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/media/i2c/adv7604.yaml b/Documentation/devicetree/bindings/media/i2c/adv7604.yaml new file mode 100644 index 000000000000..407baddfaa1d --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/adv7604.yaml @@ -0,0 +1,178 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/adv7604.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices ADV7604/11/12 video decoder with HDMI receiver + +maintainers: + - Hans Verkuil <hverkuil-cisco@xs4all.nl> + +description: + The ADV7604 and ADV7611/12 are multiformat video decoders with an integrated + HDMI receiver. The ADV7604 has four multiplexed HDMI inputs and one analog + input, and the ADV7611 has one HDMI input and no analog input. The 7612 is + similar to the 7611 but has 2 HDMI inputs. + + These device tree bindings support the ADV7611/12 only at the moment. + +properties: + compatible: + items: + - enum: + - adi,adv7611 + - adi,adv7612 + + reg: + minItems: 1 + maxItems: 13 + + reg-names: + minItems: 1 + maxItems: 13 + items: + - const: main + - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ] + - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ] + - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ] + - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ] + - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ] + - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ] + - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ] + - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ] + - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ] + - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ] + - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ] + - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ] + + interrupts: + maxItems: 1 + + reset-gpios: + maxItems: 1 + + hpd-gpios: + minItems: 1 + description: + References to the GPIOs that control the HDMI hot-plug detection pins, + one per HDMI input. The active flag indicates the GPIO level that + enables hot-plug detection. + + default-input: + maxItems: 1 + description: + Select which input is selected after reset. + + ports: + type: object + description: + A node containing input and output port nodes with endpoint definitions + as documented in + Documentation/devicetree/bindings/media/video-interfaces.txt + +required: + - compatible + - reg + +additionalProperties: false + +allOf: + - if: + properties: + compatible: + contains: + const: adi,adv7611 + then: + properties: + ports: + properties: + '#address-cells': + const: 1 + '#size-cells': + const: 0 + port@0: + type: object + description: Input port + port@1: + type: object + description: Output port + + required: + - port@1 + + additionalProperties: false + + required: + - ports + + - if: + properties: + compatible: + contains: + const: adi,adv7612 + then: + properties: + ports: + properties: + '#address-cells': + const: 1 + '#size-cells': + const: 0 + port@2: + type: object + description: Output port + + patternProperties: + "^port@[0-1]$": + type: object + description: Input port + + required: + - port@2 + + additionalProperties: false + + required: + - ports + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + hdmi_receiver@4c { + compatible = "adi,adv7611"; + /* + * The edid page will be accessible @ 0x66 on the I2C bus. All + * other maps will retain their default addresses. + */ + reg = <0x4c>, <0x66>; + reg-names = "main", "edid"; + + reset-gpios = <&ioexp 0 GPIO_ACTIVE_LOW>; + hpd-gpios = <&ioexp 2 GPIO_ACTIVE_HIGH>; + default-input = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + }; + + port@1 { + reg = <1>; + hdmi_in: endpoint { + remote-endpoint = <&ccdc_in>; + }; + }; + }; + + + }; + }; diff --git a/Documentation/devicetree/bindings/media/i2c/aptina,mt9v111.txt b/Documentation/devicetree/bindings/media/i2c/aptina,mt9v111.txt deleted file mode 100644 index bd896e9f67d1..000000000000 --- a/Documentation/devicetree/bindings/media/i2c/aptina,mt9v111.txt +++ /dev/null @@ -1,46 +0,0 @@ -* Aptina MT9V111 CMOS sensor ----------------------------- - -The Aptina MT9V111 is a 1/4-Inch VGA-format digital image sensor with a core -based on Aptina MT9V011 sensor and an integrated Image Flow Processor (IFP). - -The sensor has an active pixel array of 640x480 pixels and can output a number -of image resolution and formats controllable through a simple two-wires -interface. - -Required properties: --------------------- - -- compatible: shall be "aptina,mt9v111". -- clocks: reference to the system clock input provider. - -Optional properties: --------------------- - -- enable-gpios: output enable signal, pin name "OE#". Active low. -- standby-gpios: low power state control signal, pin name "STANDBY". - Active high. -- reset-gpios: chip reset signal, pin name "RESET#". Active low. - -The device node must contain one 'port' child node with one 'endpoint' child -sub-node for its digital output video port, in accordance with the video -interface bindings defined in: -Documentation/devicetree/bindings/media/video-interfaces.txt - -Example: --------- - - &i2c1 { - camera@48 { - compatible = "aptina,mt9v111"; - reg = <0x48>; - - clocks = <&camera_clk>; - - port { - mt9v111_out: endpoint { - remote-endpoint = <&ceu_in>; - }; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/media/i2c/aptina,mt9v111.yaml b/Documentation/devicetree/bindings/media/i2c/aptina,mt9v111.yaml new file mode 100644 index 000000000000..ff9546e95d05 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/aptina,mt9v111.yaml @@ -0,0 +1,75 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/aptina,mt9v111.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Aptina MT9V111 CMOS sensor + +maintainers: + - Jacopo Mondi <jacopo@jmondi.org> + +description: | + The Aptina MT9V111 is a 1/4-Inch VGA-format digital image sensor with a core + based on Aptina MT9V011 sensor and an integrated Image Flow Processor (IFP). + + The sensor has an active pixel array of 640x480 pixels and can output a number + of image resolutions and formats controllable through a simple two-wires + interface. + +properties: + compatible: + const: aptina,mt9v111 + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + enable-gpios: + description: Enable signal, pin name "OE#". Active low. + maxItems: 1 + + standby-gpios: + description: | + Low power state control signal, pin name "STANDBY". Active high. + maxItems: 1 + + reset-gpios: + description: Chip reset signal, pin name "RESET#". Active low. + maxItems: 1 + + port: + type: object + description: | + Output video port. See ../video-interfaces.txt. + +required: + - compatible + - reg + - clocks + - port + +additionalProperties: false + +examples: + - | + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + camera@48 { + compatible = "aptina,mt9v111"; + reg = <0x48>; + clocks = <&camera_clk>; + + port { + mt9v111_out: endpoint { + remote-endpoint = <&ceu_in>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/media/i2c/mipi-ccs.yaml b/Documentation/devicetree/bindings/media/i2c/mipi-ccs.yaml new file mode 100644 index 000000000000..d94bd67ccea1 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/mipi-ccs.yaml @@ -0,0 +1,135 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) 2014--2020 Intel Corporation + +$id: http://devicetree.org/schemas/media/i2c/mipi-ccs.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MIPI CCS, SMIA++ and SMIA compliant camera sensors + +maintainers: + - Sakari Ailus <sakari.ailus@linux.intel.com> + +description: + + CCS (Camera Command Set) is a raw Bayer camera sensor standard defined by the + MIPI Alliance; see + <URL:https://www.mipi.org/specifications/camera-command-set>. + + SMIA (Standard Mobile Imaging Architecture) is an image sensor standard + defined jointly by Nokia and ST. SMIA++, defined by Nokia, is an extension of + that. + + More detailed documentation can be found in + Documentation/devicetree/bindings/media/video-interfaces.txt . + +properties: + compatible: + oneOf: + - items: + - const: mipi-ccs-1.1 + - const: mipi-ccs + - items: + - const: mipi-ccs-1.0 + - const: mipi-ccs + - const: nokia,smia + + reg: + maxItems: 1 + + vana-supply: + description: Analogue voltage supply (VANA), sensor dependent. + maxItems: 1 + + vcore-supply: + description: Core voltage supply (VCore), sensor dependent. + maxItems: 1 + + vio-supply: + description: I/O voltage supply (VIO), sensor dependent. + maxItems: 1 + + clocks: + description: External clock to the sensor. + maxItems: 1 + + clock-frequency: + description: Frequency of the external clock to the sensor in Hz. + + reset-gpios: + description: Reset GPIO. Also commonly called XSHUTDOWN in hardware + documentation. + maxItems: 1 + + flash-leds: + description: Flash LED phandles. See ../video-interfaces.txt for details. + + lens-focus: + description: Lens focus controller phandles. See ../video-interfaces.txt + for details. + + rotation: + description: Rotation of the sensor. See ../video-interfaces.txt for + details. + enum: [ 0, 180 ] + + port: + type: object + properties: + endpoint: + type: object + properties: + link-frequencies: + $ref: /schemas/types.yaml#/definitions/uint64-array + description: List of allowed data link frequencies. + data-lanes: + minItems: 1 + maxItems: 8 + bus-type: + description: The type of the data bus. + oneOf: + - const: 1 # CSI-2 C-PHY + - const: 3 # CCP2 + - const: 4 # CSI-2 D-PHY + + required: + - link-frequencies + - data-lanes + - bus-type + +required: + - compatible + - reg + - clock-frequency + - clocks + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c2 { + #address-cells = <1>; + #size-cells = <0>; + + clock-frequency = <400000>; + + camera-sensor@10 { + compatible = "mipi-ccs-1.0", "mipi-ccs"; + reg = <0x10>; + reset-gpios = <&gpio3 20 GPIO_ACTIVE_LOW>; + vana-supply = <&vaux3>; + clocks = <&omap3_isp 0>; + clock-frequency = <9600000>; + port { + ccs_ep: endpoint { + data-lanes = <1 2>; + remote-endpoint = <&csi2a_ep>; + link-frequencies = /bits/ 64 <199200000 210000000 + 499200000>; + bus-type = <4>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/media/i2c/nokia,smia.txt b/Documentation/devicetree/bindings/media/i2c/nokia,smia.txt deleted file mode 100644 index 10ece8108081..000000000000 --- a/Documentation/devicetree/bindings/media/i2c/nokia,smia.txt +++ /dev/null @@ -1,66 +0,0 @@ -SMIA/SMIA++ sensor - -SMIA (Standard Mobile Imaging Architecture) is an image sensor standard -defined jointly by Nokia and ST. SMIA++, defined by Nokia, is an extension -of that. These definitions are valid for both types of sensors. - -More detailed documentation can be found in -Documentation/devicetree/bindings/media/video-interfaces.txt . - -The device node should contain a "port" node which may contain one or more -endpoint nodes, in accordance with video interface bindings defined in -Documentation/devicetree/bindings/media/video-interfaces.txt . - -Mandatory properties --------------------- - -- compatible: "nokia,smia" -- reg: I2C address (0x10, or an alternative address) -- vana-supply: Analogue voltage supply (VANA), typically 2,8 volts (sensor - dependent). -- clocks: External clock to the sensor -- clock-frequency: Frequency of the external clock to the sensor -- link-frequencies: List of allowed data link frequencies. An array of - 64-bit elements. - - -Optional properties -------------------- - -- reset-gpios: XSHUTDOWN GPIO -- flash-leds: See ../video-interfaces.txt -- lens-focus: See ../video-interfaces.txt -- rotation: Integer property; valid values are 0 (sensor mounted upright) - and 180 (sensor mounted upside down). See - ../video-interfaces.txt . - - -Endpoint node mandatory properties ----------------------------------- - -- data-lanes: <1..n> - - -Example -------- - -&i2c2 { - clock-frequency = <400000>; - - camera-sensor@10 { - compatible = "nokia,smia"; - reg = <0x10>; - reset-gpios = <&gpio3 20 0>; - vana-supply = <&vaux3>; - clocks = <&omap3_isp 0>; - clock-frequency = <9600000>; - nokia,nvm-size = <512>; /* 8 * 64 */ - link-frequencies = /bits/ 64 <199200000 210000000 499200000>; - port { - smiapp_ep: endpoint { - data-lanes = <1 2>; - remote-endpoint = <&csi2a_ep>; - }; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/media/i2c/ov2680.txt b/Documentation/devicetree/bindings/media/i2c/ov2680.txt deleted file mode 100644 index 11e925ed9dad..000000000000 --- a/Documentation/devicetree/bindings/media/i2c/ov2680.txt +++ /dev/null @@ -1,46 +0,0 @@ -* Omnivision OV2680 MIPI CSI-2 sensor - -Required Properties: -- compatible: should be "ovti,ov2680". -- clocks: reference to the xvclk input clock. -- clock-names: should be "xvclk". -- DOVDD-supply: Digital I/O voltage supply. -- DVDD-supply: Digital core voltage supply. -- AVDD-supply: Analog voltage supply. - -Optional Properties: -- reset-gpios: reference to the GPIO connected to the powerdown/reset pin, - if any. This is an active low signal to the OV2680. - -The device node must contain one 'port' child node for its digital output -video port, and this port must have a single endpoint in accordance with - the video interface bindings defined in -Documentation/devicetree/bindings/media/video-interfaces.txt. - -Endpoint node required properties for CSI-2 connection are: -- remote-endpoint: a phandle to the bus receiver's endpoint node. -- clock-lanes: should be set to <0> (clock lane on hardware lane 0). -- data-lanes: should be set to <1> (one CSI-2 lane supported). - -Example: - -&i2c2 { - ov2680: camera-sensor@36 { - compatible = "ovti,ov2680"; - reg = <0x36>; - clocks = <&osc>; - clock-names = "xvclk"; - reset-gpios = <&gpio1 3 GPIO_ACTIVE_LOW>; - DOVDD-supply = <&sw2_reg>; - DVDD-supply = <&sw2_reg>; - AVDD-supply = <®_peri_3p15v>; - - port { - ov2680_to_mipi: endpoint { - remote-endpoint = <&mipi_from_sensor>; - clock-lanes = <0>; - data-lanes = <1>; - }; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/media/i2c/ov772x.txt b/Documentation/devicetree/bindings/media/i2c/ov772x.txt deleted file mode 100644 index 0b3ede5b8e6a..000000000000 --- a/Documentation/devicetree/bindings/media/i2c/ov772x.txt +++ /dev/null @@ -1,40 +0,0 @@ -* Omnivision OV7720/OV7725 CMOS sensor - -The Omnivision OV7720/OV7725 sensor supports multiple resolutions output, -such as VGA, QVGA, and any size scaling down from CIF to 40x30. It also can -support the YUV422, RGB565/555/444, GRB422 or raw RGB output formats. - -Required Properties: -- compatible: shall be one of - "ovti,ov7720" - "ovti,ov7725" -- clocks: reference to the xclk input clock. - -Optional Properties: -- reset-gpios: reference to the GPIO connected to the RSTB pin which is - active low, if any. -- powerdown-gpios: reference to the GPIO connected to the PWDN pin which is - active high, if any. - -The device node shall contain one 'port' child node with one child 'endpoint' -subnode for its digital output video port, in accordance with the video -interface bindings defined in Documentation/devicetree/bindings/media/ -video-interfaces.txt. - -Example: - -&i2c0 { - ov772x: camera@21 { - compatible = "ovti,ov7725"; - reg = <0x21>; - reset-gpios = <&axi_gpio_0 0 GPIO_ACTIVE_LOW>; - powerdown-gpios = <&axi_gpio_0 1 GPIO_ACTIVE_LOW>; - clocks = <&xclk>; - - port { - ov772x_0: endpoint { - remote-endpoint = <&vcap1_in0>; - }; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov02a10.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov02a10.yaml new file mode 100644 index 000000000000..1c3879ec4122 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov02a10.yaml @@ -0,0 +1,159 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright (c) 2020 MediaTek Inc. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/ovti,ov02a10.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Omnivision OV02A10 CMOS Sensor Device Tree Bindings + +maintainers: + - Dongchun Zhu <dongchun.zhu@mediatek.com> + +description: |- + The Omnivision OV02A10 is a low-cost, high performance, 1/5-inch, 2 megapixel + image sensor, which is the latest production derived from Omnivision's CMOS + image sensor technology. Ihis chip supports high frame rate speeds up to 30fps + @ 1600x1200 (UXGA) resolution transferred over a 1-lane MIPI interface. The + sensor output is available via CSI-2 serial data output. + +properties: + compatible: + const: ovti,ov02a10 + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + description: + External clock for the sensor. + items: + - const: eclk + + clock-frequency: + description: + Frequency of the eclk clock in Hz. + + dovdd-supply: + description: + Definition of the regulator used as Digital I/O voltage supply. + + avdd-supply: + description: + Definition of the regulator used as Analog voltage supply. + + dvdd-supply: + description: + Definition of the regulator used as Digital core voltage supply. + + powerdown-gpios: + description: + Must be the device tree identifier of the GPIO connected to the + PD_PAD pin. This pin is used to place the OV02A10 into standby mode + or shutdown mode. As the line needs to be high for the powerdown mode + to be active, it should be marked GPIO_ACTIVE_HIGH. + maxItems: 1 + + reset-gpios: + description: + Must be the device tree identifier of the GPIO connected to the + RST_PD pin. If specified, it will be asserted during driver probe. + As the line needs to be low for the reset to be active, it should be + marked GPIO_ACTIVE_LOW. + maxItems: 1 + + rotation: + description: + Definition of the sensor's placement. + allOf: + - $ref: "/schemas/types.yaml#/definitions/uint32" + - enum: + - 0 # Sensor Mounted Upright + - 180 # Sensor Mounted Upside Down + default: 0 + + # See ../video-interfaces.txt for details + port: + type: object + additionalProperties: false + description: + Output port node, single endpoint describing the CSI-2 transmitter. + + properties: + endpoint: + type: object + additionalProperties: false + + properties: + link-frequencies: true + ovti,mipi-clock-voltage: + allOf: + - $ref: "/schemas/types.yaml#/definitions/uint32" + description: + Definition of MIPI clock voltage unit. This entry corresponds to + the link speed defined by the 'link-frequencies' property. + If present, the value shall be in the range of 0-4. + default: 4 + remote-endpoint: true + + required: + - link-frequencies + - remote-endpoint + + required: + - endpoint + +required: + - compatible + - reg + - clocks + - clock-names + - clock-frequency + - dovdd-supply + - avdd-supply + - dvdd-supply + - powerdown-gpios + - reset-gpios + - port + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + ov02a10: camera-sensor@3d { + compatible = "ovti,ov02a10"; + reg = <0x3d>; + + powerdown-gpios = <&pio 107 GPIO_ACTIVE_HIGH>; + reset-gpios = <&pio 109 GPIO_ACTIVE_LOW>; + + clocks = <&ov02a10_clk>; + clock-names = "eclk"; + clock-frequency = <24000000>; + + rotation = <180>; + + dovdd-supply = <&ov02a10_dovdd>; + avdd-supply = <&ov02a10_avdd>; + dvdd-supply = <&ov02a10_dvdd>; + + port { + wcam_out: endpoint { + link-frequencies = /bits/ 64 <390000000>; + ovti,mipi-clock-voltage = <3>; + remote-endpoint = <&mipi_in_wcam>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov2680.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov2680.yaml new file mode 100644 index 000000000000..43bf749807e1 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov2680.yaml @@ -0,0 +1,99 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/ovti,ov2680.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Omnivision OV2680 CMOS Sensor + +maintainers: + - Rui Miguel Silva <rmfrfs@gmail.com> + +description: |- + The OV2680 color sensor is a low voltage, high performance 1/5 inch UXGA (2 + megapixel) CMOS image sensor that provides a single-chip UXGA (1600 x 1200) + camera. It provides full-frame, sub-sampled, or windowed 10-bit images in + various formats via the control of the Serial Camera Control Bus (SCCB) + interface. The OV2680 has an image array capable of operating at up to 30 + frames per second (fps) in UXGA resolution. + +properties: + compatible: + const: ovti,ov2680 + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + const: xvclk + + reset-gpios: + description: + The phandle and specifier for the GPIO that controls sensor reset. + This corresponds to the hardware pin XSHUTDOWN which is physically + active low. + maxItems: 1 + + dovdd-supply: + description: + Definition of the regulator used as interface power supply. + + avdd-supply: + description: + Definition of the regulator used as analog power supply. + + dvdd-supply: + description: + Definition of the regulator used as digital power supply. + + port: + type: object + description: + A node containing an output port node with an endpoint definition + as documented in + Documentation/devicetree/bindings/media/video-interfaces.txt + +required: + - compatible + - reg + - clocks + - clock-names + - dovdd-supply + - avdd-supply + - dvdd-supply + - reset-gpios + - port + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + ov2680: camera-sensor@36 { + compatible = "ovti,ov2680"; + reg = <0x36>; + clocks = <&osc>; + clock-names = "xvclk"; + reset-gpios = <&gpio1 3 GPIO_ACTIVE_LOW>; + + dovdd-supply = <&sw2_reg>; + dvdd-supply = <&sw2_reg>; + avdd-supply = <®_peri_3p15v>; + + port { + ov2680_to_mipi: endpoint { + remote-endpoint = <&mipi_from_sensor>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov772x.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov772x.yaml new file mode 100644 index 000000000000..6866c2cdac50 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov772x.yaml @@ -0,0 +1,134 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/ovti,ov772x.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Omnivision OV7720/OV7725 CMOS sensor + +maintainers: + - Jacopo Mondi <jacopo@jmondi.org> + +description: | + The Omnivision OV7720/OV7725 sensor supports multiple resolutions output, + such as VGA, QVGA, and any size scaling down from CIF to 40x30. It also can + support the YUV422, RGB565/555/444, GRB422 or raw RGB output formats. + +properties: + compatible: + enum: + - ovti,ov7720 + - ovti,ov7725 + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + reset-gpios: + description: | + Reference to the GPIO connected to the RSTB pin which is active low. + maxItems: 1 + + powerdown-gpios: + description: | + Reference to the GPIO connected to the PWDN pin which is active high. + maxItems: 1 + + port: + type: object + description: | + Video output port. See ../video-interfaces.txt. + + properties: + endpoint: + type: object + + properties: + bus-type: + enum: [5, 6] + + bus-width: + enum: [8, 10] + default: 10 + + data-shift: + enum: [0, 2] + default: 0 + + hsync-active: + enum: [0, 1] + default: 1 + + vsync-active: + enum: [0, 1] + default: 1 + + pclk-sample: + enum: [0, 1] + default: 1 + + allOf: + - if: + properties: + bus-type: + const: 6 + then: + properties: + hsync-active: false + vsync-active: false + + - if: + properties: + bus-width: + const: 10 + then: + properties: + data-shift: + const: 0 + + required: + - bus-type + + unevaluatedProperties: false + + additionalProperties: false + +required: + - compatible + - reg + - clocks + - port + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + ov772x: camera@21 { + compatible = "ovti,ov7725"; + reg = <0x21>; + reset-gpios = <&axi_gpio_0 0 GPIO_ACTIVE_LOW>; + powerdown-gpios = <&axi_gpio_0 1 GPIO_ACTIVE_LOW>; + clocks = <&xclk>; + + port { + ov772x_0: endpoint { + bus-type = <5>; + vsync-active = <0>; + hsync-active = <0>; + pclk-sample = <0>; + bus-width = <8>; + data-shift = <0>; + remote-endpoint = <&vcap1_in0>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/media/i2c/sony,imx214.txt b/Documentation/devicetree/bindings/media/i2c/sony,imx214.txt deleted file mode 100644 index f11f28a5fda4..000000000000 --- a/Documentation/devicetree/bindings/media/i2c/sony,imx214.txt +++ /dev/null @@ -1,53 +0,0 @@ -* Sony 1/3.06-Inch 13.13Mp CMOS Digital Image Sensor - -The Sony imx214 is a 1/3.06-inch CMOS active pixel digital image sensor with -an active array size of 4224H x 3200V. It is programmable through an I2C -interface. -Image data is sent through MIPI CSI-2, through 2 or 4 lanes at a maximum -throughput of 1.2Gbps/lane. - - -Required Properties: -- compatible: Shall be "sony,imx214". -- reg: I2C bus address of the device. Depending on how the sensor is wired, - it shall be <0x10> or <0x1a>; -- enable-gpios: GPIO descriptor for the enable pin. -- vdddo-supply: Chip digital IO regulator (1.8V). -- vdda-supply: Chip analog regulator (2.7V). -- vddd-supply: Chip digital core regulator (1.12V). -- clocks: Reference to the xclk clock. -- clock-frequency: Frequency of the xclk clock. - -Optional Properties: -- flash-leds: See ../video-interfaces.txt -- lens-focus: See ../video-interfaces.txt - -The imx214 device node shall contain one 'port' child node with -an 'endpoint' subnode. For further reading on port node refer to -Documentation/devicetree/bindings/media/video-interfaces.txt. - -Required Properties on endpoint: -- data-lanes: check ../video-interfaces.txt -- link-frequencies: check ../video-interfaces.txt -- remote-endpoint: check ../video-interfaces.txt - -Example: - - camera-sensor@1a { - compatible = "sony,imx214"; - reg = <0x1a>; - vdddo-supply = <&pm8994_lvs1>; - vddd-supply = <&camera_vddd_1v12>; - vdda-supply = <&pm8994_l17>; - lens-focus = <&ad5820>; - enable-gpios = <&msmgpio 25 GPIO_ACTIVE_HIGH>; - clocks = <&mmcc CAMSS_MCLK0_CLK>; - clock-frequency = <24000000>; - port { - imx214_ep: endpoint { - data-lanes = <1 2 3 4>; - link-frequencies = /bits/ 64 <480000000>; - remote-endpoint = <&csiphy0_ep>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/media/i2c/sony,imx214.yaml b/Documentation/devicetree/bindings/media/i2c/sony,imx214.yaml new file mode 100644 index 000000000000..1a3590dd0e98 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/sony,imx214.yaml @@ -0,0 +1,133 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/sony,imx214.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Sony 1/3.06-Inch 13.13MP CMOS Digital Image Sensor + +maintainers: + - Ricardo Ribalda <ribalda@kernel.org> + +description: | + The Sony IMX214 is a 1/3.06-inch CMOS active pixel digital image sensor with + an active array size of 4224H x 3200V. It is programmable through an I2C + interface. Image data is sent through MIPI CSI-2, through 2 or 4 lanes at a + maximum throughput of 1.2Gbps/lane. + +properties: + compatible: + const: sony,imx214 + + reg: + enum: + - 0x10 + - 0x1a + + clocks: + description: Reference to the xclk clock. + maxItems: 1 + + clock-frequency: + description: Frequency of the xclk clock in Hz. + + enable-gpios: + description: GPIO descriptor for the enable pin. + maxItems: 1 + + vdddo-supply: + description: Chip digital IO regulator (1.8V). + maxItems: 1 + + vdda-supply: + description: Chip analog regulator (2.7V). + maxItems: 1 + + vddd-supply: + description: Chip digital core regulator (1.12V). + maxItems: 1 + + flash-leds: + description: See ../video-interfaces.txt + + lens-focus: + description: See ../video-interfaces.txt + + port: + type: object + description: | + Video output port. See ../video-interfaces.txt. + + properties: + endpoint: + type: object + + properties: + data-lanes: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: See ../video-interfaces.txt + anyOf: + - items: + - const: 1 + - const: 2 + - items: + - const: 1 + - const: 2 + - const: 3 + - const: 4 + + link-frequencies: + $ref: /schemas/types.yaml#/definitions/uint64-array + description: See ../video-interfaces.txt + + required: + - data-lanes + - link-frequencies + + unevaluatedProperties: false + + additionalProperties: false + +required: + - compatible + - reg + - clocks + - clock-frequency + - enable-gpios + - vdddo-supply + - vdda-supply + - vddd-supply + - port + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + camera-sensor@1a { + compatible = "sony,imx214"; + reg = <0x1a>; + vdddo-supply = <&pm8994_lvs1>; + vddd-supply = <&camera_vddd_1v12>; + vdda-supply = <&pm8994_l17>; + lens-focus = <&ad5820>; + enable-gpios = <&msmgpio 25 GPIO_ACTIVE_HIGH>; + clocks = <&camera_clk>; + clock-frequency = <24000000>; + + port { + imx214_ep: endpoint { + data-lanes = <1 2 3 4>; + link-frequencies = /bits/ 64 <480000000>; + remote-endpoint = <&csiphy0_ep>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/media/imx7-csi.txt b/Documentation/devicetree/bindings/media/imx7-csi.txt deleted file mode 100644 index d80ceefa0c00..000000000000 --- a/Documentation/devicetree/bindings/media/imx7-csi.txt +++ /dev/null @@ -1,42 +0,0 @@ -Freescale i.MX7 CMOS Sensor Interface -===================================== - -csi node --------- - -This is device node for the CMOS Sensor Interface (CSI) which enables the chip -to connect directly to external CMOS image sensors. - -Required properties: - -- compatible : "fsl,imx7-csi" or "fsl,imx6ul-csi"; -- reg : base address and length of the register set for the device; -- interrupts : should contain CSI interrupt; -- clocks : list of clock specifiers, see - Documentation/devicetree/bindings/clock/clock-bindings.txt for details; -- clock-names : must contain "mclk"; - -The device node shall contain one 'port' child node with one child 'endpoint' -node, according to the bindings defined in: -Documentation/devicetree/bindings/media/video-interfaces.txt. - -In the following example a remote endpoint is a video multiplexer. - -example: - - csi: csi@30710000 { - #address-cells = <1>; - #size-cells = <0>; - - compatible = "fsl,imx7-csi"; - reg = <0x30710000 0x10000>; - interrupts = <GIC_SPI 7 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&clks IMX7D_CSI_MCLK_ROOT_CLK>; - clock-names = "mclk"; - - port { - csi_from_csi_mux: endpoint { - remote-endpoint = <&csi_mux_to_csi>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/media/imx7-mipi-csi2.txt b/Documentation/devicetree/bindings/media/imx7-mipi-csi2.txt deleted file mode 100644 index 71fd74ed3ec8..000000000000 --- a/Documentation/devicetree/bindings/media/imx7-mipi-csi2.txt +++ /dev/null @@ -1,90 +0,0 @@ -Freescale i.MX7 Mipi CSI2 -========================= - -mipi_csi2 node --------------- - -This is the device node for the MIPI CSI-2 receiver core in i.MX7 SoC. It is -compatible with previous version of Samsung D-phy. - -Required properties: - -- compatible : "fsl,imx7-mipi-csi2"; -- reg : base address and length of the register set for the device; -- interrupts : should contain MIPI CSIS interrupt; -- clocks : list of clock specifiers, see - Documentation/devicetree/bindings/clock/clock-bindings.txt for details; -- clock-names : must contain "pclk", "wrap" and "phy" entries, matching - entries in the clock property; -- power-domains : a phandle to the power domain, see - Documentation/devicetree/bindings/power/power_domain.txt for details. -- reset-names : should include following entry "mrst"; -- resets : a list of phandle, should contain reset entry of - reset-names; -- phy-supply : from the generic phy bindings, a phandle to a regulator that - provides power to MIPI CSIS core; - -Optional properties: - -- clock-frequency : The IP's main (system bus) clock frequency in Hz, default - value when this property is not specified is 166 MHz; -- fsl,csis-hs-settle : differential receiver (HS-RX) settle time; - -The device node should contain two 'port' child nodes with one child 'endpoint' -node, according to the bindings defined in: - Documentation/devicetree/bindings/ media/video-interfaces.txt. - The following are properties specific to those nodes. - -port node ---------- - -- reg : (required) can take the values 0 or 1, where 0 shall be - related to the sink port and port 1 shall be the source - one; - -endpoint node -------------- - -- data-lanes : (required) an array specifying active physical MIPI-CSI2 - data input lanes and their mapping to logical lanes; this - shall only be applied to port 0 (sink port), the array's - content is unused only its length is meaningful, - in this case the maximum length supported is 2; - -example: - - mipi_csi: mipi-csi@30750000 { - #address-cells = <1>; - #size-cells = <0>; - - compatible = "fsl,imx7-mipi-csi2"; - reg = <0x30750000 0x10000>; - interrupts = <GIC_SPI 25 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&clks IMX7D_IPG_ROOT_CLK>, - <&clks IMX7D_MIPI_CSI_ROOT_CLK>, - <&clks IMX7D_MIPI_DPHY_ROOT_CLK>; - clock-names = "pclk", "wrap", "phy"; - clock-frequency = <166000000>; - power-domains = <&pgc_mipi_phy>; - phy-supply = <®_1p0d>; - resets = <&src IMX7_RESET_MIPI_PHY_MRST>; - reset-names = "mrst"; - fsl,csis-hs-settle = <3>; - - port@0 { - reg = <0>; - - mipi_from_sensor: endpoint { - remote-endpoint = <&ov2680_to_mipi>; - data-lanes = <1>; - }; - }; - - port@1 { - reg = <1>; - - mipi_vc0_to_csi_mux: endpoint { - remote-endpoint = <&csi_mux_from_mipi_vc0>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/media/nxp,imx7-csi.yaml b/Documentation/devicetree/bindings/media/nxp,imx7-csi.yaml new file mode 100644 index 000000000000..4e81a47e60ac --- /dev/null +++ b/Documentation/devicetree/bindings/media/nxp,imx7-csi.yaml @@ -0,0 +1,71 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/nxp,imx7-csi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: i.MX7 CMOS Sensor Interface + +maintainers: + - Rui Miguel Silva <rmfrfs@gmail.com> + +description: | + This is device node for the CMOS Sensor Interface (CSI) which enables the + chip to connect directly to external CMOS image sensors. + +properties: + compatible: + enum: + - fsl,imx7-csi + - fsl,imx6ul-csi + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: mclk + + port: + type: object + description: + A node containing input port nodes with endpoint definitions as documented + in Documentation/devicetree/bindings/media/video-interfaces.txt + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - port + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/imx7d-clock.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + + csi: csi@30710000 { + compatible = "fsl,imx7-csi"; + reg = <0x30710000 0x10000>; + interrupts = <GIC_SPI 7 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clks IMX7D_CSI_MCLK_ROOT_CLK>; + clock-names = "mclk"; + + port { + csi_from_csi_mux: endpoint { + remote-endpoint = <&csi_mux_to_csi>; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml b/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml new file mode 100644 index 000000000000..0668332959e7 --- /dev/null +++ b/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml @@ -0,0 +1,173 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/nxp,imx7-mipi-csi2.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP i.MX7 Mipi CSI2 + +maintainers: + - Rui Miguel Silva <rmfrfs@gmail.com> + +description: | + This is the device node for the MIPI CSI-2 receiver core in i.MX7 soc. It is + compatible with previous version of samsung d-phy. + +properties: + compatible: + const: fsl,imx7-mipi-csi2 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + minItems: 3 + maxItems: 3 + + clock-names: + items: + - const: pclk + - const: wrap + - const: phy + + power-domains: + maxItems: 1 + + phy-supply: + description: + Phandle to a regulator that provides power to the PHY. This + regulator will be managed during the PHY power on/off sequence. + + resets: + maxItems: 1 + + reset-names: + const: mrst + + clock-frequency: + description: + The IP main (system bus) clock frequency in Hertz + default: 166000000 + + fsl,csis-hs-settle: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Differential receiver (HS-RX) settle time + + ports: + type: object + description: + A node containing input and output port nodes with endpoint definitions + as documented in + Documentation/devicetree/bindings/media/video-interfaces.txt + + properties: + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + port@0: + type: object + description: + Input port node, single endpoint describing the CSI-2 transmitter. + + properties: + reg: + const: 0 + + endpoint: + type: object + + properties: + data-lanes: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: See ../video-interfaces.txt + oneOf: + - items: + - const: 1 + - items: + - const: 1 + - const: 2 + + remote-endpoint: true + + required: + - data-lanes + - remote-endpoint + + additionalProperties: false + + additionalProperties: false + + port@1: + type: object + description: + Output port node + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - power-domains + - phy-supply + - resets + - reset-names + - ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/imx7d-clock.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/reset/imx7-reset.h> + + mipi_csi: mipi-csi@30750000 { + compatible = "fsl,imx7-mipi-csi2"; + reg = <0x30750000 0x10000>; + interrupts = <GIC_SPI 25 IRQ_TYPE_LEVEL_HIGH>; + + clocks = <&clks IMX7D_IPG_ROOT_CLK>, + <&clks IMX7D_MIPI_CSI_ROOT_CLK>, + <&clks IMX7D_MIPI_DPHY_ROOT_CLK>; + clock-names = "pclk", "wrap", "phy"; + clock-frequency = <166000000>; + + power-domains = <&pgc_mipi_phy>; + phy-supply = <®_1p0d>; + resets = <&src IMX7_RESET_MIPI_PHY_MRST>; + reset-names = "mrst"; + fsl,csis-hs-settle = <3>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + mipi_from_sensor: endpoint { + remote-endpoint = <&ov2680_to_mipi>; + data-lanes = <1>; + }; + }; + + port@1 { + reg = <1>; + + mipi_vc0_to_csi_mux: endpoint { + remote-endpoint = <&csi_mux_from_mipi_vc0>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/media/qcom,camss.txt b/Documentation/devicetree/bindings/media/qcom,camss.txt index 09eb6ed99114..498234629e21 100644 --- a/Documentation/devicetree/bindings/media/qcom,camss.txt +++ b/Documentation/devicetree/bindings/media/qcom,camss.txt @@ -8,6 +8,7 @@ Qualcomm Camera Subsystem Definition: Should contain one of: - "qcom,msm8916-camss" - "qcom,msm8996-camss" + - "qcom,sdm660-camss" - reg: Usage: required Value type: <prop-encoded-array> @@ -64,30 +65,36 @@ Qualcomm Camera Subsystem Value type: <stringlist> Definition: Should contain the following entries: - "top_ahb" + - "throttle_axi" (660 only) - "ispif_ahb" - "csiphy0_timer" - "csiphy1_timer" - "csiphy2_timer" (8996 only) + - "csiphy_ahb2crif" (660 only) - "csi0_ahb" - "csi0" - "csi0_phy" - "csi0_pix" - "csi0_rdi" + - "cphy_csid0" (660 only) - "csi1_ahb" - "csi1" - "csi1_phy" - "csi1_pix" - "csi1_rdi" + - "cphy_csid1" (660 only) - "csi2_ahb" (8996 only) - "csi2" (8996 only) - "csi2_phy" (8996 only) - "csi2_pix" (8996 only) - "csi2_rdi" (8996 only) + - "cphy_csid2" (660 only) - "csi3_ahb" (8996 only) - "csi3" (8996 only) - "csi3_phy" (8996 only) - "csi3_pix" (8996 only) - "csi3_rdi" (8996 only) + - "cphy_csid3" (660 only) - "ahb" - "vfe0" - "csi_vfe0" diff --git a/Documentation/devicetree/bindings/media/rc.yaml b/Documentation/devicetree/bindings/media/rc.yaml index 8ad2cba5f61f..946441b4e1a5 100644 --- a/Documentation/devicetree/bindings/media/rc.yaml +++ b/Documentation/devicetree/bindings/media/rc.yaml @@ -83,6 +83,7 @@ properties: - rc-it913x-v2 - rc-kaiomy - rc-khadas + - rc-khamsin - rc-kworld-315u - rc-kworld-pc150u - rc-kworld-plus-tv-analog @@ -102,6 +103,7 @@ properties: - rc-npgtech - rc-odroid - rc-pctv-sedna + - rc-pine64 - rc-pinnacle-color - rc-pinnacle-grey - rc-pinnacle-pctv-hd diff --git a/Documentation/devicetree/bindings/media/rockchip-isp1.yaml b/Documentation/devicetree/bindings/media/rockchip-isp1.yaml new file mode 100644 index 000000000000..2004c054ed1a --- /dev/null +++ b/Documentation/devicetree/bindings/media/rockchip-isp1.yaml @@ -0,0 +1,215 @@ +# SPDX-License-Identifier: (GPL-2.0+ OR MIT) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/rockchip-isp1.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Rockchip SoC Image Signal Processing unit v1 + +maintainers: + - Helen Koike <helen.koike@collabora.com> + +description: | + Rockchip ISP1 is the Camera interface for the Rockchip series of SoCs + which contains image processing, scaling, and compression functions. + +properties: + compatible: + const: rockchip,rk3399-cif-isp + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + minItems: 3 + items: + # isp0 and isp1 + - description: ISP clock + - description: ISP AXI clock + - description: ISP AHB clock + # only for isp1 + - description: ISP Pixel clock + + clock-names: + minItems: 3 + items: + # isp0 and isp1 + - const: isp + - const: aclk + - const: hclk + # only for isp1 + - const: pclk_isp + + iommus: + maxItems: 1 + + phys: + maxItems: 1 + description: phandle for the PHY port + + phy-names: + const: dphy + + power-domains: + maxItems: 1 + + # See ./video-interfaces.txt for details + ports: + type: object + additionalProperties: false + + properties: + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + port@0: + type: object + description: connection point for sensors at MIPI-DPHY RX0 + additionalProperties: false + + properties: + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + reg: + const: 0 + + patternProperties: + endpoint: + type: object + additionalProperties: false + + properties: + reg: + maxItems: 1 + + data-lanes: + minItems: 1 + maxItems: 4 + + remote-endpoint: true + + required: + - reg + - "#address-cells" + - "#size-cells" + + required: + - "#address-cells" + - "#size-cells" + - port@0 + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - iommus + - phys + - phy-names + - power-domains + - ports + +if: + properties: + compatible: + contains: + const: rockchip,rk3399-cif-isp +then: + properties: + clocks: + minItems: 3 + maxItems: 4 + clock-names: + minItems: 3 + maxItems: 4 + +additionalProperties: false + +examples: + - | + + #include <dt-bindings/clock/rk3399-cru.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/rk3399-power.h> + + parent0: parent { + #address-cells = <2>; + #size-cells = <2>; + + isp0: isp0@ff910000 { + compatible = "rockchip,rk3399-cif-isp"; + reg = <0x0 0xff910000 0x0 0x4000>; + interrupts = <GIC_SPI 43 IRQ_TYPE_LEVEL_HIGH 0>; + clocks = <&cru SCLK_ISP0>, + <&cru ACLK_ISP0_WRAPPER>, + <&cru HCLK_ISP0_WRAPPER>; + clock-names = "isp", "aclk", "hclk"; + iommus = <&isp0_mmu>; + phys = <&dphy>; + phy-names = "dphy"; + power-domains = <&power RK3399_PD_ISP0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + #address-cells = <1>; + #size-cells = <0>; + + mipi_in_wcam: endpoint@0 { + reg = <0>; + remote-endpoint = <&wcam_out>; + data-lanes = <1 2>; + }; + + mipi_in_ucam: endpoint@1 { + reg = <1>; + remote-endpoint = <&ucam_out>; + data-lanes = <1>; + }; + }; + }; + }; + + i2c7: i2c { + #address-cells = <1>; + #size-cells = <0>; + + wcam: camera@36 { + compatible = "ovti,ov5695"; + reg = <0x36>; + + port { + wcam_out: endpoint { + remote-endpoint = <&mipi_in_wcam>; + data-lanes = <1 2>; + }; + }; + }; + + ucam: camera@3c { + compatible = "ovti,ov2685"; + reg = <0x3c>; + + port { + ucam_out: endpoint { + remote-endpoint = <&mipi_in_ucam>; + data-lanes = <1>; + }; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/st,stm32-dcmi.yaml b/Documentation/devicetree/bindings/media/st,stm32-dcmi.yaml index 3fe778cb5cc3..c18574bb3e81 100644 --- a/Documentation/devicetree/bindings/media/st,stm32-dcmi.yaml +++ b/Documentation/devicetree/bindings/media/st,stm32-dcmi.yaml @@ -44,6 +44,43 @@ properties: bindings defined in Documentation/devicetree/bindings/media/video-interfaces.txt. + properties: + endpoint: + type: object + + properties: + bus-type: + enum: [5, 6] + default: 5 + + bus-width: + enum: [8, 10, 12, 14] + default: 8 + + remote-endpoint: true + + allOf: + - if: + properties: + bus-type: + const: 6 + + then: + properties: + hsync-active: false + vsync-active: false + bus-width: + enum: [8] + + required: + - remote-endpoint + - bus-type + - pclk-sample + + unevaluatedProperties: false + + additionalProperties: false + required: - compatible - reg @@ -75,6 +112,7 @@ examples: port { dcmi_0: endpoint { remote-endpoint = <&ov5640_0>; + bus-type = <5>; bus-width = <8>; hsync-active = <0>; vsync-active = <0>; diff --git a/Documentation/devicetree/bindings/net/can/tcan4x5x.txt b/Documentation/devicetree/bindings/net/can/tcan4x5x.txt index 3613c2c8f75d..0968b40aef1e 100644 --- a/Documentation/devicetree/bindings/net/can/tcan4x5x.txt +++ b/Documentation/devicetree/bindings/net/can/tcan4x5x.txt @@ -33,7 +33,7 @@ tcan4x5x: tcan4x5x@0 { spi-max-frequency = <10000000>; bosch,mram-cfg = <0x0 0 0 32 0 0 1 1>; interrupt-parent = <&gpio1>; - interrupts = <14 GPIO_ACTIVE_LOW>; + interrupts = <14 IRQ_TYPE_LEVEL_LOW>; device-state-gpios = <&gpio3 21 GPIO_ACTIVE_HIGH>; device-wake-gpios = <&gpio1 15 GPIO_ACTIVE_HIGH>; reset-gpios = <&gpio1 27 GPIO_ACTIVE_HIGH>; diff --git a/Documentation/devicetree/bindings/net/nfc/nxp-nci.txt b/Documentation/devicetree/bindings/net/nfc/nxp-nci.txt index cfaf88998918..9e4dc510a40a 100644 --- a/Documentation/devicetree/bindings/net/nfc/nxp-nci.txt +++ b/Documentation/devicetree/bindings/net/nfc/nxp-nci.txt @@ -25,7 +25,7 @@ Example (for ARM-based BeagleBone with NPC100 NFC controller on I2C2): clock-frequency = <100000>; interrupt-parent = <&gpio1>; - interrupts = <29 GPIO_ACTIVE_HIGH>; + interrupts = <29 IRQ_TYPE_LEVEL_HIGH>; enable-gpios = <&gpio0 30 GPIO_ACTIVE_HIGH>; firmware-gpios = <&gpio0 31 GPIO_ACTIVE_HIGH>; diff --git a/Documentation/devicetree/bindings/net/nfc/pn544.txt b/Documentation/devicetree/bindings/net/nfc/pn544.txt index 92f399ec22b8..2bd82562ce8e 100644 --- a/Documentation/devicetree/bindings/net/nfc/pn544.txt +++ b/Documentation/devicetree/bindings/net/nfc/pn544.txt @@ -25,7 +25,7 @@ Example (for ARM-based BeagleBone with PN544 on I2C2): clock-frequency = <400000>; interrupt-parent = <&gpio1>; - interrupts = <17 GPIO_ACTIVE_HIGH>; + interrupts = <17 IRQ_TYPE_LEVEL_HIGH>; enable-gpios = <&gpio3 21 GPIO_ACTIVE_HIGH>; firmware-gpios = <&gpio3 19 GPIO_ACTIVE_HIGH>; diff --git a/Documentation/devicetree/bindings/sound/rt1015.txt b/Documentation/devicetree/bindings/sound/rt1015.txt index fcfd02d8d32f..e498966d436f 100644 --- a/Documentation/devicetree/bindings/sound/rt1015.txt +++ b/Documentation/devicetree/bindings/sound/rt1015.txt @@ -8,10 +8,16 @@ Required properties: - reg : The I2C address of the device. +Optional properties: + +- realtek,power-up-delay-ms + Set a delay time for flush work to be completed, + this value is adjustable depending on platform. Example: rt1015: codec@28 { compatible = "realtek,rt1015"; reg = <0x28>; + realtek,power-up-delay-ms = <50>; }; diff --git a/Documentation/devicetree/bindings/vendor-prefixes.yaml b/Documentation/devicetree/bindings/vendor-prefixes.yaml index 2735be1a8470..772b148795f4 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.yaml +++ b/Documentation/devicetree/bindings/vendor-prefixes.yaml @@ -29,6 +29,8 @@ patternProperties: description: Abilis Systems "^abracon,.*": description: Abracon Corporation + "^abt,.*": + description: ShenZhen Asia Better Technology Ltd. "^acer,.*": description: Acer Inc. "^acme,.*": @@ -681,6 +683,8 @@ patternProperties: description: MiraMEMS Sensing Technology Co., Ltd. "^mitsubishi,.*": description: Mitsubishi Electric Corporation + "^modtronix,.*": + description: Modtronix Engineering "^mosaixtech,.*": description: Mosaix Technologies, Inc. "^motorola,.*": @@ -1053,6 +1057,8 @@ patternProperties: description: Trusted Computing Group "^tcl,.*": description: Toby Churchill Ltd. + "^tdo,.*": + description: Shangai Top Display Optoelectronics Co., Ltd "^technexion,.*": description: TechNexion "^technologic,.*": @@ -1210,6 +1216,8 @@ patternProperties: description: Shenzhen Xunlong Software CO.,Limited "^xylon,.*": description: Xylon + "^yes-optoelectronics,.*": + description: Yes Optoelectronics Co.,Ltd. "^ylm,.*": description: Shenzhen Yangliming Electronic Technology Co., Ltd. "^yna,.*": diff --git a/Documentation/driver-api/dma-buf.rst b/Documentation/driver-api/dma-buf.rst index 4144b669e80c..d6b2a195dbed 100644 --- a/Documentation/driver-api/dma-buf.rst +++ b/Documentation/driver-api/dma-buf.rst @@ -115,6 +115,15 @@ Kernel Functions and Structures Reference .. kernel-doc:: include/linux/dma-buf.h :internal: +Buffer Mapping Helpers +~~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: include/linux/dma-buf-map.h + :doc: overview + +.. kernel-doc:: include/linux/dma-buf-map.h + :internal: + Reservation Objects ------------------- diff --git a/Documentation/driver-api/media/camera-sensor.rst b/Documentation/driver-api/media/camera-sensor.rst index 4d1ae12b9b4d..ffb0cad8137a 100644 --- a/Documentation/driver-api/media/camera-sensor.rst +++ b/Documentation/driver-api/media/camera-sensor.rst @@ -132,3 +132,16 @@ used to obtain device's power state after the power state transition: The function returns a non-zero value if it succeeded getting the power count or runtime PM was disabled, in either of which cases the driver may proceed to access the device. + +Controls +-------- + +For camera sensors that are connected to a bus where transmitter and receiver +require common configuration set by drivers, such as CSI-2 or parallel (BT.601 +or BT.656) bus, the ``V4L2_CID_LINK_FREQ`` control is mandatory on transmitter +drivers. Receiver drivers can use the ``V4L2_CID_LINK_FREQ`` to query the +frequency used on the bus. + +The transmitter drivers should also implement ``V4L2_CID_PIXEL_RATE`` control in +order to tell the maximum pixel rate to the receiver. This is required on raw +camera sensors. diff --git a/Documentation/driver-api/media/cec-core.rst b/Documentation/driver-api/media/cec-core.rst index bc42982ac21e..a26dc87eee8f 100644 --- a/Documentation/driver-api/media/cec-core.rst +++ b/Documentation/driver-api/media/cec-core.rst @@ -143,7 +143,7 @@ To enable/disable the 'monitor all' mode:: int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable); If enabled, then the adapter should be put in a mode to also monitor messages -that not for us. Not all hardware supports this and this function is only +that are not for us. Not all hardware supports this and this function is only called if the CEC_CAP_MONITOR_ALL capability is set. This callback is optional (some hardware may always be in 'monitor all' mode). @@ -335,7 +335,7 @@ So this must work: $ cat einj.txt >error-inj The first callback is called when this file is read and it should show the -the current error injection state:: +current error injection state:: int (*error_inj_show)(struct cec_adapter *adap, struct seq_file *sf); diff --git a/Documentation/driver-api/media/csi2.rst b/Documentation/driver-api/media/csi2.rst index e1b838014906..e3bbc6baf0f0 100644 --- a/Documentation/driver-api/media/csi2.rst +++ b/Documentation/driver-api/media/csi2.rst @@ -28,10 +28,9 @@ interface elements must be present on the sub-device represents the CSI-2 transmitter. The V4L2_CID_LINK_FREQ control is used to tell the receiver driver the -frequency (and not the symbol rate) of the link. The -V4L2_CID_PIXEL_RATE is may be used by the receiver to obtain the pixel -rate the transmitter uses. The -:c:type:`v4l2_subdev_video_ops`->s_stream() callback provides an +frequency (and not the symbol rate) of the link. The V4L2_CID_PIXEL_RATE +control may be used by the receiver to obtain the pixel rate the transmitter +uses. The :c:type:`v4l2_subdev_video_ops`->s_stream() callback provides an ability to start and stop the stream. The value of the V4L2_CID_PIXEL_RATE is calculated as follows:: diff --git a/Documentation/driver-api/media/drivers/ccs/ccs-regs.asc b/Documentation/driver-api/media/drivers/ccs/ccs-regs.asc new file mode 100644 index 000000000000..f2042acc8a45 --- /dev/null +++ b/Documentation/driver-api/media/drivers/ccs/ccs-regs.asc @@ -0,0 +1,1041 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-3-Clause +# Copyright (C) 2019--2020 Intel Corporation + +# register rflags +# - f field LSB MSB rflags +# - e enum value # after a field +# - e enum value [LSB MSB] +# - b bool bit +# - l arg name min max elsize [discontig...] +# +# rflags +# 8, 16, 32 register bits (default is 8) +# v1.1 defined in version 1.1 +# f formula +# float_ireal iReal or IEEE 754; 32 bits +# ireal unsigned iReal + +# general status registers +module_model_id 0x0000 16 +module_revision_number_major 0x0002 8 +frame_count 0x0005 8 +pixel_order 0x0006 8 +- e GRBG 0 +- e RGGB 1 +- e BGGR 2 +- e GBRG 3 +MIPI_CCS_version 0x0007 8 +- e v1_0 0x10 +- e v1_1 0x11 +- f major 4 7 +- f minor 0 3 +data_pedestal 0x0008 16 +module_manufacturer_id 0x000e 16 +module_revision_number_minor 0x0010 8 +module_date_year 0x0012 8 +module_date_month 0x0013 8 +module_date_day 0x0014 8 +module_date_phase 0x0015 8 +- f 0 2 +- e ts 0 +- e es 1 +- e cs 2 +- e mp 3 +sensor_model_id 0x0016 16 +sensor_revision_number 0x0018 8 +sensor_firmware_version 0x001a 8 +serial_number 0x001c 32 +sensor_manufacturer_id 0x0020 16 +sensor_revision_number_16 0x0022 16 + +# frame format description registers +frame_format_model_type 0x0040 8 +- e 2-byte 1 +- e 4-byte 2 +frame_format_model_subtype 0x0041 8 +- f rows 0 3 +- f columns 4 7 +frame_format_descriptor(n) 0x0042 16 f +- l n 0 14 2 +- f pixels 0 11 +- f pcode 12 15 +- e embedded 1 +- e dummy_pixel 2 +- e black_pixel 3 +- e dark_pixel 4 +- e visible_pixel 5 +- e manuf_specific_0 8 +- e manuf_specific_1 9 +- e manuf_specific_2 10 +- e manuf_specific_3 11 +- e manuf_specific_4 12 +- e manuf_specific_5 13 +- e manuf_specific_6 14 +frame_format_descriptor_4(n) 0x0060 32 f +- l n 0 7 4 +- f pixels 0 15 +- f pcode 28 31 +- e embedded 1 +- e dummy_pixel 2 +- e black_pixel 3 +- e dark_pixel 4 +- e visible_pixel 5 +- e manuf_specific_0 8 +- e manuf_specific_1 9 +- e manuf_specific_2 10 +- e manuf_specific_3 11 +- e manuf_specific_4 12 +- e manuf_specific_5 13 +- e manuf_specific_6 14 + +# analog gain description registers +analog_gain_capability 0x0080 16 +- e global 0 +- e alternate_global 2 +analog_gain_code_min 0x0084 16 +analog_gain_code_max 0x0086 16 +analog_gain_code_step 0x0088 16 +analog_gain_type 0x008a 16 +analog_gain_m0 0x008c 16 +analog_gain_c0 0x008e 16 +analog_gain_m1 0x0090 16 +analog_gain_c1 0x0092 16 +analog_linear_gain_min 0x0094 16 v1.1 +analog_linear_gain_max 0x0096 16 v1.1 +analog_linear_gain_step_size 0x0098 16 v1.1 +analog_exponential_gain_min 0x009a 16 v1.1 +analog_exponential_gain_max 0x009c 16 v1.1 +analog_exponential_gain_step_size 0x009e 16 v1.1 + +# data format description registers +data_format_model_type 0x00c0 8 +- e normal 1 +- e extended 2 +data_format_model_subtype 0x00c1 8 +- f rows 0 3 +- f columns 4 7 +data_format_descriptor(n) 0x00c2 16 f +- l n 0 15 2 +- f compressed 0 7 +- f uncompressed 8 15 + +# general set-up registers +mode_select 0x0100 8 +- e software_standby 0 +- e streaming 1 +image_orientation 0x0101 8 +- b horizontal_mirror 0 +- b vertical_flip 1 +software_reset 0x0103 8 +- e off 0 +- e on 1 +grouped_parameter_hold 0x0104 8 +mask_corrupted_frames 0x0105 8 +- e allow 0 +- e mask 1 +fast_standby_ctrl 0x0106 8 +- e complete_frames 0 +- e frame_truncation 1 +CCI_address_ctrl 0x0107 8 +2nd_CCI_if_ctrl 0x0108 8 +- b enable 0 +- b ack 1 +2nd_CCI_address_ctrl 0x0109 8 +CSI_channel_identifier 0x0110 8 +CSI_signaling_mode 0x0111 8 +- e csi_2_dphy 2 +- e csi_2_cphy 3 +CSI_data_format 0x0112 16 +CSI_lane_mode 0x0114 8 +DPCM_Frame_DT 0x011d 8 +Bottom_embedded_data_DT 0x011e 8 +Bottom_embedded_data_VC 0x011f 8 + +gain_mode 0x0120 8 +- e global 0 +- e alternate 1 +ADC_bit_depth 0x0121 8 +emb_data_ctrl 0x0122 v1.1 +- b raw8_packing_for_raw16 0 +- b raw10_packing_for_raw20 1 +- b raw12_packing_for_raw24 2 + +GPIO_TRIG_mode 0x0130 8 +extclk_frequency_mhz 0x0136 16 ireal +temp_sensor_ctrl 0x0138 8 +- b enable 0 +temp_sensor_mode 0x0139 8 +temp_sensor_output 0x013a 8 + +# integration time registers +fine_integration_time 0x0200 16 +coarse_integration_time 0x0202 16 + +# analog gain registers +analog_gain_code_global 0x0204 16 +analog_linear_gain_global 0x0206 16 v1.1 +analog_exponential_gain_global 0x0208 16 v1.1 + +# digital gain registers +digital_gain_global 0x020e 16 + +# hdr control registers +Short_analog_gain_global 0x0216 16 +Short_digital_gain_global 0x0218 16 + +HDR_mode 0x0220 8 +- b enabled 0 +- b separate_analog_gain 1 +- b upscaling 2 +- b reset_sync 3 +- b timing_mode 4 +- b exposure_ctrl_direct 5 +- b separate_digital_gain 6 +HDR_resolution_reduction 0x0221 8 +- f row 0 3 +- f column 4 7 +Exposure_ratio 0x0222 8 +HDR_internal_bit_depth 0x0223 8 +Direct_short_integration_time 0x0224 16 +Short_analog_linear_gain_global 0x0226 16 v1.1 +Short_analog_exponential_gain_global 0x0228 16 v1.1 + +# clock set-up registers +vt_pix_clk_div 0x0300 16 +vt_sys_clk_div 0x0302 16 +pre_pll_clk_div 0x0304 16 +#vt_pre_pll_clk_div 0x0304 16 +pll_multiplier 0x0306 16 +#vt_pll_multiplier 0x0306 16 +op_pix_clk_div 0x0308 16 +op_sys_clk_div 0x030a 16 +op_pre_pll_clk_div 0x030c 16 +op_pll_multiplier 0x031e 16 +pll_mode 0x0310 8 +- f 0 0 +- e single 0 +- e dual 1 +op_pix_clk_div_rev 0x0312 16 v1.1 +op_sys_clk_div_rev 0x0314 16 v1.1 + +# frame timing registers +frame_length_lines 0x0340 16 +line_length_pck 0x0342 16 + +# image size registers +x_addr_start 0x0344 16 +y_addr_start 0x0346 16 +x_addr_end 0x0348 16 +y_addr_end 0x034a 16 +x_output_size 0x034c 16 +y_output_size 0x034e 16 + +# timing mode registers +Frame_length_ctrl 0x0350 8 +- b automatic 0 +Timing_mode_ctrl 0x0352 8 +- b manual_readout 0 +- b delayed_exposure 1 +Start_readout_rs 0x0353 8 +- b manual_readout_start 0 +Frame_margin 0x0354 16 + +# sub-sampling registers +x_even_inc 0x0380 16 +x_odd_inc 0x0382 16 +y_even_inc 0x0384 16 +y_odd_inc 0x0386 16 + +# monochrome readout registers +monochrome_en 0x0390 v1.1 +- e enabled 0 + +# image scaling registers +Scaling_mode 0x0400 16 +- e no_scaling 0 +- e horizontal 1 +scale_m 0x0404 16 +scale_n 0x0406 16 +digital_crop_x_offset 0x0408 16 +digital_crop_y_offset 0x040a 16 +digital_crop_image_width 0x040c 16 +digital_crop_image_height 0x040e 16 + +# image compression registers +compression_mode 0x0500 16 +- e none 0 +- e dpcm_pcm_simple 1 + +# test pattern registers +test_pattern_mode 0x0600 16 +- e none 0 +- e solid_color 1 +- e color_bars 2 +- e fade_to_grey 3 +- e pn9 4 +- e color_tile 5 +test_data_red 0x0602 16 +test_data_greenR 0x0604 16 +test_data_blue 0x0606 16 +test_data_greenB 0x0608 16 +value_step_size_smooth 0x060a 8 +value_step_size_quantised 0x060b 8 + +# phy configuration registers +tclk_post 0x0800 8 +ths_prepare 0x0801 8 +ths_zero_min 0x0802 8 +ths_trail 0x0803 8 +tclk_trail_min 0x0804 8 +tclk_prepare 0x0805 8 +tclk_zero 0x0806 8 +tlpx 0x0807 8 +phy_ctrl 0x0808 8 +- e auto 0 +- e UI 1 +- e manual 2 +tclk_post_ex 0x080a 16 +ths_prepare_ex 0x080c 16 +ths_zero_min_ex 0x080e 16 +ths_trail_ex 0x0810 16 +tclk_trail_min_ex 0x0812 16 +tclk_prepare_ex 0x0814 16 +tclk_zero_ex 0x0816 16 +tlpx_ex 0x0818 16 + +# link rate register +requested_link_rate 0x0820 32 u16.16 + +# equalization control registers +DPHY_equalization_mode 0x0824 8 v1.1 +- b eq2 0 +PHY_equalization_ctrl 0x0825 8 v1.1 +- b enable 0 + +# d-phy preamble control registers +DPHY_preamble_ctrl 0x0826 8 v1.1 +- b enable 0 +DPHY_preamble_length 0x0826 8 v1.1 + +# d-phy spread spectrum control registers +PHY_SSC_ctrl 0x0828 8 v1.1 +- b enable 0 + +# manual lp control register +manual_LP_ctrl 0x0829 8 v1.1 +- b enable 0 + +# additional phy configuration registers +twakeup 0x082a v1.1 +tinit 0x082b v1.1 +ths_exit 0x082c v1.1 +ths_exit_ex 0x082e 16 v1.1 + +# phy calibration configuration registers +PHY_periodic_calibration_ctrl 0x0830 8 +- b frame_blanking 0 +PHY_periodic_calibration_interval 0x0831 8 +PHY_init_calibration_ctrl 0x0832 8 +- b stream_start 0 +DPHY_calibration_mode 0x0833 8 v1.1 +- b also_alternate 0 +CPHY_calibration_mode 0x0834 8 v1.1 +- e format_1 0 +- e format_2 1 +- e format_3 2 +t3_calpreamble_length 0x0835 8 v1.1 +t3_calpreamble_length_per 0x0836 8 v1.1 +t3_calaltseq_length 0x0837 8 v1.1 +t3_calaltseq_length_per 0x0838 8 v1.1 +FM2_init_seed 0x083a 16 v1.1 +t3_caludefseq_length 0x083c 16 v1.1 +t3_caludefseq_length_per 0x083e 16 v1.1 + +# c-phy manual control registers +TGR_Preamble_Length 0x0841 8 +- b preamable_prog_seq 7 +- f begin_preamble_length 0 5 +TGR_Post_Length 0x0842 8 +- f post_length 0 4 +TGR_Preamble_Prog_Sequence(n2) 0x0843 +- l n2 0 6 1 +- f symbol_n_1 3 5 +- f symbol_n 0 2 +t3_prepare 0x084e 16 +t3_lpx 0x0850 16 + +# alps control register +ALPS_ctrl 0x085a 8 +- b lvlp_dphy 0 +- b lvlp_cphy 1 +- b alp_cphy 2 + +# lrte control registers +TX_REG_CSI_EPD_EN_SSP_cphy 0x0860 16 +TX_REG_CSI_EPD_OP_SLP_cphy 0x0862 16 +TX_REG_CSI_EPD_EN_SSP_dphy 0x0864 16 +TX_REG_CSI_EPD_OP_SLP_dphy 0x0866 16 +TX_REG_CSI_EPD_MISC_OPTION_cphy 0x0868 v1.1 +TX_REG_CSI_EPD_MISC_OPTION_dphy 0x0869 v1.1 + +# scrambling control registers +Scrambling_ctrl 0x0870 +- b enabled 0 +- f 2 3 +- e 1_seed_cphy 0 +- e 4_seed_cphy 3 +lane_seed_value(seed, lane) 0x0872 16 +- l seed 0 3 0x10 +- l lane 0 7 0x2 + +# usl control registers +TX_USL_REV_ENTRY 0x08c0 16 v1.1 +TX_USL_REV_Clock_Counter 0x08c2 16 v1.1 +TX_USL_REV_LP_Counter 0x08c4 16 v1.1 +TX_USL_REV_Frame_Counter 0x08c6 16 v1.1 +TX_USL_REV_Chronological_Timer 0x08c8 16 v1.1 +TX_USL_FWD_ENTRY 0x08ca 16 v1.1 +TX_USL_GPIO 0x08cc 16 v1.1 +TX_USL_Operation 0x08ce 16 v1.1 +- b reset 0 +TX_USL_ALP_ctrl 0x08d0 16 v1.1 +- b clock_pause 0 +TX_USL_APP_BTA_ACK_TIMEOUT 0x08d2 16 v1.1 +TX_USL_SNS_BTA_ACK_TIMEOUT 0x08d2 16 v1.1 +USL_Clock_Mode_d_ctrl 0x08d2 v1.1 +- b cont_clock_standby 0 +- b cont_clock_vblank 1 +- b cont_clock_hblank 2 + +# binning configuration registers +binning_mode 0x0900 8 +binning_type 0x0901 8 +binning_weighting 0x0902 8 + +# data transfer interface registers +data_transfer_if_1_ctrl 0x0a00 8 +- b enable 0 +- b write 1 +- b clear_error 2 +data_transfer_if_1_status 0x0a01 8 +- b read_if_ready 0 +- b write_if_ready 1 +- b data_corrupted 2 +- b improper_if_usage 3 +data_transfer_if_1_page_select 0x0a02 8 +data_transfer_if_1_data(p) 0x0a04 8 f +- l p 0 63 1 + +# image processing and sensor correction configuration registers +shading_correction_en 0x0b00 8 +- b enable 0 +luminance_correction_level 0x0b01 8 +green_imbalance_filter_en 0x0b02 8 +- b enable 0 +mapped_defect_correct_en 0x0b05 8 +- b enable 0 +single_defect_correct_en 0x0b06 8 +- b enable 0 +dynamic_couplet_correct_en 0x0b08 8 +- b enable 0 +combined_defect_correct_en 0x0b0a 8 +- b enable 0 +module_specific_correction_en 0x0b0c 8 +- b enable 0 +dynamic_triplet_defect_correct_en 0x0b13 8 +- b enable 0 +NF_ctrl 0x0b15 8 +- b luma 0 +- b chroma 1 +- b combined 2 + +# optical black pixel readout registers +OB_readout_control 0x0b30 8 +- b enable 0 +- b interleaving 1 +OB_virtual_channel 0x0b31 8 +OB_DT 0x0b32 8 +OB_data_format 0x0b33 8 + +# color temperature feedback registers +color_temperature 0x0b8c 16 +absolute_gain_greenr 0x0b8e 16 +absolute_gain_red 0x0b90 16 +absolute_gain_blue 0x0b92 16 +absolute_gain_greenb 0x0b94 16 + +# cfa conversion registers +CFA_conversion_ctrl 0x0ba0 v1.1 +- b bayer_conversion_enable 0 + +# flash strobe and sa strobe control registers +flash_strobe_adjustment 0x0c12 8 +flash_strobe_start_point 0x0c14 16 +tflash_strobe_delay_rs_ctrl 0x0c16 16 +tflash_strobe_width_high_rs_ctrl 0x0c18 16 +flash_mode_rs 0x0c1a 8 +- b continuous 0 +- b truncate 1 +- b async 3 +flash_trigger_rs 0x0c1b 8 +flash_status 0x0c1c 8 +- b retimed 0 +sa_strobe_mode 0x0c1d 8 +- b continuous 0 +- b truncate 1 +- b async 3 +- b adjust_edge 4 +sa_strobe_start_point 0x0c1e 16 +tsa_strobe_delay_ctrl 0x0c20 16 +tsa_strobe_width_ctrl 0x0c22 16 +sa_strobe_trigger 0x0c24 8 +sa_strobe_status 0x0c25 8 +- b retimed 0 +tSA_strobe_re_delay_ctrl 0x0c30 16 +tSA_strobe_fe_delay_ctrl 0x0c32 16 + +# pdaf control registers +PDAF_ctrl 0x0d00 16 +- b enable 0 +- b processed 1 +- b interleaved 2 +- b visible_pdaf_correction 3 +PDAF_VC 0x0d02 8 +PDAF_DT 0x0d03 8 +pd_x_addr_start 0x0d04 16 +pd_y_addr_start 0x0d06 16 +pd_x_addr_end 0x0d08 16 +pd_y_addr_end 0x0d0a 16 + +# bracketing interface configuration registers +bracketing_LUT_ctrl 0x0e00 8 +bracketing_LUT_mode 0x0e01 8 +- b continue_streaming 0 +- b loop_mode 1 +bracketing_LUT_entry_ctrl 0x0e02 8 +bracketing_LUT_frame(n) 0x0e10 v1.1 f +- l n 0 0xef 1 + +# integration time and gain parameter limit registers +integration_time_capability 0x1000 16 +- b fine 0 +coarse_integration_time_min 0x1004 16 +coarse_integration_time_max_margin 0x1006 16 +fine_integration_time_min 0x1008 16 +fine_integration_time_max_margin 0x100a 16 + +# digital gain parameter limit registers +digital_gain_capability 0x1081 +- e none 0 +- e global 2 +digital_gain_min 0x1084 16 +digital_gain_max 0x1086 16 +digital_gain_step_size 0x1088 16 + +# data pedestal capability registers +Pedestal_capability 0x10e0 8 v1.1 + +# adc capability registers +ADC_capability 0x10f0 8 +- b bit_depth_ctrl 0 +ADC_bit_depth_capability 0x10f4 32 v1.1 + +# video timing parameter limit registers +min_ext_clk_freq_mhz 0x1100 32 float_ireal +max_ext_clk_freq_mhz 0x1104 32 float_ireal +min_pre_pll_clk_div 0x1108 16 +# min_vt_pre_pll_clk_div 0x1108 16 +max_pre_pll_clk_div 0x110a 16 +# max_vt_pre_pll_clk_div 0x110a 16 +min_pll_ip_clk_freq_mhz 0x110c 32 float_ireal +# min_vt_pll_ip_clk_freq_mhz 0x110c 32 float_ireal +max_pll_ip_clk_freq_mhz 0x1110 32 float_ireal +# max_vt_pll_ip_clk_freq_mhz 0x1110 32 float_ireal +min_pll_multiplier 0x1114 16 +# min_vt_pll_multiplier 0x1114 16 +max_pll_multiplier 0x1116 16 +# max_vt_pll_multiplier 0x1116 16 +min_pll_op_clk_freq_mhz 0x1118 32 float_ireal +max_pll_op_clk_freq_mhz 0x111c 32 float_ireal + +# video timing set-up capability registers +min_vt_sys_clk_div 0x1120 16 +max_vt_sys_clk_div 0x1122 16 +min_vt_sys_clk_freq_mhz 0x1124 32 float_ireal +max_vt_sys_clk_freq_mhz 0x1128 32 float_ireal +min_vt_pix_clk_freq_mhz 0x112c 32 float_ireal +max_vt_pix_clk_freq_mhz 0x1130 32 float_ireal +min_vt_pix_clk_div 0x1134 16 +max_vt_pix_clk_div 0x1136 16 +clock_calculation 0x1138 +- b lane_speed 0 +- b link_decoupled 1 +- b dual_pll_op_sys_ddr 2 +- b dual_pll_op_pix_ddr 3 +num_of_vt_lanes 0x1139 +num_of_op_lanes 0x113a +op_bits_per_lane 0x113b 8 v1.1 + +# frame timing parameter limits +min_frame_length_lines 0x1140 16 +max_frame_length_lines 0x1142 16 +min_line_length_pck 0x1144 16 +max_line_length_pck 0x1146 16 +min_line_blanking_pck 0x1148 16 +min_frame_blanking_lines 0x114a 16 +min_line_length_pck_step_size 0x114c +timing_mode_capability 0x114d +- b auto_frame_length 0 +- b rolling_shutter_manual_readout 2 +- b delayed_exposure_start 3 +- b manual_exposure_embedded_data 4 +frame_margin_max_value 0x114e 16 +frame_margin_min_value 0x1150 +gain_delay_type 0x1151 +- e fixed 0 +- e variable 1 + +# output clock set-up capability registers +min_op_sys_clk_div 0x1160 16 +max_op_sys_clk_div 0x1162 16 +min_op_sys_clk_freq_mhz 0x1164 32 float_ireal +max_op_sys_clk_freq_mhz 0x1168 32 float_ireal +min_op_pix_clk_div 0x116c 16 +max_op_pix_clk_div 0x116e 16 +min_op_pix_clk_freq_mhz 0x1170 32 float_ireal +max_op_pix_clk_freq_mhz 0x1174 32 float_ireal + +# image size parameter limit registers +x_addr_min 0x1180 16 +y_addr_min 0x1182 16 +x_addr_max 0x1184 16 +y_addr_max 0x1186 16 +min_x_output_size 0x1188 16 +min_y_output_size 0x118a 16 +max_x_output_size 0x118c 16 +max_y_output_size 0x118e 16 + +x_addr_start_div_constant 0x1190 v1.1 +y_addr_start_div_constant 0x1191 v1.1 +x_addr_end_div_constant 0x1192 v1.1 +y_addr_end_div_constant 0x1193 v1.1 +x_size_div 0x1194 v1.1 +y_size_div 0x1195 v1.1 +x_output_div 0x1196 v1.1 +y_output_div 0x1197 v1.1 +non_flexible_resolution_support 0x1198 v1.1 +- b new_pix_addr 0 +- b new_output_res 1 +- b output_crop_no_pad 2 +- b output_size_lane_dep 3 + +min_op_pre_pll_clk_div 0x11a0 16 +max_op_pre_pll_clk_div 0x11a2 16 +min_op_pll_ip_clk_freq_mhz 0x11a4 32 float_ireal +max_op_pll_ip_clk_freq_mhz 0x11a8 32 float_ireal +min_op_pll_multiplier 0x11ac 16 +max_op_pll_multiplier 0x11ae 16 +min_op_pll_op_clk_freq_mhz 0x11b0 32 float_ireal +max_op_pll_op_clk_freq_mhz 0x11b4 32 float_ireal +clock_tree_pll_capability 0x11b8 8 +- b dual_pll 0 +- b single_pll 1 +- b ext_divider 2 +- b flexible_op_pix_clk_div 3 +clock_capa_type_capability 0x11b9 v1.1 +- b ireal 0 + +# sub-sampling parameters limit registers +min_even_inc 0x11c0 16 +min_odd_inc 0x11c2 16 +max_even_inc 0x11c4 16 +max_odd_inc 0x11c6 16 +aux_subsamp_capability 0x11c8 v1.1 +- b factor_power_of_2 1 +aux_subsamp_mono_capability 0x11c9 v1.1 +- b factor_power_of_2 1 +monochrome_capability 0x11ca v1.1 +- e inc_odd 0 +- e inc_even 1 +pixel_readout_capability 0x11cb v1.1 +- e bayer 0 +- e monochrome 1 +- e bayer_and_mono 2 +min_even_inc_mono 0x11cc 16 v1.1 +max_even_inc_mono 0x11ce 16 v1.1 +min_odd_inc_mono 0x11d0 16 v1.1 +max_odd_inc_mono 0x11d2 16 v1.1 +min_even_inc_bc2 0x11d4 16 v1.1 +max_even_inc_bc2 0x11d6 16 v1.1 +min_odd_inc_bc2 0x11d8 16 v1.1 +max_odd_inc_bc2 0x11da 16 v1.1 +min_even_inc_mono_bc2 0x11dc 16 v1.1 +max_even_inc_mono_bc2 0x11de 16 v1.1 +min_odd_inc_mono_bc2 0x11f0 16 v1.1 +max_odd_inc_mono_bc2 0x11f2 16 v1.1 + +# image scaling limit parameters +scaling_capability 0x1200 16 +- e none 0 +- e horizontal 1 +- e reserved 2 +scaler_m_min 0x1204 16 +scaler_m_max 0x1206 16 +scaler_n_min 0x1208 16 +scaler_n_max 0x120a 16 +digital_crop_capability 0x120e +- e none 0 +- e input_crop 1 + +# hdr limit registers +hdr_capability_1 0x1210 +- b 2x2_binning 0 +- b combined_analog_gain 1 +- b separate_analog_gain 2 +- b upscaling 3 +- b reset_sync 4 +- b direct_short_exp_timing 5 +- b direct_short_exp_synthesis 6 +min_hdr_bit_depth 0x1211 +hdr_resolution_sub_types 0x1212 +hdr_resolution_sub_type(n) 0x1213 +- l n 0 1 1 +- f row 0 3 +- f column 4 7 +hdr_capability_2 0x121b +- b combined_digital_gain 0 +- b separate_digital_gain 1 +- b timing_mode 3 +- b synthesis_mode 4 +max_hdr_bit_depth 0x121c + +# usl capability register +usl_support_capability 0x1230 v1.1 +- b clock_tree 0 +- b rev_clock_tree 1 +- b rev_clock_calc 2 +usl_clock_mode_d_capability 0x1231 v1.1 +- b cont_clock_standby 0 +- b cont_clock_vblank 1 +- b cont_clock_hblank 2 +- b noncont_clock_standby 3 +- b noncont_clock_vblank 4 +- b noncont_clock_hblank 5 +min_op_sys_clk_div_rev 0x1234 v1.1 +max_op_sys_clk_div_rev 0x1236 v1.1 +min_op_pix_clk_div_rev 0x1238 v1.1 +max_op_pix_clk_div_rev 0x123a v1.1 +min_op_sys_clk_freq_rev_mhz 0x123c 32 v1.1 float_ireal +max_op_sys_clk_freq_rev_mhz 0x1240 32 v1.1 float_ireal +min_op_pix_clk_freq_rev_mhz 0x1244 32 v1.1 float_ireal +max_op_pix_clk_freq_rev_mhz 0x1248 32 v1.1 float_ireal +max_bitrate_rev_d_mode_mbps 0x124c 32 v1.1 ireal +max_symrate_rev_c_mode_msps 0x1250 32 v1.1 ireal + +# image compression capability registers +compression_capability 0x1300 +- b dpcm_pcm_simple 0 + +# test mode capability registers +test_mode_capability 0x1310 16 +- b solid_color 0 +- b color_bars 1 +- b fade_to_grey 2 +- b pn9 3 +- b color_tile 5 +pn9_data_format1 0x1312 +pn9_data_format2 0x1313 +pn9_data_format3 0x1314 +pn9_data_format4 0x1315 +pn9_misc_capability 0x1316 +- f num_pixels 0 2 +- b compression 3 +test_pattern_capability 0x1317 v1.1 +- b no_repeat 1 +pattern_size_div_m1 0x1318 v1.1 + +# fifo capability registers +fifo_support_capability 0x1502 +- e none 0 +- e derating 1 +- e derating_overrating 2 + +# csi-2 capability registers +phy_ctrl_capability 0x1600 +- b auto_phy_ctl 0 +- b ui_phy_ctl 1 +- b dphy_time_ui_reg_1_ctl 2 +- b dphy_time_ui_reg_2_ctl 3 +- b dphy_time_ctl 4 +- b dphy_ext_time_ui_reg_1_ctl 5 +- b dphy_ext_time_ui_reg_2_ctl 6 +- b dphy_ext_time_ctl 7 +csi_dphy_lane_mode_capability 0x1601 +- b 1_lane 0 +- b 2_lane 1 +- b 3_lane 2 +- b 4_lane 3 +- b 5_lane 4 +- b 6_lane 5 +- b 7_lane 6 +- b 8_lane 7 +csi_signaling_mode_capability 0x1602 +- b csi_dphy 2 +- b csi_cphy 3 +fast_standby_capability 0x1603 +- e no_frame_truncation 0 +- e frame_truncation 1 +csi_address_control_capability 0x1604 +- b cci_addr_change 0 +- b 2nd_cci_addr 1 +- b sw_changeable_2nd_cci_addr 2 +data_type_capability 0x1605 +- b dpcm_programmable 0 +- b bottom_embedded_dt_programmable 1 +- b bottom_embedded_vc_programmable 2 +- b ext_vc_range 3 +csi_cphy_lane_mode_capability 0x1606 +- b 1_lane 0 +- b 2_lane 1 +- b 3_lane 2 +- b 4_lane 3 +- b 5_lane 4 +- b 6_lane 5 +- b 7_lane 6 +- b 8_lane 7 +emb_data_capability 0x1607 v1.1 +- b two_bytes_per_raw16 0 +- b two_bytes_per_raw20 1 +- b two_bytes_per_raw24 2 +- b no_one_byte_per_raw16 3 +- b no_one_byte_per_raw20 4 +- b no_one_byte_per_raw24 5 +max_per_lane_bitrate_lane_d_mode_mbps(n) 0x1608 32 ireal +- l n 0 7 4 4,0x32 +temp_sensor_capability 0x1618 +- b supported 0 +- b CCS_format 1 +- b reset_0x80 2 +max_per_lane_bitrate_lane_c_mode_mbps(n) 0x161a 32 ireal +- l n 0 7 4 4,0x30 +dphy_equalization_capability 0x162b +- b equalization_ctrl 0 +- b eq1 1 +- b eq2 2 +cphy_equalization_capability 0x162c +- b equalization_ctrl 0 +dphy_preamble_capability 0x162d +- b preamble_seq_ctrl 0 +dphy_ssc_capability 0x162e +- b supported 0 +cphy_calibration_capability 0x162f +- b manual 0 +- b manual_streaming 1 +- b format_1_ctrl 2 +- b format_2_ctrl 3 +- b format_3_ctrl 4 +dphy_calibration_capability 0x1630 +- b manual 0 +- b manual_streaming 1 +- b alternate_seq 2 +phy_ctrl_capability_2 0x1631 +- b tgr_length 0 +- b tgr_preamble_prog_seq 1 +- b extra_cphy_manual_timing 2 +- b clock_based_manual_cdphy 3 +- b clock_based_manual_dphy 4 +- b clock_based_manual_cphy 5 +- b manual_lp_dphy 6 +- b manual_lp_cphy 7 +lrte_cphy_capability 0x1632 +- b pdq_short 0 +- b spacer_short 1 +- b pdq_long 2 +- b spacer_long 3 +- b spacer_no_pdq 4 +lrte_dphy_capability 0x1633 +- b pdq_short_opt1 0 +- b spacer_short_opt1 1 +- b pdq_long_opt1 2 +- b spacer_long_opt1 3 +- b spacer_short_opt2 4 +- b spacer_long_opt2 5 +- b spacer_no_pdq_opt1 6 +- b spacer_variable_opt2 7 +alps_capability_dphy 0x1634 +- e lvlp_not_supported 0 0x3 +- e lvlp_supported 1 0x3 +- e controllable_lvlp 2 0x3 +alps_capability_cphy 0x1635 +- e lvlp_not_supported 0 0x3 +- e lvlp_supported 1 0x3 +- e controllable_lvlp 2 0x3 +- e alp_not_supported 0xc 0xc +- e alp_supported 0xd 0xc +- e controllable_alp 0xe 0xc +scrambling_capability 0x1636 +- b scrambling_supported 0 +- f max_seeds_per_lane_c 1 2 +- e 1 0 +- e 4 3 +- f num_seed_regs 3 5 +- e 0 0 +- e 1 1 +- e 4 4 +- b num_seed_per_lane 6 +dphy_manual_constant 0x1637 +cphy_manual_constant 0x1638 +CSI2_interface_capability_misc 0x1639 v1.1 +- b eotp_short_pkt_opt2 0 +PHY_ctrl_capability_3 0x165c v1.1 +- b dphy_timing_not_multiple 0 +- b dphy_min_timing_value_1 1 +- b twakeup_supported 2 +- b tinit_supported 3 +- b ths_exit_supported 4 +- b cphy_timing_not_multiple 5 +- b cphy_min_timing_value_1 6 +dphy_sf 0x165d v1.1 +cphy_sf 0x165e v1.1 +- f twakeup 0 3 +- f tinit 4 7 +dphy_limits_1 0x165f v1.1 +- f ths_prepare 0 3 +- f ths_zero 4 7 +dphy_limits_2 0x1660 v1.1 +- f ths_trail 0 3 +- f tclk_trail_min 4 7 +dphy_limits_3 0x1661 v1.1 +- f tclk_prepare 0 3 +- f tclk_zero 4 7 +dphy_limits_4 0x1662 v1.1 +- f tclk_post 0 3 +- f tlpx 4 7 +dphy_limits_5 0x1663 v1.1 +- f ths_exit 0 3 +- f twakeup 4 7 +dphy_limits_6 0x1664 v1.1 +- f tinit 0 3 +cphy_limits_1 0x1665 v1.1 +- f t3_prepare_max 0 3 +- f t3_lpx_max 4 7 +cphy_limits_2 0x1666 v1.1 +- f ths_exit_max 0 3 +- f twakeup_max 4 7 +cphy_limits_3 0x1667 v1.1 +- f tinit_max 0 3 + +# binning capability registers +min_frame_length_lines_bin 0x1700 16 +max_frame_length_lines_bin 0x1702 16 +min_line_length_pck_bin 0x1704 16 +max_line_length_pck_bin 0x1706 16 +min_line_blanking_pck_bin 0x1708 16 +fine_integration_time_min_bin 0x170a 16 +fine_integration_time_max_margin_bin 0x170c 16 +binning_capability 0x1710 +- e unsupported 0 +- e binning_then_subsampling 1 +- e subsampling_then_binning 2 +binning_weighting_capability 0x1711 +- b averaged 0 +- b summed 1 +- b bayer_corrected 2 +- b module_specific_weight 3 +binning_sub_types 0x1712 +binning_sub_type(n) 0x1713 +- l n 0 63 1 +- f row 0 3 +- f column 4 7 +binning_weighting_mono_capability 0x1771 v1.1 +- b averaged 0 +- b summed 1 +- b bayer_corrected 2 +- b module_specific_weight 3 +binning_sub_types_mono 0x1772 v1.1 +binning_sub_type_mono(n) 0x1773 v1.1 f +- l n 0 63 1 + +# data transfer interface capability registers +data_transfer_if_capability 0x1800 +- b supported 0 +- b polling 2 + +# sensor correction capability registers +shading_correction_capability 0x1900 +- b color_shading 0 +- b luminance_correction 1 +green_imbalance_capability 0x1901 +- b supported 0 +module_specific_correction_capability 0x1903 +defect_correction_capability 0x1904 16 +- b mapped_defect 0 +- b dynamic_couplet 2 +- b dynamic_single 5 +- b combined_dynamic 8 +defect_correction_capability_2 0x1906 16 +- b dynamic_triplet 3 +nf_capability 0x1908 +- b luma 0 +- b chroma 1 +- b combined 2 + +# optical black readout capability registers +ob_readout_capability 0x1980 +- b controllable_readout 0 +- b visible_pixel_readout 1 +- b different_vc_readout 2 +- b different_dt_readout 3 +- b prog_data_format 4 + +# color feedback capability registers +color_feedback_capability 0x1987 +- b kelvin 0 +- b awb_gain 1 + +# cfa pattern capability registers +CFA_pattern_capability 0x1990 v1.1 +- e bayer 0 +- e monochrome 1 +- e 4x4_quad_bayer 2 +- e vendor_specific 3 +CFA_pattern_conversion_capability 0x1991 v1.1 +- b bayer 0 + +# timer capability registers +flash_mode_capability 0x1a02 +- b single_strobe 0 +sa_strobe_mode_capability 0x1a03 +- b fixed_width 0 +- b edge_ctrl 1 + +# soft reset capability registers +reset_max_delay 0x1a10 v1.1 +reset_min_time 0x1a11 v1.1 + +# pdaf capability registers +pdaf_capability_1 0x1b80 +- b supported 0 +- b processed_bottom_embedded 1 +- b processed_interleaved 2 +- b raw_bottom_embedded 3 +- b raw_interleaved 4 +- b visible_pdaf_correction 5 +- b vc_interleaving 6 +- b dt_interleaving 7 +pdaf_capability_2 0x1b81 +- b ROI 0 +- b after_digital_crop 1 +- b ctrl_retimed 2 + +# bracketing interface capability registers +bracketing_lut_capability_1 0x1c00 +- b coarse_integration 0 +- b global_analog_gain 1 +- b flash 4 +- b global_digital_gain 5 +- b alternate_global_analog_gain 6 +bracketing_lut_capability_2 0x1c01 +- b single_bracketing_mode 0 +- b looped_bracketing_mode 1 +bracketing_lut_size 0x1c02 diff --git a/Documentation/driver-api/media/drivers/ccs/ccs.rst b/Documentation/driver-api/media/drivers/ccs/ccs.rst new file mode 100644 index 000000000000..f49e971f2d92 --- /dev/null +++ b/Documentation/driver-api/media/drivers/ccs/ccs.rst @@ -0,0 +1,82 @@ +.. SPDX-License-Identifier: GPL-2.0-only OR BSD-3-Clause + +.. include:: <isonum.txt> + +MIPI CCS camera sensor driver +============================= + +The MIPI CCS camera sensor driver is a generic driver for `MIPI CCS +<https://www.mipi.org/specifications/camera-command-set>`_ compliant +camera sensors. It exposes three sub-devices representing the pixel array, +the binner and the scaler. + +As the capabilities of individual devices vary, the driver exposes +interfaces based on the capabilities that exist in hardware. + +Pixel Array sub-device +---------------------- + +The pixel array sub-device represents the camera sensor's pixel matrix, as well +as analogue crop functionality present in many compliant devices. The analogue +crop is configured using the ``V4L2_SEL_TGT_CROP`` on the source pad (0) of the +entity. The size of the pixel matrix can be obtained by getting the +``V4L2_SEL_TGT_NATIVE_SIZE`` target. + +Binner +------ + +The binner sub-device represents the binning functionality on the sensor. For +that purpose, selection target ``V4L2_SEL_TGT_COMPOSE`` is supported on the +sink pad (0). + +Additionally, if a device has no scaler or digital crop functionality, the +source pad (1) expses another digital crop selection rectangle that can only +crop at the end of the lines and frames. + +Scaler +------ + +The scaler sub-device represents the digital crop and scaling functionality of +the sensor. The V4L2 selection target ``V4L2_SEL_TGT_CROP`` is used to +configure the digital crop on the sink pad (0) when digital crop is supported. +Scaling is configured using selection target ``V4L2_SEL_TGT_COMPOSE`` on the +sink pad (0) as well. + +Additionally, if the scaler sub-device exists, its source pad (1) exposes +another digital crop selection rectangle that can only crop at the end of the +lines and frames. + +Digital and analogue crop +------------------------- + +Digital crop functionality is referred to as cropping that effectively works by +dropping some data on the floor. Analogue crop, on the other hand, means that +the cropped information is never retrieved. In case of camera sensors, the +analogue data is never read from the pixel matrix that are outside the +configured selection rectangle that designates crop. The difference has an +effect in device timing and likely also in power consumption. + +Register definition generator +----------------------------- + +The ccs-regs.asc file contains MIPI CCS register definitions that are used +to produce C source code files for definitions that can be better used by +programs written in C language. As there are many dependencies between the +produced files, please do not modify them manually as it's error-prone and +in vain, but instead change the script producing them. + +Usage +~~~~~ + +Conventionally the script is called this way to update the CCS driver +definitions: + +.. code-block:: none + + $ Documentation/driver-api/media/drivers/ccs/mk-ccs-regs -k \ + -e drivers/media/i2c/ccs/ccs-regs.h \ + -L drivers/media/i2c/ccs/ccs-limits.h \ + -l drivers/media/i2c/ccs/ccs-limits.c \ + -c Documentation/driver-api/media/drivers/ccs/ccs-regs.asc + +**Copyright** |copy| 2020 Intel Corporation diff --git a/Documentation/driver-api/media/drivers/ccs/mk-ccs-regs b/Documentation/driver-api/media/drivers/ccs/mk-ccs-regs new file mode 100755 index 000000000000..6668deaf2f19 --- /dev/null +++ b/Documentation/driver-api/media/drivers/ccs/mk-ccs-regs @@ -0,0 +1,433 @@ +#!/usr/bin/perl -w +# SPDX-License-Identifier: GPL-2.0-only OR BSD-3-Clause +# Copyright (C) 2019--2020 Intel Corporation + +use Getopt::Long qw(:config no_ignore_case); +use File::Basename; + +my $ccsregs = "ccs-regs.asc"; +my $header; +my $regarray; +my $limitc; +my $limith; +my $kernel; +my $help; + +GetOptions("ccsregs|c=s" => \$ccsregs, + "header|e=s" => \$header, + "regarray|r=s" => \$regarray, + "limitc|l=s" => \$limitc, + "limith|L=s" => \$limith, + "kernel|k" => \$kernel, + "help|h" => \$help) or die "can't parse options"; + +$help = 1 if ! defined $header || ! defined $limitc || ! defined $limith; + +if (defined $help) { + print <<EOH +$0 - Create CCS register definitions for C + +usage: $0 -c ccs-regs.asc -e header -r regarray -l limit-c -L limit-header [-k] + + -c ccs register file + -e header file name + -r register description array file name + -l limit and capability array file name + -L limit and capability header file name + -k generate files for kernel space consumption +EOH + ; + exit 0; +} + +my $lh_hdr = ! defined $kernel + ? '#include "ccs-os.h"' . "\n" + : "#include <linux/bits.h>\n#include <linux/types.h>\n"; +my $uint32_t = ! defined $kernel ? 'uint32_t' : 'u32'; +my $uint16_t = ! defined $kernel ? 'uint16_t' : 'u16'; + +open(my $R, "< $ccsregs") or die "can't open $ccsregs"; + +open(my $H, "> $header") or die "can't open $header"; +my $A; +if (defined $regarray) { + open($A, "> $regarray") or die "can't open $regarray"; +} +open(my $LC, "> $limitc") or die "can't open $limitc"; +open(my $LH, "> $limith") or die "can't open $limith"; + +my %this; + +sub is_limit_reg($) { + my $addr = hex $_[0]; + + return 0 if $addr < 0x40; # weed out status registers + return 0 if $addr >= 0x100 && $addr < 0xfff; # weed out configuration registers + + return 1; +} + +my $uc_header = basename uc $header; +$uc_header =~ s/[^A-Z0-9]/_/g; + +my $copyright = "/* Copyright (C) 2019--2020 Intel Corporation */\n"; +my $license = "SPDX-License-Identifier: GPL-2.0-only OR BSD-3-Clause"; + +for my $fh ($A, $LC) { + print $fh "// $license\n$copyright\n" if defined $fh; +} + +for my $fh ($H, $LH) { + print $fh "/* $license */\n$copyright\n"; +} + +sub bit_def($) { + my $bit = shift @_; + + return "BIT($bit)" if defined $kernel; + return "(1U << $bit)" if $bit =~ /^[a-zA-Z0-9_]+$/; + return "(1U << ($bit))"; +} + +print $H <<EOF +#ifndef __${uc_header}__ +#define __${uc_header}__ + +EOF + ; + +print $H "#include <linux/bits.h>\n\n" if defined $kernel; + +print $H <<EOF +#define CCS_FL_BASE 16 +EOF + ; + +print $H "#define CCS_FL_16BIT " . bit_def("CCS_FL_BASE") . "\n"; +print $H "#define CCS_FL_32BIT " . bit_def("CCS_FL_BASE + 1") . "\n"; +print $H "#define CCS_FL_FLOAT_IREAL " . bit_def("CCS_FL_BASE + 2") . "\n"; +print $H "#define CCS_FL_IREAL " . bit_def("CCS_FL_BASE + 3") . "\n"; + +print $H <<EOF +#define CCS_R_ADDR(r) ((r) & 0xffff) + +EOF + ; + +print $A <<EOF +#include <stdint.h> +#include <stdio.h> +#include "ccs-extra.h" +#include "ccs-regs.h" + +EOF + if defined $A; + +my $uc_limith = basename uc $limith; +$uc_limith =~ s/[^A-Z0-9]/_/g; + +print $LH <<EOF +#ifndef __${uc_limith}__ +#define __${uc_limith}__ + +$lh_hdr +struct ccs_limit { + $uint32_t reg; + $uint16_t size; + $uint16_t flags; + const char *name; +}; + +EOF + ; +print $LH "#define CCS_L_FL_SAME_REG " . bit_def(0) . "\n\n"; + +print $LH <<EOF +extern const struct ccs_limit ccs_limits[]; + +EOF + ; + +print $LC <<EOF +#include "ccs-limits.h" +#include "ccs-regs.h" + +const struct ccs_limit ccs_limits[] = { +EOF + ; + +my $limitcount = 0; +my $argdescs; +my $reglist = "const struct ccs_reg_desc ccs_reg_desc[] = {\n"; + +sub name_split($$) { + my ($name, $addr) = @_; + my $args; + + $name =~ /([^\(]+?)(\(.*)/; + ($name, $args) = ($1, $2); + $args = [split /,\s*/, $args]; + foreach my $t (@$args) { + $t =~ s/[\(\)]//g; + $t =~ s/\//\\\//g; + } + + return ($name, $addr, $args); +} + +sub tabconv($) { + $_ = shift; + + my @l = split "\n", $_; + + map { + s/ {8,8}/\t/g; + s/\t\K +//; + } @l; + + return (join "\n", @l) . "\n"; +} + +sub elem_size(@) { + my @flags = @_; + + return 2 if grep /^16$/, @flags; + return 4 if grep /^32$/, @flags; + return 1; +} + +sub arr_size($) { + my $this = $_[0]; + my $size = $this->{elsize}; + my $h = $this->{argparams}; + + foreach my $arg (@{$this->{args}}) { + my $apref = $h->{$arg}; + + $size *= $apref->{max} - $apref->{min} + 1; + } + + return $size; +} + +sub print_args($$$) { + my ($this, $postfix, $is_same_reg) = @_; + my ($args, $argparams, $name) = + ($this->{args}, $this->{argparams}, $this->{name}); + my $varname = "ccs_reg_arg_" . (lc $name) . $postfix; + my @mins; + my @sorted_args = @{$this->{sorted_args}}; + my $lim_arg; + my $size = arr_size($this); + + $argdescs .= "static const struct ccs_reg_arg " . $varname . "[] = {\n"; + + foreach my $sorted_arg (@sorted_args) { + push @mins, $argparams->{$sorted_arg}->{min}; + } + + foreach my $sorted_arg (@sorted_args) { + my $h = $argparams->{$sorted_arg}; + + $argdescs .= "\t{ \"$sorted_arg\", $h->{min}, $h->{max}, $h->{elsize} },\n"; + + $lim_arg .= defined $lim_arg ? ", $h->{min}" : "$h->{min}"; + } + + $argdescs .= "};\n\n"; + + $reglist .= "\t{ CCS_R_" . (uc $name) . "(" . (join ",", (@mins)) . + "), $size, sizeof($varname) / sizeof(*$varname)," . + " \"" . (lc $name) . "\", $varname },\n"; + + print $LC tabconv sprintf "\t{ CCS_R_" . (uc $name) . "($lim_arg), " . + $size . ", " . ($is_same_reg ? "CCS_L_FL_SAME_REG" : "0") . + ", \"$name" . (defined $this->{discontig} ? " $lim_arg" : "") . "\" },\n" + if is_limit_reg $this->{base_addr}; +} + +my $hdr_data; + +while (<$R>) { + chop; + s/^\s*//; + next if /^[#;]/ || /^$/; + if (s/^-\s*//) { + if (s/^b\s*//) { + my ($bit, $addr) = split /\t+/; + $bit = uc $bit; + $hdr_data .= sprintf "#define %-62s %s", "CCS_" . (uc ${this{name}}) ."_$bit", bit_def($addr) . "\n"; + } elsif (s/^f\s*//) { + s/[,\.-]/_/g; + my @a = split /\s+/; + my ($msb, $lsb, $this_field) = reverse @a; + @a = ( { "name" => "SHIFT", "addr" => $lsb, "fmt" => "%uU", }, + { "name" => "MASK", "addr" => (1 << ($msb + 1)) - 1 - ((1 << $lsb) - 1), "fmt" => "0x%" . join(".", ($this{"elsize"} >> 2) x 2) . "x" } ); + $this{"field"} = $this_field; + foreach my $ar (@a) { + #print $ar->{fmt}."\n"; + $hdr_data .= sprintf "#define %-62s " . $ar->{"fmt"} . "\n", "CCS_" . (uc $this{"name"}) . (defined $this_field ? "_" . uc $this_field : "") . "_" . $ar->{"name"}, $ar->{"addr"} . "\n"; + } + } elsif (s/^e\s*//) { + s/[,\.-]/_/g; + my ($enum, $addr) = split /\s+/; + $enum = uc $enum; + $hdr_data .= sprintf "#define %-62s %s", "CCS_" . (uc ${this{name}}) . (defined $this{"field"} ? "_" . uc $this{"field"} : "") ."_$enum", $addr . ($addr =~ /0x/i ? "" : "U") . "\n"; + } elsif (s/^l\s*//) { + my ($arg, $min, $max, $elsize, @discontig) = split /\s+/; + my $size; + + foreach my $num ($min, $max) { + $num = hex $num if $num =~ /0x/i; + } + + $hdr_data .= sprintf "#define %-62s %s", "CCS_LIM_" . (uc ${this{name}} . "_MIN_$arg"), $min . ($min =~ /0x/i ? "" : "U") . "\n"; + $hdr_data .= sprintf "#define %-62s %s", "CCS_LIM_" . (uc ${this{name}} . "_MAX_$arg"), $max . ($max =~ /0x/i ? "" : "U") . "\n"; + + my $h = $this{argparams}; + + $h->{$arg} = { "min" => $min, + "max" => $max, + "elsize" => $elsize =~ /^0x/ ? hex $elsize : $elsize, + "discontig" => \@discontig }; + + $this{discontig} = $arg if @discontig; + + next if $#{$this{args}} + 1 != scalar keys %{$this{argparams}}; + + my $reg_formula = "($this{addr}"; + my $lim_formula; + + foreach my $arg (@{$this{args}}) { + my $d = $h->{$arg}->{discontig}; + my $times = $h->{$arg}->{elsize} != 1 ? + " * " . $h->{$arg}->{elsize} : ""; + + if (@$d) { + my ($lim, $offset) = split /,/, $d->[0]; + + $reg_formula .= " + (($arg) < $lim ? ($arg)$times : $offset + (($arg) - $lim)$times)"; + } else { + $reg_formula .= " + ($arg)$times"; + } + + $lim_formula .= (defined $lim_formula ? " + " : "") . "($arg)$times"; + } + + $reg_formula .= ")\n"; + $lim_formula =~ s/^\(([a-z0-9]+)\)$/$1/i; + + print $H tabconv sprintf("#define %-62s %s", "CCS_R_" . (uc $this{name}) . + $this{arglist}, $reg_formula); + + print $H tabconv $hdr_data; + undef $hdr_data; + + # Sort arguments in descending order by size + @{$this{sorted_args}} = sort { + $h->{$a}->{elsize} <= $h->{$b}->{elsize} + } @{$this{args}}; + + if (defined $this{discontig}) { + my $da = $this{argparams}->{$this{discontig}}; + my ($first_discontig) = split /,/, $da->{discontig}->[0]; + my $max = $da->{max}; + + $da->{max} = $first_discontig - 1; + print_args(\%this, "", 0); + + $da->{min} = $da->{max} + 1; + $da->{max} = $max; + print_args(\%this, $first_discontig, 1); + } else { + print_args(\%this, "", 0); + } + + next unless is_limit_reg $this{base_addr}; + + print $LH tabconv sprintf "#define %-63s%s\n", + "CCS_L_" . (uc $this{name}) . "_OFFSET(" . + (join ", ", @{$this{args}}) . ")", "($lim_formula)"; + } + + if (! @{$this{args}}) { + print $H tabconv($hdr_data); + undef $hdr_data; + } + + next; + } + + my ($name, $addr, @flags) = split /\t+/, $_; + my $args = []; + + my $sp; + + ($name, $addr, $args) = name_split($name, $addr) if /\(.*\)/; + + $name =~ s/[,\.-]/_/g; + + my $flagstring = ""; + my $size = elem_size(@flags); + $flagstring .= "| CCS_FL_16BIT " if $size eq "2"; + $flagstring .= "| CCS_FL_32BIT " if $size eq "4"; + $flagstring .= "| CCS_FL_FLOAT_IREAL " if grep /^float_ireal$/, @flags; + $flagstring .= "| CCS_FL_IREAL " if grep /^ireal$/, @flags; + $flagstring =~ s/^\| //; + $flagstring =~ s/ $//; + $flagstring = "($flagstring)" if $flagstring =~ /\|/; + my $base_addr = $addr; + $addr = "($addr | $flagstring)" if $flagstring ne ""; + + my $arglist = @$args ? "(" . (join ", ", @$args) . ")" : ""; + $hdr_data .= sprintf "#define %-62s %s\n", "CCS_R_" . (uc $name), $addr + if !@$args; + + $name =~ s/\(.*//; + + %this = ( name => $name, + addr => $addr, + base_addr => $base_addr, + argparams => {}, + args => $args, + arglist => $arglist, + elsize => $size, + ); + + if (!@$args) { + $reglist .= "\t{ CCS_R_" . (uc $name) . ", 1, 0, \"" . (lc $name) . "\", NULL },\n"; + print $H tabconv $hdr_data; + undef $hdr_data; + + print $LC tabconv sprintf "\t{ CCS_R_" . (uc $name) . ", " . + $this{elsize} . ", 0, \"$name\" },\n" + if is_limit_reg $this{base_addr}; + } + + print $LH tabconv sprintf "#define %-63s%s\n", + "CCS_L_" . (uc $this{name}), $limitcount++ + if is_limit_reg $this{base_addr}; +} + +if (defined $A) { + print $A $argdescs, $reglist; + + print $A "\t{ 0 }\n"; + + print $A "};\n"; +} + +print $H "\n#endif /* __${uc_header}__ */\n"; + +print $LH tabconv sprintf "#define %-63s%s\n", "CCS_L_LAST", $limitcount; + +print $LH "\n#endif /* __${uc_limith}__ */\n"; + +print $LC "\t{ 0 } /* Guardian */\n"; +print $LC "};\n"; + +close($R); +close($H); +close($A) if defined $A; +close($LC); +close($LH); diff --git a/Documentation/driver-api/media/drivers/index.rst b/Documentation/driver-api/media/drivers/index.rst index eb7011782863..426cda633bf0 100644 --- a/Documentation/driver-api/media/drivers/index.rst +++ b/Documentation/driver-api/media/drivers/index.rst @@ -26,6 +26,7 @@ Video4Linux (V4L) drivers tuners vimc-devel zoran + ccs/ccs Digital TV drivers diff --git a/Documentation/driver-api/media/drivers/vidtv.rst b/Documentation/driver-api/media/drivers/vidtv.rst index 65115448c52d..673bdff919ea 100644 --- a/Documentation/driver-api/media/drivers/vidtv.rst +++ b/Documentation/driver-api/media/drivers/vidtv.rst @@ -149,11 +149,11 @@ vidtv_psi.[ch] Because the generator is implemented in a separate file, it can be reused elsewhere in the media subsystem. - Currently vidtv supports working with 3 PSI tables: PAT, PMT and - SDT. + Currently vidtv supports working with 5 PSI tables: PAT, PMT, + SDT, NIT and EIT. The specification for PAT and PMT can be found in *ISO 13818-1: - Systems*, while the specification for the SDT can be found in *ETSI + Systems*, while the specification for the SDT, NIT, EIT can be found in *ETSI EN 300 468: Specification for Service Information (SI) in DVB systems*. @@ -197,6 +197,8 @@ vidtv_channel.[ch] #. Their programs will be concatenated to populate the PAT + #. Their events will be concatenated to populate the EIT + #. For each program in the PAT, a PMT section will be created #. The PMT section for a channel will be assigned its streams. @@ -256,6 +258,42 @@ Using dvb-fe-tool The first step to check whether the demod loaded successfully is to run:: $ dvb-fe-tool + Device Dummy demod for DVB-T/T2/C/S/S2 (/dev/dvb/adapter0/frontend0) capabilities: + CAN_FEC_1_2 + CAN_FEC_2_3 + CAN_FEC_3_4 + CAN_FEC_4_5 + CAN_FEC_5_6 + CAN_FEC_6_7 + CAN_FEC_7_8 + CAN_FEC_8_9 + CAN_FEC_AUTO + CAN_GUARD_INTERVAL_AUTO + CAN_HIERARCHY_AUTO + CAN_INVERSION_AUTO + CAN_QAM_16 + CAN_QAM_32 + CAN_QAM_64 + CAN_QAM_128 + CAN_QAM_256 + CAN_QAM_AUTO + CAN_QPSK + CAN_TRANSMISSION_MODE_AUTO + DVB API Version 5.11, Current v5 delivery system: DVBC/ANNEX_A + Supported delivery systems: + DVBT + DVBT2 + [DVBC/ANNEX_A] + DVBS + DVBS2 + Frequency range for the current standard: + From: 51.0 MHz + To: 2.15 GHz + Step: 62.5 kHz + Tolerance: 29.5 MHz + Symbol rate ranges for the current standard: + From: 1.00 MBauds + To: 45.0 MBauds This should return what is currently set up at the demod struct, i.e.:: @@ -314,7 +352,7 @@ For this, one should provide a configuration file known as a 'scan file', here's an example:: [Channel] - FREQUENCY = 330000000 + FREQUENCY = 474000000 MODULATION = QAM/AUTO SYMBOL_RATE = 6940000 INNER_FEC = AUTO @@ -335,6 +373,14 @@ You can browse scan tables online here: `dvb-scan-tables Assuming this channel is named 'channel.conf', you can then run:: $ dvbv5-scan channel.conf + dvbv5-scan ~/vidtv.conf + ERROR command BANDWIDTH_HZ (5) not found during retrieve + Cannot calc frequency shift. Either bandwidth/symbol-rate is unavailable (yet). + Scanning frequency #1 330000000 + (0x00) Signal= -68.00dBm + Scanning frequency #2 474000000 + Lock (0x1f) Signal= -34.45dBm C/N= 33.74dB UCB= 0 + Service Beethoven, provider LinuxTV.org: digital television For more information on dvb-scan, check its documentation online here: `dvb-scan Documentation <https://www.linuxtv.org/wiki/index.php/Dvbscan>`_. @@ -344,23 +390,38 @@ Using dvb-zap dvbv5-zap is a command line tool that can be used to record MPEG-TS to disk. The typical use is to tune into a channel and put it into record mode. The example -below - which is taken from the documentation - illustrates that:: +below - which is taken from the documentation - illustrates that\ [1]_:: - $ dvbv5-zap -c dvb_channel.conf "trilhas sonoras" -r - using demux '/dev/dvb/adapter0/demux0' + $ dvbv5-zap -c dvb_channel.conf "beethoven" -o music.ts -P -t 10 + using demux 'dvb0.demux0' reading channels from file 'dvb_channel.conf' - service has pid type 05: 204 - tuning to 573000000 Hz - audio pid 104 - dvb_set_pesfilter 104 - Lock (0x1f) Quality= Good Signal= 100.00% C/N= -13.80dB UCB= 70 postBER= 3.14x10^-3 PER= 0 - DVR interface '/dev/dvb/adapter0/dvr0' can now be opened + tuning to 474000000 Hz + pass all PID's to TS + dvb_set_pesfilter 8192 + dvb_dev_set_bufsize: buffer set to 6160384 + Lock (0x1f) Quality= Good Signal= -34.66dBm C/N= 33.41dB UCB= 0 postBER= 0 preBER= 1.05x10^-3 PER= 0 + Lock (0x1f) Quality= Good Signal= -34.57dBm C/N= 33.46dB UCB= 0 postBER= 0 preBER= 1.05x10^-3 PER= 0 + Record to file 'music.ts' started + received 24587768 bytes (2401 Kbytes/sec) + Lock (0x1f) Quality= Good Signal= -34.42dBm C/N= 33.89dB UCB= 0 postBER= 0 preBER= 2.44x10^-3 PER= 0 + +.. [1] In this example, it records 10 seconds with all program ID's stored + at the music.ts file. + -The channel can be watched by playing the contents of the DVR interface, with -some player that recognizes the MPEG-TS format, such as *mplayer* or *vlc*. +The channel can be watched by playing the contents of the stream with some +player that recognizes the MPEG-TS format, such as ``mplayer`` or ``vlc``. By playing the contents of the stream one can visually inspect the workings of -vidtv, e.g.:: +vidtv, e.g., to play a recorded TS file with:: + + $ mplayer music.ts + +or, alternatively, running this command on one terminal:: + + $ dvbv5-zap -c dvb_channel.conf "beethoven" -P -r & + +And, on a second terminal, playing the contents from DVR interface with:: $ mplayer /dev/dvb/adapter0/dvr0 @@ -423,3 +484,30 @@ A nice addition is to simulate some noise when the signal quality is bad by: - Updating the error statistics accordingly (e.g. BER, etc). - Simulating some noise in the encoded data. + +Functions and structs used within vidtv +--------------------------------------- + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_bridge.h + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_channel.h + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_demod.h + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_encoder.h + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_mux.h + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_pes.h + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_psi.h + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_s302m.h + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_ts.h + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_tuner.h + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_common.c + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_tuner.c diff --git a/Documentation/driver-api/media/dtv-frontend.rst b/Documentation/driver-api/media/dtv-frontend.rst index 91f77fe58e83..ea43cdb5b0e4 100644 --- a/Documentation/driver-api/media/dtv-frontend.rst +++ b/Documentation/driver-api/media/dtv-frontend.rst @@ -244,7 +244,7 @@ Carrier Signal to Noise ratio (:ref:`DTV-STAT-CNR`) Having it available after inner FEC is more common. Bit counts post-FEC (:ref:`DTV-STAT-POST-ERROR-BIT-COUNT` and :ref:`DTV-STAT-POST-TOTAL-BIT-COUNT`) - - Those counters measure the number of bits and bit errors errors after + - Those counters measure the number of bits and bit errors after the forward error correction (FEC) on the inner coding block (after Viterbi, LDPC or other inner code). @@ -253,7 +253,7 @@ Bit counts post-FEC (:ref:`DTV-STAT-POST-ERROR-BIT-COUNT` and :ref:`DTV-STAT-POS see :c:type:`fe_status`). Bit counts pre-FEC (:ref:`DTV-STAT-PRE-ERROR-BIT-COUNT` and :ref:`DTV-STAT-PRE-TOTAL-BIT-COUNT`) - - Those counters measure the number of bits and bit errors errors before + - Those counters measure the number of bits and bit errors before the forward error correction (FEC) on the inner coding block (before Viterbi, LDPC or other inner code). @@ -263,7 +263,7 @@ Bit counts pre-FEC (:ref:`DTV-STAT-PRE-ERROR-BIT-COUNT` and :ref:`DTV-STAT-PRE-T after ``FE_HAS_VITERBI``, see :c:type:`fe_status`). Block counts (:ref:`DTV-STAT-ERROR-BLOCK-COUNT` and :ref:`DTV-STAT-TOTAL-BLOCK-COUNT`) - - Those counters measure the number of blocks and block errors errors after + - Those counters measure the number of blocks and block errors after the forward error correction (FEC) on the inner coding block (before Viterbi, LDPC or other inner code). diff --git a/Documentation/driver-api/media/v4l2-controls.rst b/Documentation/driver-api/media/v4l2-controls.rst index 77f42ea3bac7..b2e91804829b 100644 --- a/Documentation/driver-api/media/v4l2-controls.rst +++ b/Documentation/driver-api/media/v4l2-controls.rst @@ -335,7 +335,7 @@ current and new values: union v4l2_ctrl_ptr p_new; union v4l2_ctrl_ptr p_cur; -If the control has a simple s32 type type, then: +If the control has a simple s32 type, then: .. code-block:: c @@ -349,7 +349,7 @@ Within the control ops you can freely use these. The val and cur.val speak for themselves. The p_char pointers point to character buffers of length ctrl->maximum + 1, and are always 0-terminated. -Unless the control is marked volatile the p_cur field points to the the +Unless the control is marked volatile the p_cur field points to the current cached control value. When you create a new control this value is made identical to the default value. After calling v4l2_ctrl_handler_setup() this value is passed to the hardware. It is generally a good idea to call this diff --git a/Documentation/driver-api/media/v4l2-dev.rst b/Documentation/driver-api/media/v4l2-dev.rst index 666330af31ed..99e3b5fa7444 100644 --- a/Documentation/driver-api/media/v4l2-dev.rst +++ b/Documentation/driver-api/media/v4l2-dev.rst @@ -212,7 +212,7 @@ types exist: ========================== ==================== ============================== The last argument gives you a certain amount of control over the device -device node number used (i.e. the X in ``videoX``). Normally you will pass -1 +node number used (i.e. the X in ``videoX``). Normally you will pass -1 to let the v4l2 framework pick the first free number. But sometimes users want to select a specific node number. It is common that drivers allow the user to select a specific device node number through a driver module diff --git a/Documentation/filesystems/fsverity.rst b/Documentation/filesystems/fsverity.rst index 895e9711ed88..e0204a23e997 100644 --- a/Documentation/filesystems/fsverity.rst +++ b/Documentation/filesystems/fsverity.rst @@ -27,9 +27,9 @@ automatically verified against the file's Merkle tree. Reads of any corrupted data, including mmap reads, will fail. Userspace can use another ioctl to retrieve the root hash (actually -the "file measurement", which is a hash that includes the root hash) -that fs-verity is enforcing for the file. This ioctl executes in -constant time, regardless of the file size. +the "fs-verity file digest", which is a hash that includes the Merkle +tree root hash) that fs-verity is enforcing for the file. This ioctl +executes in constant time, regardless of the file size. fs-verity is essentially a way to hash a file in constant time, subject to the caveat that reads which would violate the hash will @@ -177,9 +177,10 @@ FS_IOC_ENABLE_VERITY can fail with the following errors: FS_IOC_MEASURE_VERITY --------------------- -The FS_IOC_MEASURE_VERITY ioctl retrieves the measurement of a verity -file. The file measurement is a digest that cryptographically -identifies the file contents that are being enforced on reads. +The FS_IOC_MEASURE_VERITY ioctl retrieves the digest of a verity file. +The fs-verity file digest is a cryptographic digest that identifies +the file contents that are being enforced on reads; it is computed via +a Merkle tree and is different from a traditional full-file digest. This ioctl takes in a pointer to a variable-length structure:: @@ -197,7 +198,7 @@ On success, 0 is returned and the kernel fills in the structure as follows: - ``digest_algorithm`` will be the hash algorithm used for the file - measurement. It will match ``fsverity_enable_arg::hash_algorithm``. + digest. It will match ``fsverity_enable_arg::hash_algorithm``. - ``digest_size`` will be the size of the digest in bytes, e.g. 32 for SHA-256. (This can be redundant with ``digest_algorithm``.) - ``digest`` will be the actual bytes of the digest. @@ -257,25 +258,24 @@ non-verity one, with the following exceptions: with EIO (for read()) or SIGBUS (for mmap() reads). - If the sysctl "fs.verity.require_signatures" is set to 1 and the - file's verity measurement is not signed by a key in the fs-verity - keyring, then opening the file will fail. See `Built-in signature - verification`_. + file is not signed by a key in the fs-verity keyring, then opening + the file will fail. See `Built-in signature verification`_. Direct access to the Merkle tree is not supported. Therefore, if a verity file is copied, or is backed up and restored, then it will lose its "verity"-ness. fs-verity is primarily meant for files like executables that are managed by a package manager. -File measurement computation -============================ +File digest computation +======================= This section describes how fs-verity hashes the file contents using a -Merkle tree to produce the "file measurement" which cryptographically -identifies the file contents. This algorithm is the same for all -filesystems that support fs-verity. +Merkle tree to produce the digest which cryptographically identifies +the file contents. This algorithm is the same for all filesystems +that support fs-verity. Userspace only needs to be aware of this algorithm if it needs to -compute the file measurement itself, e.g. in order to sign the file. +compute fs-verity file digests itself, e.g. in order to sign files. .. _fsverity_merkle_tree: @@ -325,26 +325,22 @@ can't a distinguish a large file from a small second file whose data is exactly the top-level hash block of the first file. Ambiguities also arise from the convention of padding to the next block boundary. -To solve this problem, the verity file measurement is actually -computed as a hash of the following structure, which contains the -Merkle tree root hash as well as other fields such as the file size:: +To solve this problem, the fs-verity file digest is actually computed +as a hash of the following structure, which contains the Merkle tree +root hash as well as other fields such as the file size:: struct fsverity_descriptor { __u8 version; /* must be 1 */ __u8 hash_algorithm; /* Merkle tree hash algorithm */ __u8 log_blocksize; /* log2 of size of data and tree blocks */ __u8 salt_size; /* size of salt in bytes; 0 if none */ - __le32 sig_size; /* must be 0 */ + __le32 __reserved_0x04; /* must be 0 */ __le64 data_size; /* size of file the Merkle tree is built over */ __u8 root_hash[64]; /* Merkle tree root hash */ __u8 salt[32]; /* salt prepended to each hashed block */ __u8 __reserved[144]; /* must be 0's */ }; -Note that the ``sig_size`` field must be set to 0 for the purpose of -computing the file measurement, even if a signature was provided (or -will be provided) to `FS_IOC_ENABLE_VERITY`_. - Built-in signature verification =============================== @@ -359,20 +355,20 @@ kernel. Specifically, it adds support for: certificates from being added. 2. `FS_IOC_ENABLE_VERITY`_ accepts a pointer to a PKCS#7 formatted - detached signature in DER format of the file measurement. On - success, this signature is persisted alongside the Merkle tree. + detached signature in DER format of the file's fs-verity digest. + On success, this signature is persisted alongside the Merkle tree. Then, any time the file is opened, the kernel will verify the - file's actual measurement against this signature, using the - certificates in the ".fs-verity" keyring. + file's actual digest against this signature, using the certificates + in the ".fs-verity" keyring. 3. A new sysctl "fs.verity.require_signatures" is made available. When set to 1, the kernel requires that all verity files have a - correctly signed file measurement as described in (2). + correctly signed digest as described in (2). -File measurements must be signed in the following format, which is -similar to the structure used by `FS_IOC_MEASURE_VERITY`_:: +fs-verity file digests must be signed in the following format, which +is similar to the structure used by `FS_IOC_MEASURE_VERITY`_:: - struct fsverity_signed_digest { + struct fsverity_formatted_digest { char magic[8]; /* must be "FSVerity" */ __le16 digest_algorithm; __le16 digest_size; @@ -421,8 +417,8 @@ can only be set by `FS_IOC_ENABLE_VERITY`_, and it cannot be cleared. ext4 also supports encryption, which can be used simultaneously with fs-verity. In this case, the plaintext data is verified rather than -the ciphertext. This is necessary in order to make the file -measurement meaningful, since every file is encrypted differently. +the ciphertext. This is necessary in order to make the fs-verity file +digest meaningful, since every file is encrypted differently. ext4 stores the verity metadata (Merkle tree and fsverity_descriptor) past the end of the file, starting at the first 64K boundary beyond @@ -592,8 +588,8 @@ weren't already directly answered in other parts of this document. :Q: Isn't fs-verity useless because the attacker can just modify the hashes in the Merkle tree, which is stored on-disk? :A: To verify the authenticity of an fs-verity file you must verify - the authenticity of the "file measurement", which is basically the - root hash of the Merkle tree. See `Use cases`_. + the authenticity of the "fs-verity file digest", which + incorporates the root hash of the Merkle tree. See `Use cases`_. :Q: Isn't fs-verity useless because the attacker can just replace a verity file with a non-verity one? diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst index 9abee1589c1e..21be6deadc12 100644 --- a/Documentation/gpu/drm-mm.rst +++ b/Documentation/gpu/drm-mm.rst @@ -182,11 +182,11 @@ acquired and release by calling drm_gem_object_get() and drm_gem_object_put() respectively. When the last reference to a GEM object is released the GEM core calls -the :c:type:`struct drm_driver <drm_driver>` gem_free_object_unlocked +the :c:type:`struct drm_gem_object_funcs <gem_object_funcs>` free operation. That operation is mandatory for GEM-enabled drivers and must free the GEM object and all associated resources. -void (\*gem_free_object) (struct drm_gem_object \*obj); Drivers are +void (\*free) (struct drm_gem_object \*obj); Drivers are responsible for freeing all GEM object resources. This includes the resources created by the GEM core, which need to be released with drm_gem_object_release(). diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst index cff1f154b473..20868f3d0123 100644 --- a/Documentation/gpu/i915.rst +++ b/Documentation/gpu/i915.rst @@ -118,6 +118,12 @@ Atomic Plane Helpers .. kernel-doc:: drivers/gpu/drm/i915/display/intel_atomic_plane.c :internal: +Asynchronous Page Flip +---------------------- + +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_display.c + :doc: asynchronous flip implementation + Output Probing -------------- diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index b0ea17da8ff6..009d8e6c7e3c 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -105,6 +105,10 @@ converted over to the new infrastructure. One issue with the helpers is that they require that drivers handle completion events for atomic commits correctly. But fixing these bugs is good anyway. +Somewhat related is the legacy_cursor_update hack, which should be replaced with +the new atomic_async_check/commit functionality in the helpers in drivers that +still look at that flag. + Contact: Daniel Vetter, respective driver maintainers Level: Advanced @@ -149,7 +153,7 @@ have to keep track of that lock and either call ``unreference`` or ``unreference_locked`` depending upon context. Core GEM doesn't have a need for ``struct_mutex`` any more since kernel 4.8, -and there's a ``gem_free_object_unlocked`` callback for any drivers which are +and there's a GEM object ``free`` callback for any drivers which are entirely ``struct_mutex`` free. For drivers that need ``struct_mutex`` it should be replaced with a driver- @@ -197,13 +201,28 @@ Convert drivers to use drm_fbdev_generic_setup() ------------------------------------------------ Most drivers can use drm_fbdev_generic_setup(). Driver have to implement -atomic modesetting and GEM vmap support. Current generic fbdev emulation -expects the framebuffer in system memory (or system-like memory). +atomic modesetting and GEM vmap support. Historically, generic fbdev emulation +expected the framebuffer in system memory or system-like memory. By employing +struct dma_buf_map, drivers with frambuffers in I/O memory can be supported +as well. Contact: Maintainer of the driver you plan to convert Level: Intermediate +Reimplement functions in drm_fbdev_fb_ops without fbdev +------------------------------------------------------- + +A number of callback functions in drm_fbdev_fb_ops could benefit from +being rewritten without dependencies on the fbdev module. Some of the +helpers could further benefit from using struct dma_buf_map instead of +raw pointers. + +Contact: Thomas Zimmermann <tzimmermann@suse.de>, Daniel Vetter + +Level: Advanced + + drm_framebuffer_funcs and drm_mode_config_funcs.fb_create cleanup ----------------------------------------------------------------- @@ -273,6 +292,27 @@ Contact: Daniel Vetter, Noralf Tronnes Level: Advanced +Garbage collect fbdev scrolling acceleration +-------------------------------------------- + +Scroll acceleration is disabled in fbcon by hard-wiring p->scrollmode = +SCROLL_REDRAW. There's a ton of code this will allow us to remove: + +- lots of code in fbcon.c + +- a bunch of the hooks in fbcon_ops, maybe the remaining hooks could be called + directly instead of the function table (with a switch on p->rotate) + +- fb_copyarea is unused after this, and can be deleted from all drivers + +Note that not all acceleration code can be deleted, since clearing and cursor +support is still accelerated, which might be good candidates for further +deletion projects. + +Contact: Daniel Vetter + +Level: Intermediate + idr_init_base() --------------- @@ -289,11 +329,8 @@ struct drm_gem_object_funcs --------------------------- GEM objects can now have a function table instead of having the callbacks on the -DRM driver struct. This is now the preferred way and drivers can be moved over. - -We also need a 2nd version of the CMA define that doesn't require the -vmapping to be present (different hook for prime importing). Plus this needs to -be rolled out to all drivers using their own implementations, too. +DRM driver struct. This is now the preferred way. Callbacks in drivers have been +converted, except for struct drm_driver.gem_prime_mmap. Level: Intermediate @@ -449,6 +486,24 @@ Contact: Ville Syrjälä, Daniel Vetter Level: Intermediate +Use struct dma_buf_map throughout codebase +------------------------------------------ + +Pointers to shared device memory are stored in struct dma_buf_map. Each +instance knows whether it refers to system or I/O memory. Most of the DRM-wide +interface have been converted to use struct dma_buf_map, but implementations +often still use raw pointers. + +The task is to use struct dma_buf_map where it makes sense. + +* Memory managers should use struct dma_buf_map for dma-buf-imported buffers. +* TTM might benefit from using struct dma_buf_map internally. +* Framebuffer copying and blitting helpers should operate on struct dma_buf_map. + +Contact: Thomas Zimmermann <tzimmermann@suse.de>, Christian König, Daniel Vetter + +Level: Intermediate + Core refactorings ================= @@ -518,9 +573,6 @@ There's a bunch of issues with it: this (together with the drm_minor->drm_device move) would allow us to remove debugfs_init. -- Drop the return code and error checking from all debugfs functions. Greg KH is - working on this already. - Contact: Daniel Vetter Level: Intermediate diff --git a/Documentation/gpu/vkms.rst b/Documentation/gpu/vkms.rst index 61586fc861bb..13bab1d93bb3 100644 --- a/Documentation/gpu/vkms.rst +++ b/Documentation/gpu/vkms.rst @@ -10,36 +10,24 @@ TODO ==== -CRC API Improvements --------------------- - -- Optimize CRC computation ``compute_crc()`` and plane blending ``blend()`` - -- Use the alpha value to blend vaddr_src with vaddr_dst instead of - overwriting it in ``blend()``. - -- Add igt test to check cleared alpha value for XRGB plane format. - -- Add igt test to check extreme alpha values i.e. fully opaque and fully - transparent (intermediate values are affected by hw-specific rounding modes). - -Runtime Configuration ---------------------- - -We want to be able to reconfigure vkms instance without having to reload the -module. Use/Test-cases: - -- Hotplug/hotremove connectors on the fly (to be able to test DP MST handling of - compositors). +If you want to do any of the items listed below, please share your interest +with VKMS maintainers. -- Configure planes/crtcs/connectors (we'd need some code to have more than 1 of - them first). +IGT better support +------------------ -- Change output configuration: Plug/unplug screens, change EDID, allow changing - the refresh rate. +- Investigate: (1) test cases on kms_plane that are failing due to timeout on + capturing CRC; (2) when running kms_flip test cases in sequence, some + successful individual test cases are failing randomly. -The currently proposed solution is to expose vkms configuration through -configfs. All existing module options should be supported through configfs too. +- VKMS already has support for vblanks simulated via hrtimers, which can be + tested with kms_flip test; in some way, we can say that VKMS already mimics + the real hardware vblank. However, we also have virtual hardware that does + not support vblank interrupt and completes page_flip events right away; in + this case, compositor developers may end up creating a busy loop on virtual + hardware. It would be useful to support Virtual Hardware behavior in VKMS + because this can help compositor developers to test their features in + multiple scenarios. Add Plane Features ------------------ @@ -55,34 +43,50 @@ There's lots of plane features we could add support for: - Additional buffer formats, especially YUV formats for video like NV12. Low/high bpp RGB formats would also be interesting. -- Async updates (currently only possible on cursor plane using the legacy cursor - api). +- Async updates (currently only possible on cursor plane using the legacy + cursor api). + +For all of these, we also want to review the igt test coverage and make sure +all relevant igt testcases work on vkms. + +Prime Buffer Sharing +-------------------- -For all of these, we also want to review the igt test coverage and make sure all -relevant igt testcases work on vkms. +- Syzbot report - WARNING in vkms_gem_free_object: + https://syzkaller.appspot.com/bug?extid=e7ad70d406e74d8fc9d0 + +Runtime Configuration +--------------------- + +We want to be able to reconfigure vkms instance without having to reload the +module. Use/Test-cases: + +- Hotplug/hotremove connectors on the fly (to be able to test DP MST handling + of compositors). + +- Configure planes/crtcs/connectors (we'd need some code to have more than 1 of + them first). + +- Change output configuration: Plug/unplug screens, change EDID, allow changing + the refresh rate. + +The currently proposed solution is to expose vkms configuration through +configfs. All existing module options should be supported through configfs +too. Writeback support ----------------- -Currently vkms only computes a CRC for each frame. Once we have additional plane -features, we could write back the entire composited frame, and expose it as: +- The writeback and CRC capture operations share the use of composer_enabled + boolean to ensure vblanks. Probably, when these operations work together, + composer_enabled needs to refcounting the composer state to proper work. -- Writeback connector. This is useful for testing compositors if you don't have - hardware with writeback support. +- Add support for cloned writeback outputs and related test cases using a + cloned output in the IGT kms_writeback. - As a v4l device. This is useful for debugging compositors on special vkms configurations, so that developers see what's really going on. -Prime Buffer Sharing --------------------- - -We already have vgem, which is a gem driver for testing rendering, similar to -how vkms is for testing the modeset side. Adding buffer sharing support to vkms -allows us to test them together, to test synchronization and lots of other -features. Also, this allows compositors to test whether they work correctly on -SoC chips, where the display and rendering is very often split between 2 -drivers. - Output Features --------------- @@ -93,7 +97,10 @@ Output Features - Add support for link status, so that compositors can validate their runtime fallbacks when e.g. a Display Port link goes bad. -- All the hotplug handling describe under "Runtime Configuration". +CRC API Improvements +-------------------- + +- Optimize CRC computation ``compute_crc()`` and plane blending ``blend()`` Atomic Check using eBPF ----------------------- diff --git a/Documentation/kbuild/llvm.rst b/Documentation/kbuild/llvm.rst index cf3ca236d2cc..21c847890d03 100644 --- a/Documentation/kbuild/llvm.rst +++ b/Documentation/kbuild/llvm.rst @@ -57,9 +57,8 @@ to enable them. :: They can be enabled individually. The full list of the parameters: :: make CC=clang LD=ld.lld AR=llvm-ar NM=llvm-nm STRIP=llvm-strip \ - OBJCOPY=llvm-objcopy OBJDUMP=llvm-objdump OBJSIZE=llvm-size \ - READELF=llvm-readelf HOSTCC=clang HOSTCXX=clang++ HOSTAR=llvm-ar \ - HOSTLD=ld.lld + OBJCOPY=llvm-objcopy OBJDUMP=llvm-objdump READELF=llvm-readelf \ + HOSTCC=clang HOSTCXX=clang++ HOSTAR=llvm-ar HOSTLD=ld.lld Currently, the integrated assembler is disabled by default. You can pass ``LLVM_IAS=1`` to enable it. diff --git a/Documentation/networking/netdev-FAQ.rst b/Documentation/networking/netdev-FAQ.rst index 21537766be4d..4b9ed5874d5a 100644 --- a/Documentation/networking/netdev-FAQ.rst +++ b/Documentation/networking/netdev-FAQ.rst @@ -254,6 +254,32 @@ you will have done run-time testing specific to your change, but at a minimum, your changes should survive an ``allyesconfig`` and an ``allmodconfig`` build without new warnings or failures. +Q: How do I post corresponding changes to user space components? +---------------------------------------------------------------- +A: User space code exercising kernel features should be posted +alongside kernel patches. This gives reviewers a chance to see +how any new interface is used and how well it works. + +When user space tools reside in the kernel repo itself all changes +should generally come as one series. If series becomes too large +or the user space project is not reviewed on netdev include a link +to a public repo where user space patches can be seen. + +In case user space tooling lives in a separate repository but is +reviewed on netdev (e.g. patches to `iproute2` tools) kernel and +user space patches should form separate series (threads) when posted +to the mailing list, e.g.:: + + [PATCH net-next 0/3] net: some feature cover letter + └─ [PATCH net-next 1/3] net: some feature prep + └─ [PATCH net-next 2/3] net: some feature do it + └─ [PATCH net-next 3/3] selftest: net: some feature + + [PATCH iproute2-next] ip: add support for some feature + +Posting as one thread is discouraged because it confuses patchwork +(as of patchwork 2.2.2). + Q: Any other tips to help ensure my net/net-next patch gets OK'd? ----------------------------------------------------------------- A: Attention to detail. Re-read your own work as if you were the diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst index 55a2d9b2ce33..a4c75a28c839 100644 --- a/Documentation/userspace-api/ioctl/ioctl-number.rst +++ b/Documentation/userspace-api/ioctl/ioctl-number.rst @@ -323,6 +323,7 @@ Code Seq# Include File Comments <mailto:tlewis@mindspring.com> 0xA3 90-9F linux/dtlk.h 0xA4 00-1F uapi/linux/tee.h Generic TEE subsystem +0xA4 00-1F uapi/asm/sgx.h <mailto:linux-sgx@vger.kernel.org> 0xAA 00-3F linux/uapi/linux/userfaultfd.h 0xAB 00-1F linux/nbd.h 0xAC 00-1F linux/raw.h diff --git a/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst b/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst index d3387b1fa7c5..663bdef8d6da 100644 --- a/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst +++ b/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst @@ -188,7 +188,7 @@ Available follower modes are: in combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`, otherwise the ``EINVAL`` error code will be returned. In 'monitor all' mode all messages this CEC device transmits and all messages it receives, including - directed messages for other CEC devices will be reported. This is + directed messages for other CEC devices, will be reported. This is very useful for debugging, but not all devices support this. This mode requires that the :ref:`CEC_CAP_MONITOR_ALL <CEC-CAP-MONITOR-ALL>` capability is set, otherwise the ``EINVAL`` error code is returned. This is only allowed if diff --git a/Documentation/userspace-api/media/dvb/audio.rst b/Documentation/userspace-api/media/dvb/audio.rst index 071abac9d52d..eaae5675a47d 100644 --- a/Documentation/userspace-api/media/dvb/audio.rst +++ b/Documentation/userspace-api/media/dvb/audio.rst @@ -8,7 +8,7 @@ Digital TV Audio Device The Digital TV audio device controls the MPEG2 audio decoder of the Digital TV hardware. It can be accessed through ``/dev/dvb/adapter?/audio?``. Data -types and and ioctl definitions can be accessed by including +types and ioctl definitions can be accessed by including ``linux/dvb/audio.h`` in your application. Please note that some Digital TV cards don’t have their own MPEG decoder, which diff --git a/Documentation/userspace-api/media/dvb/ca.rst b/Documentation/userspace-api/media/dvb/ca.rst index 6f6821e322a9..0dc00e5e4a8c 100644 --- a/Documentation/userspace-api/media/dvb/ca.rst +++ b/Documentation/userspace-api/media/dvb/ca.rst @@ -7,7 +7,7 @@ Digital TV CA Device #################### The Digital TV CA device controls the conditional access hardware. It -can be accessed through ``/dev/dvb/adapter?/ca?``. Data types and and ioctl +can be accessed through ``/dev/dvb/adapter?/ca?``. Data types and ioctl definitions can be accessed by including ``linux/dvb/ca.h`` in your application. diff --git a/Documentation/userspace-api/media/dvb/demux.rst b/Documentation/userspace-api/media/dvb/demux.rst index 364ef48472ee..ef05abcf14d1 100644 --- a/Documentation/userspace-api/media/dvb/demux.rst +++ b/Documentation/userspace-api/media/dvb/demux.rst @@ -11,7 +11,7 @@ digital TV. If the driver and hardware supports, those filters are implemented at the hardware. Otherwise, the Kernel provides a software emulation. -It can be accessed through ``/dev/adapter?/demux?``. Data types and and +It can be accessed through ``/dev/adapter?/demux?``. Data types and ioctl definitions can be accessed by including ``linux/dvb/dmx.h`` in your application. diff --git a/Documentation/userspace-api/media/dvb/dmx-qbuf.rst b/Documentation/userspace-api/media/dvb/dmx-qbuf.rst index 17e70143c1b0..1a13a33834db 100644 --- a/Documentation/userspace-api/media/dvb/dmx-qbuf.rst +++ b/Documentation/userspace-api/media/dvb/dmx-qbuf.rst @@ -50,7 +50,7 @@ by a :ref:`DMX_QUERYBUF` ioctl will do as well. When ``DMX_QBUF`` is called with a pointer to this structure, it locks the memory pages of the buffer in physical memory, so they cannot be swapped out to disk. Buffers remain locked until dequeued, until the -the device is closed. +device is closed. Applications call the ``DMX_DQBUF`` ioctl to dequeue a filled (capturing) buffer from the driver's outgoing queue. diff --git a/Documentation/userspace-api/media/dvb/net.rst b/Documentation/userspace-api/media/dvb/net.rst index 33368f5150c5..020a023d3b61 100644 --- a/Documentation/userspace-api/media/dvb/net.rst +++ b/Documentation/userspace-api/media/dvb/net.rst @@ -23,7 +23,7 @@ types that are present on the transport stream. This is done through virtual ``dvb?_?`` network interfaces, and will be controlled/routed via the standard ip tools (like ip, route, netstat, ifconfig, etc). -Data types and and ioctl definitions are defined via ``linux/dvb/net.h`` +Data types and ioctl definitions are defined via ``linux/dvb/net.h`` header. diff --git a/Documentation/userspace-api/media/dvb/video.rst b/Documentation/userspace-api/media/dvb/video.rst index 3ed1bbfb93c3..38a8d39a1d25 100644 --- a/Documentation/userspace-api/media/dvb/video.rst +++ b/Documentation/userspace-api/media/dvb/video.rst @@ -8,7 +8,7 @@ Digital TV Video Device The Digital TV video device controls the MPEG2 video decoder of the Digital TV hardware. It can be accessed through **/dev/dvb/adapter0/video0**. Data -types and and ioctl definitions can be accessed by including +types and ioctl definitions can be accessed by including **linux/dvb/video.h** in your application. Note that the Digital TV video device only controls decoding of the MPEG video diff --git a/Documentation/userspace-api/media/lirc.h.rst.exceptions b/Documentation/userspace-api/media/lirc.h.rst.exceptions index ac768d769113..e74b73cd0e9e 100644 --- a/Documentation/userspace-api/media/lirc.h.rst.exceptions +++ b/Documentation/userspace-api/media/lirc.h.rst.exceptions @@ -64,6 +64,7 @@ ignore symbol RC_PROTO_RCMM12 ignore symbol RC_PROTO_RCMM24 ignore symbol RC_PROTO_RCMM32 ignore symbol RC_PROTO_XBOX_DVD +ignore symbol RC_PROTO_MAX # Undocumented macros diff --git a/Documentation/userspace-api/media/rc/keytable.c.rst b/Documentation/userspace-api/media/rc/keytable.c.rst index 0b50cfaf2d86..243e02d2611f 100644 --- a/Documentation/userspace-api/media/rc/keytable.c.rst +++ b/Documentation/userspace-api/media/rc/keytable.c.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later file: uapi/v4l/keytable.c ========================= diff --git a/Documentation/userspace-api/media/rc/lirc-dev-intro.rst b/Documentation/userspace-api/media/rc/lirc-dev-intro.rst index 167b354bf051..c88973732282 100644 --- a/Documentation/userspace-api/media/rc/lirc-dev-intro.rst +++ b/Documentation/userspace-api/media/rc/lirc-dev-intro.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. _lirc_dev_intro: @@ -57,12 +57,12 @@ on the following table. This mode is for both sending and receiving IR. - For transmitting (aka sending), create a ``struct lirc_scancode`` with + For transmitting (aka sending), create a struct lirc_scancode with the desired scancode set in the ``scancode`` member, :c:type:`rc_proto` set to the :ref:`IR protocol <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. + 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 @@ -136,6 +136,13 @@ on the following table. This mode is used only for IR send. +************************************* +Data types used by LIRC_MODE_SCANCODE +************************************* + +.. kernel-doc:: include/uapi/linux/lirc.h + :identifiers: lirc_scancode rc_proto + ******************** BPF based IR decoder ******************** diff --git a/Documentation/userspace-api/media/rc/lirc-dev.rst b/Documentation/userspace-api/media/rc/lirc-dev.rst index 5510dc02a822..978f86d30fae 100644 --- a/Documentation/userspace-api/media/rc/lirc-dev.rst +++ b/Documentation/userspace-api/media/rc/lirc-dev.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. _lirc_dev: diff --git a/Documentation/userspace-api/media/rc/lirc-func.rst b/Documentation/userspace-api/media/rc/lirc-func.rst index 420a3dbf0d6b..793f295d3ac9 100644 --- a/Documentation/userspace-api/media/rc/lirc-func.rst +++ b/Documentation/userspace-api/media/rc/lirc-func.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. _lirc_func: diff --git a/Documentation/userspace-api/media/rc/lirc-get-features.rst b/Documentation/userspace-api/media/rc/lirc-get-features.rst index 66a243dbd437..4bf25860f932 100644 --- a/Documentation/userspace-api/media/rc/lirc-get-features.rst +++ b/Documentation/userspace-api/media/rc/lirc-get-features.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc_get_features: diff --git a/Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst b/Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst index 188478ed1233..628fe31792b2 100644 --- a/Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst +++ b/Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc_get_rec_mode: diff --git a/Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst b/Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst index e29445c5ce16..4dfa9c23634b 100644 --- a/Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst +++ b/Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc_get_rec_resolution: diff --git a/Documentation/userspace-api/media/rc/lirc-get-send-mode.rst b/Documentation/userspace-api/media/rc/lirc-get-send-mode.rst index 77472fb5608a..637871805be6 100644 --- a/Documentation/userspace-api/media/rc/lirc-get-send-mode.rst +++ b/Documentation/userspace-api/media/rc/lirc-get-send-mode.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc_get_send_mode: diff --git a/Documentation/userspace-api/media/rc/lirc-get-timeout.rst b/Documentation/userspace-api/media/rc/lirc-get-timeout.rst index f5f3e06d6206..597c3282ae12 100644 --- a/Documentation/userspace-api/media/rc/lirc-get-timeout.rst +++ b/Documentation/userspace-api/media/rc/lirc-get-timeout.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc_get_min_timeout: diff --git a/Documentation/userspace-api/media/rc/lirc-header.rst b/Documentation/userspace-api/media/rc/lirc-header.rst index 8bd0acc9913a..54cb40b8a065 100644 --- a/Documentation/userspace-api/media/rc/lirc-header.rst +++ b/Documentation/userspace-api/media/rc/lirc-header.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. _lirc_header: diff --git a/Documentation/userspace-api/media/rc/lirc-read.rst b/Documentation/userspace-api/media/rc/lirc-read.rst index d589560214f4..ce34318698b7 100644 --- a/Documentation/userspace-api/media/rc/lirc-read.rst +++ b/Documentation/userspace-api/media/rc/lirc-read.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc-read: diff --git a/Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst b/Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst index 9bf9811a905a..04ced1aa664b 100644 --- a/Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst +++ b/Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc_set_measure_carrier_mode: diff --git a/Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst index 530bc223930a..7512dc86b03a 100644 --- a/Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst +++ b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc_set_rec_carrier_range: diff --git a/Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst index 28c928f1cc14..60e321446ea7 100644 --- a/Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst +++ b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc_set_rec_carrier: diff --git a/Documentation/userspace-api/media/rc/lirc-set-rec-timeout-reports.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-timeout-reports.rst index 83e7155c5796..aebe81012939 100644 --- a/Documentation/userspace-api/media/rc/lirc-set-rec-timeout-reports.rst +++ b/Documentation/userspace-api/media/rc/lirc-set-rec-timeout-reports.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc_set_rec_timeout_reports: diff --git a/Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst index 8f3f9adf54ab..bf9fb2cc61c3 100644 --- a/Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst +++ b/Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc_set_rec_timeout: diff --git a/Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst b/Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst index e3810ba58746..a003f9447553 100644 --- a/Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst +++ b/Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc_set_send_carrier: diff --git a/Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst b/Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst index 52a072529af9..2979752acbcd 100644 --- a/Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst +++ b/Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc_set_send_duty_cycle: diff --git a/Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst b/Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst index 68f4cc2e3ae3..38acbcd6e91c 100644 --- a/Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst +++ b/Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc_set_transmitter_mask: diff --git a/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst b/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst index be5321c4a91f..c9d578e291b8 100644 --- a/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst +++ b/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc_set_wideband_receiver: diff --git a/Documentation/userspace-api/media/rc/lirc-write.rst b/Documentation/userspace-api/media/rc/lirc-write.rst index c1c3230d4fd6..970a8b3fa1ca 100644 --- a/Documentation/userspace-api/media/rc/lirc-write.rst +++ b/Documentation/userspace-api/media/rc/lirc-write.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. c:namespace:: RC .. _lirc-write: diff --git a/Documentation/userspace-api/media/rc/rc-intro.rst b/Documentation/userspace-api/media/rc/rc-intro.rst index 1338478e2bd4..2ba62cde2369 100644 --- a/Documentation/userspace-api/media/rc/rc-intro.rst +++ b/Documentation/userspace-api/media/rc/rc-intro.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. _Remote_controllers_Intro: diff --git a/Documentation/userspace-api/media/rc/rc-protos.rst b/Documentation/userspace-api/media/rc/rc-protos.rst index 2e290584a210..a2eab3b45647 100644 --- a/Documentation/userspace-api/media/rc/rc-protos.rst +++ b/Documentation/userspace-api/media/rc/rc-protos.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. _Remote_controllers_Protocols: diff --git a/Documentation/userspace-api/media/rc/rc-sysfs-nodes.rst b/Documentation/userspace-api/media/rc/rc-sysfs-nodes.rst index 43c442696438..34d6a0a1f4d3 100644 --- a/Documentation/userspace-api/media/rc/rc-sysfs-nodes.rst +++ b/Documentation/userspace-api/media/rc/rc-sysfs-nodes.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. _remote_controllers_sysfs_nodes: diff --git a/Documentation/userspace-api/media/rc/rc-table-change.rst b/Documentation/userspace-api/media/rc/rc-table-change.rst index 61c77b080ae8..d7de8a56ddfe 100644 --- a/Documentation/userspace-api/media/rc/rc-table-change.rst +++ b/Documentation/userspace-api/media/rc/rc-table-change.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. _Remote_controllers_table_change: diff --git a/Documentation/userspace-api/media/rc/rc-tables.rst b/Documentation/userspace-api/media/rc/rc-tables.rst index 8dc11657fc23..aafbfda1f401 100644 --- a/Documentation/userspace-api/media/rc/rc-tables.rst +++ b/Documentation/userspace-api/media/rc/rc-tables.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. _Remote_controllers_tables: diff --git a/Documentation/userspace-api/media/rc/remote_controllers.rst b/Documentation/userspace-api/media/rc/remote_controllers.rst index 2d9078accb35..f89291838637 100644 --- a/Documentation/userspace-api/media/rc/remote_controllers.rst +++ b/Documentation/userspace-api/media/rc/remote_controllers.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later .. include:: <isonum.txt> .. _remote_controllers: diff --git a/Documentation/userspace-api/media/v4l/biblio.rst b/Documentation/userspace-api/media/v4l/biblio.rst index 7869b6f6ff72..64d241daf63c 100644 --- a/Documentation/userspace-api/media/v4l/biblio.rst +++ b/Documentation/userspace-api/media/v4l/biblio.rst @@ -270,7 +270,17 @@ EBU Tech 3213 ============= -:title: E.B.U. Standard for Chromaticity Tolerances for Studio Monitors" +:title: E.B.U. Standard for Chromaticity Tolerances for Studio Monitors + +:author: European Broadcast Union (http://www.ebu.ch) + +.. _tech3321: + +EBU Tech 3321 +============= + + +:title: E.B.U. guidelines for Consumer Flat Panel Displays (FPDs) :author: European Broadcast Union (http://www.ebu.ch) diff --git a/Documentation/userspace-api/media/v4l/buffer.rst b/Documentation/userspace-api/media/v4l/buffer.rst index 7dbdfbb4a0a9..1b0fdc160533 100644 --- a/Documentation/userspace-api/media/v4l/buffer.rst +++ b/Documentation/userspace-api/media/v4l/buffer.rst @@ -604,7 +604,7 @@ Buffer Flags :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Due to hardware limitations, the last buffer may be empty. In this case the driver will set the ``bytesused`` field to 0, regardless of - the format. Any Any subsequent call to the + the format. Any subsequent call to the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore, but return an ``EPIPE`` error code. * .. _`V4L2-BUF-FLAG-REQUEST-FD`: diff --git a/Documentation/userspace-api/media/v4l/colorspaces-details.rst b/Documentation/userspace-api/media/v4l/colorspaces-details.rst index 014e7c9fc655..126f66482a0d 100644 --- a/Documentation/userspace-api/media/v4l/colorspaces-details.rst +++ b/Documentation/userspace-api/media/v4l/colorspaces-details.rst @@ -674,8 +674,9 @@ Colorspace EBU Tech. 3213 (V4L2_COLORSPACE_470_SYSTEM_BG) ========================================================= The :ref:`tech3213` standard defines the colorspace used by PAL/SECAM -in 1975. In practice this colorspace is obsolete and SMPTE 170M should -be used instead. The default transfer function is +in 1975. Note that this colorspace is not supported by the HDMI interface. +Instead :ref:`tech3321` recommends that Rec. 709 is used instead for HDMI. +The default transfer function is ``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is ``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and the white reference diff --git a/Documentation/userspace-api/media/v4l/common.rst b/Documentation/userspace-api/media/v4l/common.rst index d84aeb703165..8c263c5a85d8 100644 --- a/Documentation/userspace-api/media/v4l/common.rst +++ b/Documentation/userspace-api/media/v4l/common.rst @@ -44,6 +44,7 @@ applicable to all devices. ext-ctrls-image-source ext-ctrls-image-process ext-ctrls-codec + ext-ctrls-codec-stateless ext-ctrls-jpeg ext-ctrls-dv ext-ctrls-rf-tuner diff --git a/Documentation/userspace-api/media/v4l/dev-mem2mem.rst b/Documentation/userspace-api/media/v4l/dev-mem2mem.rst index d8db46886555..7041bb3d5b8d 100644 --- a/Documentation/userspace-api/media/v4l/dev-mem2mem.rst +++ b/Documentation/userspace-api/media/v4l/dev-mem2mem.rst @@ -32,7 +32,7 @@ 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`. More details on how to use codec memory-to-memory +See :ref:`codec-controls`. More details on how to use codec memory-to-memory devices are given in the following sections. .. toctree:: diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst new file mode 100644 index 000000000000..01e3b1a3fb99 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst @@ -0,0 +1,793 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _codec-stateless-controls: + +********************************* +Stateless Codec Control Reference +********************************* + +The Stateless Codec control class is intended to support +stateless decoder and encoders (i.e. hardware accelerators). + +These drivers are typically supported by the :ref:`stateless_decoder`, +and deal with parsed pixel formats such as V4L2_PIX_FMT_H264_SLICE. + +Stateless Codec Control ID +========================== + +.. _codec-stateless-control-id: + +``V4L2_CID_CODEC_STATELESS_CLASS (class)`` + The Stateless Codec class descriptor. + +.. _v4l2-codec-stateless-h264: + +``V4L2_CID_STATELESS_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. + +.. 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_STATELESS_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. + +.. 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_SCALING_MATRIX_PRESENT`` + - 0x00000080 + - Indicates that ``V4L2_CID_STATELESS_H264_SCALING_MATRIX`` + must be used for this picture. + +``V4L2_CID_STATELESS_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. + +.. 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]`` + - Scaling matrix after applying the inverse scanning process. + Expected list order is Intra Y, Intra Cb, Intra Cr, Inter Y, + Inter Cb, Inter Cr. The values on each scaling list are + expected in raster scan order. + * - __u8 + - ``scaling_list_8x8[6][64]`` + - Scaling matrix after applying the inverse scanning process. + Expected list order is Intra Y, Inter Y, Intra Cb, Inter Cb, + Intra Cr, Inter Cr. The values on each scaling list are + expected in raster scan order. + +``V4L2_CID_STATELESS_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. + +.. 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 + - ``header_bit_size`` + - Offset in bits to slice_data() from the beginning of this slice. + * - __u32 + - ``first_mb_in_slice`` + - + * - __u8 + - ``slice_type`` + - + * - __u8 + - ``colour_plane_id`` + - + * - __u8 + - ``redundant_pic_cnt`` + - + * - __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`` + - If num_ref_idx_active_override_flag is not set, this field must be + set to the value of num_ref_idx_l0_default_active_minus1. + * - __u8 + - ``num_ref_idx_l1_active_minus1`` + - If num_ref_idx_active_override_flag is not set, this field must be + set to the value of num_ref_idx_l1_default_active_minus1. + * - __u8 + - ``reserved`` + - Applications and drivers must set this to zero. + * - struct :c:type:`v4l2_h264_reference` + - ``ref_pic_list0[32]`` + - Reference picture list after applying the per-slice modifications + * - struct :c:type:`v4l2_h264_reference` + - ``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_DIRECT_SPATIAL_MV_PRED`` + - 0x00000001 + - + * - ``V4L2_H264_SLICE_FLAG_SP_FOR_SWITCH`` + - 0x00000002 + - + +``V4L2_CID_STATELESS_H264_PRED_WEIGHTS (struct)`` + Prediction weight table defined according to :ref:`h264`, + section 7.4.3.2 "Prediction Weight Table Semantics". + The prediction weight table must be passed by applications + under the conditions explained in section 7.3.3 "Slice header + syntax". + +.. c:type:: v4l2_ctrl_h264_pred_weights + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_h264_pred_weights + :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]`` + - + +``Picture Reference`` + +.. c:type:: v4l2_h264_reference + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_h264_reference + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``fields`` + - Specifies how the picture is referenced. See :ref:`Reference Fields <h264_ref_fields>` + * - __u8 + - ``index`` + - Index into the :c:type:`v4l2_ctrl_h264_decode_params`.dpb array. + +.. _h264_ref_fields: + +``Reference Fields`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_TOP_FIELD_REF`` + - 0x1 + - The top field in field pair is used for short-term reference. + * - ``V4L2_H264_BOTTOM_FIELD_REF`` + - 0x2 + - The bottom field in field pair is used for short-term reference. + * - ``V4L2_H264_FRAME_REF`` + - 0x3 + - The frame (or the top/bottom fields, if it's a field pair) + is used for short-term reference. + +``V4L2_CID_STATELESS_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. + +.. 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 + - ``nal_ref_idc`` + - NAL reference ID value coming from the NAL Unit header + * - __u16 + - ``frame_num`` + - + * - __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 + * - __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`` + - + * - __u32 + - ``dec_ref_pic_marking_bit_size`` + - Size in bits of the dec_ref_pic_marking() syntax element. + * - __u32 + - ``pic_order_cnt_bit_size`` + - Combined size in bits of the picture order count related syntax + elements: pic_order_cnt_lsb, delta_pic_order_cnt_bottom, + delta_pic_order_cnt0, and delta_pic_order_cnt1. + * - __u32 + - ``slice_group_change_cycle`` + - + * - __u32 + - ``reserved`` + - Applications and drivers must set this to zero. + * - __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 + * - ``V4L2_H264_DECODE_PARAM_FLAG_FIELD_PIC`` + - 0x00000002 + - + * - ``V4L2_H264_DECODE_PARAM_FLAG_BOTTOM_FIELD`` + - 0x00000004 + - + +.. 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. + * - __u32 + - ``pic_num`` + - + * - __u16 + - ``frame_num`` + - + * - __u8 + - ``fields`` + - Specifies how the DPB entry is referenced. See :ref:`Reference Fields <h264_ref_fields>` + * - __u8 + - ``reserved[5]`` + - Applications and drivers must set this to zero. + * - __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 (non-empty) and should be considered. + * - ``V4L2_H264_DPB_ENTRY_FLAG_ACTIVE`` + - 0x00000002 + - The DPB entry is used for reference. + * - ``V4L2_H264_DPB_ENTRY_FLAG_LONG_TERM`` + - 0x00000004 + - The DPB entry is used for long-term reference. + * - ``V4L2_H264_DPB_ENTRY_FLAG_FIELD`` + - 0x00000008 + - The DPB entry is a single field or a complementary field pair. + +``V4L2_CID_STATELESS_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. + +.. c:type:: v4l2_stateless_h264_decode_mode + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_STATELESS_H264_DECODE_MODE_SLICE_BASED`` + - 0 + - Decoding is done at the slice granularity. + The OUTPUT buffer must contain a single slice. + When this mode is selected, the ``V4L2_CID_STATELESS_H264_SLICE_PARAMS`` + control shall be set. When multiple slices compose a frame, + use of ``V4L2_BUF_CAP_SUPPORTS_M2M_HOLD_CAPTURE_BUF`` flag + is required. + * - ``V4L2_STATELESS_H264_DECODE_MODE_FRAME_BASED`` + - 1 + - Decoding is done at the frame granularity, + The OUTPUT buffer must contain all slices needed to decode the + frame. The OUTPUT buffer must also contain both fields. + This mode will be supported by devices that + parse the slice(s) header(s) in hardware. When this mode is + selected, the ``V4L2_CID_STATELESS_H264_SLICE_PARAMS`` + control shall not be set. + +``V4L2_CID_STATELESS_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. + +.. c:type:: v4l2_stateless_h264_start_code + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_STATELESS_H264_START_CODE_NONE`` + - 0 + - Selecting this value specifies that H264 slices are passed + to the driver without any start code. + * - ``V4L2_STATELESS_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. + + +.. _codec-stateless-fwht: + +``V4L2_CID_STATELESS_FWHT_PARAMS (struct)`` + Specifies the FWHT (Fast Walsh Hadamard Transform) parameters (as extracted + from the bitstream) for the associated FWHT data. This includes the necessary + parameters for configuring a stateless hardware decoding pipeline for FWHT. + This codec is specific to the vicodec test driver. + +.. c:type:: v4l2_ctrl_fwht_params + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.4cm}|p{4.3cm}|p{11.8cm}| + +.. flat-table:: struct v4l2_ctrl_fwht_params + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u64 + - ``backward_ref_ts`` + - Timestamp of the V4L2 capture buffer to use as backward reference, used + with 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. + * - __u32 + - ``version`` + - The version of the codec. Set to ``V4L2_FWHT_VERSION``. + * - __u32 + - ``width`` + - The width of the frame. + * - __u32 + - ``height`` + - The height of the frame. + * - __u32 + - ``flags`` + - The flags of the frame, see :ref:`fwht-flags`. + * - __u32 + - ``colorspace`` + - The colorspace of the frame, from enum :c:type:`v4l2_colorspace`. + * - __u32 + - ``xfer_func`` + - The transfer function, from enum :c:type:`v4l2_xfer_func`. + * - __u32 + - ``ycbcr_enc`` + - The Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`. + * - __u32 + - ``quantization`` + - The quantization range, from enum :c:type:`v4l2_quantization`. + + + +.. _fwht-flags: + +FWHT Flags +========== + +.. cssclass:: longtable + +.. tabularcolumns:: |p{6.8cm}|p{2.4cm}|p{8.3cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * - ``V4L2_FWHT_FL_IS_INTERLACED`` + - 0x00000001 + - Set if this is an interlaced format. + * - ``V4L2_FWHT_FL_IS_BOTTOM_FIRST`` + - 0x00000002 + - Set if this is a bottom-first (NTSC) interlaced format. + * - ``V4L2_FWHT_FL_IS_ALTERNATE`` + - 0x00000004 + - Set if each 'frame' contains just one field. + * - ``V4L2_FWHT_FL_IS_BOTTOM_FIELD`` + - 0x00000008 + - If V4L2_FWHT_FL_IS_ALTERNATE was set, then this is set if this 'frame' is the + bottom field, else it is the top field. + * - ``V4L2_FWHT_FL_LUMA_IS_UNCOMPRESSED`` + - 0x00000010 + - Set if the Y' (luma) plane is uncompressed. + * - ``V4L2_FWHT_FL_CB_IS_UNCOMPRESSED`` + - 0x00000020 + - Set if the Cb plane is uncompressed. + * - ``V4L2_FWHT_FL_CR_IS_UNCOMPRESSED`` + - 0x00000040 + - Set if the Cr plane is uncompressed. + * - ``V4L2_FWHT_FL_CHROMA_FULL_HEIGHT`` + - 0x00000080 + - Set if the chroma plane has the same height as the luma plane, + else the chroma plane is half the height of the luma plane. + * - ``V4L2_FWHT_FL_CHROMA_FULL_WIDTH`` + - 0x00000100 + - Set if the chroma plane has the same width as the luma plane, + else the chroma plane is half the width of the luma plane. + * - ``V4L2_FWHT_FL_ALPHA_IS_UNCOMPRESSED`` + - 0x00000200 + - Set if the alpha plane is uncompressed. + * - ``V4L2_FWHT_FL_I_FRAME`` + - 0x00000400 + - Set if this is an I-frame. + * - ``V4L2_FWHT_FL_COMPONENTS_NUM_MSK`` + - 0x00070000 + - The number of color components - 1. + * - ``V4L2_FWHT_FL_PIXENC_MSK`` + - 0x00180000 + - The mask for the pixel encoding. + * - ``V4L2_FWHT_FL_PIXENC_YUV`` + - 0x00080000 + - Set if the pixel encoding is YUV. + * - ``V4L2_FWHT_FL_PIXENC_RGB`` + - 0x00100000 + - Set if the pixel encoding is RGB. + * - ``V4L2_FWHT_FL_PIXENC_HSV`` + - 0x00180000 + - Set if the pixel encoding is HSV. diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst index ce728c757eaf..454ecd9a0f83 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later -.. _mpeg-controls: +.. _codec-controls: *********************** Codec Control Reference @@ -26,7 +26,7 @@ Generic Codec Controls Codec Control IDs ----------------- -``V4L2_CID_MPEG_CLASS (class)`` +``V4L2_CID_CODEC_CLASS (class)`` The Codec class descriptor. Calling :ref:`VIDIOC_QUERYCTRL` for this control will return a description of this control class. This description can be @@ -1502,698 +1502,6 @@ 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_SCALING_MATRIX_PRESENT`` - - 0x00000080 - - Indicates that ``V4L2_CID_MPEG_VIDEO_H264_SCALING_MATRIX`` - must be used for this picture. - -``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]`` - - Scaling matrix after applying the inverse scanning process. - Expected list order is Intra Y, Intra Cb, Intra Cr, Inter Y, - Inter Cb, Inter Cr. The values on each scaling list are - expected in raster scan order. - * - __u8 - - ``scaling_list_8x8[6][64]`` - - Scaling matrix after applying the inverse scanning process. - Expected list order is Intra Y, Inter Y, Intra Cb, Inter Cb, - Intra Cr, Inter Cr. The values on each scaling list are - expected in raster scan order. - -``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. - -.. 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 - - ``header_bit_size`` - - Offset in bits to slice_data() from the beginning of this slice. - * - __u32 - - ``first_mb_in_slice`` - - - * - __u8 - - ``slice_type`` - - - * - __u8 - - ``colour_plane_id`` - - - * - __u8 - - ``redundant_pic_cnt`` - - - * - __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`` - - If num_ref_idx_active_override_flag is not set, this field must be - set to the value of num_ref_idx_l0_default_active_minus1. - * - __u8 - - ``num_ref_idx_l1_active_minus1`` - - If num_ref_idx_active_override_flag is not set, this field must be - set to the value of num_ref_idx_l1_default_active_minus1. - * - __u8 - - ``reserved`` - - Applications and drivers must set this to zero. - * - struct :c:type:`v4l2_h264_reference` - - ``ref_pic_list0[32]`` - - Reference picture list after applying the per-slice modifications - * - struct :c:type:`v4l2_h264_reference` - - ``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_DIRECT_SPATIAL_MV_PRED`` - - 0x00000001 - - - * - ``V4L2_H264_SLICE_FLAG_SP_FOR_SWITCH`` - - 0x00000002 - - - -``V4L2_CID_MPEG_VIDEO_H264_PRED_WEIGHTS (struct)`` - Prediction weight table defined according to :ref:`h264`, - section 7.4.3.2 "Prediction Weight Table Semantics". - The prediction weight table must be passed by applications - under the conditions explained in section 7.3.3 "Slice header - syntax". - - .. note:: - - This compound control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_ctrl_h264_pred_weights - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_ctrl_h264_pred_weights - :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]`` - - - -``Picture Reference`` - -.. c:type:: v4l2_h264_reference - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_h264_reference - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``fields`` - - Specifies how the picture is referenced. See :ref:`Reference Fields <h264_ref_fields>` - * - __u8 - - ``index`` - - Index into the :c:type:`v4l2_ctrl_h264_decode_params`.dpb array. - -.. _h264_ref_fields: - -``Reference Fields`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_H264_TOP_FIELD_REF`` - - 0x1 - - The top field in field pair is used for short-term reference. - * - ``V4L2_H264_BOTTOM_FIELD_REF`` - - 0x2 - - The bottom field in field pair is used for short-term reference. - * - ``V4L2_H264_FRAME_REF`` - - 0x3 - - The frame (or the top/bottom fields, if it's a field pair) - is used for short-term reference. - -``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 - - ``nal_ref_idc`` - - NAL reference ID value coming from the NAL Unit header - * - __u16 - - ``frame_num`` - - - * - __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 - * - __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`` - - - * - __u32 - - ``dec_ref_pic_marking_bit_size`` - - Size in bits of the dec_ref_pic_marking() syntax element. - * - __u32 - - ``pic_order_cnt_bit_size`` - - Combined size in bits of the picture order count related syntax - elements: pic_order_cnt_lsb, delta_pic_order_cnt_bottom, - delta_pic_order_cnt0, and delta_pic_order_cnt1. - * - __u32 - - ``slice_group_change_cycle`` - - - * - __u32 - - ``reserved`` - - Applications and drivers must set this to zero. - * - __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 - * - ``V4L2_H264_DECODE_PARAM_FLAG_FIELD_PIC`` - - 0x00000002 - - - * - ``V4L2_H264_DECODE_PARAM_FLAG_BOTTOM_FIELD`` - - 0x00000004 - - - -.. 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. - * - __u32 - - ``pic_num`` - - - * - __u16 - - ``frame_num`` - - - * - __u8 - - ``fields`` - - Specifies how the DPB entry is referenced. See :ref:`Reference Fields <h264_ref_fields>` - * - __u8 - - ``reserved[5]`` - - Applications and drivers must set this to zero. - * - __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 (non-empty) and should be considered. - * - ``V4L2_H264_DPB_ENTRY_FLAG_ACTIVE`` - - 0x00000002 - - The DPB entry is used for reference. - * - ``V4L2_H264_DPB_ENTRY_FLAG_LONG_TERM`` - - 0x00000004 - - The DPB entry is used for long-term reference. - * - ``V4L2_H264_DPB_ENTRY_FLAG_FIELD`` - - 0x00000008 - - The DPB entry is a single field or a complementary field pair. - -``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. - The OUTPUT buffer must contain a single slice. - When this mode is selected, the ``V4L2_CID_MPEG_VIDEO_H264_SLICE_PARAMS`` - control shall be set. When multiple slices compose a frame, - use of ``V4L2_BUF_CAP_SUPPORTS_M2M_HOLD_CAPTURE_BUF`` flag - is required. - * - ``V4L2_MPEG_VIDEO_H264_DECODE_MODE_FRAME_BASED`` - - 1 - - Decoding is done at the frame granularity, - The OUTPUT buffer must contain all slices needed to decode the - frame. The OUTPUT buffer must also contain both fields. - This mode will be supported by devices that - parse the slice(s) header(s) in hardware. When this mode is - selected, the ``V4L2_CID_MPEG_VIDEO_H264_SLICE_PARAMS`` - control shall not be set. - -``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: ``V4L2_CID_MPEG_VIDEO_MPEG2_SLICE_PARAMS (struct)`` @@ -2905,127 +2213,6 @@ enum v4l2_mpeg_mfc51_video_force_frame_type - - Force a non-coded frame. -.. _v4l2-mpeg-fwht: - -``V4L2_CID_MPEG_VIDEO_FWHT_PARAMS (struct)`` - Specifies the fwht parameters (as extracted from the bitstream) for the - associated FWHT data. This includes the necessary parameters for - configuring a stateless hardware decoding pipeline for FWHT. - - .. note:: - - This compound control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_ctrl_fwht_params - -.. cssclass:: longtable - -.. tabularcolumns:: |p{1.4cm}|p{4.3cm}|p{11.8cm}| - -.. flat-table:: struct v4l2_ctrl_fwht_params - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u64 - - ``backward_ref_ts`` - - Timestamp of the V4L2 capture buffer to use as backward reference, used - with 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. - * - __u32 - - ``version`` - - The version of the codec - * - __u32 - - ``width`` - - The width of the frame - * - __u32 - - ``height`` - - The height of the frame - * - __u32 - - ``flags`` - - The flags of the frame, see :ref:`fwht-flags`. - * - __u32 - - ``colorspace`` - - The colorspace of the frame, from enum :c:type:`v4l2_colorspace`. - * - __u32 - - ``xfer_func`` - - The transfer function, from enum :c:type:`v4l2_xfer_func`. - * - __u32 - - ``ycbcr_enc`` - - The Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`. - * - __u32 - - ``quantization`` - - The quantization range, from enum :c:type:`v4l2_quantization`. - - - -.. _fwht-flags: - -FWHT Flags -============ - -.. cssclass:: longtable - -.. tabularcolumns:: |p{6.8cm}|p{2.4cm}|p{8.3cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 4 - - * - ``FWHT_FL_IS_INTERLACED`` - - 0x00000001 - - Set if this is an interlaced format - * - ``FWHT_FL_IS_BOTTOM_FIRST`` - - 0x00000002 - - Set if this is a bottom-first (NTSC) interlaced format - * - ``FWHT_FL_IS_ALTERNATE`` - - 0x00000004 - - Set if each 'frame' contains just one field - * - ``FWHT_FL_IS_BOTTOM_FIELD`` - - 0x00000008 - - If FWHT_FL_IS_ALTERNATE was set, then this is set if this 'frame' is the - bottom field, else it is the top field. - * - ``FWHT_FL_LUMA_IS_UNCOMPRESSED`` - - 0x00000010 - - Set if the luma plane is uncompressed - * - ``FWHT_FL_CB_IS_UNCOMPRESSED`` - - 0x00000020 - - Set if the cb plane is uncompressed - * - ``FWHT_FL_CR_IS_UNCOMPRESSED`` - - 0x00000040 - - Set if the cr plane is uncompressed - * - ``FWHT_FL_CHROMA_FULL_HEIGHT`` - - 0x00000080 - - Set if the chroma plane has the same height as the luma plane, - else the chroma plane is half the height of the luma plane - * - ``FWHT_FL_CHROMA_FULL_WIDTH`` - - 0x00000100 - - Set if the chroma plane has the same width as the luma plane, - else the chroma plane is half the width of the luma plane - * - ``FWHT_FL_ALPHA_IS_UNCOMPRESSED`` - - 0x00000200 - - Set if the alpha plane is uncompressed - * - ``FWHT_FL_I_FRAME`` - - 0x00000400 - - Set if this is an I-frame - * - ``FWHT_FL_COMPONENTS_NUM_MSK`` - - 0x00070000 - - A 4-values flag - the number of components - 1 - * - ``FWHT_FL_PIXENC_YUV`` - - 0x00080000 - - Set if the pixel encoding is YUV - * - ``FWHT_FL_PIXENC_RGB`` - - 0x00100000 - - Set if the pixel encoding is RGB - * - ``FWHT_FL_PIXENC_HSV`` - - 0x00180000 - - Set if the pixel encoding is HSV - - CX2341x MPEG Controls ===================== diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst index 9457dc340c31..de43f5c8486d 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst @@ -58,3 +58,17 @@ Image Source Control IDs The unit cell consists of the whole area of the pixel, sensitive and non-sensitive. This control is required for automatic calibration of sensors/cameras. + +.. c:type:: v4l2_area + +.. flat-table:: struct v4l2_area + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``width`` + - Width of the area. + * - __u32 + - ``height`` + - Height of the area. diff --git a/Documentation/userspace-api/media/v4l/extended-controls.rst b/Documentation/userspace-api/media/v4l/extended-controls.rst index 70301538d222..44fcd67f20bf 100644 --- a/Documentation/userspace-api/media/v4l/extended-controls.rst +++ b/Documentation/userspace-api/media/v4l/extended-controls.rst @@ -55,8 +55,8 @@ controls in that array and a control class. Control classes are used to group similar controls into a single class. For example, control class ``V4L2_CTRL_CLASS_USER`` contains all user controls (i. e. all controls that can also be set using the old :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` -ioctl). Control class ``V4L2_CTRL_CLASS_MPEG`` contains all controls -relating to MPEG encoding, etc. +ioctl). Control class ``V4L2_CTRL_CLASS_CODEC`` contains controls +relating to codecs. All controls in the control array must belong to the specified control class. An error is returned if this is not the case. @@ -130,9 +130,9 @@ control class is found: .. code-block:: c - qctrl.id = V4L2_CTRL_CLASS_MPEG | V4L2_CTRL_FLAG_NEXT_CTRL; + qctrl.id = V4L2_CTRL_CLASS_CODEC | V4L2_CTRL_FLAG_NEXT_CTRL; while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &qctrl)) { - if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4L2_CTRL_CLASS_MPEG) + if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4L2_CTRL_CLASS_CODEC) break; /* ... */ qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; diff --git a/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst b/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst index d585909bc4e2..acad5f3ca0c1 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst @@ -57,18 +57,18 @@ Compressed Formats - H264 parsed slice data, including slice headers, either with or without the start code, 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`). + H264 pipeline with the :ref:`stateless_decoder`. 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. + through the ``V4L2_CID_STATELESS_H264_DECODE_MODE`` + and ``V4L2_CID_STATELESS_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 + required to be passed through the ``V4L2_CID_STATELESS_H264_SPS``, + ``V4L2_CID_STATELESS_H264_PPS``, + ``V4L2_CID_STATELESS_H264_SCALING_MATRIX``, + ``V4L2_CID_STATELESS_H264_SLICE_PARAMS`` and + ``V4L2_CID_STATELESS_H264_DECODE_PARAMS`` controls. See the + :ref:`associated Codec Control IDs <v4l2-codec-stateless-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. @@ -77,11 +77,6 @@ Compressed Formats 7.3.2.8 "Slice layer without partitioning RBSP syntax" and the following sections. - .. 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`` @@ -196,10 +191,10 @@ Compressed Formats through the ``V4L2_CID_MPEG_VIDEO_HEVC_DECODE_MODE`` and ``V4L2_CID_MPEG_VIDEO_HEVC_START_CODE`` controls. Metadata associated with the frame to decode is required to be passed - through the following controls : - * ``V4L2_CID_MPEG_VIDEO_HEVC_SPS`` - * ``V4L2_CID_MPEG_VIDEO_HEVC_PPS`` - * ``V4L2_CID_MPEG_VIDEO_HEVC_SLICE_PARAMS`` + through the following controls: + ``V4L2_CID_MPEG_VIDEO_HEVC_SPS``, + ``V4L2_CID_MPEG_VIDEO_HEVC_PPS``, and + ``V4L2_CID_MPEG_VIDEO_HEVC_SLICE_PARAMS``. See the :ref:`associated Codec Control IDs <v4l2-mpeg-hevc>`. Buffers associated with this pixel format must contain the appropriate number of macroblocks to decode a full corresponding frame. @@ -222,4 +217,6 @@ Compressed Formats - ``V4L2_PIX_FMT_FWHT_STATELESS`` - 'SFWH' - Same format as V4L2_PIX_FMT_FWHT but requires stateless codec implementation. - See the :ref:`associated Codec Control IDs <v4l2-mpeg-fwht>`. + Metadata associated with the frame to decode is required to be passed + through the ``V4L2_CID_STATELESS_FWHT_PARAMS`` control. + See the :ref:`associated Codec Control ID <codec-stateless-fwht>`. diff --git a/Documentation/userspace-api/media/v4l/pixfmt-grey.rst b/Documentation/userspace-api/media/v4l/pixfmt-grey.rst deleted file mode 100644 index 121365b03c57..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-grey.rst +++ /dev/null @@ -1,44 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-GREY: - -************************** -V4L2_PIX_FMT_GREY ('GREY') -************************** - -Grey-scale image - - -Description -=========== - -This is a grey-scale image. It is really a degenerate Y'CbCr format -which simply contains no Cb or Cr data. - -**Byte Order.** -Each cell is one byte. - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-m420.rst b/Documentation/userspace-api/media/v4l/pixfmt-m420.rst index 13cf36a8cd5c..c01a949e7c11 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-m420.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-m420.rst @@ -67,60 +67,5 @@ Each cell is one byte. **Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 1 - - Y - - - - Y - - Y - - - - Y - * - - * - 2 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 3 - - Y - - - - Y - - Y - - - - Y +Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>` +horizontally and vertically. diff --git a/Documentation/userspace-api/media/v4l/pixfmt-meta-rkisp1.rst b/Documentation/userspace-api/media/v4l/pixfmt-meta-rkisp1.rst index 7e43837ed260..fa04f00bcd2e 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-meta-rkisp1.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-meta-rkisp1.rst @@ -1,7 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -.. _v4l2-meta-fmt-params-rkisp1: -.. _v4l2-meta-fmt-stat-rkisp1: +.. _v4l2-meta-fmt-rk-isp1-params: + +.. _v4l2-meta-fmt-rk-isp1-stat-3a: ***************************************************************************** V4L2_META_FMT_RK_ISP1_PARAMS ('rk1p'), V4L2_META_FMT_RK_ISP1_STAT_3A ('rk1s') @@ -46,4 +47,4 @@ important tuning tools using software control loop. rkisp1 uAPI data types ====================== -.. kernel-doc:: drivers/staging/media/rkisp1/uapi/rkisp1-config.h +.. kernel-doc:: include/uapi/linux/rkisp1-config.h diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv12.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv12.rst deleted file mode 100644 index dd2f38129fe6..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-nv12.rst +++ /dev/null @@ -1,129 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-NV12: -.. _V4L2-PIX-FMT-NV21: - -****************************************************** -V4L2_PIX_FMT_NV12 ('NV12'), V4L2_PIX_FMT_NV21 ('NV21') -****************************************************** - - -V4L2_PIX_FMT_NV21 -Formats with ½ horizontal and vertical chroma resolution, also known as -YUV 4:2:0. One luminance and one chrominance plane with alternating -chroma samples as opposed to ``V4L2_PIX_FMT_YVU420`` - - -Description -=========== - -These are two-plane versions of the YUV 4:2:0 format. The three -components are separated into two sub-images or planes. The Y plane is -first. The Y plane has one byte per pixel. For ``V4L2_PIX_FMT_NV12``, a -combined CbCr plane immediately follows the Y plane in memory. The CbCr -plane is the same width, in bytes, as the Y plane (and of the image), -but is half as tall in pixels. Each CbCr pair belongs to four pixels. -For example, Cb\ :sub:`0`/Cr\ :sub:`0` belongs to Y'\ :sub:`00`, -Y'\ :sub:`01`, Y'\ :sub:`10`, Y'\ :sub:`11`. ``V4L2_PIX_FMT_NV21`` is -the same except the Cb and Cr bytes are swapped, the CrCb plane starts -with a Cr byte. - -If the Y plane has pad bytes after each row, then the CbCr plane has as -many pad bytes after its rows. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - start + 16: - - Cb\ :sub:`00` - - Cr\ :sub:`00` - - Cb\ :sub:`01` - - Cr\ :sub:`01` - * - start + 20: - - Cb\ :sub:`10` - - Cr\ :sub:`10` - - Cb\ :sub:`11` - - Cr\ :sub:`11` - - -**Color Sample Location:** - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 1 - - Y - - - - Y - - Y - - - - Y - * - - * - 2 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 3 - - Y - - - - Y - - Y - - - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv12m.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv12m.rst deleted file mode 100644 index 250f8b977605..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-nv12m.rst +++ /dev/null @@ -1,144 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-NV12M: -.. _v4l2-pix-fmt-nv12mt-16x16: -.. _V4L2-PIX-FMT-NV21M: - -*********************************************************************************** -V4L2_PIX_FMT_NV12M ('NM12'), V4L2_PIX_FMT_NV21M ('NM21'), V4L2_PIX_FMT_NV12MT_16X16 -*********************************************************************************** - - -V4L2_PIX_FMT_NV21M -V4L2_PIX_FMT_NV12MT_16X16 -Variation of ``V4L2_PIX_FMT_NV12`` and ``V4L2_PIX_FMT_NV21`` with planes -non contiguous in memory. - - -Description -=========== - -This is a multi-planar, two-plane version of the YUV 4:2:0 format. The -three components are separated into two sub-images or planes. -``V4L2_PIX_FMT_NV12M`` differs from ``V4L2_PIX_FMT_NV12`` in that the -two planes are non-contiguous in memory, i.e. the chroma plane do not -necessarily immediately follows the luma plane. The luminance data -occupies the first plane. The Y plane has one byte per pixel. In the -second plane there is a chrominance data with alternating chroma -samples. The CbCr plane is the same width, in bytes, as the Y plane (and -of the image), but is half as tall in pixels. Each CbCr pair belongs to -four pixels. For example, Cb\ :sub:`0`/Cr\ :sub:`0` belongs to -Y'\ :sub:`00`, Y'\ :sub:`01`, Y'\ :sub:`10`, Y'\ :sub:`11`. -``V4L2_PIX_FMT_NV12MT_16X16`` is the tiled version of -``V4L2_PIX_FMT_NV12M`` with 16x16 macroblock tiles. Here pixels are -arranged in 16x16 2D tiles and tiles are arranged in linear order in -memory. ``V4L2_PIX_FMT_NV21M`` is the same as ``V4L2_PIX_FMT_NV12M`` -except the Cb and Cr bytes are swapped, the CrCb plane starts with a Cr -byte. - -``V4L2_PIX_FMT_NV12M`` is intended to be used only in drivers and -applications that support the multi-planar API, described in -:ref:`planar-apis`. - -If the Y plane has pad bytes after each row, then the CbCr plane has as -many pad bytes after its rows. - -**Byte Order.** -Each cell is one byte. - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start0 + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start0 + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start0 + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start0 + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - - * - start1 + 0: - - Cb\ :sub:`00` - - Cr\ :sub:`00` - - Cb\ :sub:`01` - - Cr\ :sub:`01` - * - start1 + 4: - - Cb\ :sub:`10` - - Cr\ :sub:`10` - - Cb\ :sub:`11` - - Cr\ :sub:`11` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 1 - - Y - - - - Y - - Y - - - - Y - * - - * - 2 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - - - C - - - * - 3 - - Y - - - - Y - - Y - - - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv12mt.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv12mt.rst deleted file mode 100644 index 46f63d793ec5..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-nv12mt.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-NV12MT: - -**************************** -V4L2_PIX_FMT_NV12MT ('TM12') -**************************** - -Formats with ½ horizontal and vertical chroma resolution. This format -has two planes - one for luminance and one for chrominance. Chroma -samples are interleaved. The difference to ``V4L2_PIX_FMT_NV12`` is the -memory layout. Pixels are grouped in macroblocks of 64x32 size. The -order of macroblocks in memory is also not standard. - - -Description -=========== - -This is the two-plane versions of the YUV 4:2:0 format where data is -grouped into 64x32 macroblocks. The three components are separated into -two sub-images or planes. The Y plane has one byte per pixel and pixels -are grouped into 64x32 macroblocks. The CbCr plane has the same width, -in bytes, as the Y plane (and the image), but is half as tall in pixels. -The chroma plane is also grouped into 64x32 macroblocks. - -Width of the buffer has to be aligned to the multiple of 128, and height -alignment is 32. Every four adjacent buffers - two horizontally and two -vertically are grouped together and are located in memory in Z or -flipped Z order. - -Layout of macroblocks in memory is presented in the following figure. - - -.. _nv12mt: - -.. kernel-figure:: nv12mt.svg - :alt: nv12mt.svg - :align: center - - V4L2_PIX_FMT_NV12MT macroblock Z shape memory layout - -The requirement that width is multiple of 128 is implemented because, -the Z shape cannot be cut in half horizontally. In case the vertical -resolution of macroblocks is odd then the last row of macroblocks is -arranged in a linear order. - -In case of chroma the layout is identical. Cb and Cr samples are -interleaved. Height of the buffer is aligned to 32. - - -.. _nv12mt_ex: - -.. kernel-figure:: nv12mt_example.svg - :alt: nv12mt_example.svg - :align: center - - Example V4L2_PIX_FMT_NV12MT memory layout of macroblocks - -Memory layout of macroblocks of ``V4L2_PIX_FMT_NV12MT`` format in most -extreme case. diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv16.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv16.rst deleted file mode 100644 index 22295fc0c359..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-nv16.rst +++ /dev/null @@ -1,153 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-NV16: -.. _V4L2-PIX-FMT-NV61: - -****************************************************** -V4L2_PIX_FMT_NV16 ('NV16'), V4L2_PIX_FMT_NV61 ('NV61') -****************************************************** - -V4L2_PIX_FMT_NV61 -Formats with ½ horizontal chroma resolution, also known as YUV 4:2:2. -One luminance and one chrominance plane with alternating chroma samples -as opposed to ``V4L2_PIX_FMT_YVU420`` - - -Description -=========== - -These are two-plane versions of the YUV 4:2:2 format. The three -components are separated into two sub-images or planes. The Y plane is -first. The Y plane has one byte per pixel. For ``V4L2_PIX_FMT_NV16``, a -combined CbCr plane immediately follows the Y plane in memory. The CbCr -plane is the same width and height, in bytes, as the Y plane (and of the -image). Each CbCr pair belongs to two pixels. For example, -Cb\ :sub:`0`/Cr\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`. -``V4L2_PIX_FMT_NV61`` is the same except the Cb and Cr bytes are -swapped, the CrCb plane starts with a Cr byte. - -If the Y plane has pad bytes after each row, then the CbCr plane has as -many pad bytes after its rows. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - start + 16: - - Cb\ :sub:`00` - - Cr\ :sub:`00` - - Cb\ :sub:`01` - - Cr\ :sub:`01` - * - start + 20: - - Cb\ :sub:`10` - - Cr\ :sub:`10` - - Cb\ :sub:`11` - - Cr\ :sub:`11` - * - start + 24: - - Cb\ :sub:`20` - - Cr\ :sub:`20` - - Cb\ :sub:`21` - - Cr\ :sub:`21` - * - start + 28: - - Cb\ :sub:`30` - - Cr\ :sub:`30` - - Cb\ :sub:`31` - - Cr\ :sub:`31` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 1 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - - * - 2 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 3 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv16m.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv16m.rst deleted file mode 100644 index 812bf2ccabf0..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-nv16m.rst +++ /dev/null @@ -1,157 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-NV16M: -.. _v4l2-pix-fmt-nv61m: - -******************************************************** -V4L2_PIX_FMT_NV16M ('NM16'), V4L2_PIX_FMT_NV61M ('NM61') -******************************************************** - -V4L2_PIX_FMT_NV61M -Variation of ``V4L2_PIX_FMT_NV16`` and ``V4L2_PIX_FMT_NV61`` with planes -non contiguous in memory. - - -Description -=========== - -This is a multi-planar, two-plane version of the YUV 4:2:2 format. The -three components are separated into two sub-images or planes. -``V4L2_PIX_FMT_NV16M`` differs from ``V4L2_PIX_FMT_NV16`` in that the -two planes are non-contiguous in memory, i.e. the chroma plane does not -necessarily immediately follow the luma plane. The luminance data -occupies the first plane. The Y plane has one byte per pixel. In the -second plane there is chrominance data with alternating chroma samples. -The CbCr plane is the same width and height, in bytes, as the Y plane. -Each CbCr pair belongs to two pixels. For example, -Cb\ :sub:`0`/Cr\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`. -``V4L2_PIX_FMT_NV61M`` is the same as ``V4L2_PIX_FMT_NV16M`` except the -Cb and Cr bytes are swapped, the CrCb plane starts with a Cr byte. - -``V4L2_PIX_FMT_NV16M`` and ``V4L2_PIX_FMT_NV61M`` are intended to be -used only in drivers and applications that support the multi-planar API, -described in :ref:`planar-apis`. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start0 + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start0 + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start0 + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start0 + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - - * - start1 + 0: - - Cb\ :sub:`00` - - Cr\ :sub:`00` - - Cb\ :sub:`02` - - Cr\ :sub:`02` - * - start1 + 4: - - Cb\ :sub:`10` - - Cr\ :sub:`10` - - Cb\ :sub:`12` - - Cr\ :sub:`12` - * - start1 + 8: - - Cb\ :sub:`20` - - Cr\ :sub:`20` - - Cb\ :sub:`22` - - Cr\ :sub:`22` - * - start1 + 12: - - Cb\ :sub:`30` - - Cr\ :sub:`30` - - Cb\ :sub:`32` - - Cr\ :sub:`32` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 1 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - - * - 2 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - - * - 3 - - Y - - - - Y - - Y - - - - Y - * - - - - - C - - - - - - C - - diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv24.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv24.rst deleted file mode 100644 index bf1b94062fc2..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-nv24.rst +++ /dev/null @@ -1,95 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-NV24: -.. _V4L2-PIX-FMT-NV42: - -****************************************************** -V4L2_PIX_FMT_NV24 ('NV24'), V4L2_PIX_FMT_NV42 ('NV42') -****************************************************** - -V4L2_PIX_FMT_NV42 -Formats with full horizontal and vertical chroma resolutions, also known -as YUV 4:4:4. One luminance and one chrominance plane with alternating -chroma samples as opposed to ``V4L2_PIX_FMT_YVU420`` - - -Description -=========== - -These are two-plane versions of the YUV 4:4:4 format. The three -components are separated into two sub-images or planes. The Y plane is -first, with each Y sample stored in one byte per pixel. For -``V4L2_PIX_FMT_NV24``, a combined CbCr plane immediately follows the Y -plane in memory. The CbCr plane has the same width and height, in -pixels, as the Y plane (and the image). Each line contains one CbCr pair -per pixel, with each Cb and Cr sample stored in one byte. -``V4L2_PIX_FMT_NV42`` is the same except that the Cb and Cr samples are -swapped, the CrCb plane starts with a Cr sample. - -If the Y plane has pad bytes after each row, then the CbCr plane has -twice as many pad bytes after its rows. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - start + 16: - - Cb\ :sub:`00` - - Cr\ :sub:`00` - - Cb\ :sub:`01` - - Cr\ :sub:`01` - - Cb\ :sub:`02` - - Cr\ :sub:`02` - - Cb\ :sub:`03` - - Cr\ :sub:`03` - * - start + 24: - - Cb\ :sub:`10` - - Cr\ :sub:`10` - - Cb\ :sub:`11` - - Cr\ :sub:`11` - - Cb\ :sub:`12` - - Cr\ :sub:`12` - - Cb\ :sub:`13` - - Cr\ :sub:`13` - * - start + 32: - - Cb\ :sub:`20` - - Cr\ :sub:`20` - - Cb\ :sub:`21` - - Cr\ :sub:`21` - - Cb\ :sub:`22` - - Cr\ :sub:`22` - - Cb\ :sub:`23` - - Cr\ :sub:`23` - * - start + 40: - - Cb\ :sub:`30` - - Cr\ :sub:`30` - - Cb\ :sub:`31` - - Cr\ :sub:`31` - - Cb\ :sub:`32` - - Cr\ :sub:`32` - - Cb\ :sub:`33` - - Cr\ :sub:`33` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst index 84262208dd1c..eb551b57557e 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst @@ -6,12 +6,32 @@ Packed YUV formats ****************** -Description -=========== +Similarly to the packed RGB formats, the packed YUV formats store the Y, Cb and +Cr components consecutively in memory. They may apply subsampling to the chroma +components and thus differ in how they interlave the three components. -Similar to the packed RGB formats these formats store the Y, Cb and Cr -component of each pixel in one 16 or 32 bit word. +.. note:: + + - In all the tables that follow, bit 7 is the most significant bit in a byte. + - 'Y', 'Cb' and 'Cr' denote bits of the luma, blue chroma (also known as + 'U') and red chroma (also known as 'V') components respectively. 'A' + denotes bits of the alpha component (if supported by the format), and 'X' + denotes padding bits. + + +4:4:4 Subsampling +================= +These formats do not subsample the chroma components and store each pixels as a +full triplet of Y, Cb and Cr values. + +The next table lists the packed YUV 4:4:4 formats with less than 8 bits per +component. They are named based on the order of the Y, Cb and Cr components as +seen in a 16-bit word, which is then stored in memory in little endian byte +order, and on the number of bits for each component. For instance the YUV565 +format stores a pixel in a 16-bit word [15:0] laid out at as [Y'\ :sub:`4-0` +Cb\ :sub:`5-0` Cr\ :sub:`4-0`], and stored in memory in two bytes, +[Cb\ :sub:`2-0` Cr\ :sub:`4-0`] followed by [Y'\ :sub:`4-0` Cb\ :sub:`5-3`]. .. raw:: latex @@ -19,11 +39,9 @@ component of each pixel in one 16 or 32 bit word. \tiny \setlength{\tabcolsep}{2pt} -.. _packed-yuv-formats: - -.. tabularcolumns:: |p{2.5cm}|p{0.69cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}| +.. tabularcolumns:: |p{2.5cm}|p{0.69cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}| -.. flat-table:: Packed YUV Image Formats +.. flat-table:: Packed YUV 4:4:4 Image Formats (less than 8bpc) :header-rows: 2 :stub-columns: 0 @@ -34,10 +52,6 @@ component of each pixel in one 16 or 32 bit word. - :cspan:`7` Byte 1 - - :cspan:`7` Byte 2 - - - :cspan:`7` Byte 3 - * - - - 7 @@ -58,24 +72,6 @@ component of each pixel in one 16 or 32 bit word. - 1 - 0 - - 7 - - 6 - - 5 - - 4 - - 3 - - 2 - - 1 - - 0 - - - 7 - - 6 - - 5 - - 4 - - 3 - - 2 - - 1 - - 0 - * .. _V4L2-PIX-FMT-YUV444: - ``V4L2_PIX_FMT_YUV444`` @@ -99,8 +95,6 @@ component of each pixel in one 16 or 32 bit word. - Y'\ :sub:`1` - Y'\ :sub:`0` - - :cspan:`15` - * .. _V4L2-PIX-FMT-YUV555: - ``V4L2_PIX_FMT_YUV555`` @@ -124,7 +118,6 @@ component of each pixel in one 16 or 32 bit word. - Cb\ :sub:`4` - Cb\ :sub:`3` - - :cspan:`15` * .. _V4L2-PIX-FMT-YUV565: - ``V4L2_PIX_FMT_YUV565`` @@ -148,226 +141,219 @@ component of each pixel in one 16 or 32 bit word. - Cb\ :sub:`4` - Cb\ :sub:`3` - - :cspan:`15` +.. raw:: latex - * .. _V4L2-PIX-FMT-YUV32: + \endgroup - - ``V4L2_PIX_FMT_YUV32`` - - 'YUV4' +.. note:: - - a\ :sub:`7` - - a\ :sub:`6` - - a\ :sub:`5` - - a\ :sub:`4` - - a\ :sub:`3` - - a\ :sub:`2` - - a\ :sub:`1` - - a\ :sub:`0` + For the YUV444 and YUV555 formats, the value of alpha bits is undefined + when reading from the driver, ignored when writing to the driver, except + when alpha blending has been negotiated for a :ref:`Video Overlay + <overlay>` or :ref:`Video Output Overlay <osd>`. - - Y'\ :sub:`7` - - Y'\ :sub:`6` - - Y'\ :sub:`5` - - Y'\ :sub:`4` - - Y'\ :sub:`3` - - Y'\ :sub:`2` - - Y'\ :sub:`1` - - Y'\ :sub:`0` - - Cb\ :sub:`7` - - Cb\ :sub:`6` - - Cb\ :sub:`5` - - Cb\ :sub:`4` - - Cb\ :sub:`3` - - Cb\ :sub:`2` - - Cb\ :sub:`1` - - Cb\ :sub:`0` +The next table lists the packed YUV 4:4:4 formats with 8 bits per component. +They are named based on the order of the Y, Cb and Cr components as stored in +memory, and on the total number of bits per pixel. For instance, the VUYX32 +format stores a pixel with Cr\ :sub:`7-0` in the first byte, Cb\ :sub:`7-0` in +the second byte and Y'\ :sub:`7-0` in the third byte. - - Cr\ :sub:`7` - - Cr\ :sub:`6` - - Cr\ :sub:`5` - - Cr\ :sub:`4` - - Cr\ :sub:`3` - - Cr\ :sub:`2` - - Cr\ :sub:`1` - - Cr\ :sub:`0` +.. flat-table:: Packed YUV Image Formats (8bpc) + :header-rows: 1 + :stub-columns: 0 - * .. _V4L2-PIX-FMT-AYUV32: + * - Identifier + - Code + - Byte 0 + - Byte 1 + - Byte 2 + - Byte 3 - - ``V4L2_PIX_FMT_AYUV32`` - - 'AYUV' + * .. _V4L2-PIX-FMT-YUV32: - - 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_YUV32`` + - 'YUV4' - - Y'\ :sub:`7` - - Y'\ :sub:`6` - - Y'\ :sub:`5` - - Y'\ :sub:`4` - - Y'\ :sub:`3` - - Y'\ :sub:`2` - - Y'\ :sub:`1` - - Y'\ :sub:`0` + - A\ :sub:`7-0` + - Y'\ :sub:`7-0` + - Cb\ :sub:`7-0` + - Cr\ :sub:`7-0` - - Cb\ :sub:`7` - - Cb\ :sub:`6` - - Cb\ :sub:`5` - - Cb\ :sub:`4` - - Cb\ :sub:`3` - - Cb\ :sub:`2` - - Cb\ :sub:`1` - - Cb\ :sub:`0` + * .. _V4L2-PIX-FMT-AYUV32: - - Cr\ :sub:`7` - - Cr\ :sub:`6` - - Cr\ :sub:`5` - - Cr\ :sub:`4` - - Cr\ :sub:`3` - - Cr\ :sub:`2` - - Cr\ :sub:`1` - - Cr\ :sub:`0` + - ``V4L2_PIX_FMT_AYUV32`` + - 'AYUV' + + - A\ :sub:`7-0` + - Y'\ :sub:`7-0` + - Cb\ :sub:`7-0` + - Cr\ :sub:`7-0` * .. _V4L2-PIX-FMT-XYUV32: - ``V4L2_PIX_FMT_XYUV32`` - 'XYUV' - - - - - - - - - - - - - - - - - - - Y'\ :sub:`7` - - Y'\ :sub:`6` - - Y'\ :sub:`5` - - Y'\ :sub:`4` - - Y'\ :sub:`3` - - Y'\ :sub:`2` - - Y'\ :sub:`1` - - Y'\ :sub:`0` - - - Cb\ :sub:`7` - - Cb\ :sub:`6` - - Cb\ :sub:`5` - - Cb\ :sub:`4` - - Cb\ :sub:`3` - - Cb\ :sub:`2` - - Cb\ :sub:`1` - - Cb\ :sub:`0` - - - Cr\ :sub:`7` - - Cr\ :sub:`6` - - Cr\ :sub:`5` - - Cr\ :sub:`4` - - Cr\ :sub:`3` - - Cr\ :sub:`2` - - Cr\ :sub:`1` - - Cr\ :sub:`0` + - X\ :sub:`7-0` + - Y'\ :sub:`7-0` + - Cb\ :sub:`7-0` + - Cr\ :sub:`7-0` * .. _V4L2-PIX-FMT-VUYA32: - ``V4L2_PIX_FMT_VUYA32`` - 'VUYA' - - Cr\ :sub:`7` - - Cr\ :sub:`6` - - Cr\ :sub:`5` - - Cr\ :sub:`4` - - Cr\ :sub:`3` - - Cr\ :sub:`2` - - Cr\ :sub:`1` - - Cr\ :sub:`0` - - - Cb\ :sub:`7` - - Cb\ :sub:`6` - - Cb\ :sub:`5` - - Cb\ :sub:`4` - - Cb\ :sub:`3` - - Cb\ :sub:`2` - - Cb\ :sub:`1` - - Cb\ :sub:`0` - - - Y'\ :sub:`7` - - Y'\ :sub:`6` - - Y'\ :sub:`5` - - Y'\ :sub:`4` - - Y'\ :sub:`3` - - Y'\ :sub:`2` - - Y'\ :sub:`1` - - Y'\ :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` + - Cr\ :sub:`7-0` + - Cb\ :sub:`7-0` + - Y'\ :sub:`7-0` + - A\ :sub:`7-0` * .. _V4L2-PIX-FMT-VUYX32: - ``V4L2_PIX_FMT_VUYX32`` - 'VUYX' - - Cr\ :sub:`7` - - Cr\ :sub:`6` - - Cr\ :sub:`5` - - Cr\ :sub:`4` - - Cr\ :sub:`3` - - Cr\ :sub:`2` - - Cr\ :sub:`1` - - Cr\ :sub:`0` + - Cr\ :sub:`7-0` + - Cb\ :sub:`7-0` + - Y'\ :sub:`7-0` + - X\ :sub:`7-0` - - Cb\ :sub:`7` - - Cb\ :sub:`6` - - Cb\ :sub:`5` - - Cb\ :sub:`4` - - Cb\ :sub:`3` - - Cb\ :sub:`2` - - Cb\ :sub:`1` - - Cb\ :sub:`0` +.. note:: - - Y'\ :sub:`7` - - Y'\ :sub:`6` - - Y'\ :sub:`5` - - Y'\ :sub:`4` + - The alpha component is expected to contain a meaningful value that can be + used by drivers and applications. + - The padding bits contain undefined values that must be ignored by all + applications and drivers. + + +4:2:2 Subsampling +================= + +These formats, commonly referred to as YUYV or YUY2, subsample the chroma +components horizontally by 2, storing 2 pixels in 4 bytes. + +.. flat-table:: Packed YUV 4:2:2 Formats + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Byte 0 + - Byte 1 + - Byte 2 + - Byte 3 + - Byte 4 + - Byte 5 + - Byte 6 + - Byte 7 + * .. _V4L2-PIX-FMT-UYVY: + + - ``V4L2_PIX_FMT_UYVY`` + - 'UYVY' + + - Cb\ :sub:`0` + - Y'\ :sub:`0` + - Cr\ :sub:`0` + - Y'\ :sub:`1` + - Cb\ :sub:`2` + - Y'\ :sub:`2` + - Cr\ :sub:`2` - Y'\ :sub:`3` + * .. _V4L2-PIX-FMT-VYUY: + + - ``V4L2_PIX_FMT_VYUY`` + - 'VYUY' + + - Cr\ :sub:`0` + - Y'\ :sub:`0` + - Cb\ :sub:`0` + - Y'\ :sub:`1` + - Cr\ :sub:`2` - Y'\ :sub:`2` + - Cb\ :sub:`2` + - Y'\ :sub:`3` + * .. _V4L2-PIX-FMT-YUYV: + + - ``V4L2_PIX_FMT_YUYV`` + - 'YUYV' + + - Y'\ :sub:`0` + - Cb\ :sub:`0` - Y'\ :sub:`1` + - Cr\ :sub:`0` + - Y'\ :sub:`2` + - Cb\ :sub:`2` + - Y'\ :sub:`3` + - Cr\ :sub:`2` + * .. _V4L2-PIX-FMT-YVYU: + + - ``V4L2_PIX_FMT_YVYU`` + - 'YVYU' + - Y'\ :sub:`0` + - Cr\ :sub:`0` + - Y'\ :sub:`1` + - Cb\ :sub:`0` + - Y'\ :sub:`2` + - Cr\ :sub:`2` + - Y'\ :sub:`3` + - Cb\ :sub:`2` - - - - - - - - - - - - - - - - +**Color Sample Location:** +Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>` +horizontally. -.. raw:: latex - \endgroup +4:1:1 Subsampling +================= + +This format subsamples the chroma components horizontally by 4, storing 8 +pixels in 12 bytes. + +.. flat-table:: Packed YUV 4:1:1 Formats + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Byte 0 + - Byte 1 + - Byte 2 + - Byte 3 + - Byte 4 + - Byte 5 + - Byte 6 + - Byte 7 + - Byte 8 + - Byte 9 + - Byte 10 + - Byte 11 + * .. _V4L2-PIX-FMT-Y41P: + + - ``V4L2_PIX_FMT_Y41P`` + - 'Y41P' + + - Cb\ :sub:`0` + - Y'\ :sub:`0` + - Cr\ :sub:`0` + - Y'\ :sub:`1` + - Cb\ :sub:`4` + - Y'\ :sub:`2` + - Cr\ :sub:`4` + - Y'\ :sub:`3` + - Y'\ :sub:`4` + - Y'\ :sub:`5` + - Y'\ :sub:`6` + - Y'\ :sub:`7` .. note:: - #) Bit 7 is the most significant bit; + Do not confuse ``V4L2_PIX_FMT_Y41P`` with + :ref:`V4L2_PIX_FMT_YUV411P <V4L2-PIX-FMT-YUV411P>`. Y41P is derived from + "YUV 4:1:1 *packed*", while YUV411P stands for "YUV 4:1:1 *planar*". - #) The value of a = alpha bits is undefined when reading from the driver, - ignored when writing to the driver, except when alpha blending has - been negotiated for a :ref:`Video Overlay <overlay>` or - :ref:`Video Output Overlay <osd>` for the formats Y444, YUV555 and - YUV4. However, for formats AYUV32 and VUYA32, the alpha component is - expected to contain a meaningful value that can be used by drivers - and applications. And, the formats XYUV32 and VUYX32 contain undefined - alpha values that must be ignored by all applications and drivers. +**Color Sample Location:** +Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>` +horizontally. diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst index 9d827097c1d9..897676ee2c9d 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst @@ -6,13 +6,62 @@ 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. +These formats encode each pixel as a triplet of RGB values. They are packed +formats, meaning that the RGB values for one pixel are stored consecutively in +memory and each pixel consumes an integer number of bytes. When the number of +bits required to store a pixel is not aligned to a byte boundary, the data is +padded with additional bits to fill the remaining byte. + +The formats differ by the number of bits per RGB component (typically but not +always the same for all components), the order of components in memory, and the +presence of an alpha component or additional padding bits. + +The usage and value of the alpha bits in formats that support them (named ARGB +or a permutation thereof, 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 captures an alpha channel the alpha component will have +a meaningful value. Otherwise, when the device doesn't capture 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. + +Formats that contain padding bits are named XRGB (or a permutation thereof). +The padding bits contain undefined values and must be ignored by applications, +devices and drivers, for both :ref:`capture` and :ref:`output` devices. + +.. note:: + + - In all the tables that follow, bit 7 is the most significant bit in a byte. + - 'r', 'g' and 'b' denote bits of the red, green and blue components + respectively. 'a' denotes bits of the alpha component (if supported by the + format), and 'x' denotes padding bits. + + +Less Than 8 Bits Per Component +============================== + +These formats store an RGB triplet in one, two or four bytes. They are named +based on the order of the RGB components as seen in a 8-, 16- or 32-bit word, +which is then stored in memory in little endian byte order (unless otherwise +noted by the presence of bit 31 in the 4CC value), and on the number of bits +for each component. For instance, the RGB565 format stores a pixel in a 16-bit +word [15:0] laid out at as [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`], and +stored in memory in two bytes, [R\ :sub:`4` R\ :sub:`3` R\ :sub:`2` R\ :sub:`1` +R\ :sub:`0` G\ :sub:`5` G\ :sub:`4` G\ :sub:`3`] followed by [G\ :sub:`2` +G\ :sub:`1` G\ :sub:`0` B\ :sub:`4` B\ :sub:`3` B\ :sub:`2` B\ :sub:`1` +B\ :sub:`0`]. .. raw:: latex @@ -23,7 +72,7 @@ next to each other in memory. .. 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 +.. flat-table:: RGB Formats With Less Than 8 Bits Per Component :header-rows: 2 :stub-columns: 0 @@ -121,10 +170,10 @@ next to each other in memory. - b\ :sub:`1` - b\ :sub:`0` - - `-` - - `-` - - `-` - - `-` + - x + - x + - x + - x - r\ :sub:`3` - r\ :sub:`2` - r\ :sub:`1` @@ -162,10 +211,10 @@ next to each other in memory. - b\ :sub:`2` - b\ :sub:`1` - b\ :sub:`0` - - `-` - - `-` - - `-` - - `-` + - x + - x + - x + - x - r\ :sub:`3` - r\ :sub:`2` @@ -213,10 +262,10 @@ next to each other in memory. - r\ :sub:`1` - r\ :sub:`0` - - `-` - - `-` - - `-` - - `-` + - x + - x + - x + - x - b\ :sub:`3` - b\ :sub:`2` - b\ :sub:`1` @@ -254,10 +303,10 @@ next to each other in memory. - r\ :sub:`2` - r\ :sub:`1` - r\ :sub:`0` - - `-` - - `-` - - `-` - - `-` + - x + - x + - x + - x - b\ :sub:`3` - b\ :sub:`2` @@ -305,7 +354,7 @@ next to each other in memory. - b\ :sub:`1` - b\ :sub:`0` - - `-` + - x - r\ :sub:`4` - r\ :sub:`3` - r\ :sub:`2` @@ -349,7 +398,7 @@ next to each other in memory. - b\ :sub:`2` - b\ :sub:`1` - b\ :sub:`0` - - `-` + - x - r\ :sub:`4` - r\ :sub:`3` @@ -397,7 +446,7 @@ next to each other in memory. - r\ :sub:`1` - r\ :sub:`0` - - `-` + - x - b\ :sub:`4` - b\ :sub:`3` - b\ :sub:`2` @@ -441,7 +490,7 @@ next to each other in memory. - r\ :sub:`2` - r\ :sub:`1` - r\ :sub:`0` - - `-` + - x - b\ :sub:`4` - b\ :sub:`3` @@ -503,7 +552,7 @@ next to each other in memory. - ``V4L2_PIX_FMT_XRGB555X`` - 'XR15' | (1 << 31) - - `-` + - x - r\ :sub:`4` - r\ :sub:`3` - r\ :sub:`2` @@ -544,538 +593,188 @@ next to each other in memory. - b\ :sub:`1` - b\ :sub:`0` - - * .. _V4L2-PIX-FMT-BGR24: + * .. _V4L2-PIX-FMT-BGR666: - - ``V4L2_PIX_FMT_BGR24`` - - 'BGR3' + - ``V4L2_PIX_FMT_BGR666`` + - 'BGRH' - - 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: + - x + - x + - x + - x + - x + - x - - ``V4L2_PIX_FMT_RGB24`` - - 'RGB3' + - x + - x + - x + - x + - x + - x + - x + - x - - r\ :sub:`7` - - r\ :sub:`6` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` - - r\ :sub:`1` - - r\ :sub:`0` +.. raw:: latex - - g\ :sub:`7` - - g\ :sub:`6` - - g\ :sub:`5` - - g\ :sub:`4` - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` + \endgroup - - 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' +8 Bits Per Component +==================== - - b\ :sub:`5` - - b\ :sub:`4` - - b\ :sub:`3` - - b\ :sub:`2` - - b\ :sub:`1` - - b\ :sub:`0` - - g\ :sub:`5` - - g\ :sub:`4` +These formats store an RGB triplet in three or four bytes. They are named based +on the order of the RGB components as stored in memory, and on the total number +of bits per pixel. For instance, RGB24 format stores a pixel with [R\ :sub:`7` +R\ :sub:`6` R\ :sub:`5` R\ :sub:`4` R\ :sub:`3` R\ :sub:`2` R\ :sub:`1` +R\ :sub:`0`] in the first byte, [G\ :sub:`7` G\ :sub:`6` G\ :sub:`5` G\ :sub:`4` +G\ :sub:`3` G\ :sub:`2` G\ :sub:`1` G\ :sub:`0`] in the second byte and +[B\ :sub:`7` B\ :sub:`6` B\ :sub:`5` B\ :sub:`4` B\ :sub:`3` B\ :sub:`2` +B\ :sub:`1` B\ :sub:`0`] in the third byte. This differs from the DRM format +nomenclature that instead use the order of components as seen in a 24- or +32-bit little endian word. - - g\ :sub:`3` - - g\ :sub:`2` - - g\ :sub:`1` - - g\ :sub:`0` - - r\ :sub:`5` - - r\ :sub:`4` - - r\ :sub:`3` - - r\ :sub:`2` +.. raw:: latex - - r\ :sub:`1` - - r\ :sub:`0` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - * .. _V4L2-PIX-FMT-ABGR32: + \begingroup + \tiny + \setlength{\tabcolsep}{2pt} - - ``V4L2_PIX_FMT_ABGR32`` - - 'AR24' +.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}| - - 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` +.. flat-table:: RGB Formats With 8 Bits Per Component + :header-rows: 1 + :stub-columns: 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` + * - Identifier + - Code + - Byte 0 in memory + - Byte 1 + - Byte 2 + - Byte 3 + * .. _V4L2-PIX-FMT-BGR24: - - 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_BGR24`` + - 'BGR3' - - ``V4L2_PIX_FMT_XBGR32`` - - 'XR24' + - G\ :sub:`7-0` + - B\ :sub:`7-0` + - R\ :sub:`7-0` + - + * .. _V4L2-PIX-FMT-RGB24: - - 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_RGB24`` + - 'RGB3' - - 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-0` + - G\ :sub:`7-0` + - B\ :sub:`7-0` + - + * .. _V4L2-PIX-FMT-ABGR32: - - 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_ABGR32`` + - 'AR24' - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` + - B\ :sub:`7-0` + - G\ :sub:`7-0` + - R\ :sub:`7-0` + - A\ :sub:`7-0` + * .. _V4L2-PIX-FMT-XBGR32: + + - ``V4L2_PIX_FMT_XBGR32`` + - 'XR24' + + - B\ :sub:`7-0` + - G\ :sub:`7-0` + - R\ :sub:`7-0` + - X\ :sub:`7-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` + - A\ :sub:`7-0` + - B\ :sub:`7-0` + - G\ :sub:`7-0` + - R\ :sub:`7-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` + - X\ :sub:`7-0` + - B\ :sub:`7-0` + - G\ :sub:`7-0` + - R\ :sub:`7-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` + - R\ :sub:`7-0` + - G\ :sub:`7-0` + - B\ :sub:`7-0` + - A\ :sub:`7-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` - - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` - - `-` + - R\ :sub:`7-0` + - G\ :sub:`7-0` + - B\ :sub:`7-0` + - X\ :sub:`7-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` + - A\ :sub:`7-0` + - R\ :sub:`7-0` + - G\ :sub:`7-0` + - B\ :sub:`7-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` + - X\ :sub:`7-0` + - R\ :sub:`7-0` + - G\ :sub:`7-0` + - B\ :sub:`7-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. +Deprecated RGB Formats +====================== +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)`` is ill-defined and they are interpreted as in either +the corresponding ARGB or XRGB format, depending on the driver. .. raw:: latex diff --git a/Documentation/userspace-api/media/v4l/pixfmt-uyvy.rst b/Documentation/userspace-api/media/v4l/pixfmt-uyvy.rst deleted file mode 100644 index bae975fb14f6..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-uyvy.rst +++ /dev/null @@ -1,110 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-UYVY: - -************************** -V4L2_PIX_FMT_UYVY ('UYVY') -************************** - - -Variation of ``V4L2_PIX_FMT_YUYV`` with different order of samples in -memory - - -Description -=========== - -In this format each four bytes is two pixels. Each four bytes is two -Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr -belong to both pixels. As you can see, the Cr and Cb components have -half the horizontal resolution of the Y component. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Cb\ :sub:`00` - - Y'\ :sub:`00` - - Cr\ :sub:`00` - - Y'\ :sub:`01` - - Cb\ :sub:`01` - - Y'\ :sub:`02` - - Cr\ :sub:`01` - - Y'\ :sub:`03` - * - start + 8: - - Cb\ :sub:`10` - - Y'\ :sub:`10` - - Cr\ :sub:`10` - - Y'\ :sub:`11` - - Cb\ :sub:`11` - - Y'\ :sub:`12` - - Cr\ :sub:`11` - - Y'\ :sub:`13` - * - start + 16: - - Cb\ :sub:`20` - - Y'\ :sub:`20` - - Cr\ :sub:`20` - - Y'\ :sub:`21` - - Cb\ :sub:`21` - - Y'\ :sub:`22` - - Cr\ :sub:`21` - - Y'\ :sub:`23` - * - start + 24: - - Cb\ :sub:`30` - - Y'\ :sub:`30` - - Cr\ :sub:`30` - - Y'\ :sub:`31` - - Cb\ :sub:`31` - - Y'\ :sub:`32` - - Cr\ :sub:`31` - - Y'\ :sub:`33` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - C - - Y - - Y - - C - - Y - * - 1 - - Y - - C - - Y - - Y - - C - - Y - * - 2 - - Y - - C - - Y - - Y - - C - - Y - * - 3 - - Y - - C - - Y - - Y - - C - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-vyuy.rst b/Documentation/userspace-api/media/v4l/pixfmt-vyuy.rst deleted file mode 100644 index aff8588b67a9..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-vyuy.rst +++ /dev/null @@ -1,108 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-VYUY: - -************************** -V4L2_PIX_FMT_VYUY ('VYUY') -************************** - - -Variation of ``V4L2_PIX_FMT_YUYV`` with different order of samples in -memory - - -Description -=========== - -In this format each four bytes is two pixels. Each four bytes is two -Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr -belong to both pixels. As you can see, the Cr and Cb components have -half the horizontal resolution of the Y component. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Cr\ :sub:`00` - - Y'\ :sub:`00` - - Cb\ :sub:`00` - - Y'\ :sub:`01` - - Cr\ :sub:`01` - - Y'\ :sub:`02` - - Cb\ :sub:`01` - - Y'\ :sub:`03` - * - start + 8: - - Cr\ :sub:`10` - - Y'\ :sub:`10` - - Cb\ :sub:`10` - - Y'\ :sub:`11` - - Cr\ :sub:`11` - - Y'\ :sub:`12` - - Cb\ :sub:`11` - - Y'\ :sub:`13` - * - start + 16: - - Cr\ :sub:`20` - - Y'\ :sub:`20` - - Cb\ :sub:`20` - - Y'\ :sub:`21` - - Cr\ :sub:`21` - - Y'\ :sub:`22` - - Cb\ :sub:`21` - - Y'\ :sub:`23` - * - start + 24: - - Cr\ :sub:`30` - - Y'\ :sub:`30` - - Cb\ :sub:`30` - - Y'\ :sub:`31` - - Cr\ :sub:`31` - - Y'\ :sub:`32` - - Cb\ :sub:`31` - - Y'\ :sub:`33` - - -**Color Sample Location:** - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - - - 2 - - 3 - * - 0 - - Y - - C - - Y - - Y - - C - - Y - * - 1 - - Y - - C - - Y - - Y - - C - - Y - * - 2 - - Y - - C - - Y - - Y - - C - - Y - * - 3 - - Y - - C - - Y - - Y - - C - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y10.rst b/Documentation/userspace-api/media/v4l/pixfmt-y10.rst deleted file mode 100644 index 05f018dd883f..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y10.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-Y10: - -************************* -V4L2_PIX_FMT_Y10 ('Y10 ') -************************* - - -Grey-scale image - - -Description -=========== - -This is a grey-scale image with a depth of 10 bits per pixel. Pixels are -stored in 16-bit words with unused high bits padded with 0. The least -significant byte is stored at lower memory addresses (little-endian). - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00low` - - Y'\ :sub:`00high` - - Y'\ :sub:`01low` - - Y'\ :sub:`01high` - - Y'\ :sub:`02low` - - Y'\ :sub:`02high` - - Y'\ :sub:`03low` - - Y'\ :sub:`03high` - * - start + 8: - - Y'\ :sub:`10low` - - Y'\ :sub:`10high` - - Y'\ :sub:`11low` - - Y'\ :sub:`11high` - - Y'\ :sub:`12low` - - Y'\ :sub:`12high` - - Y'\ :sub:`13low` - - Y'\ :sub:`13high` - * - start + 16: - - Y'\ :sub:`20low` - - Y'\ :sub:`20high` - - Y'\ :sub:`21low` - - Y'\ :sub:`21high` - - Y'\ :sub:`22low` - - Y'\ :sub:`22high` - - Y'\ :sub:`23low` - - Y'\ :sub:`23high` - * - start + 24: - - Y'\ :sub:`30low` - - Y'\ :sub:`30high` - - Y'\ :sub:`31low` - - Y'\ :sub:`31high` - - Y'\ :sub:`32low` - - Y'\ :sub:`32high` - - Y'\ :sub:`33low` - - Y'\ :sub:`33high` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y10b.rst b/Documentation/userspace-api/media/v4l/pixfmt-y10b.rst deleted file mode 100644 index 38d353b37df9..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y10b.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-Y10BPACK: - -****************************** -V4L2_PIX_FMT_Y10BPACK ('Y10B') -****************************** - -Grey-scale image as a bit-packed array - - -Description -=========== - -This is a packed grey-scale image format with a depth of 10 bits per -pixel. Pixels are stored in a bit-packed array of 10bit bits per pixel, -with no padding between them and with the most significant bits coming -first from the left. - -**Bit-packed representation.** - -pixels cross the byte boundary and have a ratio of 5 bytes for each 4 -pixels. - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - Y'\ :sub:`00[9:2]` - - Y'\ :sub:`00[1:0]`\ Y'\ :sub:`01[9:4]` - - Y'\ :sub:`01[3:0]`\ Y'\ :sub:`02[9:6]` - - Y'\ :sub:`02[5:0]`\ Y'\ :sub:`03[9:8]` - - Y'\ :sub:`03[7:0]` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y10p.rst b/Documentation/userspace-api/media/v4l/pixfmt-y10p.rst deleted file mode 100644 index dd20d3438732..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y10p.rst +++ /dev/null @@ -1,43 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-Y10P: - -****************************** -V4L2_PIX_FMT_Y10P ('Y10P') -****************************** - -Grey-scale image as a MIPI RAW10 packed array - - -Description -=========== - -This is a packed grey-scale image format with a depth of 10 bits per -pixel. Every four consecutive pixels are packed into 5 bytes. Each of -the first 4 bytes contain the 8 high order bits of the pixels, and -the 5th byte contains the 2 least significants bits of each pixel, -in the same order. - -**Bit-packed representation.** - -.. raw:: latex - - \small - -.. tabularcolumns:: |p{1.2cm}||p{1.2cm}||p{1.2cm}||p{1.2cm}|p{3.2cm}|p{3.2cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 8 8 8 8 64 - - * - Y'\ :sub:`00[9:2]` - - Y'\ :sub:`01[9:2]` - - Y'\ :sub:`02[9:2]` - - Y'\ :sub:`03[9:2]` - - Y'\ :sub:`03[1:0]`\ (bits 7--6) Y'\ :sub:`02[1:0]`\ (bits 5--4) - Y'\ :sub:`01[1:0]`\ (bits 3--2) Y'\ :sub:`00[1:0]`\ (bits 1--0) - -.. raw:: latex - - \normalsize diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y12.rst b/Documentation/userspace-api/media/v4l/pixfmt-y12.rst deleted file mode 100644 index 20e12a18da72..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y12.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-Y12: - -************************* -V4L2_PIX_FMT_Y12 ('Y12 ') -************************* - - -Grey-scale image - - -Description -=========== - -This is a grey-scale image with a depth of 12 bits per pixel. Pixels are -stored in 16-bit words with unused high bits padded with 0. The least -significant byte is stored at lower memory addresses (little-endian). - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00low` - - Y'\ :sub:`00high` - - Y'\ :sub:`01low` - - Y'\ :sub:`01high` - - Y'\ :sub:`02low` - - Y'\ :sub:`02high` - - Y'\ :sub:`03low` - - Y'\ :sub:`03high` - * - start + 8: - - Y'\ :sub:`10low` - - Y'\ :sub:`10high` - - Y'\ :sub:`11low` - - Y'\ :sub:`11high` - - Y'\ :sub:`12low` - - Y'\ :sub:`12high` - - Y'\ :sub:`13low` - - Y'\ :sub:`13high` - * - start + 16: - - Y'\ :sub:`20low` - - Y'\ :sub:`20high` - - Y'\ :sub:`21low` - - Y'\ :sub:`21high` - - Y'\ :sub:`22low` - - Y'\ :sub:`22high` - - Y'\ :sub:`23low` - - Y'\ :sub:`23high` - * - start + 24: - - Y'\ :sub:`30low` - - Y'\ :sub:`30high` - - Y'\ :sub:`31low` - - Y'\ :sub:`31high` - - Y'\ :sub:`32low` - - Y'\ :sub:`32high` - - Y'\ :sub:`33low` - - Y'\ :sub:`33high` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y14.rst b/Documentation/userspace-api/media/v4l/pixfmt-y14.rst deleted file mode 100644 index 2a4826b77105..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y14.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-Y14: - -************************* -V4L2_PIX_FMT_Y14 ('Y14 ') -************************* - - -Grey-scale image - - -Description -=========== - -This is a grey-scale image with a depth of 14 bits per pixel. Pixels are -stored in 16-bit words with unused high bits padded with 0. The least -significant byte is stored at lower memory addresses (little-endian). - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00low` - - Y'\ :sub:`00high` - - Y'\ :sub:`01low` - - Y'\ :sub:`01high` - - Y'\ :sub:`02low` - - Y'\ :sub:`02high` - - Y'\ :sub:`03low` - - Y'\ :sub:`03high` - * - start + 8: - - Y'\ :sub:`10low` - - Y'\ :sub:`10high` - - Y'\ :sub:`11low` - - Y'\ :sub:`11high` - - Y'\ :sub:`12low` - - Y'\ :sub:`12high` - - Y'\ :sub:`13low` - - Y'\ :sub:`13high` - * - start + 16: - - Y'\ :sub:`20low` - - Y'\ :sub:`20high` - - Y'\ :sub:`21low` - - Y'\ :sub:`21high` - - Y'\ :sub:`22low` - - Y'\ :sub:`22high` - - Y'\ :sub:`23low` - - Y'\ :sub:`23high` - * - start + 24: - - Y'\ :sub:`30low` - - Y'\ :sub:`30high` - - Y'\ :sub:`31low` - - Y'\ :sub:`31high` - - Y'\ :sub:`32low` - - Y'\ :sub:`32high` - - Y'\ :sub:`33low` - - Y'\ :sub:`33high` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y16-be.rst b/Documentation/userspace-api/media/v4l/pixfmt-y16-be.rst deleted file mode 100644 index 6d70cd78cbf6..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y16-be.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-Y16-BE: - -**************************************** -V4L2_PIX_FMT_Y16_BE ('Y16 ' | (1 << 31)) -**************************************** - - -Grey-scale image - - -Description -=========== - -This is a grey-scale image with a depth of 16 bits per pixel. The most -significant byte is stored at lower memory addresses (big-endian). - -.. note:: - - The actual sampling precision may be lower than 16 bits, for - example 10 bits per pixel with values in range 0 to 1023. - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00high` - - Y'\ :sub:`00low` - - Y'\ :sub:`01high` - - Y'\ :sub:`01low` - - Y'\ :sub:`02high` - - Y'\ :sub:`02low` - - Y'\ :sub:`03high` - - Y'\ :sub:`03low` - * - start + 8: - - Y'\ :sub:`10high` - - Y'\ :sub:`10low` - - Y'\ :sub:`11high` - - Y'\ :sub:`11low` - - Y'\ :sub:`12high` - - Y'\ :sub:`12low` - - Y'\ :sub:`13high` - - Y'\ :sub:`13low` - * - start + 16: - - Y'\ :sub:`20high` - - Y'\ :sub:`20low` - - Y'\ :sub:`21high` - - Y'\ :sub:`21low` - - Y'\ :sub:`22high` - - Y'\ :sub:`22low` - - Y'\ :sub:`23high` - - Y'\ :sub:`23low` - * - start + 24: - - Y'\ :sub:`30high` - - Y'\ :sub:`30low` - - Y'\ :sub:`31high` - - Y'\ :sub:`31low` - - Y'\ :sub:`32high` - - Y'\ :sub:`32low` - - Y'\ :sub:`33high` - - Y'\ :sub:`33low` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y16.rst b/Documentation/userspace-api/media/v4l/pixfmt-y16.rst deleted file mode 100644 index 398ad8ba5d64..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y16.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-Y16: - -************************* -V4L2_PIX_FMT_Y16 ('Y16 ') -************************* - - -Grey-scale image - - -Description -=========== - -This is a grey-scale image with a depth of 16 bits per pixel. The least -significant byte is stored at lower memory addresses (little-endian). - -.. note:: - - The actual sampling precision may be lower than 16 bits, for - example 10 bits per pixel with values in range 0 to 1023. - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00low` - - Y'\ :sub:`00high` - - Y'\ :sub:`01low` - - Y'\ :sub:`01high` - - Y'\ :sub:`02low` - - Y'\ :sub:`02high` - - Y'\ :sub:`03low` - - Y'\ :sub:`03high` - * - start + 8: - - Y'\ :sub:`10low` - - Y'\ :sub:`10high` - - Y'\ :sub:`11low` - - Y'\ :sub:`11high` - - Y'\ :sub:`12low` - - Y'\ :sub:`12high` - - Y'\ :sub:`13low` - - Y'\ :sub:`13high` - * - start + 16: - - Y'\ :sub:`20low` - - Y'\ :sub:`20high` - - Y'\ :sub:`21low` - - Y'\ :sub:`21high` - - Y'\ :sub:`22low` - - Y'\ :sub:`22high` - - Y'\ :sub:`23low` - - Y'\ :sub:`23high` - * - start + 24: - - Y'\ :sub:`30low` - - Y'\ :sub:`30high` - - Y'\ :sub:`31low` - - Y'\ :sub:`31high` - - Y'\ :sub:`32low` - - Y'\ :sub:`32high` - - Y'\ :sub:`33low` - - Y'\ :sub:`33high` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y41p.rst b/Documentation/userspace-api/media/v4l/pixfmt-y41p.rst deleted file mode 100644 index d14cedf8f317..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-y41p.rst +++ /dev/null @@ -1,151 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-Y41P: - -************************** -V4L2_PIX_FMT_Y41P ('Y41P') -************************** - - -Format with ¼ horizontal chroma resolution, also known as YUV 4:1:1 - - -Description -=========== - -In this format each 12 bytes is eight pixels. In the twelve bytes are -two CbCr pairs and eight Y's. The first CbCr pair goes with the first -four Y's, and the second CbCr pair goes with the other four Y's. The Cb -and Cr components have one fourth the horizontal resolution of the Y -component. - -Do not confuse this format with -:ref:`V4L2_PIX_FMT_YUV411P <V4L2-PIX-FMT-YUV411P>`. Y41P is derived -from "YUV 4:1:1 *packed*", while YUV411P stands for "YUV 4:1:1 -*planar*". - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Cb\ :sub:`00` - - Y'\ :sub:`00` - - Cr\ :sub:`00` - - Y'\ :sub:`01` - - Cb\ :sub:`01` - - Y'\ :sub:`02` - - Cr\ :sub:`01` - - Y'\ :sub:`03` - - Y'\ :sub:`04` - - Y'\ :sub:`05` - - Y'\ :sub:`06` - - Y'\ :sub:`07` - * - start + 12: - - Cb\ :sub:`10` - - Y'\ :sub:`10` - - Cr\ :sub:`10` - - Y'\ :sub:`11` - - Cb\ :sub:`11` - - Y'\ :sub:`12` - - Cr\ :sub:`11` - - Y'\ :sub:`13` - - Y'\ :sub:`14` - - Y'\ :sub:`15` - - Y'\ :sub:`16` - - Y'\ :sub:`17` - * - start + 24: - - Cb\ :sub:`20` - - Y'\ :sub:`20` - - Cr\ :sub:`20` - - Y'\ :sub:`21` - - Cb\ :sub:`21` - - Y'\ :sub:`22` - - Cr\ :sub:`21` - - Y'\ :sub:`23` - - Y'\ :sub:`24` - - Y'\ :sub:`25` - - Y'\ :sub:`26` - - Y'\ :sub:`27` - * - start + 36: - - Cb\ :sub:`30` - - Y'\ :sub:`30` - - Cr\ :sub:`30` - - Y'\ :sub:`31` - - Cb\ :sub:`31` - - Y'\ :sub:`32` - - Cr\ :sub:`31` - - Y'\ :sub:`33` - - Y'\ :sub:`34` - - Y'\ :sub:`35` - - Y'\ :sub:`36` - - Y'\ :sub:`37` - - -**Color Sample Location:** - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - 1 - - - - 2 - - 3 - - 4 - - 5 - - - - 6 - - 7 - * - 0 - - Y - - Y - - C - - Y - - Y - - Y - - Y - - C - - Y - - Y - * - 1 - - Y - - Y - - C - - Y - - Y - - Y - - Y - - C - - Y - - Y - * - 2 - - Y - - Y - - C - - Y - - Y - - Y - - Y - - C - - Y - - Y - * - 3 - - Y - - Y - - C - - Y - - Y - - Y - - Y - - C - - Y - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst new file mode 100644 index 000000000000..0c8c5e0a380e --- /dev/null +++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst @@ -0,0 +1,126 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _yuv-luma-only: + +***************** +Luma-Only Formats +***************** + +This family of formats only store the luma component of a Y'CbCr image. They +are often referred to as greyscale formats. + +.. note:: + + - In all the tables that follow, bit 7 is the most significant bit in a byte. + - Formats are described with the minimum number of pixels needed to create a + byte-aligned repeating pattern. `...` indicates repetition of the pattern. + - Y'\ :sub:`x`\ [9:2] denotes bits 9 to 2 of the Y' value for pixel at colum + `x`. + - `0` denotes padding bits set to 0. + + +.. flat-table:: Luma-Only Image Formats + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Byte 0 + - Byte 1 + - Byte 2 + - Byte 3 + - Byte 4 + + * .. _V4L2-PIX-FMT-GREY: + + - ``V4L2_PIX_FMT_GREY`` + - 'GREY' + + - Y'\ :sub:`0`\ [7:0] + - ... + - ... + - ... + - ... + + * .. _V4L2-PIX-FMT-Y10: + + - ``V4L2_PIX_FMT_Y10`` + - 'Y10 ' + + - Y'\ :sub:`0`\ [7:0] + - `000000` Y'\ :sub:`0`\ [9:8] + - ... + - ... + - ... + + * .. _V4L2-PIX-FMT-Y10BPACK: + + - ``V4L2_PIX_FMT_Y10BPACK`` + - 'Y10B' + + - Y'\ :sub:`0`\ [9:2] + - Y'\ :sub:`0`\ [1:0] Y'\ :sub:`1`\ [9:4] + - Y'\ :sub:`1`\ [3:0] Y'\ :sub:`2`\ [9:6] + - Y'\ :sub:`2`\ [5:0] Y'\ :sub:`3`\ [9:8] + - Y'\ :sub:`3`\ [7:0] + + * .. _V4L2-PIX-FMT-Y10P: + + - ``V4L2_PIX_FMT_Y10P`` + - 'Y10P' + + - Y'\ :sub:`0`\ [7:0] + - Y'\ :sub:`1`\ [9:8] + - Y'\ :sub:`2`\ [9:2] + - Y'\ :sub:`3`\ [9:2] + - Y'\ :sub:`3`\ [1:0] Y'\ :sub:`2`\ [1:0] Y'\ :sub:`1`\ [1:0] Y'\ :sub:`0`\ [1:0] + + * .. _V4L2-PIX-FMT-Y12: + + - ``V4L2_PIX_FMT_Y12`` + - 'Y12 ' + + - Y'\ :sub:`0`\ [7:0] + - `0000` Y'\ :sub:`0`\ [11:8] + - ... + - ... + - ... + + * .. _V4L2-PIX-FMT-Y14: + + - ``V4L2_PIX_FMT_Y14`` + - 'Y14 ' + + - Y'\ :sub:`0`\ [7:0] + - `00` Y'\ :sub:`0`\ [13:8] + - ... + - ... + - ... + + * .. _V4L2-PIX-FMT-Y16: + + - ``V4L2_PIX_FMT_Y16`` + - 'Y16 ' + + - Y'\ :sub:`0`\ [7:0] + - Y'\ :sub:`0`\ [15:8] + - ... + - ... + - ... + + * .. _V4L2-PIX-FMT-Y16-BE: + + - ``V4L2_PIX_FMT_Y16_BE`` + - 'Y16 ' | (1U << 31) + + - Y'\ :sub:`0`\ [15:8] + - Y'\ :sub:`0`\ [7:0] + - ... + - ... + - ... + +.. note:: + + For the Y16 and Y16_BE formats, the actual sampling precision may be lower + than 16 bits. For example, 10 bits per pixel uses values in the range 0 to + 1023. diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst new file mode 100644 index 000000000000..7d4d39201a3f --- /dev/null +++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst @@ -0,0 +1,950 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. planar-yuv: + +****************** +Planar YUV formats +****************** + +Planar formats split luma and chroma data in separate memory regions. They +exist in two variants: + +- Semi-planar formats use two planes. The first plane is the luma plane and + stores the Y components. The second plane is the chroma plane and stores the + Cb and Cr components interleaved. + +- Fully planar formats use three planes to store the Y, Cb and Cr components + separately. + +Within a plane, components are stored in pixel order, which may be linear or +tiled. Padding may be supported at the end of the lines, and the line stride of +the chroma planes may be constrained by the line stride of the luma plane. + +Some planar formats allow planes to be placed in independent memory locations. +They are identified by an 'M' suffix in their name (such as in +``V4L2_PIX_FMT_NV12M``). Those formats are intended to be used only in drivers +and applications that support the multi-planar API, described in +:ref:`planar-apis`. Unless explicitly documented as supporting non-contiguous +planes, formats require the planes to follow each other immediately in memory. + + +Semi-Planar YUV Formats +======================= + +These formats are commonly referred to as NV formats (NV12, NV16, ...). They +use two planes, and store the luma components in the first plane and the chroma +components in the second plane. The Cb and Cr components are interleaved in the +chroma plane, with Cb and Cr always stored in pairs. The chroma order is +exposed as different formats. + +For memory contiguous formats, the number of padding pixels at the end of the +chroma lines is identical to the padding of the luma lines. Without horizontal +subsampling, the chroma line stride (in bytes) is thus equal to twice the luma +line stride. With horizontal subsampling by 2, the chroma line stride is equal +to the luma line stride. Vertical subsampling doesn't affect the line stride. + +For non-contiguous formats, no constraints are enforced by the format on the +relationship between the luma and chroma line padding and stride. + +All components are stored with the same number of bits per component. + +.. flat-table:: Overview of Semi-Planar YUV Formats + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Bits per component + - Subsampling + - Chroma order [1]_ + - Contiguous [2]_ + - Tiling [3]_ + * - V4L2_PIX_FMT_NV12 + - 'NV12' + - 8 + - 4:2:0 + - Cb, Cr + - Yes + - Linear + * - V4L2_PIX_FMT_NV21 + - 'NV21' + - 8 + - 4:2:0 + - Cr, Cr + - Yes + - Linear + * - V4L2_PIX_FMT_NV12M + - 'NM12' + - 8 + - 4:2:0 + - Cb, Cr + - No + - Linear + * - V4L2_PIX_FMT_NV21M + - 'NM21' + - 8 + - 4:2:0 + - Cr, Cr + - No + - Linear + * - V4L2_PIX_FMT_NV12MT + - 'TM12' + - 8 + - 4:2:0 + - Cb, Cr + - No + - 64x32 macroblocks + + Horizontal Z order + * - V4L2_PIX_FMT_NV12MT_16X16 + - 'VM12' + - 8 + - 4:2:2 + - Cb, Cr + - No + - 16x16 macroblocks + * - V4L2_PIX_FMT_NV16 + - 'NV16' + - 8 + - 4:2:2 + - Cb, Cr + - Yes + - Linear + * - V4L2_PIX_FMT_NV61 + - 'NV61' + - 8 + - 4:2:2 + - Cr, Cr + - Yes + - Linear + * - V4L2_PIX_FMT_NV16M + - 'NM16' + - 8 + - 4:2:2 + - Cb, Cr + - No + - Linear + * - V4L2_PIX_FMT_NV61M + - 'NM61' + - 8 + - 4:2:2 + - Cr, Cr + - No + - Linear + * - V4L2_PIX_FMT_NV24 + - 'NV24' + - 8 + - 4:4:4 + - Cb, Cr + - Yes + - Linear + * - V4L2_PIX_FMT_NV42 + - 'NV42' + - 8 + - 4:4:4 + - Cr, Cr + - Yes + - Linear + +.. note:: + + .. [1] Order of chroma samples in the second plane + .. [2] Indicates if planes have to be contiguous in memory or can be + disjoint + .. [3] Macroblock size in pixels + + +**Color Sample Location:** +Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>` +horizontally. + + +.. _V4L2-PIX-FMT-NV12: +.. _V4L2-PIX-FMT-NV21: +.. _V4L2-PIX-FMT-NV12M: +.. _V4L2-PIX-FMT-NV21M: + +NV12, NV21, NV12M and NV21M +--------------------------- + +Semi-planar YUV 4:2:0 formats. The chroma plane is subsampled by 2 in each +direction. Chroma lines contain half the number of pixels and the same number +of bytes as luma lines, and the chroma plane contains half the number of lines +of the luma plane. + +.. flat-table:: Sample 4x4 NV12 Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 16: + - Cb\ :sub:`00` + - Cr\ :sub:`00` + - Cb\ :sub:`01` + - Cr\ :sub:`01` + * - start + 20: + - Cb\ :sub:`10` + - Cr\ :sub:`10` + - Cb\ :sub:`11` + - Cr\ :sub:`11` + +.. flat-table:: Sample 4x4 NV12M Image + :header-rows: 0 + :stub-columns: 0 + + * - start0 + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start0 + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start0 + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start0 + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - + * - start1 + 0: + - Cb\ :sub:`00` + - Cr\ :sub:`00` + - Cb\ :sub:`01` + - Cr\ :sub:`01` + * - start1 + 4: + - Cb\ :sub:`10` + - Cr\ :sub:`10` + - Cb\ :sub:`11` + - Cr\ :sub:`11` + + +.. _V4L2-PIX-FMT-NV12MT: +.. _V4L2-PIX-FMT-NV12MT-16X16: + +NV12MT and MV12MT_16X16 +----------------------- + +Semi-planar YUV 4:2:0 formats, using macroblock tiling. The chroma plane is +subsampled by 2 in each direction. Chroma lines contain half the number of +pixels and the same number of bytes as luma lines, and the chroma plane +contains half the number of lines of the luma plane. + +``V4L2_PIX_FMT_NV12MT_16X16`` stores pixel in 2D 16x16 macroblocks, and stores +macroblocks linearly in memory. The line stride and image height must be +aligned to a multiple of 16. The layouts of the luma and chroma planes are +identical. + +``V4L2_PIX_FMT_NV12MT`` stores pixels in 2D 64x32 macroblocks, and stores 2x2 +groups of macroblocks in Z-order in memory, alternating Z and mirrored Z shapes +horizontally. The line stride must be a multiple of 128 pixels to ensure an +integer number of Z shapes. The image height must be a multiple of 32 pixels. +If the vertical resolution is an odd number of macroblocks, the last row of +macroblocks is stored in linear order. The layouts of the luma and chroma +planes are identical. + +.. _nv12mt: + +.. kernel-figure:: nv12mt.svg + :alt: nv12mt.svg + :align: center + + V4L2_PIX_FMT_NV12MT macroblock Z shape memory layout + +.. _nv12mt_ex: + +.. kernel-figure:: nv12mt_example.svg + :alt: nv12mt_example.svg + :align: center + + Example V4L2_PIX_FMT_NV12MT memory layout of macroblocks + + +.. _V4L2-PIX-FMT-NV16: +.. _V4L2-PIX-FMT-NV61: +.. _V4L2-PIX-FMT-NV16M: +.. _V4L2-PIX-FMT-NV61M: + +NV16, NV61, NV16M and NV61M +--------------------------- + +Semi-planar YUV 4:2:2 formats. The chroma plane is subsampled by 2 in the +horizontal direction. Chroma lines contain half the number of pixels and the +same number of bytes as luma lines, and the chroma plane contains the same +number of lines as the luma plane. + +.. flat-table:: Sample 4x4 NV16 Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 16: + - Cb\ :sub:`00` + - Cr\ :sub:`00` + - Cb\ :sub:`01` + - Cr\ :sub:`01` + * - start + 20: + - Cb\ :sub:`10` + - Cr\ :sub:`10` + - Cb\ :sub:`11` + - Cr\ :sub:`11` + * - start + 24: + - Cb\ :sub:`20` + - Cr\ :sub:`20` + - Cb\ :sub:`21` + - Cr\ :sub:`21` + * - start + 28: + - Cb\ :sub:`30` + - Cr\ :sub:`30` + - Cb\ :sub:`31` + - Cr\ :sub:`31` + +.. flat-table:: Sample 4x4 NV16M Image + :header-rows: 0 + :stub-columns: 0 + + * - start0 + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start0 + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start0 + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start0 + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - + * - start1 + 0: + - Cb\ :sub:`00` + - Cr\ :sub:`00` + - Cb\ :sub:`02` + - Cr\ :sub:`02` + * - start1 + 4: + - Cb\ :sub:`10` + - Cr\ :sub:`10` + - Cb\ :sub:`12` + - Cr\ :sub:`12` + * - start1 + 8: + - Cb\ :sub:`20` + - Cr\ :sub:`20` + - Cb\ :sub:`22` + - Cr\ :sub:`22` + * - start1 + 12: + - Cb\ :sub:`30` + - Cr\ :sub:`30` + - Cb\ :sub:`32` + - Cr\ :sub:`32` + + +.. _V4L2-PIX-FMT-NV24: +.. _V4L2-PIX-FMT-NV42: + +NV24 and NV42 +------------- + +Semi-planar YUV 4:4:4 formats. The chroma plane is subsampled by 2 in the +horizontal direction. Chroma lines contain half the number of pixels and the +same number of bytes as luma lines, and the chroma plane contains the same +number of lines as the luma plane. + +.. flat-table:: Sample 4x4 NV24 Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 16: + - Cb\ :sub:`00` + - Cr\ :sub:`00` + - Cb\ :sub:`01` + - Cr\ :sub:`01` + - Cb\ :sub:`02` + - Cr\ :sub:`02` + - Cb\ :sub:`03` + - Cr\ :sub:`03` + * - start + 24: + - Cb\ :sub:`10` + - Cr\ :sub:`10` + - Cb\ :sub:`11` + - Cr\ :sub:`11` + - Cb\ :sub:`12` + - Cr\ :sub:`12` + - Cb\ :sub:`13` + - Cr\ :sub:`13` + * - start + 32: + - Cb\ :sub:`20` + - Cr\ :sub:`20` + - Cb\ :sub:`21` + - Cr\ :sub:`21` + - Cb\ :sub:`22` + - Cr\ :sub:`22` + - Cb\ :sub:`23` + - Cr\ :sub:`23` + * - start + 40: + - Cb\ :sub:`30` + - Cr\ :sub:`30` + - Cb\ :sub:`31` + - Cr\ :sub:`31` + - Cb\ :sub:`32` + - Cr\ :sub:`32` + - Cb\ :sub:`33` + - Cr\ :sub:`33` + + +Fully Planar YUV Formats +======================== + +These formats store the Y, Cb and Cr components in three separate planes. The +luma plane comes first, and the order of the two chroma planes varies between +formats. The two chroma planes always use the same subsampling. + +For memory contiguous formats, the number of padding pixels at the end of the +chroma lines is identical to the padding of the luma lines. The chroma line +stride (in bytes) is thus equal to the luma line stride divided by the +horizontal subsampling factor. Vertical subsampling doesn't affect the line +stride. + +For non-contiguous formats, no constraints are enforced by the format on the +relationship between the luma and chroma line padding and stride. + +All components are stored with the same number of bits per component. + +.. flat-table:: Overview of Fully Planar YUV Formats + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Bits per component + - Subsampling + - Planes order [4]_ + - Contiguous [5]_ + + * - V4L2_PIX_FMT_YUV410 + - 'YUV9' + - 8 + - 4:1:0 + - Y, Cb, Cr + - Yes + * - V4L2_PIX_FMT_YVU410 + - 'YVU9' + - 8 + - 4:1:0 + - Y, Cr, Cb + - Yes + * - V4L2_PIX_FMT_YUV411P + - '411P' + - 8 + - 4:1:1 + - Y, Cb, Cr + - Yes + * - V4L2_PIX_FMT_YUV420M + - 'YM12' + - 8 + - 4:2:0 + - Y, Cb, Cr + - No + * - V4L2_PIX_FMT_YVU420M + - 'YM21' + - 8 + - 4:2:0 + - Y, Cr, Cb + - No + * - V4L2_PIX_FMT_YUV420 + - 'YU12' + - 8 + - 4:2:0 + - Y, Cb, Cr + - Yes + * - V4L2_PIX_FMT_YVU420 + - 'YV12' + - 8 + - 4:2:0 + - Y, Cr, Cb + - Yes + * - V4L2_PIX_FMT_YUV422P + - '422P' + - 8 + - 4:2:2 + - Y, Cb, Cr + - Yes + * - V4L2_PIX_FMT_YUV422M + - 'YM16' + - 8 + - 4:2:2 + - Y, Cb, Cr + - No + * - V4L2_PIX_FMT_YVU422M + - 'YM61' + - 8 + - 4:2:2 + - Y, Cr, Cb + - No + * - V4L2_PIX_FMT_YUV444M + - 'YM24' + - 8 + - 4:4:4 + - Y, Cb, Cr + - No + * - V4L2_PIX_FMT_YVU444M + - 'YM42' + - 8 + - 4:4:4 + - Y, Cr, Cb + - No + +.. note:: + + .. [4] Order of luma and chroma planes + .. [5] Indicates if planes have to be contiguous in memory or can be + disjoint + + +**Color Sample Location:** +Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>` +horizontally. + +.. _V4L2-PIX-FMT-YUV410: +.. _V4L2-PIX-FMT-YVU410: + +YUV410 and YVU410 +----------------- + +Planar YUV 4:1:0 formats. The chroma planes are subsampled by 4 in each +direction. Chroma lines contain a quarter of the number of pixels and bytes of +the luma lines, and the chroma planes contain a quarter of the number of lines +of the luma plane. + +.. flat-table:: Sample 4x4 YUV410 Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 16: + - Cr\ :sub:`00` + * - start + 17: + - Cb\ :sub:`00` + + +.. _V4L2-PIX-FMT-YUV411P: + +YUV411P +------- + +Planar YUV 4:1:1 formats. The chroma planes are subsampled by 4 in the +horizontal direction. Chroma lines contain a quarter of the number of pixels +and bytes of the luma lines, and the chroma planes contain the same number of +lines as the luma plane. + +.. flat-table:: Sample 4x4 YUV411P Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 16: + - Cb\ :sub:`00` + * - start + 17: + - Cb\ :sub:`10` + * - start + 18: + - Cb\ :sub:`20` + * - start + 19: + - Cb\ :sub:`30` + * - start + 20: + - Cr\ :sub:`00` + * - start + 21: + - Cr\ :sub:`10` + * - start + 22: + - Cr\ :sub:`20` + * - start + 23: + - Cr\ :sub:`30` + + +.. _V4L2-PIX-FMT-YUV420: +.. _V4L2-PIX-FMT-YVU420: +.. _V4L2-PIX-FMT-YUV420M: +.. _V4L2-PIX-FMT-YVU420M: + +YUV420, YVU420, YUV420M and YVU420M +----------------------------------- + +Planar YUV 4:2:0 formats. The chroma planes are subsampled by 2 in each +direction. Chroma lines contain half of the number of pixels and bytes of the +luma lines, and the chroma planes contain half of the number of lines of the +luma plane. + +.. flat-table:: Sample 4x4 YUV420 Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 16: + - Cr\ :sub:`00` + - Cr\ :sub:`01` + * - start + 18: + - Cr\ :sub:`10` + - Cr\ :sub:`11` + * - start + 20: + - Cb\ :sub:`00` + - Cb\ :sub:`01` + * - start + 22: + - Cb\ :sub:`10` + - Cb\ :sub:`11` + +.. flat-table:: Sample 4x4 YUV420M Image + :header-rows: 0 + :stub-columns: 0 + + * - start0 + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start0 + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start0 + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start0 + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - + * - start1 + 0: + - Cb\ :sub:`00` + - Cb\ :sub:`01` + * - start1 + 2: + - Cb\ :sub:`10` + - Cb\ :sub:`11` + * - + * - start2 + 0: + - Cr\ :sub:`00` + - Cr\ :sub:`01` + * - start2 + 2: + - Cr\ :sub:`10` + - Cr\ :sub:`11` + + +.. _V4L2-PIX-FMT-YUV422P: +.. _V4L2-PIX-FMT-YUV422M: +.. _V4L2-PIX-FMT-YVU422M: + +YUV422P, YUV422M and YVU422M +---------------------------- + +Planar YUV 4:2:2 formats. The chroma planes are subsampled by 2 in the +horizontal direction. Chroma lines contain half of the number of pixels and +bytes of the luma lines, and the chroma planes contain the same number of lines +as the luma plane. + +.. flat-table:: Sample 4x4 YUV422P Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 16: + - Cb\ :sub:`00` + - Cb\ :sub:`01` + * - start + 18: + - Cb\ :sub:`10` + - Cb\ :sub:`11` + * - start + 20: + - Cb\ :sub:`20` + - Cb\ :sub:`21` + * - start + 22: + - Cb\ :sub:`30` + - Cb\ :sub:`31` + * - start + 24: + - Cr\ :sub:`00` + - Cr\ :sub:`01` + * - start + 26: + - Cr\ :sub:`10` + - Cr\ :sub:`11` + * - start + 28: + - Cr\ :sub:`20` + - Cr\ :sub:`21` + * - start + 30: + - Cr\ :sub:`30` + - Cr\ :sub:`31` + +.. flat-table:: Sample 4x4 YUV422M Image + :header-rows: 0 + :stub-columns: 0 + + * - start0 + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start0 + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start0 + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start0 + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - + * - start1 + 0: + - Cb\ :sub:`00` + - Cb\ :sub:`01` + * - start1 + 2: + - Cb\ :sub:`10` + - Cb\ :sub:`11` + * - start1 + 4: + - Cb\ :sub:`20` + - Cb\ :sub:`21` + * - start1 + 6: + - Cb\ :sub:`30` + - Cb\ :sub:`31` + * - + * - start2 + 0: + - Cr\ :sub:`00` + - Cr\ :sub:`01` + * - start2 + 2: + - Cr\ :sub:`10` + - Cr\ :sub:`11` + * - start2 + 4: + - Cr\ :sub:`20` + - Cr\ :sub:`21` + * - start2 + 6: + - Cr\ :sub:`30` + - Cr\ :sub:`31` + + +.. _V4L2-PIX-FMT-YUV444M: +.. _V4L2-PIX-FMT-YVU444M: + +YUV444M and YVU444M +------------------- + +Planar YUV 4:4:4 formats. The chroma planes are no subsampled. Chroma lines +contain the same number of pixels and bytes of the luma lines, and the chroma +planes contain the same number of lines as the luma plane. + +.. flat-table:: Sample 4x4 YUV444M Image + :header-rows: 0 + :stub-columns: 0 + + * - start0 + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start0 + 4: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start0 + 8: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start0 + 12: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - + * - start1 + 0: + - Cb\ :sub:`00` + - Cb\ :sub:`01` + - Cb\ :sub:`02` + - Cb\ :sub:`03` + * - start1 + 4: + - Cb\ :sub:`10` + - Cb\ :sub:`11` + - Cb\ :sub:`12` + - Cb\ :sub:`13` + * - start1 + 8: + - Cb\ :sub:`20` + - Cb\ :sub:`21` + - Cb\ :sub:`22` + - Cb\ :sub:`23` + * - start1 + 12: + - Cb\ :sub:`20` + - Cb\ :sub:`21` + - Cb\ :sub:`32` + - Cb\ :sub:`33` + * - + * - start2 + 0: + - Cr\ :sub:`00` + - Cr\ :sub:`01` + - Cr\ :sub:`02` + - Cr\ :sub:`03` + * - start2 + 4: + - Cr\ :sub:`10` + - Cr\ :sub:`11` + - Cr\ :sub:`12` + - Cr\ :sub:`13` + * - start2 + 8: + - Cr\ :sub:`20` + - Cr\ :sub:`21` + - Cr\ :sub:`22` + - Cr\ :sub:`23` + * - start2 + 12: + - Cr\ :sub:`30` + - Cr\ :sub:`31` + - Cr\ :sub:`32` + - Cr\ :sub:`33` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv410.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv410.rst deleted file mode 100644 index de2e519adc60..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv410.rst +++ /dev/null @@ -1,127 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-YVU410: -.. _v4l2-pix-fmt-yuv410: - -********************************************************** -V4L2_PIX_FMT_YVU410 ('YVU9'), V4L2_PIX_FMT_YUV410 ('YUV9') -********************************************************** - - -V4L2_PIX_FMT_YUV410 -Planar formats with ¼ horizontal and vertical chroma resolution, also -known as YUV 4:1:0 - - -Description -=========== - -These are planar formats, as opposed to a packed format. The three -components are separated into three sub-images or planes. The Y plane is -first. The Y plane has one byte per pixel. For ``V4L2_PIX_FMT_YVU410``, -the Cr plane immediately follows the Y plane in memory. The Cr plane is -¼ the width and ¼ the height of the Y plane (and of the image). Each Cr -belongs to 16 pixels, a four-by-four square of the image. Following the -Cr plane is the Cb plane, just like the Cr plane. -``V4L2_PIX_FMT_YUV410`` is the same, except the Cb plane comes first, -then the Cr plane. - -If the Y plane has pad bytes after each row, then the Cr and Cb planes -have ¼ as many pad bytes after their rows. In other words, four Cx rows -(including padding) are exactly as long as one Y row (including -padding). - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - start + 16: - - Cr\ :sub:`00` - * - start + 17: - - Cb\ :sub:`00` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - - - Y - - - - Y - * - - * - 1 - - Y - - - - Y - - - - Y - - - - Y - * - - - - - - - - - C - - - - - - - * - 2 - - Y - - - - Y - - - - Y - - - - Y - * - - * - 3 - - Y - - - - Y - - - - Y - - - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv411p.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv411p.rst deleted file mode 100644 index 998aa9b1328f..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv411p.rst +++ /dev/null @@ -1,115 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-YUV411P: - -***************************** -V4L2_PIX_FMT_YUV411P ('411P') -***************************** - - -Format with ¼ horizontal chroma resolution, also known as YUV 4:1:1. -Planar layout as opposed to ``V4L2_PIX_FMT_Y41P`` - - -Description -=========== - -This format is not commonly used. This is a planar format similar to the -4:2:2 planar format except with half as many chroma. The three -components are separated into three sub-images or planes. The Y plane is -first. The Y plane has one byte per pixel. The Cb plane immediately -follows the Y plane in memory. The Cb plane is ¼ the width of the Y -plane (and of the image). Each Cb belongs to 4 pixels all on the same -row. For example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`, -Y'\ :sub:`02` and Y'\ :sub:`03`. Following the Cb plane is the Cr plane, -just like the Cb plane. - -If the Y plane has pad bytes after each row, then the Cr and Cb planes -have ¼ as many pad bytes after their rows. In other words, four C x rows -(including padding) is exactly as long as one Y row (including padding). - -**Byte Order.** -Each cell is one byte. - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - start + 16: - - Cb\ :sub:`00` - * - start + 17: - - Cb\ :sub:`10` - * - start + 18: - - Cb\ :sub:`20` - * - start + 19: - - Cb\ :sub:`30` - * - start + 20: - - Cr\ :sub:`00` - * - start + 21: - - Cr\ :sub:`10` - * - start + 22: - - Cr\ :sub:`20` - * - start + 23: - - Cr\ :sub:`30` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - 1 - - - - 2 - - 3 - * - 0 - - Y - - Y - - C - - Y - - Y - * - 1 - - Y - - Y - - C - - Y - - Y - * - 2 - - Y - - Y - - C - - Y - - Y - * - 3 - - Y - - Y - - C - - Y - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv420.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv420.rst deleted file mode 100644 index f1c7baf32685..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv420.rst +++ /dev/null @@ -1,143 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-YVU420: -.. _V4L2-PIX-FMT-YUV420: - -********************************************************** -V4L2_PIX_FMT_YVU420 ('YV12'), V4L2_PIX_FMT_YUV420 ('YU12') -********************************************************** - - -V4L2_PIX_FMT_YUV420 -Planar formats with ½ horizontal and vertical chroma resolution, also -known as YUV 4:2:0 - - -Description -=========== - -These are planar formats, as opposed to a packed format. The three -components are separated into three sub- images or planes. The Y plane -is first. The Y plane has one byte per pixel. For -``V4L2_PIX_FMT_YVU420``, the Cr plane immediately follows the Y plane in -memory. The Cr plane is half the width and half the height of the Y -plane (and of the image). Each Cr belongs to four pixels, a two-by-two -square of the image. For example, Cr\ :sub:`0` belongs to Y'\ :sub:`00`, -Y'\ :sub:`01`, Y'\ :sub:`10`, and Y'\ :sub:`11`. Following the Cr plane -is the Cb plane, just like the Cr plane. ``V4L2_PIX_FMT_YUV420`` is the -same except the Cb plane comes first, then the Cr plane. - -If the Y plane has pad bytes after each row, then the Cr and Cb planes -have half as many pad bytes after their rows. In other words, two Cx -rows (including padding) is exactly as long as one Y row (including -padding). - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - start + 16: - - Cr\ :sub:`00` - - Cr\ :sub:`01` - * - start + 18: - - Cr\ :sub:`10` - - Cr\ :sub:`11` - * - start + 20: - - Cb\ :sub:`00` - - Cb\ :sub:`01` - * - start + 22: - - Cb\ :sub:`10` - - Cb\ :sub:`11` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - - - Y - - - - Y - * - - - - - C - - - - - - - - C - - - * - 1 - - Y - - - - Y - - - - Y - - - - Y - * - - * - 2 - - Y - - - - Y - - - - Y - - - - Y - * - - - - - C - - - - - - - - C - - - * - 3 - - Y - - - - Y - - - - Y - - - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv420m.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv420m.rst deleted file mode 100644 index cd20a57e0621..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv420m.rst +++ /dev/null @@ -1,152 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-YUV420M: -.. _v4l2-pix-fmt-yvu420m: - -************************************************************ -V4L2_PIX_FMT_YUV420M ('YM12'), V4L2_PIX_FMT_YVU420M ('YM21') -************************************************************ - - -V4L2_PIX_FMT_YVU420M -Variation of ``V4L2_PIX_FMT_YUV420`` and ``V4L2_PIX_FMT_YVU420`` with -planes non contiguous in memory. - - -Description -=========== - -This is a multi-planar format, as opposed to a packed format. The three -components are separated into three sub-images or planes. - -The Y plane is first. The Y plane has one byte per pixel. For -``V4L2_PIX_FMT_YUV420M`` the Cb data constitutes the second plane which -is half the width and half the height of the Y plane (and of the image). -Each Cb belongs to four pixels, a two-by-two square of the image. For -example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`, -Y'\ :sub:`10`, and Y'\ :sub:`11`. The Cr data, just like the Cb plane, -is in the third plane. - -``V4L2_PIX_FMT_YVU420M`` is the same except the Cr data is stored in the -second plane and the Cb data in the third plane. - -If the Y plane has pad bytes after each row, then the Cb and Cr planes -have half as many pad bytes after their rows. In other words, two Cx -rows (including padding) is exactly as long as one Y row (including -padding). - -``V4L2_PIX_FMT_YUV420M`` and ``V4L2_PIX_FMT_YVU420M`` are intended to be -used only in drivers and applications that support the multi-planar API, -described in :ref:`planar-apis`. - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start0 + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start0 + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start0 + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start0 + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - - * - start1 + 0: - - Cb\ :sub:`00` - - Cb\ :sub:`01` - * - start1 + 2: - - Cb\ :sub:`10` - - Cb\ :sub:`11` - * - - * - start2 + 0: - - Cr\ :sub:`00` - - Cr\ :sub:`01` - * - start2 + 2: - - Cr\ :sub:`10` - - Cr\ :sub:`11` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - - - 2 - - - - 3 - * - 0 - - Y - - - - Y - - - - Y - - - - Y - * - - - - - C - - - - - - - - C - - - * - 1 - - Y - - - - Y - - - - Y - - - - Y - * - - * - 2 - - Y - - - - Y - - - - Y - - - - Y - * - - - - - C - - - - - - - - C - - - * - 3 - - Y - - - - Y - - - - Y - - - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv422m.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv422m.rst deleted file mode 100644 index 32bf15e1426e..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv422m.rst +++ /dev/null @@ -1,141 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-YUV422M: -.. _v4l2-pix-fmt-yvu422m: - -************************************************************ -V4L2_PIX_FMT_YUV422M ('YM16'), V4L2_PIX_FMT_YVU422M ('YM61') -************************************************************ - - -V4L2_PIX_FMT_YVU422M -Planar formats with ½ horizontal resolution, also known as YUV and YVU -4:2:2 - - -Description -=========== - -This is a multi-planar format, as opposed to a packed format. The three -components are separated into three sub-images or planes. - -The Y plane is first. The Y plane has one byte per pixel. For -``V4L2_PIX_FMT_YUV422M`` the Cb data constitutes the second plane which -is half the width of the Y plane (and of the image). Each Cb belongs to -two pixels. For example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`, -Y'\ :sub:`01`. The Cr data, just like the Cb plane, is in the third -plane. - -``V4L2_PIX_FMT_YVU422M`` is the same except the Cr data is stored in the -second plane and the Cb data in the third plane. - -If the Y plane has pad bytes after each row, then the Cb and Cr planes -have half as many pad bytes after their rows. In other words, two Cx -rows (including padding) is exactly as long as one Y row (including -padding). - -``V4L2_PIX_FMT_YUV422M`` and ``V4L2_PIX_FMT_YVU422M`` are intended to be -used only in drivers and applications that support the multi-planar API, -described in :ref:`planar-apis`. - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start0 + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start0 + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start0 + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start0 + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - - * - start1 + 0: - - Cb\ :sub:`00` - - Cb\ :sub:`01` - * - start1 + 2: - - Cb\ :sub:`10` - - Cb\ :sub:`11` - * - start1 + 4: - - Cb\ :sub:`20` - - Cb\ :sub:`21` - * - start1 + 6: - - Cb\ :sub:`30` - - Cb\ :sub:`31` - * - - * - start2 + 0: - - Cr\ :sub:`00` - - Cr\ :sub:`01` - * - start2 + 2: - - Cr\ :sub:`10` - - Cr\ :sub:`11` - * - start2 + 4: - - Cr\ :sub:`20` - - Cr\ :sub:`21` - * - start2 + 6: - - Cr\ :sub:`30` - - Cr\ :sub:`31` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - C - - Y - - Y - - C - - Y - * - 1 - - Y - - C - - Y - - Y - - C - - Y - * - 2 - - Y - - C - - Y - - Y - - C - - Y - * - 3 - - Y - - C - - Y - - Y - - C - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv422p.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv422p.rst deleted file mode 100644 index b178be558361..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv422p.rst +++ /dev/null @@ -1,129 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-YUV422P: - -***************************** -V4L2_PIX_FMT_YUV422P ('422P') -***************************** - - -Format with ½ horizontal chroma resolution, also known as YUV 4:2:2. -Planar layout as opposed to ``V4L2_PIX_FMT_YUYV`` - - -Description -=========== - -This format is not commonly used. This is a planar version of the YUYV -format. The three components are separated into three sub-images or -planes. The Y plane is first. The Y plane has one byte per pixel. The Cb -plane immediately follows the Y plane in memory. The Cb plane is half -the width of the Y plane (and of the image). Each Cb belongs to two -pixels. For example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`, -Y'\ :sub:`01`. Following the Cb plane is the Cr plane, just like the Cb -plane. - -If the Y plane has pad bytes after each row, then the Cr and Cb planes -have half as many pad bytes after their rows. In other words, two Cx -rows (including padding) is exactly as long as one Y row (including -padding). - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - start + 16: - - Cb\ :sub:`00` - - Cb\ :sub:`01` - * - start + 18: - - Cb\ :sub:`10` - - Cb\ :sub:`11` - * - start + 20: - - Cb\ :sub:`20` - - Cb\ :sub:`21` - * - start + 22: - - Cb\ :sub:`30` - - Cb\ :sub:`31` - * - start + 24: - - Cr\ :sub:`00` - - Cr\ :sub:`01` - * - start + 26: - - Cr\ :sub:`10` - - Cr\ :sub:`11` - * - start + 28: - - Cr\ :sub:`20` - - Cr\ :sub:`21` - * - start + 30: - - Cr\ :sub:`30` - - Cr\ :sub:`31` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - C - - Y - - Y - - C - - Y - * - 1 - - Y - - C - - Y - - Y - - C - - Y - * - 2 - - Y - - C - - Y - - Y - - C - - Y - * - 3 - - Y - - C - - Y - - Y - - C - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv444m.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv444m.rst deleted file mode 100644 index 90bdee2e2b0d..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv444m.rst +++ /dev/null @@ -1,141 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-YUV444M: -.. _v4l2-pix-fmt-yvu444m: - -************************************************************ -V4L2_PIX_FMT_YUV444M ('YM24'), V4L2_PIX_FMT_YVU444M ('YM42') -************************************************************ - - -V4L2_PIX_FMT_YVU444M -Planar formats with full horizontal resolution, also known as YUV and -YVU 4:4:4 - - -Description -=========== - -This is a multi-planar format, as opposed to a packed format. The three -components are separated into three sub-images or planes. - -The Y plane is first. The Y plane has one byte per pixel. For -``V4L2_PIX_FMT_YUV444M`` the Cb data constitutes the second plane which -is the same width and height as the Y plane (and as the image). The Cr -data, just like the Cb plane, is in the third plane. - -``V4L2_PIX_FMT_YVU444M`` is the same except the Cr data is stored in the -second plane and the Cb data in the third plane. - -If the Y plane has pad bytes after each row, then the Cb and Cr planes -have the same number of pad bytes after their rows. - -``V4L2_PIX_FMT_YUV444M`` and ``V4L2_PIX_FMT_YUV444M`` are intended to be -used only in drivers and applications that support the multi-planar API, -described in :ref:`planar-apis`. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start0 + 0: - - Y'\ :sub:`00` - - Y'\ :sub:`01` - - Y'\ :sub:`02` - - Y'\ :sub:`03` - * - start0 + 4: - - Y'\ :sub:`10` - - Y'\ :sub:`11` - - Y'\ :sub:`12` - - Y'\ :sub:`13` - * - start0 + 8: - - Y'\ :sub:`20` - - Y'\ :sub:`21` - - Y'\ :sub:`22` - - Y'\ :sub:`23` - * - start0 + 12: - - Y'\ :sub:`30` - - Y'\ :sub:`31` - - Y'\ :sub:`32` - - Y'\ :sub:`33` - * - - * - start1 + 0: - - Cb\ :sub:`00` - - Cb\ :sub:`01` - - Cb\ :sub:`02` - - Cb\ :sub:`03` - * - start1 + 4: - - Cb\ :sub:`10` - - Cb\ :sub:`11` - - Cb\ :sub:`12` - - Cb\ :sub:`13` - * - start1 + 8: - - Cb\ :sub:`20` - - Cb\ :sub:`21` - - Cb\ :sub:`22` - - Cb\ :sub:`23` - * - start1 + 12: - - Cb\ :sub:`20` - - Cb\ :sub:`21` - - Cb\ :sub:`32` - - Cb\ :sub:`33` - * - - * - start2 + 0: - - Cr\ :sub:`00` - - Cr\ :sub:`01` - - Cr\ :sub:`02` - - Cr\ :sub:`03` - * - start2 + 4: - - Cr\ :sub:`10` - - Cr\ :sub:`11` - - Cr\ :sub:`12` - - Cr\ :sub:`13` - * - start2 + 8: - - Cr\ :sub:`20` - - Cr\ :sub:`21` - - Cr\ :sub:`22` - - Cr\ :sub:`23` - * - start2 + 12: - - Cr\ :sub:`30` - - Cr\ :sub:`31` - - Cr\ :sub:`32` - - Cr\ :sub:`33` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - 1 - - 2 - - 3 - * - 0 - - YC - - YC - - YC - - YC - * - 1 - - YC - - YC - - YC - - YC - * - 2 - - YC - - YC - - YC - - YC - * - 3 - - YC - - YC - - YC - - YC diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuyv.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuyv.rst deleted file mode 100644 index ca073a5098a9..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuyv.rst +++ /dev/null @@ -1,118 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-YUYV: - -************************** -V4L2_PIX_FMT_YUYV ('YUYV') -************************** - - -Packed format with ½ horizontal chroma resolution, also known as YUV -4:2:2 - - -Description -=========== - -In this format each four bytes is two pixels. Each four bytes is two -Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr -belong to both pixels. As you can see, the Cr and Cb components have -half the horizontal resolution of the Y component. ``V4L2_PIX_FMT_YUYV`` -is known in the Windows environment as YUY2. - -**Byte Order.** -Each cell is one byte. - - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Cb\ :sub:`00` - - Y'\ :sub:`01` - - Cr\ :sub:`00` - - Y'\ :sub:`02` - - Cb\ :sub:`01` - - Y'\ :sub:`03` - - Cr\ :sub:`01` - * - start + 8: - - Y'\ :sub:`10` - - Cb\ :sub:`10` - - Y'\ :sub:`11` - - Cr\ :sub:`10` - - Y'\ :sub:`12` - - Cb\ :sub:`11` - - Y'\ :sub:`13` - - Cr\ :sub:`11` - * - start + 16: - - Y'\ :sub:`20` - - Cb\ :sub:`20` - - Y'\ :sub:`21` - - Cr\ :sub:`20` - - Y'\ :sub:`22` - - Cb\ :sub:`21` - - Y'\ :sub:`23` - - Cr\ :sub:`21` - * - start + 24: - - Y'\ :sub:`30` - - Cb\ :sub:`30` - - Y'\ :sub:`31` - - Cr\ :sub:`30` - - Y'\ :sub:`32` - - Cb\ :sub:`31` - - Y'\ :sub:`33` - - Cr\ :sub:`31` - - -**Color Sample Location:** - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - - - 2 - - - - 3 - * - 0 - - Y - - C - - Y - - - - Y - - C - - Y - * - 1 - - Y - - C - - Y - - - - Y - - C - - Y - * - 2 - - Y - - C - - Y - - - - Y - - C - - Y - * - 3 - - Y - - C - - Y - - - - Y - - C - - Y diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yvyu.rst b/Documentation/userspace-api/media/v4l/pixfmt-yvyu.rst deleted file mode 100644 index 81ebec525ae5..000000000000 --- a/Documentation/userspace-api/media/v4l/pixfmt-yvyu.rst +++ /dev/null @@ -1,108 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _V4L2-PIX-FMT-YVYU: - -************************** -V4L2_PIX_FMT_YVYU ('YVYU') -************************** - - -Variation of ``V4L2_PIX_FMT_YUYV`` with different order of samples in -memory - - -Description -=========== - -In this format each four bytes is two pixels. Each four bytes is two -Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr -belong to both pixels. As you can see, the Cr and Cb components have -half the horizontal resolution of the Y component. - -**Byte Order.** -Each cell is one byte. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - start + 0: - - Y'\ :sub:`00` - - Cr\ :sub:`00` - - Y'\ :sub:`01` - - Cb\ :sub:`00` - - Y'\ :sub:`02` - - Cr\ :sub:`01` - - Y'\ :sub:`03` - - Cb\ :sub:`01` - * - start + 8: - - Y'\ :sub:`10` - - Cr\ :sub:`10` - - Y'\ :sub:`11` - - Cb\ :sub:`10` - - Y'\ :sub:`12` - - Cr\ :sub:`11` - - Y'\ :sub:`13` - - Cb\ :sub:`11` - * - start + 16: - - Y'\ :sub:`20` - - Cr\ :sub:`20` - - Y'\ :sub:`21` - - Cb\ :sub:`20` - - Y'\ :sub:`22` - - Cr\ :sub:`21` - - Y'\ :sub:`23` - - Cb\ :sub:`21` - * - start + 24: - - Y'\ :sub:`30` - - Cr\ :sub:`30` - - Y'\ :sub:`31` - - Cb\ :sub:`30` - - Y'\ :sub:`32` - - Cr\ :sub:`31` - - Y'\ :sub:`33` - - Cb\ :sub:`31` - - -**Color Sample Location:** - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - - - 0 - - - - 1 - - 2 - - - - 3 - * - 0 - - Y - - C - - Y - - Y - - C - - Y - * - 1 - - Y - - C - - Y - - Y - - C - - Y - * - 2 - - Y - - C - - Y - - Y - - C - - Y - * - 3 - - Y - - C - - Y - - Y - - C - - Y diff --git a/Documentation/userspace-api/media/v4l/selection-api-configuration.rst b/Documentation/userspace-api/media/v4l/selection-api-configuration.rst index 37617eda2fa6..fee49bf1a1c0 100644 --- a/Documentation/userspace-api/media/v4l/selection-api-configuration.rst +++ b/Documentation/userspace-api/media/v4l/selection-api-configuration.rst @@ -94,7 +94,7 @@ specified using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. The top left corner, width and height of the source rectangle, that is the area from which image date are processed by the hardware, is given -by the ``V4L2_SEL_TGT_CROP``. Its coordinates are expressed in in the +by the ``V4L2_SEL_TGT_CROP``. Its coordinates are expressed in the same coordinate system as the bounds rectangle. The active cropping area must lie completely inside the crop boundaries and the driver may further adjust the requested size and/or position according to hardware diff --git a/Documentation/userspace-api/media/v4l/subdev-formats.rst b/Documentation/userspace-api/media/v4l/subdev-formats.rst index c9b7bb3ca089..7f16cbe46e5c 100644 --- a/Documentation/userspace-api/media/v4l/subdev-formats.rst +++ b/Documentation/userspace-api/media/v4l/subdev-formats.rst @@ -7899,3 +7899,30 @@ formats. - 0x5001 - Interleaved raw UYVY and JPEG image format with embedded meta-data used by Samsung S3C73MX camera sensors. + +.. _v4l2-mbus-metadata-fmts: + +Metadata Formats +^^^^^^^^^^^^^^^^ + +This section lists all metadata formats. + +The following table lists the existing metadata formats. + +.. tabularcolumns:: |p{8.0cm}|p{1.4cm}|p{7.7cm}| + +.. flat-table:: Metadata formats + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Comments + * .. _MEDIA-BUS-FMT-METADATA-FIXED: + + - MEDIA_BUS_FMT_METADATA_FIXED + - 0x7001 + - This format should be used when the same driver handles + both sides of the link and the bus format is a fixed + metadata format that is not configurable from userspace. + Width and height will be set to 0 for this format. diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst b/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst index f2173e310d67..b9c62affbb5a 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst @@ -53,7 +53,7 @@ by the ``controls`` fields. To get the current value of a set of controls applications initialize the ``id``, ``size`` and ``reserved2`` fields of each struct :c:type:`v4l2_ext_control` and call the -:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl. String controls controls must also set the +:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl. String controls must also set the ``string`` field. Controls of compound types (``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set) must set the ``ptr`` field. @@ -180,10 +180,38 @@ still cause this situation. - ``p_u32`` - A pointer to a matrix control of unsigned 32-bit values. Valid if this control is of type ``V4L2_CTRL_TYPE_U32``. - * - :c:type:`v4l2_area` * + * - struct :c:type:`v4l2_area` * - ``p_area`` - A pointer to a struct :c:type:`v4l2_area`. Valid if this control is of type ``V4L2_CTRL_TYPE_AREA``. + * - struct :c:type:`v4l2_ctrl_h264_sps` * + - ``p_h264_sps`` + - A pointer to a struct :c:type:`v4l2_ctrl_h264_sps`. Valid if this control is + of type ``V4L2_CTRL_TYPE_H264_SPS``. + * - struct :c:type:`v4l2_ctrl_h264_pps` * + - ``p_h264_pps`` + - A pointer to a struct :c:type:`v4l2_ctrl_h264_pps`. Valid if this control is + of type ``V4L2_CTRL_TYPE_H264_PPS``. + * - struct :c:type:`v4l2_ctrl_h264_scaling_matrix` * + - ``p_h264_scaling_matrix`` + - A pointer to a struct :c:type:`v4l2_ctrl_h264_scaling_matrix`. Valid if this control is + of type ``V4L2_CTRL_TYPE_H264_SCALING_MATRIX``. + * - struct :c:type:`v4l2_ctrl_h264_pred_weights` * + - ``p_h264_pred_weights`` + - A pointer to a struct :c:type:`v4l2_ctrl_h264_pred_weights`. Valid if this control is + of type ``V4L2_CTRL_TYPE_H264_PRED_WEIGHTS``. + * - struct :c:type:`v4l2_ctrl_h264_slice_params` * + - ``p_h264_slice_params`` + - A pointer to a struct :c:type:`v4l2_ctrl_h264_slice_params`. Valid if this control is + of type ``V4L2_CTRL_TYPE_H264_SLICE_PARAMS``. + * - struct :c:type:`v4l2_ctrl_h264_decode_params` * + - ``p_h264_decode_params`` + - A pointer to a struct :c:type:`v4l2_ctrl_h264_decode_params`. Valid if this control is + of type ``V4L2_CTRL_TYPE_H264_DECODE_PARAMS``. + * - struct :c:type:`v4l2_ctrl_fwht_params` * + - ``p_fwht_params`` + - A pointer to a struct :c:type:`v4l2_ctrl_fwht_params`. Valid if this control is + of type ``V4L2_CTRL_TYPE_FWHT_PARAMS``. * - void * - ``ptr`` - A pointer to a compound type which can be an N-dimensional array @@ -322,10 +350,10 @@ still cause this situation. :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` and :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` ioctl belong to this class. - * - ``V4L2_CTRL_CLASS_MPEG`` + * - ``V4L2_CTRL_CLASS_CODEC`` - 0x990000 - - The class containing MPEG compression controls. These controls are - described in :ref:`mpeg-controls`. + - The class containing stateful codec controls. These controls are + described in :ref:`codec-controls`. * - ``V4L2_CTRL_CLASS_CAMERA`` - 0x9a0000 - The class containing camera controls. These controls are described @@ -358,6 +386,14 @@ still cause this situation. - 0xa20000 - The class containing RF tuner controls. These controls are described in :ref:`rf-tuner-controls`. + * - ``V4L2_CTRL_CLASS_DETECT`` + - 0xa30000 + - The class containing motion or object detection controls. These controls + are described in :ref:`detect-controls`. + * - ``V4L2_CTRL_CLASS_CODEC_STATELESS`` + - 0xa40000 + - The class containing stateless codec controls. These controls are + described in :ref:`codec-stateless-controls`. Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-output.rst b/Documentation/userspace-api/media/v4l/vidioc-g-output.rst index 3138c4cc8fe3..dbcdd51dd2a8 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-output.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-output.rst @@ -46,7 +46,7 @@ To select a video output applications store the number of the desired output in an integer and call the :ref:`VIDIOC_S_OUTPUT <VIDIOC_G_OUTPUT>` ioctl with a pointer to this integer. Side effects are possible. For example outputs may support different video standards, so the driver may implicitly -switch the current standard. standard. Because of these possible side +switch the current standard. Because of these possible side effects applications must select an output before querying or negotiating any other parameters. diff --git a/Documentation/userspace-api/media/v4l/vidioc-qbuf.rst b/Documentation/userspace-api/media/v4l/vidioc-qbuf.rst index fbf8c5962d8a..77e0747a6d28 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-qbuf.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-qbuf.rst @@ -163,7 +163,7 @@ EINVAL The buffer ``type`` is not supported, or the ``index`` is out of bounds, or no buffers have been allocated yet, or the ``userptr`` or ``length`` are invalid, or the ``V4L2_BUF_FLAG_REQUEST_FD`` flag was - set but the the given ``request_fd`` was invalid, or ``m.fd`` was + set but the given ``request_fd`` was invalid, or ``m.fd`` was an invalid DMABUF file descriptor. EIO diff --git a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst index 9b8716f90f12..82f61f1e2fb8 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst @@ -462,6 +462,12 @@ See also the examples in :ref:`control`. - n/a - A struct :c:type:`v4l2_ctrl_h264_decode_params`, containing H264 decode parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_FWHT_PARAMS`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_fwht_params`, containing FWHT + parameters for stateless video decoders. * - ``V4L2_CTRL_TYPE_HEVC_SPS`` - n/a - n/a diff --git a/Documentation/userspace-api/media/v4l/yuv-formats.rst b/Documentation/userspace-api/media/v4l/yuv-formats.rst index 4a05a105a9e6..24b34cdfa6fe 100644 --- a/Documentation/userspace-api/media/v4l/yuv-formats.rst +++ b/Documentation/userspace-api/media/v4l/yuv-formats.rst @@ -14,44 +14,260 @@ reconstructed by subtracting from the brightness component. See :ref:`colorspaces` for conversion examples. YUV was chosen because early television would only transmit brightness information. To add color in a way compatible with existing receivers a new signal carrier -was added to transmit the color difference signals. Secondary in the YUV -format the U and V components usually have lower resolution than the Y -component. This is an analog video compression technique taking -advantage of a property of the human visual system, being more sensitive -to brightness information. +was added to transmit the color difference signals. + + +Subsampling +=========== + +YUV formats commonly encode images with a lower resolution for the chroma +components than for the luma component. This compression technique, taking +advantage of the human eye being more sensitive to luminance than color +differences, is called chroma subsampling. + +While many combinations of subsampling factors in the horizontal and vertical +direction are possible, common factors are 1 (no subsampling), 2 and 4, with +horizontal subsampling always larger than or equal to vertical subsampling. +Common combinations are named as follows. + +- `4:4:4`: No subsampling +- `4:2:2`: Horizontal subsampling by 2, no vertical subsampling +- `4:2:0`: Horizontal subsampling by 2, vertical subsampling by 2 +- `4:1:1`: Horizontal subsampling by 4, no vertical subsampling +- `4:1:0`: Horizontal subsampling by 4, vertical subsampling by 4 + +Subsampling the chroma component effectively creates chroma values that can be +located in different spatial locations: + +- .. _yuv-chroma-centered: + + The subsampled chroma value may be calculated by simply averaging the chroma + value of two consecutive pixels. It effectively models the chroma of a pixel + sited between the two original pixels. This is referred to as centered or + interstitially sited chroma. + +- .. _yuv-chroma-cosited: + + The other option is to subsample chroma values in a way that place them in + the same spatial sites as the pixels. This may be performed by skipping every + other chroma sample (creating aliasing artifacts), or with filters using an + odd number of taps. This is referred to as co-sited chroma. + +The following examples show different combination of chroma siting in a 4x4 +image. + +.. flat-table:: 4:2:2 subsampling, interstitially sited + :header-rows: 1 + :stub-columns: 1 + + * - + - 0 + - + - 1 + - + - 2 + - + - 3 + * - 0 + - Y + - C + - Y + - + - Y + - C + - Y + * - 1 + - Y + - C + - Y + - + - Y + - C + - Y + * - 2 + - Y + - C + - Y + - + - Y + - C + - Y + * - 3 + - Y + - C + - Y + - + - Y + - C + - Y + +.. flat-table:: 4:2:2 subsampling, co-sited + :header-rows: 1 + :stub-columns: 1 + + * - + - 0 + - + - 1 + - + - 2 + - + - 3 + * - 0 + - Y/C + - + - Y + - + - Y/C + - + - Y + * - 1 + - Y/C + - + - Y + - + - Y/C + - + - Y + * - 2 + - Y/C + - + - Y + - + - Y/C + - + - Y + * - 3 + - Y/C + - + - Y + - + - Y/C + - + - Y + +.. flat-table:: 4:2:0 subsampling, horizontally interstitially sited, vertically co-sited + :header-rows: 1 + :stub-columns: 1 + + * - + - 0 + - + - 1 + - + - 2 + - + - 3 + * - 0 + - Y + - C + - Y + - + - Y + - C + - Y + * - 1 + - Y + - + - Y + - + - Y + - + - Y + * - 2 + - Y + - C + - Y + - + - Y + - C + - Y + * - 3 + - Y + - + - Y + - + - Y + - + - Y + +.. flat-table:: 4:1:0 subsampling, horizontally and vertically interstitially sited + :header-rows: 1 + :stub-columns: 1 + + * - + - 0 + - + - 1 + - + - 2 + - + - 3 + * - 0 + - Y + - + - Y + - + - Y + - + - Y + * - + - + - + - + - + - + - + - + * - 1 + - Y + - + - Y + - + - Y + - + - Y + * - + - + - + - + - C + - + - + - + * - 2 + - Y + - + - Y + - + - Y + - + - Y + * - + - + - + - + - + - + - + - + * - 3 + - Y + - + - Y + - + - Y + - + - Y .. toctree:: :maxdepth: 1 pixfmt-packed-yuv - pixfmt-grey - pixfmt-y10 - pixfmt-y12 - pixfmt-y14 - pixfmt-y10b - pixfmt-y10p - pixfmt-y16 - pixfmt-y16-be + pixfmt-yuv-planar + pixfmt-yuv-luma pixfmt-y8i pixfmt-y12i pixfmt-uv8 - pixfmt-yuyv - pixfmt-uyvy - pixfmt-yvyu - pixfmt-vyuy - pixfmt-y41p - pixfmt-yuv420 - pixfmt-yuv420m - pixfmt-yuv422m - pixfmt-yuv444m - pixfmt-yuv410 - pixfmt-yuv422p - pixfmt-yuv411p - pixfmt-nv12 - pixfmt-nv12m - pixfmt-nv12mt - pixfmt-nv16 - pixfmt-nv16m - pixfmt-nv24 pixfmt-m420 diff --git a/Documentation/userspace-api/media/videodev2.h.rst.exceptions b/Documentation/userspace-api/media/videodev2.h.rst.exceptions index 121e396a2779..0ed170c6e720 100644 --- a/Documentation/userspace-api/media/videodev2.h.rst.exceptions +++ b/Documentation/userspace-api/media/videodev2.h.rst.exceptions @@ -139,12 +139,14 @@ 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_PRED_WEIGHTS :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` replace symbol V4L2_CTRL_TYPE_HEVC_SPS :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_HEVC_PPS :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_HEVC_SLICE_PARAMS :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_AREA :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_FWHT_PARAMS :c:type:`v4l2_ctrl_type` # V4L2 capability defines replace define V4L2_CAP_VIDEO_CAPTURE device-capabilities diff --git a/Documentation/virt/kvm/mmu.rst b/Documentation/virt/kvm/mmu.rst index 1c030dbac7c4..5bfe28b0728e 100644 --- a/Documentation/virt/kvm/mmu.rst +++ b/Documentation/virt/kvm/mmu.rst @@ -455,7 +455,7 @@ If the generation number of the spte does not equal the global generation number, it will ignore the cached MMIO information and handle the page fault through the slow path. -Since only 19 bits are used to store generation-number on mmio spte, all +Since only 18 bits are used to store generation-number on mmio spte, all pages are zapped when there is an overflow. Unfortunately, a single memory access might access kvm_memslots(kvm) multiple diff --git a/Documentation/x86/index.rst b/Documentation/x86/index.rst index b224d12c880b..647a570d4931 100644 --- a/Documentation/x86/index.rst +++ b/Documentation/x86/index.rst @@ -33,3 +33,4 @@ x86-specific Documentation i386/index x86_64/index sva + sgx diff --git a/Documentation/x86/sgx.rst b/Documentation/x86/sgx.rst new file mode 100644 index 000000000000..eaee1368b4fd --- /dev/null +++ b/Documentation/x86/sgx.rst @@ -0,0 +1,211 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=============================== +Software Guard eXtensions (SGX) +=============================== + +Overview +======== + +Software Guard eXtensions (SGX) hardware enables for user space applications +to set aside private memory regions of code and data: + +* Privileged (ring-0) ENCLS functions orchestrate the construction of the. + regions. +* Unprivileged (ring-3) ENCLU functions allow an application to enter and + execute inside the regions. + +These memory regions are called enclaves. An enclave can be only entered at a +fixed set of entry points. Each entry point can hold a single hardware thread +at a time. While the enclave is loaded from a regular binary file by using +ENCLS functions, only the threads inside the enclave can access its memory. The +region is denied from outside access by the CPU, and encrypted before it leaves +from LLC. + +The support can be determined by + + ``grep sgx /proc/cpuinfo`` + +SGX must both be supported in the processor and enabled by the BIOS. If SGX +appears to be unsupported on a system which has hardware support, ensure +support is enabled in the BIOS. If a BIOS presents a choice between "Enabled" +and "Software Enabled" modes for SGX, choose "Enabled". + +Enclave Page Cache +================== + +SGX utilizes an *Enclave Page Cache (EPC)* to store pages that are associated +with an enclave. It is contained in a BIOS-reserved region of physical memory. +Unlike pages used for regular memory, pages can only be accessed from outside of +the enclave during enclave construction with special, limited SGX instructions. + +Only a CPU executing inside an enclave can directly access enclave memory. +However, a CPU executing inside an enclave may access normal memory outside the +enclave. + +The kernel manages enclave memory similar to how it treats device memory. + +Enclave Page Types +------------------ + +**SGX Enclave Control Structure (SECS)** + Enclave's address range, attributes and other global data are defined + by this structure. + +**Regular (REG)** + Regular EPC pages contain the code and data of an enclave. + +**Thread Control Structure (TCS)** + Thread Control Structure pages define the entry points to an enclave and + track the execution state of an enclave thread. + +**Version Array (VA)** + Version Array pages contain 512 slots, each of which can contain a version + number for a page evicted from the EPC. + +Enclave Page Cache Map +---------------------- + +The processor tracks EPC pages in a hardware metadata structure called the +*Enclave Page Cache Map (EPCM)*. The EPCM contains an entry for each EPC page +which describes the owning enclave, access rights and page type among the other +things. + +EPCM permissions are separate from the normal page tables. This prevents the +kernel from, for instance, allowing writes to data which an enclave wishes to +remain read-only. EPCM permissions may only impose additional restrictions on +top of normal x86 page permissions. + +For all intents and purposes, the SGX architecture allows the processor to +invalidate all EPCM entries at will. This requires that software be prepared to +handle an EPCM fault at any time. In practice, this can happen on events like +power transitions when the ephemeral key that encrypts enclave memory is lost. + +Application interface +===================== + +Enclave build functions +----------------------- + +In addition to the traditional compiler and linker build process, SGX has a +separate enclave “build” process. Enclaves must be built before they can be +executed (entered). The first step in building an enclave is opening the +**/dev/sgx_enclave** device. Since enclave memory is protected from direct +access, special privileged instructions are Then used to copy data into enclave +pages and establish enclave page permissions. + +.. kernel-doc:: arch/x86/kernel/cpu/sgx/ioctl.c + :functions: sgx_ioc_enclave_create + sgx_ioc_enclave_add_pages + sgx_ioc_enclave_init + sgx_ioc_enclave_provision + +Enclave vDSO +------------ + +Entering an enclave can only be done through SGX-specific EENTER and ERESUME +functions, and is a non-trivial process. Because of the complexity of +transitioning to and from an enclave, enclaves typically utilize a library to +handle the actual transitions. This is roughly analogous to how glibc +implementations are used by most applications to wrap system calls. + +Another crucial characteristic of enclaves is that they can generate exceptions +as part of their normal operation that need to be handled in the enclave or are +unique to SGX. + +Instead of the traditional signal mechanism to handle these exceptions, SGX +can leverage special exception fixup provided by the vDSO. The kernel-provided +vDSO function wraps low-level transitions to/from the enclave like EENTER and +ERESUME. The vDSO function intercepts exceptions that would otherwise generate +a signal and return the fault information directly to its caller. This avoids +the need to juggle signal handlers. + +.. kernel-doc:: arch/x86/include/uapi/asm/sgx.h + :functions: vdso_sgx_enter_enclave_t + +ksgxd +===== + +SGX support includes a kernel thread called *ksgxwapd*. + +EPC sanitization +---------------- + +ksgxd is started when SGX initializes. Enclave memory is typically ready +For use when the processor powers on or resets. However, if SGX has been in +use since the reset, enclave pages may be in an inconsistent state. This might +occur after a crash and kexec() cycle, for instance. At boot, ksgxd +reinitializes all enclave pages so that they can be allocated and re-used. + +The sanitization is done by going through EPC address space and applying the +EREMOVE function to each physical page. Some enclave pages like SECS pages have +hardware dependencies on other pages which prevents EREMOVE from functioning. +Executing two EREMOVE passes removes the dependencies. + +Page reclaimer +-------------- + +Similar to the core kswapd, ksgxd, is responsible for managing the +overcommitment of enclave memory. If the system runs out of enclave memory, +*ksgxwapd* “swaps” enclave memory to normal memory. + +Launch Control +============== + +SGX provides a launch control mechanism. After all enclave pages have been +copied, kernel executes EINIT function, which initializes the enclave. Only after +this the CPU can execute inside the enclave. + +ENIT function takes an RSA-3072 signature of the enclave measurement. The function +checks that the measurement is correct and signature is signed with the key +hashed to the four **IA32_SGXLEPUBKEYHASH{0, 1, 2, 3}** MSRs representing the +SHA256 of a public key. + +Those MSRs can be configured by the BIOS to be either readable or writable. +Linux supports only writable configuration in order to give full control to the +kernel on launch control policy. Before calling EINIT function, the driver sets +the MSRs to match the enclave's signing key. + +Encryption engines +================== + +In order to conceal the enclave data while it is out of the CPU package, the +memory controller has an encryption engine to transparently encrypt and decrypt +enclave memory. + +In CPUs prior to Ice Lake, the Memory Encryption Engine (MEE) is used to +encrypt pages leaving the CPU caches. MEE uses a n-ary Merkle tree with root in +SRAM to maintain integrity of the encrypted data. This provides integrity and +anti-replay protection but does not scale to large memory sizes because the time +required to update the Merkle tree grows logarithmically in relation to the +memory size. + +CPUs starting from Icelake use Total Memory Encryption (TME) in the place of +MEE. TME-based SGX implementations do not have an integrity Merkle tree, which +means integrity and replay-attacks are not mitigated. B, it includes +additional changes to prevent cipher text from being returned and SW memory +aliases from being Created. + +DMA to enclave memory is blocked by range registers on both MEE and TME systems +(SDM section 41.10). + +Usage Models +============ + +Shared Library +-------------- + +Sensitive data and the code that acts on it is partitioned from the application +into a separate library. The library is then linked as a DSO which can be loaded +into an enclave. The application can then make individual function calls into +the enclave through special SGX instructions. A run-time within the enclave is +configured to marshal function parameters into and out of the enclave and to +call the correct library function. + +Application Container +--------------------- + +An application may be loaded into a container enclave which is specially +configured with a library OS and run-time which permits the application to run. +The enclave run-time and library OS work together to execute the application +when a thread enters the enclave. diff --git a/Documentation/xtensa/mmu.rst b/Documentation/xtensa/mmu.rst index e52a12960fdc..450573afa31a 100644 --- a/Documentation/xtensa/mmu.rst +++ b/Documentation/xtensa/mmu.rst @@ -82,7 +82,8 @@ Default MMUv2-compatible layout:: +------------------+ | VMALLOC area | VMALLOC_START 0xc0000000 128MB - 64KB +------------------+ VMALLOC_END - | Cache aliasing | TLBTEMP_BASE_1 0xc7ff0000 DCACHE_WAY_SIZE + +------------------+ + | Cache aliasing | TLBTEMP_BASE_1 0xc8000000 DCACHE_WAY_SIZE | remap area 1 | +------------------+ | Cache aliasing | TLBTEMP_BASE_2 DCACHE_WAY_SIZE @@ -124,7 +125,8 @@ Default MMUv2-compatible layout:: +------------------+ | VMALLOC area | VMALLOC_START 0xa0000000 128MB - 64KB +------------------+ VMALLOC_END - | Cache aliasing | TLBTEMP_BASE_1 0xa7ff0000 DCACHE_WAY_SIZE + +------------------+ + | Cache aliasing | TLBTEMP_BASE_1 0xa8000000 DCACHE_WAY_SIZE | remap area 1 | +------------------+ | Cache aliasing | TLBTEMP_BASE_2 DCACHE_WAY_SIZE @@ -167,7 +169,8 @@ Default MMUv2-compatible layout:: +------------------+ | VMALLOC area | VMALLOC_START 0x90000000 128MB - 64KB +------------------+ VMALLOC_END - | Cache aliasing | TLBTEMP_BASE_1 0x97ff0000 DCACHE_WAY_SIZE + +------------------+ + | Cache aliasing | TLBTEMP_BASE_1 0x98000000 DCACHE_WAY_SIZE | remap area 1 | +------------------+ | Cache aliasing | TLBTEMP_BASE_2 DCACHE_WAY_SIZE |