[v3,12/14] config: Add global configuration file documentation
diff mbox series

Message ID 20240627145156.1094127-13-mzamazal@redhat.com
State Superseded
Headers show
Series
  • Add global configuration file
Related show

Commit Message

Milan Zamazal June 27, 2024, 2:51 p.m. UTC
Extend (and rename) the documentation of environment variables with
information about the configuration file.

Signed-off-by: Milan Zamazal <mzamazal@redhat.com>
---
 Documentation/index.rst                       |   2 +-
 Documentation/meson.build                     |   2 +-
 ...ariables.rst => runtime_configuration.rst} | 108 ++++++++++++++++--
 3 files changed, 98 insertions(+), 14 deletions(-)
 rename Documentation/{environment_variables.rst => runtime_configuration.rst} (63%)

Patch
diff mbox series

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 30d39523..c07b56d8 100644
--- a/Documentation/meson.build
+++ b/Documentation/meson.build
@@ -71,7 +71,6 @@  if sphinx.found()
         'conf.py',
         'contributing.rst',
         'docs.rst',
-        'environment_variables.rst',
         'guides/application-developer.rst',
         'guides/introduction.rst',
         'guides/ipa.rst',
@@ -80,6 +79,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 63%
rename from Documentation/environment_variables.rst
rename to Documentation/runtime_configuration.rst
index 4e9fbb27..70a8bd57 100644
--- a/Documentation/environment_variables.rst
+++ b/Documentation/runtime_configuration.rst
@@ -1,43 +1,127 @@ 
 .. 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_match_list: # pipeline names, separated by commas
+    pipelines:
+      rkisp1:
+        cameras:
+        - CAMERA-ID:
+          tuning-file: # full path
+      rpi:
+        config_file: # full path
+        cameras:
+        - CAMERA-ID:
+          tuning-file: # full path
+      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_match_list: rkisp1,simple
+     pipelines:
+       rkisp1:
+         cameras:
+         - "/base/axi/pcie@120000/rp1/i2c@88000/imx283@1a":
+           tuning_file: /home/pi/imx283.json
+         - "/base/axi/pcie@120000/rp1/i2c@80000/imx335@1a":
+           tuning_file: /home/pi/imx335.json
+       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_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
@@ -45,7 +129,7 @@  LIBCAMERA_PIPELINES_MATCH_LIST
 
    Example value: ``rkisp1,simple``
 
-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``
@@ -144,7 +228,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.