Debian Codegraph @

Documentation/userspace-api/media/v4l/v4l2-isp.rst

raw
1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
3 .. _v4l2-isp:
4
5 ************************
6 Generic V4L2 ISP formats
7 ************************
8
9 Generic ISP formats are metadata formats that define a mechanism to pass ISP
10 parameters and statistics between userspace and drivers in V4L2 buffers. They
11 are designed to allow extending them in a backward-compatible way.
12
13 ISP parameters
14 ==============
15
16 The generic ISP configuration parameters format is realized by a defining a
17 single C structure that contains a header, followed by a binary buffer where
18 userspace programs a variable number of ISP configuration data block, one for
19 each supported ISP feature.
20
21 The :c:type:`v4l2_isp_params_buffer` structure defines the buffer header which
22 is followed by a binary buffer of ISP configuration data. Userspace shall
23 correctly populate the buffer header with the generic parameters format version
24 and with the size (in bytes) of the binary data buffer where it will store the
25 ISP blocks configuration.
26
27 Each *ISP configuration block* is preceded by an header implemented by the
28 :c:type:`v4l2_isp_params_block_header` structure, followed by the configuration
29 parameters for that specific block, defined by the ISP driver specific data
30 types.
31
32 Userspace applications are responsible for correctly populating each block's
33 header fields (type, flags and size) and the block-specific parameters.
34
35 ISP block enabling, disabling and configuration
36 -----------------------------------------------
37
38 When userspace wants to configure and enable an ISP block it shall fully
39 populate the block configuration and set the V4L2_ISP_PARAMS_FL_BLOCK_ENABLE
40 bit in the block header's `flags` field.
41
42 When userspace simply wants to disable an ISP block the
43 V4L2_ISP_PARAMS_FL_BLOCK_DISABLE bit should be set in block header's `flags`
44 field. Drivers accept a configuration parameters block with no additional
45 data after the header in this case.
46
47 If the configuration of an already active ISP block has to be updated,
48 userspace shall fully populate the ISP block parameters and omit setting the
49 V4L2_ISP_PARAMS_FL_BLOCK_ENABLE and V4L2_ISP_PARAMS_FL_BLOCK_DISABLE bits in the
50 header's `flags` field.
51
52 Setting both the V4L2_ISP_PARAMS_FL_BLOCK_ENABLE and
53 V4L2_ISP_PARAMS_FL_BLOCK_DISABLE bits in the flags field is not allowed and
54 returns an error.
55
56 Extension to the parameters format can be implemented by adding new blocks
57 definition without invalidating the existing ones.
58
59 ISP statistics
60 ==============
61
62 Support for generic statistics format is not yet implemented in Video4Linux2.
63
64 V4L2 ISP uAPI data types
65 ========================
66
67 .. kernel-doc:: include/uapi/linux/media/v4l2-isp.h