From patchwork Tue Oct 27 15:12:40 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Sebastian Fricke X-Patchwork-Id: 10268 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 A4C34C3B5C for ; Tue, 27 Oct 2020 15:12:48 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 2263E62150; Tue, 27 Oct 2020 16:12:48 +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="sn3Cd3NW"; dkim-atps=neutral Received: from mail-wm1-x32d.google.com (mail-wm1-x32d.google.com [IPv6:2a00:1450:4864:20::32d]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id C520062034 for ; Tue, 27 Oct 2020 16:12:46 +0100 (CET) Received: by mail-wm1-x32d.google.com with SMTP id e2so1813058wme.1 for ; Tue, 27 Oct 2020 08:12:46 -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=BOBt8W8JqypWOkZ5KahlIowDXL0nlbB2xnNvII4G8n0=; b=sn3Cd3NW8TH3vYZtmZm0MfcpRmMefqiaAK8J8QjuD1+KQ+/+BFors1w2O0UH3JsFKl gEMYd1JgvITzPDyR8HsoXqum4UaWbWYXKYO2cmAj+Rrn1gSlzBi0EEPjYzHGZ1t8JF11 0e592GSCRKNYG2X0eauuDwI/yu/UpdSJUWDAGHCXkwKbbO2+Ykxk15JFxCzETKaeveX1 GYcG1PIxgqGjsoBJTVGAJZUJ1AV6Y5lcaKVHn2xJ8/GHvizrfqWm/sKi2yyuynYKQxZu FKnAcFFg7ZOq8cxQdzTZKS8KTkGmwXst/jNfxvS1KMUFScWhiu4wVsi+kXgr3DMH2qa2 mNeA== 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=BOBt8W8JqypWOkZ5KahlIowDXL0nlbB2xnNvII4G8n0=; b=bfaqh7uv6SPIR1vk6ctq4ekw/79uOMNNnT7EEt+XVXxfDygryw2mlDw41rIkLckM6h uMhpldVgjaDw2Omb+QJOqHAQ3njygKu7p31IYxX9wH1rwz6T/NxPOxdMh4m0LuFr6+qE 71msB/Q5Z2C2eP23+36JBnD8bA31vnUt2wU8H4XZ8TXEj6JWzLdodvxntGyKWEKCJ+N+ qfpRDkyOiQEO1U6O50KiRu9o/MMYyWR/Xqm9h5GOmNqs9qWWTOOYoTI33dA3AmWMfZvD YQ/PkskfxxzSjvpUpNBa9YVhHHt3Xi3RnT9XuwaDIPtgHp6yUHlVu0Qso71s//8euCgd D9NQ== X-Gm-Message-State: AOAM531cgDIhsvNGwC2og+PUUXFioWnA8j06rl2cTKtcko2+IoBAOOF/ o3Ge+CPrFh9AGO5/lYSmiw19DuiquYc= X-Google-Smtp-Source: ABdhPJwQPsQquzkLeSyUbpfOXBzr6NXf4gbqhlZsNLtMwbff+qSkmh5ECpqPz/64W8QTDLKkn+ewxw== X-Received: by 2002:a7b:c15a:: with SMTP id z26mr3145732wmi.62.1603811565841; Tue, 27 Oct 2020 08:12:45 -0700 (PDT) Received: from basti.fritz.box (p200300d1ff01b200e383df520a7e258b.dip0.t-ipconnect.de. [2003:d1:ff01:b200:e383:df52:a7e:258b]) by smtp.gmail.com with ESMTPSA id t19sm2187082wmj.42.2020.10.27.08.12.44 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 27 Oct 2020 08:12:45 -0700 (PDT) From: Sebastian Fricke To: libcamera-devel@lists.libcamera.org Date: Tue, 27 Oct 2020 16:12:40 +0100 Message-Id: <20201027151240.24065-1-sebastian.fricke.linux@gmail.com> X-Mailer: git-send-email 2.20.1 MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH] 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. Signed-off-by: Sebastian Fricke --- .../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 `__ + +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