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

19240 diff mbox series

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@raspberrypi.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
 Documentation/guides/pipeline-handler.rst | 48 +++++++++++++++++++++++
 1 file changed, 48 insertions(+)

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@raspberrypi.com>
> Reviewed-by: Laurent Pinchart <laurent.pinchart@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 ?

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

> +      },
> +
> +      '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
>

Hi Jacopo,

Thank you for the feedback!

On Mon, 27 Nov 2023 at 17:14, Jacopo Mondi
<jacopo.mondi@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@raspberrypi.com>
> > Reviewed-by: Laurent Pinchart <laurent.pinchart@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
> >

Quoting Jacopo Mondi via libcamera-devel (2023-11-27 17:14:28)
> 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@raspberrypi.com>
> > Reviewed-by: Laurent Pinchart <laurent.pinchart@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 ?
> 
> > +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 ?
> 
> > +      },
> > +
> > +      '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

/This controls/The controls/

With that and the above handled...


Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>


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