[PATCH v2 11/13] config: Add global configuration file documentation
Kieran Bingham
kieran.bingham at ideasonboard.com
Tue Apr 23 16:13:00 CEST 2024
Quoting Naushir Patuck (2024-04-23 15:02:57)
> 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.
Oh - absolutely. Any camera referenced in a config file should be
referenced by it's camera identifier.
pi at beehive:~ $ cam --list
Available cameras:
1: 'imx283' (/base/axi/pcie at 120000/rp1/i2c at 88000/imx283 at 1a)
2: 'imx335' (/base/axi/pcie at 120000/rp1/i2c at 80000/imx335 at 1a)
So that would have to be:
cameras:
- "/base/axi/pcie at 120000/rp1/i2c at 88000/imx283 at 1a":
tuning_file: /home/pi/imx283.json
- "/base/axi/pcie at 120000/rp1/i2c at 80000/imx335 at 1a":
tuning_file: /home/pi/imx335.json
Assuming the above doesn't break yaml requirements.
> 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