[{"id":28103,"web_url":"https://patchwork.libcamera.org/comment/28103/","msgid":"<20231120042209.GI524@pendragon.ideasonboard.com>","date":"2023-11-20T04:22:09","subject":"Re: [libcamera-devel] [PATCH v1 5/5] documentation: Document vendor\n\tspecific control and properties handling","submitter":{"id":2,"url":"https://patchwork.libcamera.org/api/people/2/","name":"Laurent Pinchart","email":"laurent.pinchart@ideasonboard.com"},"content":"Hi Naush,\n\nThank you for the patch.\n\nOn Fri, Nov 10, 2023 at 11:00:02AM +0000, Naushir Patuck via libcamera-devel wrote:\n> Add some documentation to the pipeline handler file describing how to\n> implement and handle vendor specific controls and properties with a\n> small example.\n> \n> Signed-off-by: Naushir Patuck \n> ---\n> Documentation/guides/pipeline-handler.rst | 53 +++++++++++++++++++++++\n> 1 file changed, 53 insertions(+)\n> \n> diff --git a/Documentation/guides/pipeline-handler.rst b/Documentation/guides/pipeline-handler.rst\n> index 10b9c75c2a7f..417eceeb62bd 100644\n> --- a/Documentation/guides/pipeline-handler.rst\n> +++ b/Documentation/guides/pipeline-handler.rst\n> @@ -672,6 +672,59 @@ handling controls:\n> #include \n> #include \n> \n> +Vendor specific controls and properties\n\ns/Vendor specific/Vendor-specific/\n\nSame below.\n\n> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n> +\n> +Vendor specific controls and properties may be defined in a separate YMAL file\n\ns/YMAL/YAML/\n\n> +and included in the build by defining the pipeline handler to file mapping in\n> +include/libcamera/meson.build.\n> +\n> +For example, adding a Raspberry Pi vendor control file for the PiSP pipeline\n> +handler is done with the following mapping:\n> +\n> +.. code-block:: meson\n> +\n> + vendor_mappings = {\n> + # Mapping of vendor (pipeline handler) specific controls files\n> + 'controls':\n> + {\n> + 'rpi/pisp': 'control_ids_rpi.yaml',\n> + },\n> + # Mapping of vendor (pipeline handler) specific properties files\n> + 'properties':\n> + {\n> +\n> + }\n> + }\n> +\n> +It is also possible (though inadvisable for maintenance purposes) to add vendor\n> +specific controls directly in the the src/libcamera/`control_ids.yaml`_ or\n> +src/libcamera/`properties_ids.yaml`_ files.\n\nLet's not mention it if it's not advisable :-)\n\n> +\n> +Vendor specific controls and properties must contain a `vendor: `\n> +tag in the YAML definition. Every unique vendor tag must define a unique and\n> +non-overlapping range of reserved control IDs in src/libcamera/control_ranges.yaml.\n\nThis may change depending on the review discussion.\n\n> +\n> +For example, the following block defines a vendor specific control with the\n> +`rpi` vendor tag:\n> +\n> +.. code-block:: yaml\n> +\n> + - PispConfigDumpFile:\n> + type: string\n> + vendor: rpi\n> + description: |\n> + Triggers the Raspberry Pi PiSP pipeline handler to generate a JSON\n> + formatted dump of the Backend configuration to the filename given by the\n> + value of the control.\n> +\n> +This controls will be generated in the vendor specific namespace\n> +`libcamera::controls::rpi`. Additionally a `#define\n> +LIBCAMERA_RPI_VENDOR_CONTROL` will be available to allow applications to test\n\nI think LIBCAMERA_RPI_VENDOR_CONTROLS would be better than\nLIBCAMERA_RPI_VENDOR_CONTROL.\n\n> +for the availability of these controls.\n> +\n> +Note that draft controls are defined with the `vendor: draft` tag.\n> +\n> Generating a default configuration\n> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\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 7F725BDE6B\n\tfor ;\n\tMon, 20 Nov 2023 04:22:05 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id CCDEC629BB;\n\tMon, 20 Nov 2023 05:22:04 +0100 (CET)","from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[213.167.242.64])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 28831629B6\n\tfor ;\n\tMon, 20 Nov 2023 05:22:03 +0100 (CET)","from pendragon.ideasonboard.com (213-243-189-158.bb.dnainternet.fi\n\t[213.243.189.158])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id 7784874A;\n\tMon, 20 Nov 2023 05:21:33 +0100 (CET)"],"DKIM-Signature":["v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org;\n\ts=mail; t=1700454124;\n\tbh=Amb4j1ND3ILGfwu6Z6tBC8jfm+Welk5+Pg61R9jfqa8=;\n\th=Date:To:References:In-Reply-To:Subject:List-Id:List-Unsubscribe:\n\tList-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To:Cc:\n\tFrom;\n\tb=3G32SuYNMNz+vtF8bJm657DQ4Spp+PpRyTD842WpW/5CNeH7DWrKANZoJmaLYXLFn\n\tYakzGyitjeEKuJCrAHiUcX0ezJwpELMT8PNeiA74MQpBWDovk3KaAIiWgAUWQl1h8w\n\tpzNfjYorgWC1FroUoWkyMlw1VImaFYkwIuDSah77Xh0pK+EE4rfHOYcw/LD0cE67q5\n\tW/pl5TPVXcjyJU2cwrxChQ94jC0U5ray24u479q2H6An8F15nmJl945LLCvspLL2hZ\n\tMou0yZZZM3OH480nFfj14KHvXifJipRYxlZzQB5FVlYgYLqBcKs1O3I/SIyk8uTZr+\n\tKKUTDvSP42RCw==","v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1700454093;\n\tbh=Amb4j1ND3ILGfwu6Z6tBC8jfm+Welk5+Pg61R9jfqa8=;\n\th=Date:From:To:Cc:Subject:References:In-Reply-To:From;\n\tb=g1lRIkiRr53d+feKT+hF+4gNVA+XwxN0nqUmwkdZ38gdFGgAwrIMfbge73o09R99+\n\t9okU/TBXXHViHmDmnRNlfwW7ERFKmVGHdYVuh756y1X5NmgnO41f/D7HapHydEz7V/\n\tTBR2qdynLXxMu7TAVOxuvshTcpI0d6pf7X6SsmDA="],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (1024-bit key; \n\tunprotected) header.d=ideasonboard.com\n\theader.i=@ideasonboard.com\n\theader.b=\"g1lRIkiR\"; dkim-atps=neutral","Date":"Mon, 20 Nov 2023 06:22:09 +0200","To":"Naushir Patuck ","Message-ID":"<20231120042209.GI524@pendragon.ideasonboard.com>","References":"<20231110110002.21381-1-naush@raspberrypi.com>\n\t<20231110110002.21381-6-naush@raspberrypi.com>","MIME-Version":"1.0","Content-Type":"text/plain; charset=utf-8","Content-Disposition":"inline","In-Reply-To":"<20231110110002.21381-6-naush@raspberrypi.com>","Subject":"Re: [libcamera-devel] [PATCH v1 5/5] documentation: Document vendor\n\tspecific control and properties handling","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","From":"Laurent Pinchart via libcamera-devel\n\t","Reply-To":"Laurent Pinchart ","Cc":"libcamera-devel@lists.libcamera.org","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "}}]