summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSebastian Fricke <sebastian.fricke.linux@gmail.com>2020-11-20 16:52:34 +0100
committerLaurent Pinchart <laurent.pinchart@ideasonboard.com>2020-12-27 12:29:05 +0200
commit3fde82d8490e7fbdc02922d2b692fe3c0d9c8e29 (patch)
tree5ef23678a1e0987b8fa75fcaeeacd1b832180c22
parentd769cbb8348a869bd513aac5145996376b7c4568 (diff)
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>
-rw-r--r--Documentation/environment_variables.rst134
-rw-r--r--Documentation/index.rst1
-rw-r--r--Documentation/meson.build1
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',