[libcamera-devel] [PATCH v1 5/5] documentation: Document vendor specific control and properties handling

[Naushir Patuck]

Add some documentation to the pipeline handler file describing how to
implement and handle vendor specific controls and properties with a
small example.

Signed-off-by: Naushir Patuck <naush at raspberrypi.com>
---
 Documentation/guides/pipeline-handler.rst | 53 +++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/Documentation/guides/pipeline-handler.rst b/Documentation/guides/pipeline-handler.rst
index 10b9c75c2a7f..417eceeb62bd 100644
--- a/Documentation/guides/pipeline-handler.rst
+++ b/Documentation/guides/pipeline-handler.rst
@@ -672,6 +672,59 @@ handling controls:
    #include <libcamera/controls.h>
    #include <libcamera/control_ids.h>
 
+Vendor specific controls and properties
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Vendor specific controls and properties may be defined in a separate YMAL file
+and included in the build by defining the pipeline handler to file mapping in
+include/libcamera/meson.build.
+
+For example, adding a Raspberry Pi vendor control file for the PiSP pipeline
+handler is done with the following mapping:
+
+.. code-block:: meson
+
+   vendor_mappings = {
+      # Mapping of vendor (pipeline handler) specific controls files
+      'controls':
+      {
+         'rpi/pisp': 'control_ids_rpi.yaml',
+      },
+      # Mapping of vendor (pipeline handler) specific properties files
+      'properties':
+      {
+
+      }
+   }
+
+It is also possible (though inadvisable for maintenance purposes) to add vendor
+specific controls directly in the the src/libcamera/`control_ids.yaml`_ or
+src/libcamera/`properties_ids.yaml`_ files.
+
+Vendor specific controls and properties must contain a `vendor: <vendor_string>`
+tag in the YAML definition. Every unique vendor tag must define a unique and
+non-overlapping range of reserved control IDs in src/libcamera/control_ranges.yaml.
+
+For example, the following block defines a vendor specific control with the
+`rpi` vendor tag:
+
+.. code-block:: yaml
+
+  - PispConfigDumpFile:
+      type: string
+      vendor: rpi
+      description: |
+        Triggers the Raspberry Pi PiSP pipeline handler to generate a JSON
+        formatted dump of the Backend configuration to the filename given by the
+        value of the control.
+
+This controls will be generated in the vendor specific namespace
+`libcamera::controls::rpi`. Additionally a `#define
+LIBCAMERA_RPI_VENDOR_CONTROL` will be available to allow applications to test
+for the availability of these controls.
+
+Note that draft controls are defined with the `vendor: draft` tag.
+
 Generating a default configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- 
2.34.1