[{"id":35795,"web_url":"https://patchwork.libcamera.org/comment/35795/","msgid":"<175766783481.2127323.16652154819406835734@neptunite.rasen.tech>","date":"2025-09-12T09:03:54","subject":"Re: [PATCH v17 08/12] Documentation: Add global configuration file\n\tdocumentation","submitter":{"id":17,"url":"https://patchwork.libcamera.org/api/people/17/","name":"Paul Elder","email":"paul.elder@ideasonboard.com"},"content":"Hi Milan,\n\nThanks for the patch.\n\nQuoting Milan Zamazal (2025-09-11 18:29:38)\n> Extend (and rename) the documentation of environment variables with\n> information about the configuration file.\n> \n> Signed-off-by: Milan Zamazal \n\nLooks good to me.\n\nReviewed-by: Paul Elder \n\n> ---\n> Documentation/documentation-contents.rst | 2 +-\n> Documentation/index.rst | 2 +-\n> Documentation/meson.build | 2 +-\n> ...ariables.rst => runtime_configuration.rst} | 116 ++++++++++++++++--\n> 4 files changed, 107 insertions(+), 15 deletions(-)\n> rename Documentation/{environment_variables.rst => runtime_configuration.rst} (65%)\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 a8d4afc01..b47b16e97 100644\n> --- a/Documentation/meson.build\n> +++ b/Documentation/meson.build\n> @@ -157,7 +157,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> @@ -169,6 +168,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 65%\n> rename from Documentation/environment_variables.rst\n> rename to Documentation/runtime_configuration.rst\n> index 0cb4e27cd..8792232d7 100644\n> --- a/Documentation/environment_variables.rst\n> +++ b/Documentation/runtime_configuration.rst\n> @@ -2,14 +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> -\n> -List of variables\n> ------------------\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:\n> + - ... # pipeline name\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:\n> + - rkisp1\n> + - simple\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 and configuration options\n> +-------------------------------------------\n> \n> LIBCAMERA_LOG_FILE\n> The custom destination for log output.\n> @@ -24,27 +105,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 +136,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 into 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> @@ -62,6 +147,13 @@ LIBCAMERA__TUNING_FILE\n> \n> Example value: ``/usr/local/share/libcamera/ipa/rpi/vc4/custom_sensor.json``\n> \n> +pipelines.simple.supported_devices.driver, pipelines.simple.supported_devices.software_isp\n> + Override whether software ISP is enabled for the given driver.\n> +\n> + Example `driver` value: ``mxc-isi``\n> +\n> + Example `software_isp` value: ``true``\n> +\n> Further details\n> ---------------\n> \n> @@ -156,7 +248,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> \n> -- \n> 2.51.0\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 E2EC1BDB13\n\tfor ;\n\tFri, 12 Sep 2025 09:04:06 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id D5BE269370;\n\tFri, 12 Sep 2025 11:04:05 +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 0126F613A3\n\tfor ;\n\tFri, 12 Sep 2025 11:04:03 +0200 (CEST)","from neptunite.rasen.tech (unknown\n\t[IPv6:2404:7a81:160:2100:5c83:71e0:e0c7:1670])\n\tby perceval.ideasonboard.com (Postfix) with UTF8SMTPSA id B095D14A6; \n\tFri, 12 Sep 2025 11:02:47 +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=\"Kv4Ahwm8\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1757667768;\n\tbh=MPc2HW66z5LX3yyTY/q9LWjN0p9ry6jU3onlzzfuuHE=;\n\th=In-Reply-To:References:Subject:From:Cc:To:Date:From;\n\tb=Kv4Ahwm8fLQkc9mqs0W3TybI65WlCZ/MvHbJR4gDqawrs8Ah40W9m+FlugmjEAy86\n\t4MB7m7oihrYrqcFwV4+EtspmlYfmMqfl2n9w+jVKXNPxwxsZXUo3WVooZTcoBxly53\n\tIVAXTMWod3igsJpfYcHI7OEVmktOVo3T0zS0z7D0=","Content-Type":"text/plain; charset=\"utf-8\"","MIME-Version":"1.0","Content-Transfer-Encoding":"quoted-printable","In-Reply-To":"<20250911092945.16517-9-mzamazal@redhat.com>","References":"<20250911092945.16517-1-mzamazal@redhat.com>\n\t<20250911092945.16517-9-mzamazal@redhat.com>","Subject":"Re: [PATCH v17 08/12] Documentation: Add global configuration file\n\tdocumentation","From":"Paul Elder ","Cc":"Milan Zamazal , Kieran Bingham\n\t, =?utf-8?q?Barnab=C3=A1s_P=C5=91cze?=\n\t, Laurent Pinchart\n\t","To":"Milan Zamazal , libcamera-devel@lists.libcamera.org","Date":"Fri, 12 Sep 2025 18:03:54 +0900","Message-ID":"<175766783481.2127323.16652154819406835734@neptunite.rasen.tech>","User-Agent":"alot/0.0.0","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\" "}}]