| 1 |
.. SPDX-License-Identifier: GPL-2.0 |
| 2 |
|
| 3 |
V4L2 generic ISP parameters and statistics support |
| 4 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 5 |
|
| 6 |
Design rationale |
| 7 |
================ |
| 8 |
|
| 9 |
ISP configuration parameters and statistics are processed and collected by |
| 10 |
drivers and exchanged with userspace through data types that usually |
| 11 |
reflect the ISP peripheral registers layout. |
| 12 |
|
| 13 |
Each ISP driver defines its own metadata output format for parameters and |
| 14 |
a metadata capture format for statistics. The buffer layout is realized by a |
| 15 |
set of C structures that reflects the registers layout. The number and types |
| 16 |
of C structures is fixed by the format definition and becomes part of the Linux |
| 17 |
kernel uAPI/uABI interface. |
| 18 |
|
| 19 |
Because of the hard requirement of backward compatibility when extending the |
| 20 |
user API/ABI interface, modifying an ISP driver capture or output metadata |
| 21 |
format after it has been accepted by mainline is very hard if not impossible. |
| 22 |
|
| 23 |
It generally happens, in fact, that after the first accepted revision of an ISP |
| 24 |
driver the buffers layout need to be modified, either to support new hardware |
| 25 |
blocks, to fix bugs or to support different revisions of the hardware. |
| 26 |
|
| 27 |
Each of these situations would require defining a new metadata format, making it |
| 28 |
really hard to maintain and extend drivers and requiring userspace to use |
| 29 |
the correct format depending on the kernel revision in use. |
| 30 |
|
| 31 |
V4L2 ISP configuration parameters |
| 32 |
================================= |
| 33 |
|
| 34 |
For these reasons, Video4Linux2 defines generic types for ISP configuration |
| 35 |
parameters and statistics. Drivers are still expected to define their own |
| 36 |
formats for their metadata output and capture nodes, but the buffers layout can |
| 37 |
be defined using the extensible and versioned types defined by |
| 38 |
include/uapi/linux/media/v4l2-isp.h. |
| 39 |
|
| 40 |
Drivers are expected to provide the definitions of their supported ISP blocks |
| 41 |
and the expected maximum size of a buffer. |
| 42 |
|
| 43 |
For driver developers a set of helper functions to assist them with validation |
| 44 |
of the buffer received from userspace is available in |
| 45 |
drivers/media/v4l2-core/v4l2-isp.c |
| 46 |
|
| 47 |
V4L2 ISP support driver documentation |
| 48 |
===================================== |
| 49 |
.. kernel-doc:: include/media/v4l2-isp.h |