From patchwork Tue Apr 23 10:30:26 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Milan Zamazal X-Patchwork-Id: 19926 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 C7D5BBE08B for ; Tue, 23 Apr 2024 10:31:42 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 565176342E; Tue, 23 Apr 2024 12:31:42 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.b="eyI7jX5L"; dkim-atps=neutral Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 2C122633ED for ; Tue, 23 Apr 2024 12:31:32 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1713868291; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=ZTbw4do6UUbclIccaLrZ+AbTwZ279YD/xIq/O9saBy4=; b=eyI7jX5LIrzkThC3pRlVKTE3Jday0iR3EmBmG176bmnyR9nTe10WTwQ/3DjpwLd1kLyviG vNQym6XirKFrR39APYdd4J7btoc09k/ByJB+oJWfAeHXhwbBX4KkfgdscVIpKAYXNxW6CM XnW7ClV54024TT3GCxxAI56hJq5fE2o= Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-33-LwsQnSgcPfilU6fITyMY8g-1; Tue, 23 Apr 2024 06:31:29 -0400 X-MC-Unique: LwsQnSgcPfilU6fITyMY8g-1 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 96E023C0ED4B; Tue, 23 Apr 2024 10:31:29 +0000 (UTC) Received: from nuthatch.redhat.com (unknown [10.45.225.63]) by smtp.corp.redhat.com (Postfix) with ESMTP id A51DF1C060D0; Tue, 23 Apr 2024 10:31:28 +0000 (UTC) From: Milan Zamazal To: libcamera-devel@lists.libcamera.org Cc: Milan Zamazal , Naushir Patuck Subject: [PATCH v2 11/13] config: Add global configuration file documentation Date: Tue, 23 Apr 2024 12:30:26 +0200 Message-ID: <20240423103034.364150-12-mzamazal@redhat.com> In-Reply-To: <20240423103034.364150-1-mzamazal@redhat.com> References: <20240423103034.364150-1-mzamazal@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.7 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com 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" Extend (and rename) the documentation of environment variables with information about the configuration file. Signed-off-by: Milan Zamazal --- Documentation/index.rst | 2 +- Documentation/meson.build | 2 +- ...ariables.rst => runtime_configuration.rst} | 96 ++++++++++++++++--- 3 files changed, 87 insertions(+), 13 deletions(-) rename Documentation/{environment_variables.rst => runtime_configuration.rst} (65%) diff --git a/Documentation/index.rst b/Documentation/index.rst index 5442ae75..aa277b85 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -19,7 +19,7 @@ Pipeline Handler Writer's Guide IPA Writer's guide Tracing guide - Environment variables + Runtime configuration Sensor driver requirements Lens driver requirements Python Bindings diff --git a/Documentation/meson.build b/Documentation/meson.build index 3872e0a8..f8ca63eb 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -70,7 +70,6 @@ if sphinx.found() 'conf.py', 'contributing.rst', 'docs.rst', - 'environment_variables.rst', 'guides/application-developer.rst', 'guides/introduction.rst', 'guides/ipa.rst', @@ -79,6 +78,7 @@ if sphinx.found() 'index.rst', 'lens_driver_requirements.rst', 'python-bindings.rst', + 'runtime_configuration.rst', 'sensor_driver_requirements.rst', 'software-isp-benchmarking.rst', '../README.rst', diff --git a/Documentation/environment_variables.rst b/Documentation/runtime_configuration.rst similarity index 65% rename from Documentation/environment_variables.rst rename to Documentation/runtime_configuration.rst index a9b230bc..d3972363 100644 --- a/Documentation/environment_variables.rst +++ b/Documentation/runtime_configuration.rst @@ -1,43 +1,117 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -Environment variables +Runtime configuration ===================== -The libcamera behaviour can be tuned through environment variables. This -document lists all the available variables and describes their usage. +The libcamera behaviour can be tuned through a configuration file or +environment variables. This document lists all the configuration options +and describes their usage. + +General rules +------------- + +The configuration file is looked up in the following locations, in this +order: + +- $XDG_CONFIG_HOME/libcamera/configuration.yaml +- LIBCAMERA_SYSCONF_DIR/configuration.yaml +- /etc/libcamera/configuration.yaml + +The first configuration file found wins, contingent configuration files +in other locations are ignored. + +Settings in environment variables take precedence over settings in +configuration files. This allows overriding behaviour temporarily +without the need to modify configuration files. + +Configuration options +--------------------- + +Here is an overview of the available configuration options, in the YAML +file structure: + +:: + + configuration: + ipa: + config_paths: # full paths to directories, separated by colons + force_isolation: # true/false + module_paths: # full paths to directories, separated by colons + log: + color: # true/false for color/no-color + file: # either `syslog` or a full path + levels: # see Log levels + pipelines: + rkisp1: + tuning_file: # full path + rpi: + config_file: # full path + tuning_file: # full path + simple: + supported_devices: + - driver: # driver name, e.g. `mxc-isi` + software_isp: # true/false + +Configuration file example +-------------------------- + +:: + + --- + version: 1 + configuration: + ipa: + config_paths: /home/user/.libcamera/share/ipa:/opt/libcamera/vendor/share/ipa + module_paths: /home/user/.libcamera/lib:/opt/libcamera/vendor/lib + force_isolation: true + log: + color: false + file: syslog + levels: 'IPAManager:DEBUG' + pipelines: + rkisp1: + tuning_file: /home/user/.libcamera/rkisp1.yaml + rpi: + config_file: /usr/local/share/libcamera/pipeline/rpi/vc4/minimal_mem.yaml + simple: + supported_devices: + - driver: mxc-isi + software_isp: true List of variables ----------------- -LIBCAMERA_LOG_FILE +The corresponding configuration file paths are listed in parentheses. + +LIBCAMERA_LOG_FILE (log.file) The custom destination for log output. Example value: ``/home/{user}/camera_log.log`` -LIBCAMERA_LOG_LEVELS +LIBCAMERA_LOG_LEVELS (log.levels) Configure the verbosity of log messages for different categories (`more `__). Example value: ``*:DEBUG`` -LIBCAMERA_LOG_NO_COLOR +LIBCAMERA_LOG_NO_COLOR (log.color) Disable coloring of log messages (`more `__). -LIBCAMERA_IPA_CONFIG_PATH +LIBCAMERA_IPA_CONFIG_PATH (ipa.config_paths) Define custom search locations for IPA configurations (`more `__). Example value: ``${HOME}/.libcamera/share/ipa:/opt/libcamera/vendor/share/ipa`` -LIBCAMERA_IPA_FORCE_ISOLATION +LIBCAMERA_IPA_FORCE_ISOLATION (ipa.force_isolation) When set to a non-empty string, force process isolation of all IPA modules. Example value: ``1`` -LIBCAMERA_IPA_MODULE_PATH +LIBCAMERA_IPA_MODULE_PATH (ipa.module_paths) Define custom search locations for IPA modules (`more `__). Example value: ``${HOME}/.libcamera/lib:/opt/libcamera/vendor/lib`` -LIBCAMERA_RPI_CONFIG_FILE +LIBCAMERA_RPI_CONFIG_FILE (pipelines.rpi.config_file) Define a custom configuration file to use in the Raspberry Pi pipeline handler. Example value: ``/usr/local/share/libcamera/pipeline/rpi/vc4/minimal_mem.yaml`` @@ -136,7 +210,7 @@ code. IPA configuration ~~~~~~~~~~~~~~~~~ -IPA modules use configuration files to store parameters. The format and +IPA modules use their own configuration files to store parameters. The format and contents of the configuration files is specific to the IPA module. They usually contain tuning parameters for the algorithms, in JSON format.