[PATCH v2 11/13] config: Add global configuration file documentation

[Kieran Bingham]

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
>