[libcamera-devel] [PATCH v3 7/7] documentation: Document vendor specific controls and properties handling

[Naushir Patuck]

Hi Jacopo,

Thank you for the feedback!

On Mon, 27 Nov 2023 at 17:14, Jacopo Mondi
<jacopo.mondi at ideasonboard.com> wrote:
>
> Hi Naush
>
> On Fri, Nov 24, 2023 at 12:37:13PM +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>
> > Reviewed-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
> > ---
> >  Documentation/guides/pipeline-handler.rst | 48 +++++++++++++++++++++++
> >  1 file changed, 48 insertions(+)
> >
> > diff --git a/Documentation/guides/pipeline-handler.rst b/Documentation/guides/pipeline-handler.rst
> > index 66d428a19c4f..5a3d00b1b879 100644
> > --- a/Documentation/guides/pipeline-handler.rst
> > +++ b/Documentation/guides/pipeline-handler.rst
> > @@ -672,6 +672,54 @@ handling controls:
> >     #include <libcamera/controls.h>
> >     #include <libcamera/control_ids.h>
> >
> > +Vendor-specific controls and properties
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > +
> > +Vendor-specific controls and properties must be defined in a separate YAML file
> > +and included in the build by defining the pipeline handler to file mapping in
> > +include/libcamera/meson.build.
> > +
>
> The vendor-specific file has to be placed in src/libcamera I presume ?
> Should we specify that ?

Sure, I'll specify the full path.

>
> > +For example, adding a Raspberry Pi vendor control file for the PiSP pipeline
> > +handler is done with the following mapping:
> > +
> > +.. code-block:: meson
> > +
> > +   controls_map = {
> > +      'controls': {
> > +         'draft': 'control_ids_draft.yaml',
> > +         'libcamera': 'control_ids.yaml',
> > +         'rpi/pisp': 'control_ids_rpi.yaml',
>
> Should we say this item has to match the pipeline option as specified
> in the meson build options ?

Sounds reasonable.  I'll make the change for the next version.

Regards,
Naush


>
> > +      },
> > +
> > +      'properties': {
> > +         'draft': 'property_ids_draft.yaml',
> > +         'libcamera': 'property_ids.yaml',
> > +      }
> > +   }
> > +
> > +Vendor-specific controls and properties must contain a `vendor: <vendor_string>`
> > +tag in the YAML file. 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
> > +
> > +    vendor: rpi
> > +    controls:
> > +      - PispConfigDumpFile:
> > +          type: string
> > +          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_HAS_RPI_VENDOR_CONTROLS` will be available to allow applications to
> > +test for the availability of these controls.
> > +
> >  Generating a default configuration
> >  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> >
> > --
> > 2.34.1
> >