[PATCH v2 11/13] config: Add global configuration file documentation
Kieran Bingham
kieran.bingham at ideasonboard.com
Tue Apr 23 14:02:54 CEST 2024
Quoting Milan Zamazal (2024-04-23 12:48:10)
> Kieran Bingham <kieran.bingham at ideasonboard.com> writes:
>
> > Quoting Milan Zamazal (2024-04-23 11:30:26)
> >> Extend (and rename) the documentation of environment variables with
> >> information about the configuration file.
> >
> >>
> >> Signed-off-by: Milan Zamazal <mzamazal at redhat.com>
> >> ---
> >> Documentation/index.rst | 2 +-
> >> Documentation/meson.build | 2 +-
> >> ...ariables.rst => runtime_configuration.rst} | 96 ++++++++++++++++---
> >> 3 files changed, 87 insertions(+), 13 deletions(-)
> >> rename Documentation/{environment_variables.rst => runtime_configuration.rst} (65%)
> >>
> >> diff --git a/Documentation/index.rst b/Documentation/index.rst
> >> index 5442ae75..aa277b85 100644
> >> --- a/Documentation/index.rst
> >> +++ b/Documentation/index.rst
> >> @@ -19,7 +19,7 @@
> >> Pipeline Handler Writer's Guide <guides/pipeline-handler>
> >> IPA Writer's guide <guides/ipa>
> >> Tracing guide <guides/tracing>
> >> - Environment variables <environment_variables>
> >> + Runtime configuration <runtime_configuration>
> >> Sensor driver requirements <sensor_driver_requirements>
> >> Lens driver requirements <lens_driver_requirements>
> >> Python Bindings <python-bindings>
> >> diff --git a/Documentation/meson.build b/Documentation/meson.build
> >> index 3872e0a8..f8ca63eb 100644
> >> --- a/Documentation/meson.build
> >> +++ b/Documentation/meson.build
> >> @@ -70,7 +70,6 @@ if sphinx.found()
> >> 'conf.py',
> >> 'contributing.rst',
> >> 'docs.rst',
> >> - 'environment_variables.rst',
> >> 'guides/application-developer.rst',
> >> 'guides/introduction.rst',
> >> 'guides/ipa.rst',
> >> @@ -79,6 +78,7 @@ if sphinx.found()
> >> 'index.rst',
> >> 'lens_driver_requirements.rst',
> >> '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 65%
> >> rename from Documentation/environment_variables.rst
> >> rename to Documentation/runtime_configuration.rst
> >> index a9b230bc..d3972363 100644
> >> --- a/Documentation/environment_variables.rst
> >> +++ b/Documentation/runtime_configuration.rst
> >> @@ -1,43 +1,117 @@
> >> .. SPDX-License-Identifier: CC-BY-SA-4.0
> >>
> >> -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
> >> +- /etc/libcamera/configuration.yaml
> >> +
> >> +The first configuration file found wins, contingent 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:
> >> + config_paths: # full paths to directories, separated by colons
> >> + force_isolation: # true/false
> >> + module_paths: # full paths to directories, separated by colons
> >> + log:
> >> + color: # true/false for color/no-color
> >> + file: # either `syslog` or a full path
> >> + levels: # see Log levels
> >> + pipelines:
> >> + rkisp1:
> >> + tuning_file: # full path
> >> + rpi:
> >> + config_file: # full path
> >> + tuning_file: # full path
> >
> > In fact, for the tuning files - I believe these need to be indexed by
> > camera id ...
> >
> > Imagine running qcam on a Raspberry Pi 5 with two cameras. Setting a
> > single tuning file would then override and apply for both cameras
> > incorrectly (qcam can run either camera selectively, and same with the
> > pipewire use cases etc...)
>
> I see. This is based on the current code, which looks for a configuration file
Oh absolutely. But I think there's a big difference when we move these
to a configuration file which outlives a single run of a single binary
and will affect /all/ cameras managed by a single pipeline handler.
I don't think /you/ specifically have to address this - but it's
important to consider here that it affects any camera.
> based on the given sensor model but allows overriding it with an environment
> variable (and here also the given configuration option). The corresponding
> commit messages don't provide the reason for overriding, perhaps for debugging
> or experimentation?
Some of Raspberry Pi's cameras have multiple tuning files, so this lets
users choose which one to select at present.
It's definitely somethign that is worthy of being in a configuration
file. But it's a per-camera thing, not a per-pipeline handler thing.
I suspect it means even the environment variable is misleading too! The
same issue would occur there if you launch qcam with a single tuning
file overridden.
> Maybe we could leave these configuration environment variables without
> configuration file options or we could enhance the configuration as you suggest.
> But I don't know what's the intended use case. Suggestions?
Naush - any thoughts here?
--
Kieran
>
> >> + 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
> >> + force_isolation: true
> >> + log:
> >> + color: false
> >> + file: syslog
> >> + levels: 'IPAManager:DEBUG'
> >> + pipelines:
> >> + rkisp1:
> >> + tuning_file: /home/user/.libcamera/rkisp1.yaml
> >> + rpi:
> >> + config_file: /usr/local/share/libcamera/pipeline/rpi/vc4/minimal_mem.yaml
> >> + simple:
> >> + supported_devices:
> >> + - driver: mxc-isi
> >> + software_isp: true
> >>
> >> List of variables
> >> -----------------
> >>
> >> -LIBCAMERA_LOG_FILE
> >> +The corresponding configuration file paths are listed in parentheses.
> >> +
> >> +LIBCAMERA_LOG_FILE (log.file)
> >> The custom destination for log output.
> >>
> >> Example value: ``/home/{user}/camera_log.log``
> >>
> >> -LIBCAMERA_LOG_LEVELS
> >> +LIBCAMERA_LOG_LEVELS (log.levels)
> >> Configure the verbosity of log messages for different categories (`more <Log levels_>`__).
> >>
> >> Example value: ``*:DEBUG``
> >>
> >> -LIBCAMERA_LOG_NO_COLOR
> >> +LIBCAMERA_LOG_NO_COLOR (log.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_RPI_CONFIG_FILE
> >> +LIBCAMERA_RPI_CONFIG_FILE (pipelines.rpi.config_file)
> >> Define a custom configuration file to use in the Raspberry Pi pipeline handler.
> >>
> >> Example value: ``/usr/local/share/libcamera/pipeline/rpi/vc4/minimal_mem.yaml``
> >> @@ -136,7 +210,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.42.0
> >>
>
More information about the libcamera-devel
mailing list