[libcamera-devel] [PATCH] Documentation: Add descriptions for env. variables
Sebastian Fricke
sebastian.fricke.linux at gmail.com
Tue Oct 27 16:12:40 CET 2020
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.
Signed-off-by: Sebastian Fricke <sebastian.fricke.linux at gmail.com>
---
.../guides/environment_variables.rst | 141 ++++++++++++++++++
Documentation/index.rst | 1 +
Documentation/meson.build | 1 +
3 files changed, 143 insertions(+)
create mode 100644 Documentation/guides/environment_variables.rst
diff --git a/Documentation/guides/environment_variables.rst b/Documentation/guides/environment_variables.rst
new file mode 100644
index 0000000..483a816
--- /dev/null
+++ b/Documentation/guides/environment_variables.rst
@@ -0,0 +1,141 @@
+Environment variables
+=====================
+
+List of variables
+-----------------
+
++---------------------------+-----------------------------------------+---------------------------------+---------------------------------------------------------------+
+| Environment variable | Description | Example value | Further information |
++===========================+=========================================+=================================+===============================================================+
+| LIBCAMERA_LOG_FILE | Custom destination for log output | ``/home/{user}/camera_log.log`` | |
++---------------------------+-----------------------------------------+---------------------------------+---------------------------------------------------------------+
+| LIBCAMERA_LOG_LEVELS | Log verbosity | ``*:DEBUG`` | `Levels <#log-levels>`__ and `Categories <#log-categories>`__ |
++---------------------------+-----------------------------------------+---------------------------------+---------------------------------------------------------------+
+| LIBCAMERA_IPA_CONFIG_PATH | Custom locations for IPA configurations | ``/use/path/one:/tmp/path/two`` | `IPA configuration <#ipa-configuration>`__ |
++---------------------------+-----------------------------------------+---------------------------------+---------------------------------------------------------------+
+| LIBCAMERA_IPA_MODULE_PATH | Custom locations for IPA modules | ``/usr/path/one:/tmp/path/two`` | `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 those variables locally or globally, but there is a restriction for ``LIBCAMERA_LOG_LEVELS`` in a local environment.
+
+Examples:
+
+Enable full debug output to a separate file, for every `category <#log-categories>`__ within a local environment:
+
+.. code:: bash
+
+ :~$ LIBCAMERA_LOG_FILE='/home/{USER}/camera_log.log'
+ :~$ LIBCAMERA_LOG_LEVELS='*:DEBUG'
+ :~$ 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.
+
+**Doesn’t work ?**: We have experienced cases were a local assignment
+to ``LIBCAMERA_LOG_LEVELS`` isn’t acknowledged by the application.
+There are 2 solutions for that problem:
+
+1. Execute the command and set the value in a single prompt:
+
+ ``:~$ LIBCAMERA_LOG_LEVELS=0 cam --list``
+2. Set the environment variable globally:
+
+ ``:~$ export LIBCAMERA_LOG_LEVELS=0 && 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
+- INFO
+- WARN
+- ERROR
+- FATAL
+
+Log categories
+~~~~~~~~~~~~~~~
+
++------------------+----------------+------------+----------------+---------------------+----------------+
+| Main classes | Pipe-lines | V4L2 | Android | IPA | Others |
++==================+================+============+================+=====================+================+
+| Allocator | IPU3 | V4L2 | CameraMetadata | IPAManager | IPCUnixSocket |
++------------------+----------------+------------+----------------+---------------------+----------------+
+| Buffer | RPI | V4L2Compat | EXIF | IPAModule | LogAPITest |
++------------------+----------------+------------+----------------+---------------------+----------------+
+| Camera | RPISTREAM | | HAL | IPAProxy | LogProcessTest |
++------------------+----------------+------------+----------------+---------------------+----------------+
+| CameraSensor | RPI_S_W | | JPEG | IPAProxyLinuxWorker | SysFs |
++------------------+----------------+------------+----------------+---------------------+----------------+
+| Controls | RkISP1 | | | IPARkISP1 | |
++------------------+----------------+------------+----------------+---------------------+----------------+
+| DeviceEnumerator | SimplePipeline | | | IPARPI | |
++------------------+----------------+------------+----------------+---------------------+----------------+
+| Event | Timeline | | | IPAVimc | |
++------------------+----------------+------------+----------------+---------------------+----------------+
+| File | UVC | | | RPiFocus | |
++------------------+----------------+------------+----------------+---------------------+----------------+
+| FileDescriptor | VIMC | | | | |
++------------------+----------------+------------+----------------+---------------------+----------------+
+| Formats | | | | | |
++------------------+----------------+------------+----------------+---------------------+----------------+
+| MediaDevice | | | | | |
++------------------+----------------+------------+----------------+---------------------+----------------+
+| Message | | | | | |
++------------------+----------------+------------+----------------+---------------------+----------------+
+| Object | | | | | |
++------------------+----------------+------------+----------------+---------------------+----------------+
+| Pipeline | | | | | |
++------------------+----------------+------------+----------------+---------------------+----------------+
+| Process | | | | | |
++------------------+----------------+------------+----------------+---------------------+----------------+
+| Request | | | | | |
++------------------+----------------+------------+----------------+---------------------+----------------+
+| Serialization | | | | | |
++------------------+----------------+------------+----------------+---------------------+----------------+
+| Serializer | | | | | |
++------------------+----------------+------------+----------------+---------------------+----------------+
+| Stream | | | | | |
++------------------+----------------+------------+----------------+---------------------+----------------+
+| Thread | | | | | |
++------------------+----------------+------------+----------------+---------------------+----------------+
+| 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
--
2.20.1
More information about the libcamera-devel
mailing list