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