From patchwork Thu Oct 29 08:37:35 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sebastian Fricke X-Patchwork-Id: 10295 Return-Path: X-Original-To: parsemail@patchwork.libcamera.org Delivered-To: parsemail@patchwork.libcamera.org Received: from lancelot.ideasonboard.com (lancelot.ideasonboard.com [92.243.16.209]) by patchwork.libcamera.org (Postfix) with ESMTPS id 24D0CBDB9B for ; Thu, 29 Oct 2020 08:37:40 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id EB79662838; Thu, 29 Oct 2020 09:37:39 +0100 (CET) Authentication-Results: lancelot.ideasonboard.com; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.b="dW6CPIv3"; dkim-atps=neutral Received: from mail-ed1-x52d.google.com (mail-ed1-x52d.google.com [IPv6:2a00:1450:4864:20::52d]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 3C0EA62053 for ; Thu, 29 Oct 2020 09:37:38 +0100 (CET) Received: by mail-ed1-x52d.google.com with SMTP id g25so1375570edm.6 for ; Thu, 29 Oct 2020 01:37:38 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:mime-version :content-transfer-encoding; bh=N7MuaMRIAGTsnw8HW/eL74xLodUYTr71b/y3CKzBS00=; b=dW6CPIv3szScdaOgaKhVZRcIKX99buMHvmTIOQ3WVWAOb3J1Wcp+LMbd0Nr0wUy6gK I70ZnmS/G0M9vNXtKHSZVekKyJSQVWUci+riRiMAXFQfrLwhUJ/6MBo+swhRBQ/FtUjK fr+QxDgwiKItgPtUmqeJEHfNpB1ykf5JDkLAGaEgQQa+nhBhDtN+m9Wu4yfxDfTm2LFm vC2OjD3jSSE+ReZQAzmxab7aOkNQISw6flLOgJiA4uKLuDJhOVuuv6mVAGgW6m4k+6LA LQ8kSGVFWIr6C+3/DIknmaI5d2UvzGPsazl+jHKS/jSUtQ9sESGzpcjOaF8rfWfwL7b6 Gx+Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:mime-version :content-transfer-encoding; bh=N7MuaMRIAGTsnw8HW/eL74xLodUYTr71b/y3CKzBS00=; b=tES3zMG2WhcvhBsk03AYnJDcNEcz6yzQTsm6Ez2QA3U4UQwMF2Qb0tW9y3N2tutTbv KEoPcpaF3pHtHYywwEAUWnZTaJZCLWKjpsBq/0lqKkuue8xkMPGQ1L4sSI9elZzSPkDI p9ZabHWUVYTl8cYkqpJQOgoFtDA8mAOiEVhZC4L9k8NtEu2XFx2svJnaIzSKXBsX1lMj m8FeZ7OIYGCMy2gvtwIvJN1Z/ErWulF9MwyL+0qfzbIS1K8xoghD4okCB1K4NFfDJYB+ C+h/cHzUE45thONj/zIBd4lDlq9KccBTqgXfep9XmpZmStmxSgZFLfQrTotXmdv39gxM 2i8Q== X-Gm-Message-State: AOAM532xA4IY88gLiUjSn4gRJrl2T2LAp5E+StxJo995cy8xCgJ5OX9J yRycwEFAsq5KEnb8X42TJAifr9CXn2I= X-Google-Smtp-Source: ABdhPJwPntxTlvRxHPIEiT/cDHq4AD7SrNksg3POW5NLuyPQzZZcqD4aDXPwUtwCz7OdOqIbfzXnHA== X-Received: by 2002:a05:6402:1042:: with SMTP id e2mr2898191edu.320.1603960657636; Thu, 29 Oct 2020 01:37:37 -0700 (PDT) Received: from basti.fritz.box (p200300d1ff0150000177fa94b6a5f6ca.dip0.t-ipconnect.de. [2003:d1:ff01:5000:177:fa94:b6a5:f6ca]) by smtp.gmail.com with ESMTPSA id rn28sm509384ejb.22.2020.10.29.01.37.36 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 29 Oct 2020 01:37:37 -0700 (PDT) From: Sebastian Fricke To: libcamera-devel@lists.libcamera.org Date: Thu, 29 Oct 2020 09:37:35 +0100 Message-Id: <20201029083735.21477-1-sebastian.fricke.linux@gmail.com> X-Mailer: git-send-email 2.20.1 MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH V2] Documentation: Add descriptions for env. variables X-BeenThere: libcamera-devel@lists.libcamera.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" 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 --- .../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 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 `__ + +IPA module +~~~~~~~~~~~ + +Existing IPA modules can be located in the +`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 Application Writer's Guide Pipeline Handler Writer's Guide + Environment variables 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