From caa7302b3a346d9a9ec85568cff52d2cee5f32c4 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Fri, 18 Jun 2021 16:21:36 +0200 Subject: media: include/uapi/linux/cec.h: typo: SATERDAY -> SATURDAY Fix typo in a define: CEC_OP_REC_SEQ_SATERDAY -> CEC_OP_REC_SEQ_SATURDAY This isn't used yet in actual applications to the best of my knowledge, and it certainly doesn't break the ABI since the value doesn't change. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/userspace-api/media/cec.h.rst.exceptions | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/userspace-api') diff --git a/Documentation/userspace-api/media/cec.h.rst.exceptions b/Documentation/userspace-api/media/cec.h.rst.exceptions index d83790ccac8e..13de01d9555e 100644 --- a/Documentation/userspace-api/media/cec.h.rst.exceptions +++ b/Documentation/userspace-api/media/cec.h.rst.exceptions @@ -140,7 +140,7 @@ ignore define CEC_OP_REC_SEQ_TUESDAY ignore define CEC_OP_REC_SEQ_WEDNESDAY ignore define CEC_OP_REC_SEQ_THURSDAY ignore define CEC_OP_REC_SEQ_FRIDAY -ignore define CEC_OP_REC_SEQ_SATERDAY +ignore define CEC_OP_REC_SEQ_SATURDAY ignore define CEC_OP_REC_SEQ_ONCE_ONLY ignore define CEC_MSG_CLEAR_DIGITAL_TIMER -- cgit v1.2.3 From 229e5bdcd39ed3ca0a71dc8500ba4ea90d4415db Mon Sep 17 00:00:00 2001 From: Jernej Skrabec Date: Sun, 6 Jun 2021 10:23:13 +0200 Subject: media: hevc: Add segment address field If HEVC frame consists of multiple slices, segment address has to be known in order to properly decode it. Add segment address field to slice parameters. Signed-off-by: Jernej Skrabec Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst | 3 +++ include/media/hevc-ctrls.h | 3 ++- 2 files changed, 5 insertions(+), 1 deletion(-) (limited to 'Documentation/userspace-api') diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst index 8c6e2a11ed95..dc096a5562cd 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst @@ -3000,6 +3000,9 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - * - __u8 - ``pic_struct`` - + * - __u32 + - ``slice_segment_addr`` + - * - __u8 - ``ref_idx_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` - The list of L0 reference elements as indices in the DPB. diff --git a/include/media/hevc-ctrls.h b/include/media/hevc-ctrls.h index 53c0038c792b..781371bff2ad 100644 --- a/include/media/hevc-ctrls.h +++ b/include/media/hevc-ctrls.h @@ -196,10 +196,11 @@ struct v4l2_ctrl_hevc_slice_params { __u8 pic_struct; /* ISO/IEC 23008-2, ITU-T Rec. H.265: General slice segment header */ + __u32 slice_segment_addr; __u8 ref_idx_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]; __u8 ref_idx_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]; - __u8 padding[5]; + __u8 padding; /* ISO/IEC 23008-2, ITU-T Rec. H.265: Weighted prediction parameter */ struct v4l2_hevc_pred_weight_table pred_weight_table; -- cgit v1.2.3 From b9a543364299e09ba236c69acb021ebbf7cebf1a Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Mon, 1 Feb 2021 10:16:03 +0100 Subject: media: Documentation: media: Improve camera sensor documentation Modernise the documentation to make it more precise and update the use of pixel rate control and various other changes. In particular: - Use non-proportional font for file names, properties as well as controls. - The unit of the HBLANK control is pixels, not lines. - The unit of PIXEL_RATE control is pixels per second, not Hz. - Merge common requirements for CSI-2 and parallel busses. - Include all DT properties needed for assigned clocks. - Fix referencing the link rate control. - SMIA driver's new name is CCS driver. - The PIXEL_RATE control denotes pixel rate on the pixel array on camera sensors. Do not suggest it is used to tell the maximum pixel rate on the bus anymore. - Improve ReST syntax (plain struct and function names). - Remove the suggestion to use s_power() in receiver drivers. - Make MIPI website URL use HTTPS, add Wikipedia links to BT.601 and BT.656. Fixes: e4cf8c58af75 ("media: Documentation: media: Document how to write camera sensor drivers") Signed-off-by: Sakari Ailus Reviewed-by: Jacopo Mondi Reviewed-by: Andrey Konovalov Signed-off-by: Mauro Carvalho Chehab --- Documentation/driver-api/media/camera-sensor.rst | 45 +++----- Documentation/driver-api/media/csi2.rst | 94 ----------------- Documentation/driver-api/media/index.rst | 2 +- Documentation/driver-api/media/tx-rx.rst | 117 +++++++++++++++++++++ .../media/v4l/ext-ctrls-image-process.rst | 2 + 5 files changed, 137 insertions(+), 123 deletions(-) delete mode 100644 Documentation/driver-api/media/csi2.rst create mode 100644 Documentation/driver-api/media/tx-rx.rst (limited to 'Documentation/userspace-api') diff --git a/Documentation/driver-api/media/camera-sensor.rst b/Documentation/driver-api/media/camera-sensor.rst index 7160336aa475..c7d4891bd24e 100644 --- a/Documentation/driver-api/media/camera-sensor.rst +++ b/Documentation/driver-api/media/camera-sensor.rst @@ -3,10 +3,10 @@ Writing camera sensor drivers ============================= -CSI-2 ------ +CSI-2 and parallel (BT.601 and BT.656) busses +--------------------------------------------- -Please see what is written on :ref:`MIPI_CSI_2`. +Please see :ref:`transmitter-receiver`. Handling clocks --------------- @@ -26,15 +26,16 @@ user. ACPI ~~~~ -Read the "clock-frequency" _DSD property to denote the frequency. The driver can -rely on this frequency being used. +Read the ``clock-frequency`` _DSD property to denote the frequency. The driver +can rely on this frequency being used. Devicetree ~~~~~~~~~~ -The currently preferred way to achieve this is using "assigned-clock-rates" -property. See Documentation/devicetree/bindings/clock/clock-bindings.txt for -more information. The driver then gets the frequency using clk_get_rate(). +The currently preferred way to achieve this is using ``assigned-clocks``, +``assigned-clock-parents`` and ``assigned-clock-rates`` properties. See +``Documentation/devicetree/bindings/clock/clock-bindings.txt`` for more +information. The driver then gets the frequency using ``clk_get_rate()``. This approach has the drawback that there's no guarantee that the frequency hasn't been modified directly or indirectly by another driver, or supported by @@ -55,7 +56,7 @@ processing pipeline as one or more sub-devices with different cropping and scaling configurations. The output size of the device is the result of a series of cropping and scaling operations from the device's pixel array's size. -An example of such a driver is the smiapp driver (see drivers/media/i2c/smiapp). +An example of such a driver is the CCS driver (see ``drivers/media/i2c/ccs``). Register list based drivers ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -67,7 +68,7 @@ level are independent. How a driver picks such configuration is based on the format set on a source pad at the end of the device's internal pipeline. Most sensor drivers are implemented this way, see e.g. -drivers/media/i2c/imx319.c for an example. +``drivers/media/i2c/imx319.c`` for an example. Frame interval configuration ---------------------------- @@ -94,9 +95,10 @@ large variety of devices beyond camera sensors. Devices that have no analogue crop, use the full source image size, i.e. pixel array size. Horizontal and vertical blanking are specified by ``V4L2_CID_HBLANK`` and -``V4L2_CID_VBLANK``, respectively. The unit of these controls are lines. The -pixel rate is specified by ``V4L2_CID_PIXEL_RATE`` in the same sub-device. The -unit of that control is Hz. +``V4L2_CID_VBLANK``, respectively. The unit of the ``V4L2_CID_HBLANK`` control +is pixels and the unit of the ``V4L2_CID_VBLANK`` is lines. The pixel rate in +the sensor's **pixel array** is specified by ``V4L2_CID_PIXEL_RATE`` in the same +sub-device. The unit of that control is pixels per second. Register list based drivers need to implement read-only sub-device nodes for the purpose. Devices that are not register list based need these to configure the @@ -125,14 +127,14 @@ general, the device must be powered on at least when its registers are being accessed and when it is streaming. Existing camera sensor drivers may rely on the old -:c:type:`v4l2_subdev_core_ops`->s_power() callback for bridge or ISP drivers to +struct v4l2_subdev_core_ops->s_power() callback for bridge or ISP drivers to manage their power state. This is however **deprecated**. If you feel you need to begin calling an s_power from an ISP or a bridge driver, instead please add runtime PM support to the sensor driver you are using. Likewise, new drivers should not use s_power. Please see examples in e.g. ``drivers/media/i2c/ov8856.c`` and -``drivers/media/i2c/smiapp/smiapp-core.c``. The two drivers work in both ACPI +``drivers/media/i2c/ccs/ccs-core.c``. The two drivers work in both ACPI and DT based systems. Control framework @@ -149,16 +151,3 @@ 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/csi2.rst b/Documentation/driver-api/media/csi2.rst deleted file mode 100644 index 11c52b0be8b8..000000000000 --- a/Documentation/driver-api/media/csi2.rst +++ /dev/null @@ -1,94 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -.. _MIPI_CSI_2: - -MIPI CSI-2 -========== - -CSI-2 is a data bus intended for transferring images from cameras to -the host SoC. It is defined by the `MIPI alliance`_. - -.. _`MIPI alliance`: http://www.mipi.org/ - -Media bus formats ------------------ - -See :ref:`v4l2-mbus-pixelcode` for details on which media bus formats should -be used for CSI-2 interfaces. - -Transmitter drivers -------------------- - -CSI-2 transmitter, such as a sensor or a TV tuner, drivers need to -provide the CSI-2 receiver with information on the CSI-2 bus -configuration. These include the V4L2_CID_LINK_FREQ and -V4L2_CID_PIXEL_RATE controls and -(:c:type:`v4l2_subdev_video_ops`->s_stream() callback). These -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 -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:: - - pixel_rate = link_freq * 2 * nr_of_lanes * 16 / k / bits_per_sample - -where - -.. list-table:: variables in pixel rate calculation - :header-rows: 1 - - * - variable or constant - - description - * - link_freq - - The value of the V4L2_CID_LINK_FREQ integer64 menu item. - * - nr_of_lanes - - Number of data lanes used on the CSI-2 link. This can - be obtained from the OF endpoint configuration. - * - 2 - - Two bits are transferred per clock cycle per lane. - * - bits_per_sample - - Number of bits per sample. - * - k - - 16 for D-PHY and 7 for C-PHY - -The transmitter drivers must, if possible, configure the CSI-2 -transmitter to *LP-11 mode* whenever the transmitter is powered on but -not active, and maintain *LP-11 mode* until stream on. Only at stream -on should the transmitter activate the clock on the clock lane and -transition to *HS mode*. - -Some transmitters do this automatically but some have to be explicitly -programmed to do so, and some are unable to do so altogether due to -hardware constraints. - -Stopping the transmitter -^^^^^^^^^^^^^^^^^^^^^^^^ - -A transmitter stops sending the stream of images as a result of -calling the ``.s_stream()`` callback. Some transmitters may stop the -stream at a frame boundary whereas others stop immediately, -effectively leaving the current frame unfinished. The receiver driver -should not make assumptions either way, but function properly in both -cases. - -Receiver drivers ----------------- - -Before the receiver driver may enable the CSI-2 transmitter by using -the :c:type:`v4l2_subdev_video_ops`->s_stream(), it must have powered -the transmitter up by using the -:c:type:`v4l2_subdev_core_ops`->s_power() callback. This may take -place either indirectly by using :c:func:`v4l2_pipeline_pm_get` or -directly. - -Formats -------- - -The media bus pixel codes document parallel formats. Should the pixel data be -transported over a serial bus, the media bus pixel code that describes a -parallel format that transfers a sample on a single clock cycle is used. diff --git a/Documentation/driver-api/media/index.rst b/Documentation/driver-api/media/index.rst index 813d7db59da7..08e206567408 100644 --- a/Documentation/driver-api/media/index.rst +++ b/Documentation/driver-api/media/index.rst @@ -37,7 +37,7 @@ Documentation/userspace-api/media/index.rst rc-core mc-core cec-core - csi2 + tx-rx camera-sensor drivers/index diff --git a/Documentation/driver-api/media/tx-rx.rst b/Documentation/driver-api/media/tx-rx.rst new file mode 100644 index 000000000000..4c8584e7b6f2 --- /dev/null +++ b/Documentation/driver-api/media/tx-rx.rst @@ -0,0 +1,117 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _transmitter-receiver: + +Pixel data transmitter and receiver drivers +=========================================== + +V4L2 supports various devices that transmit and receiver pixel data. Examples of +these devices include a camera sensor, a TV tuner and a parallel or a CSI-2 +receiver in an SoC. + +Bus types +--------- + +The following busses are the most common. This section discusses these two only. + +MIPI CSI-2 +^^^^^^^^^^ + +CSI-2 is a data bus intended for transferring images from cameras to +the host SoC. It is defined by the `MIPI alliance`_. + +.. _`MIPI alliance`: https://www.mipi.org/ + +Parallel +^^^^^^^^ + +`BT.601`_ and `BT.656`_ are the most common parallel busses. + +.. _`BT.601`: https://en.wikipedia.org/wiki/Rec._601 +.. _`BT.656`: https://en.wikipedia.org/wiki/ITU-R_BT.656 + +Transmitter drivers +------------------- + +Transmitter drivers generally need to provide the receiver drivers with the +configuration of the transmitter. What is required depends on the type of the +bus. These are common for both busses. + +Media bus pixel code +^^^^^^^^^^^^^^^^^^^^ + +See :ref:`v4l2-mbus-pixelcode`. + +Link frequency +^^^^^^^^^^^^^^ + +The :ref:`V4L2_CID_LINK_FREQ ` control is used to tell the +receiver the frequency of the bus (i.e. it is not the same as the symbol rate). + +``.s_stream()`` callback +^^^^^^^^^^^^^^^^^^^^^^^^ + +The struct struct v4l2_subdev_video_ops->s_stream() callback is used by the +receiver driver to control the transmitter driver's streaming state. + + +CSI-2 transmitter drivers +------------------------- + +Pixel rate +^^^^^^^^^^ + +The pixel rate on the bus is calculated as follows:: + + pixel_rate = link_freq * 2 * nr_of_lanes * 16 / k / bits_per_sample + +where + +.. list-table:: variables in pixel rate calculation + :header-rows: 1 + + * - variable or constant + - description + * - link_freq + - The value of the ``V4L2_CID_LINK_FREQ`` integer64 menu item. + * - nr_of_lanes + - Number of data lanes used on the CSI-2 link. This can + be obtained from the OF endpoint configuration. + * - 2 + - Data is transferred on both rising and falling edge of the signal. + * - bits_per_sample + - Number of bits per sample. + * - k + - 16 for D-PHY and 7 for C-PHY + +.. note:: + + The pixel rate calculated this way is **not** the same thing as the + pixel rate on the camera sensor's pixel array which is indicated by the + :ref:`V4L2_CID_PIXEL_RATE ` control. + +LP-11 and LP-111 modes +^^^^^^^^^^^^^^^^^^^^^^ + +The transmitter drivers must, if possible, configure the CSI-2 transmitter to +*LP-11 or LP-111 mode* whenever the transmitter is powered on but not active, +and maintain *LP-11 or LP-111 mode* until stream on. Only at stream on should +the transmitter activate the clock on the clock lane and transition to *HS +mode*. + +Some transmitters do this automatically but some have to be explicitly +programmed to do so, and some are unable to do so altogether due to +hardware constraints. + +The receiver thus need to be configured to expect LP-11 or LP-111 mode from the +transmitter before the transmitter driver's ``.s_stream()`` op is called. + +Stopping the transmitter +^^^^^^^^^^^^^^^^^^^^^^^^ + +A transmitter stops sending the stream of images as a result of +calling the ``.s_stream()`` callback. Some transmitters may stop the +stream at a frame boundary whereas others stop immediately, +effectively leaving the current frame unfinished. The receiver driver +should not make assumptions either way, but function properly in both +cases. diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst index 87698c15c027..37dad2f4df8c 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst @@ -20,6 +20,8 @@ Image Process Control IDs ``V4L2_CID_IMAGE_PROC_CLASS (class)`` The IMAGE_PROC class descriptor. +.. _v4l2-cid-link-freq: + ``V4L2_CID_LINK_FREQ (integer menu)`` Data bus frequency. Together with the media bus pixel code, bus type (clock cycles per sample), the data bus frequency defines the pixel -- cgit v1.2.3 From 6f8f9fdec8e4615a2cf539bbcad400d4b3a39070 Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Mon, 8 Feb 2021 11:33:14 +0100 Subject: media: Documentation: media: Fix v4l2-async kerneldoc syntax Fix kerneldoc syntax in v4l2-async. The references were not produced correctly. Signed-off-by: Sakari Ailus Reviewed-by: Jacopo Mondi Signed-off-by: Mauro Carvalho Chehab --- Documentation/driver-api/media/tx-rx.rst | 8 +++--- .../media/v4l/ext-ctrls-image-process.rst | 2 ++ include/media/v4l2-async.h | 30 +++++++++++----------- 3 files changed, 21 insertions(+), 19 deletions(-) (limited to 'Documentation/userspace-api') diff --git a/Documentation/driver-api/media/tx-rx.rst b/Documentation/driver-api/media/tx-rx.rst index 4c8584e7b6f2..12d492d25df2 100644 --- a/Documentation/driver-api/media/tx-rx.rst +++ b/Documentation/driver-api/media/tx-rx.rst @@ -5,7 +5,7 @@ Pixel data transmitter and receiver drivers =========================================== -V4L2 supports various devices that transmit and receiver pixel data. Examples of +V4L2 supports various devices that transmit and receive pixel data. Examples of these devices include a camera sensor, a TV tuner and a parallel or a CSI-2 receiver in an SoC. @@ -95,9 +95,9 @@ LP-11 and LP-111 modes The transmitter drivers must, if possible, configure the CSI-2 transmitter to *LP-11 or LP-111 mode* whenever the transmitter is powered on but not active, -and maintain *LP-11 or LP-111 mode* until stream on. Only at stream on should -the transmitter activate the clock on the clock lane and transition to *HS -mode*. +and maintain *LP-11 or LP-111 mode* until stream on. Only at stream on time +should the transmitter activate the clock on the clock lane and transition to +*HS mode*. Some transmitters do this automatically but some have to be explicitly programmed to do so, and some are unable to do so altogether due to diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst index 37dad2f4df8c..ed65fb594cc8 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst @@ -37,6 +37,8 @@ Image Process Control IDs by selecting the desired horizontal and vertical blanking. The unit of this control is Hz. +.. _v4l2-cid-pixel-rate: + ``V4L2_CID_PIXEL_RATE (64-bit integer)`` Pixel rate in the source pads of the subdev. This control is read-only and its unit is pixels / second. diff --git a/include/media/v4l2-async.h b/include/media/v4l2-async.h index 5b275a845c20..fa4901162663 100644 --- a/include/media/v4l2-async.h +++ b/include/media/v4l2-async.h @@ -129,11 +129,11 @@ void v4l2_async_debug_init(struct dentry *debugfs_dir); * * This function initializes the notifier @asd_list. It must be called * before adding a subdevice to a notifier, using one of: - * @v4l2_async_notifier_add_fwnode_remote_subdev, - * @v4l2_async_notifier_add_fwnode_subdev, - * @v4l2_async_notifier_add_i2c_subdev, - * @__v4l2_async_notifier_add_subdev or - * @v4l2_async_notifier_parse_fwnode_endpoints. + * v4l2_async_notifier_add_fwnode_remote_subdev(), + * v4l2_async_notifier_add_fwnode_subdev(), + * v4l2_async_notifier_add_i2c_subdev(), + * __v4l2_async_notifier_add_subdev() or + * v4l2_async_notifier_parse_fwnode_endpoints(). */ void v4l2_async_notifier_init(struct v4l2_async_notifier *notifier); @@ -145,9 +145,9 @@ void v4l2_async_notifier_init(struct v4l2_async_notifier *notifier); * @asd: pointer to &struct v4l2_async_subdev * * \warning: Drivers should avoid using this function and instead use one of: - * @v4l2_async_notifier_add_fwnode_subdev, - * @v4l2_async_notifier_add_fwnode_remote_subdev or - * @v4l2_async_notifier_add_i2c_subdev. + * v4l2_async_notifier_add_fwnode_subdev(), + * v4l2_async_notifier_add_fwnode_remote_subdev() or + * v4l2_async_notifier_add_i2c_subdev(). * * Call this function before registering a notifier to link the provided @asd to * the notifiers master @asd_list. The @asd must be allocated with k*alloc() as @@ -200,7 +200,7 @@ __v4l2_async_notifier_add_fwnode_remote_subdev(struct v4l2_async_notifier *notif * function also gets a reference of the fwnode which is released later at * notifier cleanup time. * - * This is just like @v4l2_async_notifier_add_fwnode_subdev, but with the + * This is just like v4l2_async_notifier_add_fwnode_subdev(), but with the * exception that the fwnode refers to a local endpoint, not the remote one. */ #define v4l2_async_notifier_add_fwnode_remote_subdev(notifier, ep, type) \ @@ -265,13 +265,13 @@ void v4l2_async_notifier_unregister(struct v4l2_async_notifier *notifier); * sub-devices allocated for the purposes of the notifier but not the notifier * itself. The user is responsible for calling this function to clean up the * notifier after calling - * @v4l2_async_notifier_add_fwnode_remote_subdev, - * @v4l2_async_notifier_add_fwnode_subdev, - * @v4l2_async_notifier_add_i2c_subdev, - * @__v4l2_async_notifier_add_subdev or - * @v4l2_async_notifier_parse_fwnode_endpoints. + * v4l2_async_notifier_add_fwnode_remote_subdev(), + * v4l2_async_notifier_add_fwnode_subdev(), + * v4l2_async_notifier_add_i2c_subdev(), + * __v4l2_async_notifier_add_subdev() or + * v4l2_async_notifier_parse_fwnode_endpoints(). * - * There is no harm from calling v4l2_async_notifier_cleanup in other + * There is no harm from calling v4l2_async_notifier_cleanup() in other * cases as long as its memory has been zeroed after it has been * allocated. */ -- cgit v1.2.3 From 8925b53083980057de99599ba8dd2a72b03406a6 Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Tue, 22 Jun 2021 12:52:03 +0200 Subject: media: Documentation: v4l: Fix V4L2_CID_PIXEL_RATE documentation The V4L2_CID_PIXEL_RATE is nowadays used to tell pixel sampling rate in the sub-device's pixel array, not the pixel rate over a link (for which it also becomes unfit with the addition of multiplexed streams later on). Fix this. Signed-off-by: Sakari Ailus Reviewed-by: Jacopo Mondi Reviewed-by: Andrey Konovalov Signed-off-by: Mauro Carvalho Chehab --- Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/userspace-api') diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst index ed65fb594cc8..2b5a13dc843f 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst @@ -40,7 +40,7 @@ Image Process Control IDs .. _v4l2-cid-pixel-rate: ``V4L2_CID_PIXEL_RATE (64-bit integer)`` - Pixel rate in the source pads of the subdev. This control is + Pixel sampling rate in the device's pixel array. This control is read-only and its unit is pixels / second. ``V4L2_CID_TEST_PATTERN (menu)`` -- cgit v1.2.3 From e5a466d4bcf962daa8fea589b09a5675bda275a1 Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Tue, 22 Jun 2021 13:17:20 +0200 Subject: media: Documentation: v4l: Improve frame rate configuration documentation Improve the documentation of the frame rate configuration so that it can be understood by a regular human being. Signed-off-by: Sakari Ailus Signed-off-by: Mauro Carvalho Chehab --- .../media/v4l/ext-ctrls-image-process.rst | 23 ++++++++++------------ 1 file changed, 10 insertions(+), 13 deletions(-) (limited to 'Documentation/userspace-api') diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst index 2b5a13dc843f..b1c2ab2854af 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst @@ -23,19 +23,7 @@ Image Process Control IDs .. _v4l2-cid-link-freq: ``V4L2_CID_LINK_FREQ (integer menu)`` - Data bus frequency. Together with the media bus pixel code, bus type - (clock cycles per sample), the data bus frequency defines the pixel - rate (``V4L2_CID_PIXEL_RATE``) in the pixel array (or possibly - elsewhere, if the device is not an image sensor). The frame rate can - be calculated from the pixel clock, image width and height and - horizontal and vertical blanking. While the pixel rate control may - be defined elsewhere than in the subdev containing the pixel array, - the frame rate cannot be obtained from that information. This is - because only on the pixel array it can be assumed that the vertical - and horizontal blanking information is exact: no other blanking is - allowed in the pixel array. The selection of frame rate is performed - by selecting the desired horizontal and vertical blanking. The unit - of this control is Hz. + The frequency of the data bus (e.g. parallel or CSI-2). .. _v4l2-cid-pixel-rate: @@ -43,6 +31,15 @@ Image Process Control IDs Pixel sampling rate in the device's pixel array. This control is read-only and its unit is pixels / second. + Some devices use horizontal and vertical balanking to configure the frame + rate. The frame rate can be calculated from the pixel rate, analogue crop + rectangle as well as horizontal and vertical blanking. The pixel rate + control may be present in a different sub-device than the blanking controls + and the analogue crop rectangle configuration. + + The configuration of the frame rate is performed by selecting the desired + horizontal and vertical blanking. The unit of this control is Hz. + ``V4L2_CID_TEST_PATTERN (menu)`` Some capture/display/sensor devices have the capability to generate test pattern images. These hardware specific test patterns can be -- cgit v1.2.3 From ea9f91199ca99dd9b3fba004b7614eed233ba1ac Mon Sep 17 00:00:00 2001 From: Stanimir Varbanov Date: Tue, 22 Jun 2021 13:39:56 +0200 Subject: media: docs: ext-ctrls-codec: Document cyclic intra-refresh zero control value In all drivers _CYCLIC_INTRA_REFRESH_MB default control value is zero which means that the macroblocks will not be intra-refreshed. Document this _CYCLIC_INTRA_REFRESH_MB control behaviour in control description. Acked-by: Hans Verkuil Signed-off-by: Stanimir Varbanov Signed-off-by: Mauro Carvalho Chehab --- Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'Documentation/userspace-api') diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst index dc096a5562cd..999b2360cef8 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst @@ -1174,7 +1174,9 @@ enum v4l2_mpeg_video_h264_entropy_mode - Cyclic intra macroblock refresh. This is the number of continuous macroblocks refreshed every frame. Each frame a successive set of macroblocks is refreshed until the cycle completes and starts from - the top of the frame. Applicable to H264, H263 and MPEG4 encoder. + the top of the frame. Setting this control to zero means that + macroblocks will not be refreshed. + Applicable to H264, H263 and MPEG4 encoder. ``V4L2_CID_MPEG_VIDEO_FRAME_RC_ENABLE (boolean)`` Frame level rate control enable. If this control is disabled then -- cgit v1.2.3 From 9d5adeecc409365e45cd89657f0392d0dd5c217f Mon Sep 17 00:00:00 2001 From: Stanimir Varbanov Date: Tue, 22 Jun 2021 13:39:57 +0200 Subject: media: v4l2-ctrls: Add intra-refresh period control Add a control to set intra-refresh period. Acked-by: Hans Verkuil Signed-off-by: Stanimir Varbanov Signed-off-by: Mauro Carvalho Chehab --- .../userspace-api/media/v4l/ext-ctrls-codec.rst | 17 ++++++++++++++++- drivers/media/v4l2-core/v4l2-ctrls-defs.c | 2 ++ include/uapi/linux/v4l2-controls.h | 1 + 3 files changed, 19 insertions(+), 1 deletion(-) (limited to 'Documentation/userspace-api') diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst index 999b2360cef8..976d34445a24 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst @@ -1175,9 +1175,24 @@ enum v4l2_mpeg_video_h264_entropy_mode - macroblocks refreshed every frame. Each frame a successive set of macroblocks is refreshed until the cycle completes and starts from the top of the frame. Setting this control to zero means that - macroblocks will not be refreshed. + macroblocks will not be refreshed. Note that this control will not + take effect when ``V4L2_CID_MPEG_VIDEO_INTRA_REFRESH_PERIOD`` control + is set to non zero value. Applicable to H264, H263 and MPEG4 encoder. +``V4L2_CID_MPEG_VIDEO_INTRA_REFRESH_PERIOD (integer)`` + Intra macroblock refresh period. This sets the period to refresh + the whole frame. In other words, this defines the number of frames + for which the whole frame will be intra-refreshed. An example: + setting period to 1 means that the whole frame will be refreshed, + setting period to 2 means that the half of macroblocks will be + intra-refreshed on frameX and the other half of macroblocks + will be refreshed in frameX + 1 and so on. Setting the period to + zero means no period is specified. + Note that if the client sets this control to non zero value the + ``V4L2_CID_MPEG_VIDEO_CYCLIC_INTRA_REFRESH_MB`` control shall be + ignored. Applicable to H264 and HEVC encoders. + ``V4L2_CID_MPEG_VIDEO_FRAME_RC_ENABLE (boolean)`` Frame level rate control enable. If this control is disabled then the quantization parameter for each frame type is constant and set diff --git a/drivers/media/v4l2-core/v4l2-ctrls-defs.c b/drivers/media/v4l2-core/v4l2-ctrls-defs.c index b6344bbf1e00..421300e13a41 100644 --- a/drivers/media/v4l2-core/v4l2-ctrls-defs.c +++ b/drivers/media/v4l2-core/v4l2-ctrls-defs.c @@ -833,6 +833,7 @@ const char *v4l2_ctrl_get_name(u32 id) case V4L2_CID_MPEG_VIDEO_DECODER_SLICE_INTERFACE: return "Decoder Slice Interface"; case V4L2_CID_MPEG_VIDEO_DECODER_MPEG4_DEBLOCK_FILTER: return "MPEG4 Loop Filter Enable"; case V4L2_CID_MPEG_VIDEO_CYCLIC_INTRA_REFRESH_MB: return "Number of Intra Refresh MBs"; + case V4L2_CID_MPEG_VIDEO_INTRA_REFRESH_PERIOD: return "Intra Refresh Period"; case V4L2_CID_MPEG_VIDEO_FRAME_RC_ENABLE: return "Frame Level Rate Control Enable"; case V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE: return "H264 MB Level Rate Control"; case V4L2_CID_MPEG_VIDEO_HEADER_MODE: return "Sequence Header Mode"; @@ -1258,6 +1259,7 @@ void v4l2_ctrl_fill(u32 id, const char **name, enum v4l2_ctrl_type *type, case V4L2_CID_MPEG_VIDEO_MV_H_SEARCH_RANGE: case V4L2_CID_MPEG_VIDEO_MV_V_SEARCH_RANGE: case V4L2_CID_MPEG_VIDEO_DEC_DISPLAY_DELAY: + case V4L2_CID_MPEG_VIDEO_INTRA_REFRESH_PERIOD: *type = V4L2_CTRL_TYPE_INTEGER; break; case V4L2_CID_MPEG_VIDEO_LTR_COUNT: diff --git a/include/uapi/linux/v4l2-controls.h b/include/uapi/linux/v4l2-controls.h index fdf97a6d7d18..5532b5f68493 100644 --- a/include/uapi/linux/v4l2-controls.h +++ b/include/uapi/linux/v4l2-controls.h @@ -435,6 +435,7 @@ enum v4l2_mpeg_video_multi_slice_mode { #define V4L2_CID_MPEG_VIDEO_FRAME_LTR_INDEX (V4L2_CID_CODEC_BASE+233) #define V4L2_CID_MPEG_VIDEO_USE_LTR_FRAMES (V4L2_CID_CODEC_BASE+234) #define V4L2_CID_MPEG_VIDEO_DEC_CONCEAL_COLOR (V4L2_CID_CODEC_BASE+235) +#define V4L2_CID_MPEG_VIDEO_INTRA_REFRESH_PERIOD (V4L2_CID_CODEC_BASE+236) /* CIDs for the MPEG-2 Part 2 (H.262) codec */ #define V4L2_CID_MPEG_VIDEO_MPEG2_LEVEL (V4L2_CID_CODEC_BASE+270) -- cgit v1.2.3