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

[Milan Zamazal]

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
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?

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?

>> +      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
>>