[v12,08/12] config: Add global configuration file documentation

23724 diff mbox series

Extend (and rename) the documentation of environment variables with
information about the configuration file.

Signed-off-by: Milan Zamazal <mzamazal@redhat.com>
---
 Documentation/documentation-contents.rst      |   2 +-
 Documentation/index.rst                       |   2 +-
 Documentation/meson.build                     |   2 +-
 ...ariables.rst => runtime_configuration.rst} | 105 ++++++++++++++++--
 4 files changed, 99 insertions(+), 12 deletions(-)
 rename Documentation/{environment_variables.rst => runtime_configuration.rst} (66%)

Hi

2025. 07. 02. 15:10 keltezéssel, Milan Zamazal írta:
> Extend (and rename) the documentation of environment variables with
> information about the configuration file.
> 
> Signed-off-by: Milan Zamazal <mzamazal@redhat.com>
> ---
>   Documentation/documentation-contents.rst      |   2 +-
>   Documentation/index.rst                       |   2 +-
>   Documentation/meson.build                     |   2 +-
>   ...ariables.rst => runtime_configuration.rst} | 105 ++++++++++++++++--
>   4 files changed, 99 insertions(+), 12 deletions(-)
>   rename Documentation/{environment_variables.rst => runtime_configuration.rst} (66%)
> 
> diff --git a/Documentation/documentation-contents.rst b/Documentation/documentation-contents.rst
> index 5c1118493..4be3729cf 100644
> --- a/Documentation/documentation-contents.rst
> +++ b/Documentation/documentation-contents.rst
> @@ -7,7 +7,7 @@
>      * :doc:`/feature_requirements`
>      * :doc:`/guides/application-developer`
>      * :doc:`/python-bindings`
> -   * :doc:`/environment_variables`
> +   * :doc:`/runtime_configuration`
>      * :doc:`/api-html/index`
>      * :doc:`/code-of-conduct`
>      * |
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index 251112fbd..200de6f67 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -12,13 +12,13 @@
>   
>      Application Writer's Guide <guides/application-developer>
>      Camera Sensor Model <camera-sensor-model>
> -   Environment variables <environment_variables>
>      Feature Requirements <feature_requirements>
>      IPA Writer's guide <guides/ipa>
>      Lens driver requirements <lens_driver_requirements>
>      libcamera Architecture <libcamera_architecture>
>      Pipeline Handler Writer's Guide <guides/pipeline-handler>
>      Python Bindings <python-bindings>
> +   Runtime configuration <runtime_configuration>
>      Sensor driver requirements <sensor_driver_requirements>
>      SoftwareISP Benchmarking <software-isp-benchmarking>
>      Tracing guide <guides/tracing>
> diff --git a/Documentation/meson.build b/Documentation/meson.build
> index 0fc5909d0..6d5af0f62 100644
> --- a/Documentation/meson.build
> +++ b/Documentation/meson.build
> @@ -128,7 +128,6 @@ if sphinx.found()
>           'contributing.rst',
>           'design/ae.rst',
>           'documentation-contents.rst',
> -        'environment_variables.rst',
>           'feature_requirements.rst',
>           'guides/application-developer.rst',
>           'guides/ipa.rst',
> @@ -140,6 +139,7 @@ if sphinx.found()
>           'libcamera_architecture.rst',
>           'mali-c55.dot',
>           '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 66%
> rename from Documentation/environment_variables.rst
> rename to Documentation/runtime_configuration.rst
> index 6f1235587..f1fea1c1c 100644
> --- a/Documentation/environment_variables.rst
> +++ b/Documentation/runtime_configuration.rst
> @@ -2,15 +2,98 @@
>   
>   .. include:: documentation-contents.rst
>   
> -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

Should be `LIBCAMERA_DATA_DIR` instead of /etc.


> +
> +The first configuration file found wins, contingent configuration files
> +in other locations are ignored.

My native language is not English, but I am wondering if "contingent" is the
word to use here? I think I would personally just omit the word entirely, or
say "subsequent", or "[...] other configuration files in different locations [...]".


> +
> +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
> +      ipas:
> +        rkisp1:
> +          tuning_file: # full path
> +        rpi:
> +          tuning_file: # full path
> +    pipelines_match_list: # pipeline names, separated by commas
> +    pipelines:
> +      rpi:
> +        target: TARGET
> +        pipeline_handler:
> +          ...

rpi:
   bcm2835:
     pipeline_handler:
       ...
   pisp:
     pipeline_handler:
       ...


> +      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
> +       proxy_paths:
> +       - /home/user/.libcamera/proxy/worker
> +       - /opt/libcamera/vendor/proxy/worker
> +       force_isolation: true
> +       ipas:
> +         rpi:
> +           tuning_file: /home/pi/imx283.json
> +     pipelines_match_list: rkisp1,simple
> +     pipelines:
> +       rpi:
> +         target: bcm2835
> +         pipeline_handler:
> +            min_unicam_buffers: 2
> +            min_total_unicam_buffers: 2

Same here.


Regards,
Barnabás Pőcze


> +       simple:
> +         supported_devices:
> +         - driver: mxc-isi
> +           software_isp: true
>   
>   List of variables
>   -----------------
>   
> +The corresponding configuration file paths, if available, are listed in parentheses.
> +
>   LIBCAMERA_LOG_FILE
>      The custom destination for log output.
>   
> @@ -24,27 +107,27 @@ LIBCAMERA_LOG_LEVELS
>   LIBCAMERA_LOG_NO_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_IPA_PROXY_PATH
> +LIBCAMERA_IPA_PROXY_PATH (ipa.proxy_paths)
>      Define custom full path for a proxy worker for a given executable name.
>   
>      Example value: ``${HOME}/.libcamera/proxy/worker:/opt/libcamera/vendor/proxy/worker``
>   
> -LIBCAMERA_PIPELINES_MATCH_LIST
> +LIBCAMERA_PIPELINES_MATCH_LIST (pipelines_match_list)
>      Define an ordered list of pipeline names to be used to match the media
>      devices in the system. The pipeline handler names used to populate the
>      variable are the ones passed to the REGISTER_PIPELINE_HANDLER() macro in the
> @@ -55,6 +138,10 @@ LIBCAMERA_PIPELINES_MATCH_LIST
>   LIBCAMERA_RPI_CONFIG_FILE
>      Define a custom configuration file to use in the Raspberry Pi pipeline handler.
>   
> +   Instead of using a separate configuration file, the whole
> +   configuration can be put directly to the global configuration file as
> +   outlined above.
> +
>      Example value: ``/usr/local/share/libcamera/pipeline/rpi/vc4/minimal_mem.yaml``
>   
>   LIBCAMERA_<NAME>_TUNING_FILE
> @@ -156,7 +243,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.
>