| Message ID | 20231121145350.5956-7-naush@raspberrypi.com |
|---|---|
| State | Superseded |
| Headers | show |
| Series |
|
| Related | show |
Hi Naush, Thank you for the patch. On Tue, Nov 21, 2023 at 02:53:50PM +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 s/vendor specific/vendor-specific/ If that's a "proper English vs. US English" issue, please feel free to correct me :-) > small example. > > Signed-off-by: Naushir Patuck <naush@raspberrypi.com> > --- > Documentation/guides/pipeline-handler.rst | 52 +++++++++++++++++++++++ > 1 file changed, 52 insertions(+) > > diff --git a/Documentation/guides/pipeline-handler.rst b/Documentation/guides/pipeline-handler.rst > index 10b9c75c2a7f..26977164accf 100644 > --- a/Documentation/guides/pipeline-handler.rst > +++ b/Documentation/guides/pipeline-handler.rst > @@ -672,6 +672,58 @@ 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. > + > +For example, adding a Raspberry Pi vendor control file for the PiSP pipeline > +handler is done with the following mapping: > + > +.. code-block:: meson > + > + vendor_controls_mapping = { > + # Mapping of vendor (pipeline handler) specific controls files > + 'controls': > + { > + 'rpi/pisp': 'control_ids_rpi.yaml', > + }, > + # Mapping of vendor (pipeline handler) specific properties files > + 'properties': > + { > + > + } > + } > + > +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. Indentiation looks wrong here, the '- PispConfigDumpFile:' line is under-indented, and so are the three lines of the description text. > + > + > +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. > + > +Note that libcamera core controls are defined with the `vendor: libcamera` tag > +and libcamera draft controls are defined with the `vendor: draft` tag. I'm not sure I would have mentioned this here, as it's not really related to pipeline handlers. Up to you. Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> > + > Generating a default configuration > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ >
diff --git a/Documentation/guides/pipeline-handler.rst b/Documentation/guides/pipeline-handler.rst index 10b9c75c2a7f..26977164accf 100644 --- a/Documentation/guides/pipeline-handler.rst +++ b/Documentation/guides/pipeline-handler.rst @@ -672,6 +672,58 @@ 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. + +For example, adding a Raspberry Pi vendor control file for the PiSP pipeline +handler is done with the following mapping: + +.. code-block:: meson + + vendor_controls_mapping = { + # Mapping of vendor (pipeline handler) specific controls files + 'controls': + { + 'rpi/pisp': 'control_ids_rpi.yaml', + }, + # Mapping of vendor (pipeline handler) specific properties files + 'properties': + { + + } + } + +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. + +Note that libcamera core controls are defined with the `vendor: libcamera` tag +and libcamera draft controls are defined with the `vendor: draft` tag. + Generating a default configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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> --- Documentation/guides/pipeline-handler.rst | 52 +++++++++++++++++++++++ 1 file changed, 52 insertions(+)