Documentation: Add descriptions for environment variables

Describe the environment variables used in libcamera, excluded
variables are `LIBCAMERA_IPA_FORCE_C_API` and `LIBCAMERA_IPA_PROXY_PATH`,
the former because it is likely to be removed and the later because
it has no current use-case.

Add a brief explanation for the IPA configuration and IPA modules.
List all the available Log levels and categories and add a short guide
on how to use them for debugging.

Signed-off-by: Sebastian Fricke <sebastian.fricke.linux@gmail.com>
Reviewed-by: Jacopo Mondi <jacopo@jmondi.org>
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

3 files changed, 136 insertions, 0 deletions

diff --git a/Documentation/environment_variables.rst b/Documentation/environment_variables.rst
new file mode 100644
index 00000000..01294d79
--- /dev/null
+++ b/Documentation/environment_variables.rst
@@ -0,0 +1,134 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+Environment variables
+=====================
+
+The libcamera behaviour can be tuned through environment variables. This
+document lists all the available variables and describes their usage.
+
+List of variables
+-----------------
+
+LIBCAMERA_LOG_FILE
+   The custom destination for log output.
+
+   Example value: ``/home/{user}/camera_log.log``
+
+LIBCAMERA_LOG_LEVELS
+   Configure the verbosity of log messages for different categories (`more <#log-levels>`__).
+
+   Example value: ``*:DEBUG``
+
+LIBCAMERA_IPA_CONFIG_PATH
+   Define custom search locations for IPA configurations (`more <#ipa-configuration>`__).
+
+   Example value: ``${HOME}/.libcamera/share/ipa:/opt/libcamera/vendor/share/ipa``
+
+LIBCAMERA_IPA_MODULE_PATH
+   Define custom search locations for IPA modules (`more <#ipa-module>`__).
+
+   Example value: ``${HOME}/.libcamera/lib:/opt/libcamera/vendor/lib``
+
+Further details
+---------------
+
+Notes about debugging
+~~~~~~~~~~~~~~~~~~~~~
+
+The environment variables `LIBCAMERA_LOG_FILE` and `LIBCAMERA_LOG_LEVELS` are
+used to modify the destination and verbosity of messages provided by libcamera.
+
+The `LIBCAMERA_LOG_LEVELS` variable accepts a comma-separated list of
+'category:level' pairs.
+
+The `level <#log-levels>`__ part is mandatory and can either be specified by
+name or by numerical index associated with each level.
+
+The optional `category <#log-categories>`__ is a string matching the categories
+defined by each file in the source base using the logging infrastructure. It
+can include a wildcard ('*') character at the end to match multiple categories.
+
+For more information refer to the `API documentation <http://libcamera.org/api-html/log_8h.html#details>`__.
+
+Examples:
+
+Enable full debug output to a separate file, for every `category <#log-categories>`__
+within a local environment:
+
+.. code:: bash
+
+   :~$ LIBCAMERA_LOG_FILE='/tmp/example_log.log' \
+       LIBCAMERA_LOG_LEVELS=0 \
+       cam --list
+
+Enable full debug output for the categories `Camera` and `V4L2` within a global
+environment:
+
+.. code:: bash
+
+   :~$ export LIBCAMERA_LOG_LEVELS='Camera:DEBUG,V4L2:DEBUG'
+   :~$ cam --list
+
+Log levels
+~~~~~~~~~~~
+
+This is the list of available log levels, notice that all levels below
+the chosen one are printed, while those above are discarded.
+
+-  DEBUG (0)
+-  INFO (1)
+-  WARN (2)
+-  ERROR (3)
+-  FATAL (4)
+
+Example:
+If you choose WARN (2), you will be able to see WARN (2), ERROR (3) and FATAL (4)
+but not DEBUG (0) and INFO (1).
+
+Log categories
+~~~~~~~~~~~~~~~
+
+Every category represents a specific area of the libcamera codebase,
+the names can be located within the source code, for example:
+`src/libcamera/camera_manager.cpp <https://git.libcamera.org/libcamera/libcamera.git/tree/src/libcamera/camera_manager.cpp#n35>`__
+
+.. code:: cpp
+
+   LOG_DEFINE_CATEGORY(Camera)
+
+There are two available macros used to assign a category name to a part of the
+libcamera codebase:
+
+LOG_DEFINE_CATEGORY
+   This macro is required, in order to use the `LOGC` macro for a particular
+   category. It can only be used once for each category. If you want to create
+   log messages within multiple compilation units for the same category utilize
+   the `LOG_DECLARE_CATEGORY` macro, in every file except the definition file.
+LOG_DECLARE_CATEGORY
+   Used for sharing an already defined category between multiple separate
+   compilation units.
+
+Both macros have to be used within the libcamera namespace of the C++ source
+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.
+
+The `LIBCAMERA_IPA_CONFIG_PATH` variable can be used to specify custom
+storage locations to search for those configuration files.
+
+`Examples <https://git.libcamera.org/libcamera/libcamera.git/tree/src/ipa/raspberrypi/data>`__
+
+IPA module
+~~~~~~~~~~~
+
+In order to locate the correct IPA module for your hardware, libcamera gathers
+existing IPA modules from multiple locations. The default locations for this
+operation are the installed system path (for example on Debian:
+``/usr/local/x86_64-pc-linux-gnu/libcamera``) and the build directory.
+With the `LIBCAMERA_IPA_MODULE_PATH`, you can specify a non-default
+location to search for IPA modules.
diff --git a/Documentation/index.rst b/Documentation/index.rst
index ff697d4f..c49db18d 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -17,3 +17,4 @@
    Application Writer's Guide <guides/application-developer>
    Pipeline Handler Writer's Guide <guides/pipeline-handler>
    Tracing guide <guides/tracing>
+   Environment variables <environment_variables>
diff --git a/Documentation/meson.build b/Documentation/meson.build
index 26a12fcd..0cd5729a 100644
--- a/Documentation/meson.build
+++ b/Documentation/meson.build
@@ -52,6 +52,7 @@ if sphinx.found()
         'conf.py',
         'contributing.rst',
         'docs.rst',
+        'environment_variables.rst',
         'index.rst',
         'guides/introduction.rst',
         'guides/application-developer.rst',