[PATCH v2 11/13] config: Add global configuration file documentation
Kieran Bingham
kieran.bingham at ideasonboard.com
Tue Apr 23 13:03:18 CEST 2024
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...)
> + 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