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

[Laurent Pinchart]

Hi Naush,

Thank you for the patch.

On Fri, Nov 10, 2023 at 11:00:02AM +0000, Naushir Patuck via libcamera-devel wrote:
> 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

s/Vendor specific/Vendor-specific/

Same below.

> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Vendor specific controls and properties may be defined in a separate YMAL file

s/YMAL/YAML/

> +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.

Let's not mention it if it's not advisable :-)

> +
> +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.

This may change depending on the review discussion.

> +
> +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

I think LIBCAMERA_RPI_VENDOR_CONTROLS would be better than
LIBCAMERA_RPI_VENDOR_CONTROL.

> +for the availability of these controls.
> +
> +Note that draft controls are defined with the `vendor: draft` tag.
> +
>  Generating a default configuration
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>  

-- 
Regards,

Laurent Pinchart