Documentation: Add global configuration file documentation

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

Signed-off-by: Milan Zamazal <mzamazal@redhat.com>
Reviewed-by: Paul Elder <paul.elder@ideasonboard.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

Documentation/index.rst

@@ -8,9 +8,9 @@
 
    Introduction <self>
    Feature Requirements <feature_requirements>
+   Runtime configuration <runtime_configuration>
    Application Writer's Guide <guides/application-developer>
    Python Bindings <python-bindings>
-   Environment variables <environment_variables>
    Public API <public-api/index>
 
 .. toctree::

Documentation/meson.build

@@ -156,7 +156,6 @@ if sphinx.found()
         sphinx_conf,
         'contributing.rst',
         'design/ae.rst',
-        'environment_variables.rst',
         'feature_requirements.rst',
         'guides/application-developer.rst',
         'guides/ipa.rst',
@@ -170,6 +169,7 @@ if sphinx.found()
         'mali-c55.dot',
         'public-api/index.rst',
         'python-bindings.rst',
+        'runtime_configuration.rst',
         'sensor_driver_requirements.rst',
         'software-isp-benchmarking.rst',
        '../README.rst',

Documentation/runtime_configuration.rst

@@ -1,13 +1,82 @@
 .. 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.
 
-List of variables
------------------
+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
+- LIBCAMERA_DATA_DIR/libcamera/configuration.yaml
+
+The first configuration file found wins, 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:
+      force_isolation: # true/false
+      config_paths:
+        - ... # full path to a directory
+      module_paths:
+        - ... # full path to a directory
+    pipelines_match_list:
+      - ... # pipeline name
+    pipelines:
+      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
+     pipelines_match_list:
+       - rkisp1
+       - simple
+     pipelines:
+       simple:
+         supported_devices:
+           - driver: mxc-isi
+             software_isp: true
+
+List of variables and configuration options
+-------------------------------------------
 
 LIBCAMERA_LOG_FILE
    The custom destination for log output.
@@ -22,27 +91,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
@@ -60,6 +129,13 @@ LIBCAMERA_<NAME>_TUNING_FILE
 
    Example value: ``/usr/local/share/libcamera/ipa/rpi/vc4/custom_sensor.json``
 
+pipelines.simple.supported_devices.driver, pipelines.simple.supported_devices.software_isp
+   Override whether software ISP is enabled for the given driver.
+
+   Example `driver` value: ``mxc-isi``
+
+   Example `software_isp` value: ``true``
+
 Further details
 ---------------
 
@@ -154,9 +230,9 @@ code.
 IPA configuration
 ~~~~~~~~~~~~~~~~~
 
-IPA modules use 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.
+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.
 
 The ``LIBCAMERA_IPA_CONFIG_PATH`` variable can be used to specify custom
 storage locations to search for those configuration files.