[{"id":28146,"web_url":"https://patchwork.libcamera.org/comment/28146/","msgid":"<20231123093720.GF15697@pendragon.ideasonboard.com>","date":"2023-11-23T09:37:20","subject":"Re: [libcamera-devel] [PATCH v2 6/6] 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 Tue, Nov 21, 2023 at 02:53:50PM +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\ns/vendor specific/vendor-specific/\n\nIf that's a \"proper English vs. US English\" issue, please feel free to\ncorrect me :-)\n\n> small example.\n> \n> Signed-off-by: Naushir Patuck \n> ---\n> Documentation/guides/pipeline-handler.rst | 52 +++++++++++++++++++++++\n> 1 file changed, 52 insertions(+)\n> \n> diff --git a/Documentation/guides/pipeline-handler.rst b/Documentation/guides/pipeline-handler.rst\n> index 10b9c75c2a7f..26977164accf 100644\n> --- a/Documentation/guides/pipeline-handler.rst\n> +++ b/Documentation/guides/pipeline-handler.rst\n> @@ -672,6 +672,58 @@ handling controls:\n> #include \n> #include \n> \n> +Vendor-specific controls and properties\n> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n> +\n> +Vendor-specific controls and properties must be defined in a separate YAML file\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_controls_mapping = {\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> +Vendor-specific controls and properties must contain a `vendor: `\n> +tag in the YAML file. Every unique vendor tag must define a unique and\n> +non-overlapping range of reserved control IDs in src/libcamera/control_ranges.yaml.\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> + vendor: rpi\n> + controls:\n> + - PispConfigDumpFile:\n> + type: string\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\nIndentiation looks wrong here, the '- PispConfigDumpFile:' line is\nunder-indented, and so are the three lines of the description text.\n\n> +\n> +\n> +This controls will be generated in the vendor-specific namespace\n> +`libcamera::controls::rpi`. Additionally a `#define\n> +LIBCAMERA_HAS_RPI_VENDOR_CONTROLS` will be available to allow applications to\n> +test for the availability of these controls.\n> +\n> +Note that libcamera core controls are defined with the `vendor: libcamera` tag\n> +and libcamera draft controls are defined with the `vendor: draft` tag.\n\nI'm not sure I would have mentioned this here, as it's not really\nrelated to pipeline handlers. Up to you.\n\nReviewed-by: Laurent Pinchart \n\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 0A49BC3220\n\tfor ;\n\tThu, 23 Nov 2023 09:37:15 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 52A43629AF;\n\tThu, 23 Nov 2023 10:37:14 +0100 (CET)","from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[213.167.242.64])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 26A4861DAA\n\tfor ;\n\tThu, 23 Nov 2023 10:37:13 +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 49A3E25A;\n\tThu, 23 Nov 2023 10:36:41 +0100 (CET)"],"DKIM-Signature":["v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org;\n\ts=mail; t=1700732234;\n\tbh=Pi3XEL6LhjoQQSpjv38tmw72dqTsiFiSiOumlGUMX+A=;\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=A1js2Dg8zN4jTIks5fuUO23tfA40TX5/i180zh5J9+TSYULwH3hjVQh+wXsKdCQ8y\n\tIfi4ahqxijpcVQlCOsD0Sry/L3MXkYx6qrZm74tw0ARzMCAs+FnO3C+GVoac+6ujSK\n\tusNbc+kESmUWNkGy1yaQ5pO9PXk3RBZHvC6MyVxrPs/Xaf8GJ07IpuUjeaMl7VALuM\n\t9GaJE6WcIZ8mvKqX/M3MYF7tckLOk4Sdn6DIBAJR9gNiRz59HNDSKsjpd+OLk4HDnB\n\txx6q2ergaGfU/NNcrJLYEh4RhAte70AEahY1dgm3qA/AwOsV4C1W57WWkWnLpJpf0X\n\tsLI6rkNaJC3Tg==","v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1700732201;\n\tbh=Pi3XEL6LhjoQQSpjv38tmw72dqTsiFiSiOumlGUMX+A=;\n\th=Date:From:To:Cc:Subject:References:In-Reply-To:From;\n\tb=WUF23yqZHZ1YYqFKKwN/KGlJ6i7duP5Xqai8fxuKo36wmyxaPvso/EobLzZU930Pz\n\tIFh/VF5RXP18yB33gijJGG/IY52ZIo+Kun21sThsN2K1Gx/H7/0tr5Y0xosYgMdKDP\n\tS4KoO3VlldtSXKHXzVUmN3enxFkMz7jcu0zHzMpA="],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (1024-bit key; \n\tunprotected) header.d=ideasonboard.com\n\theader.i=@ideasonboard.com\n\theader.b=\"WUF23yqZ\"; dkim-atps=neutral","Date":"Thu, 23 Nov 2023 11:37:20 +0200","To":"Naushir Patuck ","Message-ID":"<20231123093720.GF15697@pendragon.ideasonboard.com>","References":"<20231121145350.5956-1-naush@raspberrypi.com>\n\t<20231121145350.5956-7-naush@raspberrypi.com>","MIME-Version":"1.0","Content-Type":"text/plain; charset=utf-8","Content-Disposition":"inline","In-Reply-To":"<20231121145350.5956-7-naush@raspberrypi.com>","Subject":"Re: [libcamera-devel] [PATCH v2 6/6] 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\" "}}]