From patchwork Fri Dec 6 17:11:43 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Milan Zamazal X-Patchwork-Id: 22249 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 3E454BF415 for ; Fri, 6 Dec 2024 17:12:45 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id D83D967E51; Fri, 6 Dec 2024 18:12:44 +0100 (CET) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.b="FbOmdWks"; dkim-atps=neutral Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 3B45167E2C for ; Fri, 6 Dec 2024 18:12:43 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1733505162; 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=FZ+GIkhDOAwC84ToRGdidjzrJAzWiMtgZoh5G/20jWA=; b=FbOmdWksz2eT0/3HC5czDSf6RSK1FlKErk0ILkUFF+IqR7zzRLwqRaamXwMpcv6aDuEfaN 004J7iY+H3Ft9E6xq0nTio4da1ezTShgCrX22NL8zrb3mvajpLufn1DWeQN3UoA5jZiiDE 7rtOXP7gPRXJQrZxPHaHku6XwCbkXs8= Received: from mx-prod-mc-04.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-466-KzQddOisM9eluIx8LIqAkA-1; Fri, 06 Dec 2024 12:12:39 -0500 X-MC-Unique: KzQddOisM9eluIx8LIqAkA-1 X-Mimecast-MFC-AGG-ID: KzQddOisM9eluIx8LIqAkA Received: from mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.4]) (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 mx-prod-mc-04.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 14A941955DCA; Fri, 6 Dec 2024 17:12:38 +0000 (UTC) Received: from nuthatch.redhat.com (unknown [10.45.224.27]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 9421C3000239; Fri, 6 Dec 2024 17:12:35 +0000 (UTC) From: Milan Zamazal To: libcamera-devel@lists.libcamera.org Cc: Milan Zamazal , Kieran Bingham , Naushir Patuck , =?utf-8?q?Barnab=C3=A1s_P=C5=91cze?= , Laurent Pinchart Subject: [PATCH v6 12/16] config: Add global configuration file documentation Date: Fri, 6 Dec 2024 18:11:43 +0100 Message-ID: <20241206171148.1189292-13-mzamazal@redhat.com> In-Reply-To: <20241206171148.1189292-1-mzamazal@redhat.com> References: <20241206171148.1189292-1-mzamazal@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 X-Mimecast-Spam-Score: 0 X-Mimecast-MFC-PROC-ID: 0VHj2kXzWopmsEAZ4bI41OMJIaG57Naux9PDEHFapzg_1733505158 X-Mimecast-Originator: redhat.com content-type: text/plain; charset="US-ASCII"; x-default=true 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/documentation-contents.rst | 2 +- Documentation/index.rst | 4 +- Documentation/meson.build | 2 +- ...ariables.rst => runtime_configuration.rst} | 117 ++++++++++++++++-- 4 files changed, 108 insertions(+), 17 deletions(-) rename Documentation/{environment_variables.rst => runtime_configuration.rst} (63%) diff --git a/Documentation/documentation-contents.rst b/Documentation/documentation-contents.rst index 5c111849..4be3729c 100644 --- a/Documentation/documentation-contents.rst +++ b/Documentation/documentation-contents.rst @@ -7,7 +7,7 @@ * :doc:`/feature_requirements` * :doc:`/guides/application-developer` * :doc:`/python-bindings` - * :doc:`/environment_variables` + * :doc:`/runtime_configuration` * :doc:`/api-html/index` * :doc:`/code-of-conduct` * | diff --git a/Documentation/index.rst b/Documentation/index.rst index bea40660..20d46788 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -12,13 +12,13 @@ Application Writer's Guide Camera Sensor Model - Environment variables Feature Requirements IPA Writer's guide Lens driver requirements libcamera Architecture Pipeline Handler Writer's Guide Python Bindings + Runtime configuration Sensor driver requirements SoftwareISP Benchmarking Tracing guide @@ -26,4 +26,4 @@ .. toctree:: :hidden: - introduction \ No newline at end of file + introduction diff --git a/Documentation/meson.build b/Documentation/meson.build index 36ffae23..b55e25b1 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -129,7 +129,6 @@ if sphinx.found() 'conf.py', 'contributing.rst', 'documentation-contents.rst', - 'environment_variables.rst', 'feature_requirements.rst', 'guides/application-developer.rst', 'guides/ipa.rst', @@ -141,6 +140,7 @@ if sphinx.found() 'libcamera_architecture.rst', 'mali-c55.dot', '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 63% rename from Documentation/environment_variables.rst rename to Documentation/runtime_configuration.rst index 7da9883a..3f7a104f 100644 --- a/Documentation/environment_variables.rst +++ b/Documentation/runtime_configuration.rst @@ -2,49 +2,140 @@ .. include:: documentation-contents.rst -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_match_list: # pipeline names, separated by commas + pipelines: + rkisp1: + cameras: + - CAMERA-ID: + tuning-file: # full path + rpi: + config_file: # full path + cameras: + - CAMERA-ID: + 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 + proxy_paths: + - /home/user/.libcamera/proxy/worker + - /opt/libcamera/vendor/proxy/worker + force_isolation: true + log: + color: false + file: syslog + levels: 'IPAManager:DEBUG' + pipelines_match_list: rkisp1,simple + pipelines: + rkisp1: + cameras: + - "/base/axi/pcie@120000/rp1/i2c@88000/imx283@1a": + tuning_file: /home/pi/imx283.json + - "/base/axi/pcie@120000/rp1/i2c@80000/imx335@1a": + tuning_file: /home/pi/imx335.json + 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_IPA_PROXY_PATH +LIBCAMERA_IPA_PROXY_PATH (ipa.proxy_paths) Define custom full path for a proxy worker for a given executable name. Example value: ``${HOME}/.libcamera/proxy/worker:/opt/libcamera/vendor/proxy/worker`` -LIBCAMERA_PIPELINES_MATCH_LIST +LIBCAMERA_PIPELINES_MATCH_LIST (pipelines_match_list) Define an ordered list of pipeline names to be used to match the media devices in the system. The pipeline handler names used to populate the variable are the ones passed to the REGISTER_PIPELINE_HANDLER() macro in the @@ -52,7 +143,7 @@ LIBCAMERA_PIPELINES_MATCH_LIST Example value: ``rkisp1,simple`` -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`` @@ -156,7 +247,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.