[{"id":35206,"web_url":"https://patchwork.libcamera.org/comment/35206/","msgid":"<7af7c6d7-6c13-4fed-a227-5d7d715ea0f6@ideasonboard.com>","date":"2025-07-28T15:04:33","subject":"Re: [PATCH v15 08/12] config: Add global configuration file\n\tdocumentation","submitter":{"id":216,"url":"https://patchwork.libcamera.org/api/people/216/","name":"Barnabás Pőcze","email":"barnabas.pocze@ideasonboard.com"},"content":"Hi\n\nonce again...\n\n2025. 07. 24. 12:38 keltezéssel, Milan Zamazal írta:\n> Extend (and rename) the documentation of environment variables with\n> information about the configuration file.\n> \n> Signed-off-by: Milan Zamazal \n> ---\n> Documentation/documentation-contents.rst | 2 +-\n> Documentation/index.rst | 2 +-\n> Documentation/meson.build | 2 +-\n> ...ariables.rst => runtime_configuration.rst} | 102 ++++++++++++++++--\n> 4 files changed, 96 insertions(+), 12 deletions(-)\n> rename Documentation/{environment_variables.rst => runtime_configuration.rst} (67%)\n> \n> diff --git a/Documentation/documentation-contents.rst b/Documentation/documentation-contents.rst\n> index 5c1118493..4be3729cf 100644\n> --- a/Documentation/documentation-contents.rst\n> +++ b/Documentation/documentation-contents.rst\n> @@ -7,7 +7,7 @@\n> * :doc:`/feature_requirements`\n> * :doc:`/guides/application-developer`\n> * :doc:`/python-bindings`\n> - * :doc:`/environment_variables`\n> + * :doc:`/runtime_configuration`\n> * :doc:`/api-html/index`\n> * :doc:`/code-of-conduct`\n> * |\n> diff --git a/Documentation/index.rst b/Documentation/index.rst\n> index 251112fbd..200de6f67 100644\n> --- a/Documentation/index.rst\n> +++ b/Documentation/index.rst\n> @@ -12,13 +12,13 @@\n> \n> Application Writer's Guide \n> Camera Sensor Model \n> - Environment variables \n> Feature Requirements \n> IPA Writer's guide \n> Lens driver requirements \n> libcamera Architecture \n> Pipeline Handler Writer's Guide \n> Python Bindings \n> + Runtime configuration \n> Sensor driver requirements \n> SoftwareISP Benchmarking \n> Tracing guide \n> diff --git a/Documentation/meson.build b/Documentation/meson.build\n> index 3afdcc1a8..4e17c41c0 100644\n> --- a/Documentation/meson.build\n> +++ b/Documentation/meson.build\n> @@ -129,7 +129,6 @@ if sphinx.found()\n> 'contributing.rst',\n> 'design/ae.rst',\n> 'documentation-contents.rst',\n> - 'environment_variables.rst',\n> 'feature_requirements.rst',\n> 'guides/application-developer.rst',\n> 'guides/ipa.rst',\n> @@ -141,6 +140,7 @@ if sphinx.found()\n> 'libcamera_architecture.rst',\n> 'mali-c55.dot',\n> 'python-bindings.rst',\n> + 'runtime_configuration.rst',\n> 'sensor_driver_requirements.rst',\n> 'software-isp-benchmarking.rst',\n> '../README.rst',\n> diff --git a/Documentation/environment_variables.rst b/Documentation/runtime_configuration.rst\n> similarity index 67%\n> rename from Documentation/environment_variables.rst\n> rename to Documentation/runtime_configuration.rst\n> index 6f1235587..911203db5 100644\n> --- a/Documentation/environment_variables.rst\n> +++ b/Documentation/runtime_configuration.rst\n> @@ -2,15 +2,95 @@\n> \n> .. include:: documentation-contents.rst\n> \n> -Environment variables\n> +Runtime configuration\n> =====================\n> \n> -The libcamera behaviour can be tuned through environment variables. This\n> -document lists all the available variables and describes their usage.\n> +The libcamera behaviour can be tuned through a configuration file or\n> +environment variables. This document lists all the configuration options\n> +and describes their usage.\n> +\n> +General rules\n> +-------------\n> +\n> +The configuration file is looked up in the following locations, in this\n> +order:\n> +\n> +- $XDG_CONFIG_HOME/libcamera/configuration.yaml\n> +- LIBCAMERA_SYSCONF_DIR/configuration.yaml\n> +- LIBCAMERA_DATA_DIR/libcamera/configuration.yaml\n> +\n> +The first configuration file found wins, configuration files in other\n> +locations are ignored.\n> +\n> +Settings in environment variables take precedence over settings in\n> +configuration files. This allows overriding behaviour temporarily\n> +without the need to modify configuration files.\n> +\n> +Configuration options\n> +---------------------\n> +\n> +Here is an overview of the available configuration options, in the YAML\n> +file structure:\n> +\n> +::\n> +\n> + configuration:\n> + ipa:\n> + force_isolation: # true/false\n> + config_paths:\n> + - ... # full path to a directory\n> + module_paths:\n> + - ... # full path to a directory\n> + pipelines_match_list: # pipeline names, separated by commas\n\n`envListOption()` defers to `listOption()`, so this should be a list\nin the configuration file.\n\n\n> + pipelines:\n> + rpi:\n> + bcm2835:\n> + pipeline_handler:\n> + ...\n> + pisp:\n> + pipeline_handler:\n> + ...\n> + simple:\n> + supported_devices:\n> + - driver: # driver name, e.g. `mxc-isi`\n> + software_isp: # true/false\n> +\n> +Configuration file example\n> +--------------------------\n> +\n> +::\n> +\n> + ---\n> + version: 1\n> + configuration:\n> + ipa:\n> + config_paths:\n> + - /home/user/.libcamera/share/ipa\n> + - /opt/libcamera/vendor/share/ipa\n> + module_paths:\n> + - /home/user/.libcamera/lib\n> + - /opt/libcamera/vendor/lib\n> + proxy_paths:\n> + - /home/user/.libcamera/proxy/worker\n> + - /opt/libcamera/vendor/proxy/worker\n> + force_isolation: true\n> + pipelines_match_list: rkisp1,simple\n\nSame here.\n\n\nRegards,\nBarnabás Pőcze\n\n\n> + pipelines:\n> + rpi:\n> + bcm2835:\n> + pipeline_handler:\n> + min_unicam_buffers: 2\n> + min_total_unicam_buffers: 2\n> + simple:\n> + supported_devices:\n> + - driver: mxc-isi\n> + software_isp: true\n> \n> List of variables\n> -----------------\n> \n> +The corresponding configuration file paths, if available, are listed in parentheses.\n> +\n> LIBCAMERA_LOG_FILE\n> The custom destination for log output.\n> \n> @@ -24,27 +104,27 @@ LIBCAMERA_LOG_LEVELS\n> LIBCAMERA_LOG_NO_COLOR\n> Disable coloring of log messages (`more `__).\n> \n> -LIBCAMERA_IPA_CONFIG_PATH\n> +LIBCAMERA_IPA_CONFIG_PATH (ipa.config_paths)\n> Define custom search locations for IPA configurations (`more `__).\n> \n> Example value: ``${HOME}/.libcamera/share/ipa:/opt/libcamera/vendor/share/ipa``\n> \n> -LIBCAMERA_IPA_FORCE_ISOLATION\n> +LIBCAMERA_IPA_FORCE_ISOLATION (ipa.force_isolation)\n> When set to a non-empty string, force process isolation of all IPA modules.\n> \n> Example value: ``1``\n> \n> -LIBCAMERA_IPA_MODULE_PATH\n> +LIBCAMERA_IPA_MODULE_PATH (ipa.module_paths)\n> Define custom search locations for IPA modules (`more `__).\n> \n> Example value: ``${HOME}/.libcamera/lib:/opt/libcamera/vendor/lib``\n> \n> -LIBCAMERA_IPA_PROXY_PATH\n> +LIBCAMERA_IPA_PROXY_PATH (ipa.proxy_paths)\n> Define custom full path for a proxy worker for a given executable name.\n> \n> Example value: ``${HOME}/.libcamera/proxy/worker:/opt/libcamera/vendor/proxy/worker``\n> \n> -LIBCAMERA_PIPELINES_MATCH_LIST\n> +LIBCAMERA_PIPELINES_MATCH_LIST (pipelines_match_list)\n> Define an ordered list of pipeline names to be used to match the media\n> devices in the system. The pipeline handler names used to populate the\n> variable are the ones passed to the REGISTER_PIPELINE_HANDLER() macro in the\n> @@ -55,6 +135,10 @@ LIBCAMERA_PIPELINES_MATCH_LIST\n> LIBCAMERA_RPI_CONFIG_FILE\n> Define a custom configuration file to use in the Raspberry Pi pipeline handler.\n> \n> + Instead of using a separate configuration file, the whole\n> + configuration can be put directly to the global configuration file as\n> + outlined above.\n> +\n> Example value: ``/usr/local/share/libcamera/pipeline/rpi/vc4/minimal_mem.yaml``\n> \n> LIBCAMERA__TUNING_FILE\n> @@ -156,7 +240,7 @@ code.\n> IPA configuration\n> ~~~~~~~~~~~~~~~~~\n> \n> -IPA modules use configuration files to store parameters. The format and\n> +IPA modules use their own configuration files to store parameters. The format and\n> contents of the configuration files is specific to the IPA module. They usually\n> contain tuning parameters for the algorithms, in JSON format.\n>","headers":{"Return-Path":"","X-Original-To":"parsemail@patchwork.libcamera.org","Delivered-To":"parsemail@patchwork.libcamera.org","Received":["from lancelot.ideasonboard.com (lancelot.ideasonboard.com\n\t[92.243.16.209])\n\tby patchwork.libcamera.org (Postfix) with ESMTPS id BA195BDCC1\n\tfor ;\n\tMon, 28 Jul 2025 15:04:38 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id BB36D6918C;\n\tMon, 28 Jul 2025 17:04:37 +0200 (CEST)","from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 5C3E569158\n\tfor ;\n\tMon, 28 Jul 2025 17:04:36 +0200 (CEST)","from [192.168.33.18] (185.221.140.39.nat.pool.zt.hu\n\t[185.221.140.39])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id 1CF6B3A4;\n\tMon, 28 Jul 2025 17:03:54 +0200 (CEST)"],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (1024-bit key;\n\tunprotected) header.d=ideasonboard.com header.i=@ideasonboard.com\n\theader.b=\"PbHxTnxa\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1753715034;\n\tbh=6TDKIcT6lPD+Huw+/vPk+x00WTjD4ZKB6QxnKd72XwQ=;\n\th=Date:Subject:To:Cc:References:From:In-Reply-To:From;\n\tb=PbHxTnxaaYmlyAuiHJCsSVlRCWyT9+/wobJDbr0tiGLeMPPhi8q5sm7pJuZQ65fyx\n\ttLwtLNAyBTY9khAnmoaorzC8FYq9UpSLipprkFnwdu72phFQUwv0rYclr2jisXjQAP\n\t1SUKmOTr9elzU/axwt0L4IQwbjrYLEeTcnHFU7TI=","Message-ID":"<7af7c6d7-6c13-4fed-a227-5d7d715ea0f6@ideasonboard.com>","Date":"Mon, 28 Jul 2025 17:04:33 +0200","MIME-Version":"1.0","User-Agent":"Mozilla Thunderbird","Subject":"Re: [PATCH v15 08/12] config: Add global configuration file\n\tdocumentation","To":"Milan Zamazal , libcamera-devel@lists.libcamera.org","Cc":"Kieran Bingham ,\n\tLaurent Pinchart ","References":"<20250724103834.54611-1-mzamazal@redhat.com>\n\t<20250724103834.54611-9-mzamazal@redhat.com>","From":"=?utf-8?q?Barnab=C3=A1s_P=C5=91cze?= ","Content-Language":"en-US, hu-HU","In-Reply-To":"<20250724103834.54611-9-mzamazal@redhat.com>","Content-Type":"text/plain; charset=UTF-8; format=flowed","Content-Transfer-Encoding":"8bit","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "}}]