| Message ID | 20231110110002.21381-6-naush@raspberrypi.com |
|---|---|
| State | Superseded |
| Headers | show |
| Series |
|
| Related | show |
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@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 > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ >
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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 | 53 +++++++++++++++++++++++ 1 file changed, 53 insertions(+)