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

Message ID 20201027151240.24065-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. 27, 2020, 3:12 p.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.

Signed-off-by: Sebastian Fricke <sebastian.fricke.linux@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

Patch
diff mbox series 

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