[libcamera-devel] Documentation: Add descriptions for env. variables
diff mbox series

Message ID 20201029083626.21213-1-sebastian.fricke.linux@gmail.com
State Superseded
Headers show
Series
  • [libcamera-devel] Documentation: Add descriptions for env. variables
Related show

Commit Message

Sebastian Fricke Oct. 29, 2020, 8:36 a.m. UTC 
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
for how to use them for debugging.

Changes since V1:
* abandon the usage of tables as they are too clunky and difficult to
maintain
* Fix a wrong example that does not work on most distributions and setups
* Improve structure of log categories

Signed-off-by: Sebastian Fricke <sebastian.fricke.linux@gmail.com>
---
 .../guides/environment_variables.rst          | 107 ++++++++++++++++++
 Documentation/index.rst                       |   1 +
 Documentation/meson.build                     |   1 +
 3 files changed, 109 insertions(+)
 create mode 100644 Documentation/guides/environment_variables.rst

Patch
diff mbox series 

diff --git a/Documentation/guides/environment_variables.rst b/Documentation/guides/environment_variables.rst
new file mode 100644
index 0000000..6e627fd
--- /dev/null
+++ b/Documentation/guides/environment_variables.rst
@@ -0,0 +1,107 @@ 
+Environment variables
+=====================
+
+List of variables
+-----------------
+
+* LIBCAMERA_LOG_FILE
+        * Brief description: Custom destination for log output
+        * Example value: ``/home/{user}/camera_log.log``
+
+* LIBCAMERA_LOG_LEVELS
+        * Brief description: Configure the verbosity of log messages for different categories
+        * Example value: ``*:DEBUG``
+        * Details: `Levels <#log-levels>`__ and `Categories <#log-categories>`__ 
+* LIBCAMERA_IPA_CONFIG_PATH
+        * Brief description: Define custom search locations for IPA configurations
+        * Example value: ``/usr/path/one:/tmp/path/two``
+        * Details: `IPA configuration <#ipa-configuration>`__
+* LIBCAMERA_IPA_MODULE_PATH
+        * Brief description: Define custom search locations for IPA modules
+        * Example value: ``/usr/path/one:/tmp/path/two``
+        * Details: `IPA module <#ipa-module>`__
+
+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 the libcamera API.
+
+You can define the values for these variables locally or globally. If you set it locally, note that for Bash-like shells, you need to set the value of `LIBCAMERA_LOG_LEVELS` on the same line as the command, as shown in the first example.
+
+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 & V4L2 within a
+global environment:
+
+.. code:: bash
+
+   :~$ export LIBCAMERA_LOG_LEVELS='Camera:DEBUG,V4L2:DEBUG'
+   :~$ cam --list
+
+An alternative value to for `LIBCAMERA_LOG_LEVELS` to enable
+debugging output for all categories is 0.
+
+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
+-  INFO
+-  WARN
+-  ERROR
+-  FATAL
+
+Log categories 
+~~~~~~~~~~~~~~~
+
+* Major classes: 
+          + Camera, CameraMetadata, CameraSensor, Controls, DeviceEnumerator, Formats, MediaDevice, Request
+
+* Pipeline:
+          + Pipeline, IPU3, RPI, RPISTREAM, RPI_S_W, RkISP1, SimplePipeline, Timeline, UVC, VIMC
+
+* V4L2-API:
+          + V4L2, V4L2Compat
+
+* IPA (Image Processing Algorithms):
+          + IPAManager, IPAModule, IPAProxy, IPAProxyLinuxWorker, IPARkISP1, IPARPI, IPAVimc, RPiFocus
+
+* Android specific:
+          + CameraMetadata, EXIF, HAL, JPEG
+
+* Others:
+          + Allocator, Buffer, Event, File, FileDescriptor, IPCUnixSocket, LogAPITest, LogProcessTest, Message, Object, Process, Serialization, Serializer, Stream, SysFs, Thread, Timeline, Timer
+
+IPA configuration 
+~~~~~~~~~~~~~~~~~~
+
+The format and contents of the configuration file are specific to the
+IPA (Image processing algorithm). It usually contains data that optimize
+the behaviour of the algorithms stored in JSON format. The
+``LIBCAMERA_IPA_CONFIG_PATH`` variable can be used to specify custom
+storeage locations to search for those configuration files.
+
+`Examples <https://git.libcamera.org/libcamera/libcamera.git/tree/src/ipa/raspberrypi/data>`__
+
+IPA module 
+~~~~~~~~~~~
+
+Existing IPA modules can be located in the
+`src/ipa/ <https://git.libcamera.org/libcamera/libcamera.git/tree/src/ipa>`__
+directory, they provide the interface to the ISP(image signal processer)
+and the implementation of algorithms. With the
+``LIBCAMERA_IPA_MODULE_PATH``, you can specify a non-default location to
+search for these modules.
diff --git a/Documentation/index.rst b/Documentation/index.rst
index a30688a..924bd12 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -16,3 +16,4 @@ 
    Developer Guide <guides/introduction>
    Application Writer's Guide <guides/application-developer>
    Pipeline Handler Writer's Guide <guides/pipeline-handler>
+   Environment variables <guides/environment_variables.rst>
diff --git a/Documentation/meson.build b/Documentation/meson.build
index d3d64f7..0e7ba7d 100644
--- a/Documentation/meson.build
+++ b/Documentation/meson.build
@@ -56,6 +56,7 @@  if sphinx.found()
         'guides/introduction.rst',
         'guides/application-developer.rst',
         'guides/pipeline-handler.rst',
+        'guides/environment_variables.rst',
     ]
 
     release = 'release=v' + libcamera_git_version