Message ID | 20250729073201.5369-9-mzamazal@redhat.com |
---|---|
State | Superseded |
Headers | show |
Series |
|
Related | show |
Hi Milan, Thanks for the patch. Quoting Milan Zamazal (2025-07-29 16:31:56) > Extend (and rename) the documentation of environment variables with > information about the configuration file. > > Signed-off-by: Milan Zamazal <mzamazal@redhat.com> In the commit title, s/config:/Documentation:/ (and optionally s/documentation//) > --- > Documentation/documentation-contents.rst | 2 +- > Documentation/index.rst | 2 +- > Documentation/meson.build | 2 +- > ...ariables.rst => runtime_configuration.rst} | 105 ++++++++++++++++-- > 4 files changed, 99 insertions(+), 12 deletions(-) > rename Documentation/{environment_variables.rst => runtime_configuration.rst} (67%) > > diff --git a/Documentation/documentation-contents.rst b/Documentation/documentation-contents.rst > index 5c1118493..4be3729cf 100644 > --- a/Documentation/documentation-contents.rst > +++ b/Documentation/documentation-contents.rst > @@ -7,7 +7,7 @@ > * :doc:`/feature_requirements` > * :doc:`/guides/application-developer` > * :doc:`/python-bindings` > - * :doc:`/environment_variables` > + * :doc:`/runtime_configuration` > * :doc:`/api-html/index` > * :doc:`/code-of-conduct` > * | > diff --git a/Documentation/index.rst b/Documentation/index.rst > index 251112fbd..200de6f67 100644 > --- a/Documentation/index.rst > +++ b/Documentation/index.rst > @@ -12,13 +12,13 @@ > > Application Writer's Guide <guides/application-developer> > Camera Sensor Model <camera-sensor-model> > - Environment variables <environment_variables> > Feature Requirements <feature_requirements> > IPA Writer's guide <guides/ipa> > Lens driver requirements <lens_driver_requirements> > libcamera Architecture <libcamera_architecture> > Pipeline Handler Writer's Guide <guides/pipeline-handler> > Python Bindings <python-bindings> > + Runtime configuration <runtime_configuration> > Sensor driver requirements <sensor_driver_requirements> > SoftwareISP Benchmarking <software-isp-benchmarking> > Tracing guide <guides/tracing> > diff --git a/Documentation/meson.build b/Documentation/meson.build > index 3afdcc1a8..4e17c41c0 100644 > --- a/Documentation/meson.build > +++ b/Documentation/meson.build > @@ -129,7 +129,6 @@ if sphinx.found() > 'contributing.rst', > 'design/ae.rst', > 'documentation-contents.rst', > - 'environment_variables.rst', > 'feature_requirements.rst', > 'guides/application-developer.rst', > 'guides/ipa.rst', > @@ -141,6 +140,7 @@ if sphinx.found() > 'libcamera_architecture.rst', > 'mali-c55.dot', > 'python-bindings.rst', > + 'runtime_configuration.rst', > 'sensor_driver_requirements.rst', > 'software-isp-benchmarking.rst', > '../README.rst', > diff --git a/Documentation/environment_variables.rst b/Documentation/runtime_configuration.rst > similarity index 67% > rename from Documentation/environment_variables.rst > rename to Documentation/runtime_configuration.rst > index 6f1235587..8fd80c311 100644 > --- a/Documentation/environment_variables.rst > +++ b/Documentation/runtime_configuration.rst > @@ -2,15 +2,98 @@ > > .. include:: documentation-contents.rst > > -Environment variables > +Runtime configuration > ===================== > > -The libcamera behaviour can be tuned through environment variables. This > -document lists all the available variables and describes their usage. > +The libcamera behaviour can be tuned through a configuration file or > +environment variables. This document lists all the configuration options > +and describes their usage. > + > +General rules > +------------- > + > +The configuration file is looked up in the following locations, in this > +order: > + > +- $XDG_CONFIG_HOME/libcamera/configuration.yaml > +- LIBCAMERA_SYSCONF_DIR/configuration.yaml > +- LIBCAMERA_DATA_DIR/libcamera/configuration.yaml > + > +The first configuration file found wins, configuration files in other > +locations are ignored. > + > +Settings in environment variables take precedence over settings in > +configuration files. This allows overriding behaviour temporarily > +without the need to modify configuration files. > + > +Configuration options > +--------------------- > + > +Here is an overview of the available configuration options, in the YAML > +file structure: > + > +:: > + > + configuration: > + ipa: > + force_isolation: # true/false > + config_paths: > + - ... # full path to a directory > + module_paths: > + - ... # full path to a directory > + pipelines_match_list: > + - ... # pipeline name > + pipelines: > + rpi: > + bcm2835: > + pipeline_handler: > + ... > + pisp: > + pipeline_handler: > + ... > + simple: > + supported_devices: > + - driver: # driver name, e.g. `mxc-isi` > + software_isp: # true/false > + > +Configuration file example > +-------------------------- > + > +:: > + > + --- > + version: 1 > + configuration: > + ipa: > + config_paths: > + - /home/user/.libcamera/share/ipa > + - /opt/libcamera/vendor/share/ipa > + module_paths: > + - /home/user/.libcamera/lib > + - /opt/libcamera/vendor/lib > + proxy_paths: > + - /home/user/.libcamera/proxy/worker > + - /opt/libcamera/vendor/proxy/worker > + force_isolation: true > + pipelines_match_list: > + - rkisp1 > + - simple > + pipelines: > + rpi: > + bcm2835: > + pipeline_handler: > + min_unicam_buffers: 2 > + min_total_unicam_buffers: 2 > + simple: > + supported_devices: > + - driver: mxc-isi > + software_isp: true > > List of variables > ----------------- > > +The corresponding configuration file paths, if available, are listed in parentheses. > + > LIBCAMERA_LOG_FILE > The custom destination for log output. > > @@ -24,27 +107,27 @@ LIBCAMERA_LOG_LEVELS > LIBCAMERA_LOG_NO_COLOR > Disable coloring of log messages (`more <Notes about debugging_>`__). > > -LIBCAMERA_IPA_CONFIG_PATH > +LIBCAMERA_IPA_CONFIG_PATH (ipa.config_paths) > Define custom search locations for IPA configurations (`more <IPA configuration_>`__). > > Example value: ``${HOME}/.libcamera/share/ipa:/opt/libcamera/vendor/share/ipa`` > > -LIBCAMERA_IPA_FORCE_ISOLATION > +LIBCAMERA_IPA_FORCE_ISOLATION (ipa.force_isolation) > When set to a non-empty string, force process isolation of all IPA modules. > > Example value: ``1`` > > -LIBCAMERA_IPA_MODULE_PATH > +LIBCAMERA_IPA_MODULE_PATH (ipa.module_paths) > Define custom search locations for IPA modules (`more <IPA module_>`__). > > Example value: ``${HOME}/.libcamera/lib:/opt/libcamera/vendor/lib`` > > -LIBCAMERA_IPA_PROXY_PATH > +LIBCAMERA_IPA_PROXY_PATH (ipa.proxy_paths) > Define custom full path for a proxy worker for a given executable name. > > Example value: ``${HOME}/.libcamera/proxy/worker:/opt/libcamera/vendor/proxy/worker`` > > -LIBCAMERA_PIPELINES_MATCH_LIST > +LIBCAMERA_PIPELINES_MATCH_LIST (pipelines_match_list) > Define an ordered list of pipeline names to be used to match the media > devices in the system. The pipeline handler names used to populate the > variable are the ones passed to the REGISTER_PIPELINE_HANDLER() macro in the > @@ -55,6 +138,10 @@ LIBCAMERA_PIPELINES_MATCH_LIST > LIBCAMERA_RPI_CONFIG_FILE > Define a custom configuration file to use in the Raspberry Pi pipeline handler. > > + Instead of using a separate configuration file, the whole > + configuration can be put directly to the global configuration file as s/to/into/ With these changes, Reviewed-by: Paul Elder <paul.elder@ideasonboard.com> > + outlined above. > + > Example value: ``/usr/local/share/libcamera/pipeline/rpi/vc4/minimal_mem.yaml`` > > LIBCAMERA_<NAME>_TUNING_FILE > @@ -156,7 +243,7 @@ code. > IPA configuration > ~~~~~~~~~~~~~~~~~ > > -IPA modules use configuration files to store parameters. The format and > +IPA modules use their own configuration files to store parameters. The format and > contents of the configuration files is specific to the IPA module. They usually > contain tuning parameters for the algorithms, in JSON format. > > -- > 2.50.1 >
Quoting Paul Elder (2025-09-09 18:27:35) > Hi Milan, > > Thanks for the patch. > > Quoting Milan Zamazal (2025-07-29 16:31:56) > > Extend (and rename) the documentation of environment variables with > > information about the configuration file. > > > > Signed-off-by: Milan Zamazal <mzamazal@redhat.com> > > In the commit title, s/config:/Documentation:/ > (and optionally s/documentation//) nvm, it's better to keep "documentation". Paul > > > --- > > Documentation/documentation-contents.rst | 2 +- > > Documentation/index.rst | 2 +- > > Documentation/meson.build | 2 +- > > ...ariables.rst => runtime_configuration.rst} | 105 ++++++++++++++++-- > > 4 files changed, 99 insertions(+), 12 deletions(-) > > rename Documentation/{environment_variables.rst => runtime_configuration.rst} (67%) > > > > diff --git a/Documentation/documentation-contents.rst b/Documentation/documentation-contents.rst > > index 5c1118493..4be3729cf 100644 > > --- a/Documentation/documentation-contents.rst > > +++ b/Documentation/documentation-contents.rst > > @@ -7,7 +7,7 @@ > > * :doc:`/feature_requirements` > > * :doc:`/guides/application-developer` > > * :doc:`/python-bindings` > > - * :doc:`/environment_variables` > > + * :doc:`/runtime_configuration` > > * :doc:`/api-html/index` > > * :doc:`/code-of-conduct` > > * | > > diff --git a/Documentation/index.rst b/Documentation/index.rst > > index 251112fbd..200de6f67 100644 > > --- a/Documentation/index.rst > > +++ b/Documentation/index.rst > > @@ -12,13 +12,13 @@ > > > > Application Writer's Guide <guides/application-developer> > > Camera Sensor Model <camera-sensor-model> > > - Environment variables <environment_variables> > > Feature Requirements <feature_requirements> > > IPA Writer's guide <guides/ipa> > > Lens driver requirements <lens_driver_requirements> > > libcamera Architecture <libcamera_architecture> > > Pipeline Handler Writer's Guide <guides/pipeline-handler> > > Python Bindings <python-bindings> > > + Runtime configuration <runtime_configuration> > > Sensor driver requirements <sensor_driver_requirements> > > SoftwareISP Benchmarking <software-isp-benchmarking> > > Tracing guide <guides/tracing> > > diff --git a/Documentation/meson.build b/Documentation/meson.build > > index 3afdcc1a8..4e17c41c0 100644 > > --- a/Documentation/meson.build > > +++ b/Documentation/meson.build > > @@ -129,7 +129,6 @@ if sphinx.found() > > 'contributing.rst', > > 'design/ae.rst', > > 'documentation-contents.rst', > > - 'environment_variables.rst', > > 'feature_requirements.rst', > > 'guides/application-developer.rst', > > 'guides/ipa.rst', > > @@ -141,6 +140,7 @@ if sphinx.found() > > 'libcamera_architecture.rst', > > 'mali-c55.dot', > > 'python-bindings.rst', > > + 'runtime_configuration.rst', > > 'sensor_driver_requirements.rst', > > 'software-isp-benchmarking.rst', > > '../README.rst', > > diff --git a/Documentation/environment_variables.rst b/Documentation/runtime_configuration.rst > > similarity index 67% > > rename from Documentation/environment_variables.rst > > rename to Documentation/runtime_configuration.rst > > index 6f1235587..8fd80c311 100644 > > --- a/Documentation/environment_variables.rst > > +++ b/Documentation/runtime_configuration.rst > > @@ -2,15 +2,98 @@ > > > > .. include:: documentation-contents.rst > > > > -Environment variables > > +Runtime configuration > > ===================== > > > > -The libcamera behaviour can be tuned through environment variables. This > > -document lists all the available variables and describes their usage. > > +The libcamera behaviour can be tuned through a configuration file or > > +environment variables. This document lists all the configuration options > > +and describes their usage. > > + > > +General rules > > +------------- > > + > > +The configuration file is looked up in the following locations, in this > > +order: > > + > > +- $XDG_CONFIG_HOME/libcamera/configuration.yaml > > +- LIBCAMERA_SYSCONF_DIR/configuration.yaml > > +- LIBCAMERA_DATA_DIR/libcamera/configuration.yaml > > + > > +The first configuration file found wins, configuration files in other > > +locations are ignored. > > + > > +Settings in environment variables take precedence over settings in > > +configuration files. This allows overriding behaviour temporarily > > +without the need to modify configuration files. > > + > > +Configuration options > > +--------------------- > > + > > +Here is an overview of the available configuration options, in the YAML > > +file structure: > > + > > +:: > > + > > + configuration: > > + ipa: > > + force_isolation: # true/false > > + config_paths: > > + - ... # full path to a directory > > + module_paths: > > + - ... # full path to a directory > > + pipelines_match_list: > > + - ... # pipeline name > > + pipelines: > > + rpi: > > + bcm2835: > > + pipeline_handler: > > + ... > > + pisp: > > + pipeline_handler: > > + ... > > + simple: > > + supported_devices: > > + - driver: # driver name, e.g. `mxc-isi` > > + software_isp: # true/false > > + > > +Configuration file example > > +-------------------------- > > + > > +:: > > + > > + --- > > + version: 1 > > + configuration: > > + ipa: > > + config_paths: > > + - /home/user/.libcamera/share/ipa > > + - /opt/libcamera/vendor/share/ipa > > + module_paths: > > + - /home/user/.libcamera/lib > > + - /opt/libcamera/vendor/lib > > + proxy_paths: > > + - /home/user/.libcamera/proxy/worker > > + - /opt/libcamera/vendor/proxy/worker > > + force_isolation: true > > + pipelines_match_list: > > + - rkisp1 > > + - simple > > + pipelines: > > + rpi: > > + bcm2835: > > + pipeline_handler: > > + min_unicam_buffers: 2 > > + min_total_unicam_buffers: 2 > > + simple: > > + supported_devices: > > + - driver: mxc-isi > > + software_isp: true > > > > List of variables > > ----------------- > > > > +The corresponding configuration file paths, if available, are listed in parentheses. > > + > > LIBCAMERA_LOG_FILE > > The custom destination for log output. > > > > @@ -24,27 +107,27 @@ LIBCAMERA_LOG_LEVELS > > LIBCAMERA_LOG_NO_COLOR > > Disable coloring of log messages (`more <Notes about debugging_>`__). > > > > -LIBCAMERA_IPA_CONFIG_PATH > > +LIBCAMERA_IPA_CONFIG_PATH (ipa.config_paths) > > Define custom search locations for IPA configurations (`more <IPA configuration_>`__). > > > > Example value: ``${HOME}/.libcamera/share/ipa:/opt/libcamera/vendor/share/ipa`` > > > > -LIBCAMERA_IPA_FORCE_ISOLATION > > +LIBCAMERA_IPA_FORCE_ISOLATION (ipa.force_isolation) > > When set to a non-empty string, force process isolation of all IPA modules. > > > > Example value: ``1`` > > > > -LIBCAMERA_IPA_MODULE_PATH > > +LIBCAMERA_IPA_MODULE_PATH (ipa.module_paths) > > Define custom search locations for IPA modules (`more <IPA module_>`__). > > > > Example value: ``${HOME}/.libcamera/lib:/opt/libcamera/vendor/lib`` > > > > -LIBCAMERA_IPA_PROXY_PATH > > +LIBCAMERA_IPA_PROXY_PATH (ipa.proxy_paths) > > Define custom full path for a proxy worker for a given executable name. > > > > Example value: ``${HOME}/.libcamera/proxy/worker:/opt/libcamera/vendor/proxy/worker`` > > > > -LIBCAMERA_PIPELINES_MATCH_LIST > > +LIBCAMERA_PIPELINES_MATCH_LIST (pipelines_match_list) > > Define an ordered list of pipeline names to be used to match the media > > devices in the system. The pipeline handler names used to populate the > > variable are the ones passed to the REGISTER_PIPELINE_HANDLER() macro in the > > @@ -55,6 +138,10 @@ LIBCAMERA_PIPELINES_MATCH_LIST > > LIBCAMERA_RPI_CONFIG_FILE > > Define a custom configuration file to use in the Raspberry Pi pipeline handler. > > > > + Instead of using a separate configuration file, the whole > > + configuration can be put directly to the global configuration file as > > s/to/into/ > > With these changes, > > Reviewed-by: Paul Elder <paul.elder@ideasonboard.com> > > > + outlined above. > > + > > Example value: ``/usr/local/share/libcamera/pipeline/rpi/vc4/minimal_mem.yaml`` > > > > LIBCAMERA_<NAME>_TUNING_FILE > > @@ -156,7 +243,7 @@ code. > > IPA configuration > > ~~~~~~~~~~~~~~~~~ > > > > -IPA modules use configuration files to store parameters. The format and > > +IPA modules use their own configuration files to store parameters. The format and > > contents of the configuration files is specific to the IPA module. They usually > > contain tuning parameters for the algorithms, in JSON format. > > > > -- > > 2.50.1 > >
diff --git a/Documentation/documentation-contents.rst b/Documentation/documentation-contents.rst index 5c1118493..4be3729cf 100644 --- a/Documentation/documentation-contents.rst +++ b/Documentation/documentation-contents.rst @@ -7,7 +7,7 @@ * :doc:`/feature_requirements` * :doc:`/guides/application-developer` * :doc:`/python-bindings` - * :doc:`/environment_variables` + * :doc:`/runtime_configuration` * :doc:`/api-html/index` * :doc:`/code-of-conduct` * | diff --git a/Documentation/index.rst b/Documentation/index.rst index 251112fbd..200de6f67 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -12,13 +12,13 @@ Application Writer's Guide <guides/application-developer> Camera Sensor Model <camera-sensor-model> - Environment variables <environment_variables> Feature Requirements <feature_requirements> IPA Writer's guide <guides/ipa> Lens driver requirements <lens_driver_requirements> libcamera Architecture <libcamera_architecture> Pipeline Handler Writer's Guide <guides/pipeline-handler> Python Bindings <python-bindings> + Runtime configuration <runtime_configuration> Sensor driver requirements <sensor_driver_requirements> SoftwareISP Benchmarking <software-isp-benchmarking> Tracing guide <guides/tracing> diff --git a/Documentation/meson.build b/Documentation/meson.build index 3afdcc1a8..4e17c41c0 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -129,7 +129,6 @@ if sphinx.found() 'contributing.rst', 'design/ae.rst', 'documentation-contents.rst', - 'environment_variables.rst', 'feature_requirements.rst', 'guides/application-developer.rst', 'guides/ipa.rst', @@ -141,6 +140,7 @@ if sphinx.found() 'libcamera_architecture.rst', 'mali-c55.dot', 'python-bindings.rst', + 'runtime_configuration.rst', 'sensor_driver_requirements.rst', 'software-isp-benchmarking.rst', '../README.rst', diff --git a/Documentation/environment_variables.rst b/Documentation/runtime_configuration.rst similarity index 67% rename from Documentation/environment_variables.rst rename to Documentation/runtime_configuration.rst index 6f1235587..8fd80c311 100644 --- a/Documentation/environment_variables.rst +++ b/Documentation/runtime_configuration.rst @@ -2,15 +2,98 @@ .. include:: documentation-contents.rst -Environment variables +Runtime configuration ===================== -The libcamera behaviour can be tuned through environment variables. This -document lists all the available variables and describes their usage. +The libcamera behaviour can be tuned through a configuration file or +environment variables. This document lists all the configuration options +and describes their usage. + +General rules +------------- + +The configuration file is looked up in the following locations, in this +order: + +- $XDG_CONFIG_HOME/libcamera/configuration.yaml +- LIBCAMERA_SYSCONF_DIR/configuration.yaml +- LIBCAMERA_DATA_DIR/libcamera/configuration.yaml + +The first configuration file found wins, configuration files in other +locations are ignored. + +Settings in environment variables take precedence over settings in +configuration files. This allows overriding behaviour temporarily +without the need to modify configuration files. + +Configuration options +--------------------- + +Here is an overview of the available configuration options, in the YAML +file structure: + +:: + + configuration: + ipa: + force_isolation: # true/false + config_paths: + - ... # full path to a directory + module_paths: + - ... # full path to a directory + pipelines_match_list: + - ... # pipeline name + pipelines: + rpi: + bcm2835: + pipeline_handler: + ... + pisp: + pipeline_handler: + ... + simple: + supported_devices: + - driver: # driver name, e.g. `mxc-isi` + software_isp: # true/false + +Configuration file example +-------------------------- + +:: + + --- + version: 1 + configuration: + ipa: + config_paths: + - /home/user/.libcamera/share/ipa + - /opt/libcamera/vendor/share/ipa + module_paths: + - /home/user/.libcamera/lib + - /opt/libcamera/vendor/lib + proxy_paths: + - /home/user/.libcamera/proxy/worker + - /opt/libcamera/vendor/proxy/worker + force_isolation: true + pipelines_match_list: + - rkisp1 + - simple + pipelines: + rpi: + bcm2835: + pipeline_handler: + min_unicam_buffers: 2 + min_total_unicam_buffers: 2 + simple: + supported_devices: + - driver: mxc-isi + software_isp: true List of variables ----------------- +The corresponding configuration file paths, if available, are listed in parentheses. + LIBCAMERA_LOG_FILE The custom destination for log output. @@ -24,27 +107,27 @@ LIBCAMERA_LOG_LEVELS LIBCAMERA_LOG_NO_COLOR Disable coloring of log messages (`more <Notes about debugging_>`__). -LIBCAMERA_IPA_CONFIG_PATH +LIBCAMERA_IPA_CONFIG_PATH (ipa.config_paths) Define custom search locations for IPA configurations (`more <IPA configuration_>`__). Example value: ``${HOME}/.libcamera/share/ipa:/opt/libcamera/vendor/share/ipa`` -LIBCAMERA_IPA_FORCE_ISOLATION +LIBCAMERA_IPA_FORCE_ISOLATION (ipa.force_isolation) When set to a non-empty string, force process isolation of all IPA modules. Example value: ``1`` -LIBCAMERA_IPA_MODULE_PATH +LIBCAMERA_IPA_MODULE_PATH (ipa.module_paths) Define custom search locations for IPA modules (`more <IPA module_>`__). Example value: ``${HOME}/.libcamera/lib:/opt/libcamera/vendor/lib`` -LIBCAMERA_IPA_PROXY_PATH +LIBCAMERA_IPA_PROXY_PATH (ipa.proxy_paths) Define custom full path for a proxy worker for a given executable name. Example value: ``${HOME}/.libcamera/proxy/worker:/opt/libcamera/vendor/proxy/worker`` -LIBCAMERA_PIPELINES_MATCH_LIST +LIBCAMERA_PIPELINES_MATCH_LIST (pipelines_match_list) Define an ordered list of pipeline names to be used to match the media devices in the system. The pipeline handler names used to populate the variable are the ones passed to the REGISTER_PIPELINE_HANDLER() macro in the @@ -55,6 +138,10 @@ LIBCAMERA_PIPELINES_MATCH_LIST LIBCAMERA_RPI_CONFIG_FILE Define a custom configuration file to use in the Raspberry Pi pipeline handler. + Instead of using a separate configuration file, the whole + configuration can be put directly to the global configuration file as + outlined above. + Example value: ``/usr/local/share/libcamera/pipeline/rpi/vc4/minimal_mem.yaml`` LIBCAMERA_<NAME>_TUNING_FILE @@ -156,7 +243,7 @@ code. IPA configuration ~~~~~~~~~~~~~~~~~ -IPA modules use configuration files to store parameters. The format and +IPA modules use their own configuration files to store parameters. The format and contents of the configuration files is specific to the IPA module. They usually contain tuning parameters for the algorithms, in JSON format.
Extend (and rename) the documentation of environment variables with information about the configuration file. Signed-off-by: Milan Zamazal <mzamazal@redhat.com> --- Documentation/documentation-contents.rst | 2 +- Documentation/index.rst | 2 +- Documentation/meson.build | 2 +- ...ariables.rst => runtime_configuration.rst} | 105 ++++++++++++++++-- 4 files changed, 99 insertions(+), 12 deletions(-) rename Documentation/{environment_variables.rst => runtime_configuration.rst} (67%)