[PATCH v2 11/13] config: Add global configuration file documentation
Naushir Patuck
naush at raspberrypi.com
Tue Apr 23 16:02:57 CEST 2024
On Tue, 23 Apr 2024 at 13:02, Kieran Bingham
<kieran.bingham at ideasonboard.com> wrote:
>
> 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?
This is indeed an annoying problem - even now with our environment
variable workaround. Obviously you can run with different env
variables in different processes to workaround this.
There is a problem with numbering cameras in the config file though -
the order that cameras get enumerated by the kernel is not fully
deterministic, which makes per-camera config options a bit more
complicated.
Naush
>
> --
> 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