{"id":19198,"url":"https://patchwork.libcamera.org/api/1.1/patches/19198/?format=json","web_url":"https://patchwork.libcamera.org/patch/19198/","project":{"id":1,"url":"https://patchwork.libcamera.org/api/1.1/projects/1/?format=json","name":"libcamera","link_name":"libcamera","list_id":"libcamera_core","list_email":"libcamera-devel@lists.libcamera.org","web_url":"","scm_url":"","webscm_url":""},"msgid":"<20231110110002.21381-6-naush@raspberrypi.com>","date":"2023-11-10T11:00:02","name":"[libcamera-devel,v1,5/5] documentation: Document vendor specific control and properties handling","commit_ref":null,"pull_url":null,"state":"superseded","archived":false,"hash":"fe5e5e09cf2f609ab08bd205757494bb7b654088","submitter":{"id":34,"url":"https://patchwork.libcamera.org/api/1.1/people/34/?format=json","name":"Naushir Patuck","email":"naush@raspberrypi.com"},"delegate":null,"mbox":"https://patchwork.libcamera.org/patch/19198/mbox/","series":[{"id":4068,"url":"https://patchwork.libcamera.org/api/1.1/series/4068/?format=json","web_url":"https://patchwork.libcamera.org/project/libcamera/list/?series=4068","date":"2023-11-10T10:59:57","name":"Vendor controls and properties","version":1,"mbox":"https://patchwork.libcamera.org/series/4068/mbox/"}],"comments":"https://patchwork.libcamera.org/api/patches/19198/comments/","check":"pending","checks":"https://patchwork.libcamera.org/api/patches/19198/checks/","tags":{},"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 CD5AAC32B8\n\tfor ;\n\tFri, 10 Nov 2023 11:00:06 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id EEA28629D0;\n\tFri, 10 Nov 2023 12:00:04 +0100 (CET)","from mail-wm1-x336.google.com (mail-wm1-x336.google.com\n\t[IPv6:2a00:1450:4864:20::336])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 53FF7629C9\n\tfor ;\n\tFri, 10 Nov 2023 12:00:01 +0100 (CET)","by mail-wm1-x336.google.com with SMTP id\n\t5b1f17b1804b1-4084095722aso14074515e9.1\n\tfor ;\n\tFri, 10 Nov 2023 03:00:01 -0800 (PST)","from localhost.localdomain ([93.93.133.154])\n\tby smtp.gmail.com with ESMTPSA id\n\tr15-20020a05600c35cf00b0040531f5c51asm4883156wmq.5.2023.11.10.03.00.00\n\t(version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);\n\tFri, 10 Nov 2023 03:00:00 -0800 (PST)"],"DKIM-Signature":["v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org;\n\ts=mail; t=1699614005;\n\tbh=1AU+IJ1M/QDQijTXGAuccno9bu5RU0Owm0U59pqB/ls=;\n\th=To:Date:In-Reply-To:References:Subject:List-Id:List-Unsubscribe:\n\tList-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To:\n\tFrom;\n\tb=fWSQtSKraT1nRxPz4c7bHroi1rXH0QL2TbO/y8ARg1g09gv4rtWgug9KCEObU0mVm\n\tOeBupYj6CbQ7OviT2kIS/oeM7ELa6eqVuzMaJre/O3L+TizXivLFLmhYp0H6n/nc6t\n\th0wvoltbD87ntUG6nxKxB48ff+uvwkcIgY/y/6DqC8WlgeWn9kp7jM0XqIHIEyh9cJ\n\tI8pZVPsjmekZ3qGnhhOOah1j6y7UzI4AZSx9nydEJHLptFC12PyxPnJABznjUCGXpC\n\tJfngOyvbJScROy69PfkFhF65zqe6z4F/ph7ZQAo0QEw3H3aZ6PKE0aq+wh92qXHVAi\n\tUY3UMZP9o2zbg==","v=1; a=rsa-sha256; c=relaxed/relaxed;\n\td=raspberrypi.com; s=google; t=1699614001; x=1700218801;\n\tdarn=lists.libcamera.org; \n\th=content-transfer-encoding:mime-version:references:in-reply-to\n\t:message-id:date:subject:cc:to:from:from:to:cc:subject:date\n\t:message-id:reply-to;\n\tbh=93proqkiUMkkk25+FdjfHybOo3hIivrSKFMW3MZhICg=;\n\tb=Hm/WvHyJ/2xwuvdWJ5BdPBf89vbcSYARJp6DAVHotfzGq0QIf6zqj42qccoHMg7Q97\n\tDMW4hy2WVfYrcCOOmqxQOmCm3W6znlYpiMyNLF84Xk+EcFZgDDgD8lXwCFtM/ytvhyhp\n\t/rabDiJgdohtT03Dmo6JAWdadQoKOlRuQa0ZtpnUiJST6nzLS0rtbUrhjaJtprmGj2Oz\n\tAIAIrQ4VdAaLLzX/LPH0sLFWnTF3m+eUAQ3Dkr+NCjm0p2iCYExf4BalmPFuac9Brdhq\n\t6ePjlwZrHP9YsZKwvSFbxt0aoyEK0Ccf3i0UBvucCJZ+Pt6apjkpA7V6p0FmHmQJd0TY\n\tr0Nw=="],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (2048-bit key; \n\tunprotected) header.d=raspberrypi.com\n\theader.i=@raspberrypi.com\n\theader.b=\"Hm/WvHyJ\"; dkim-atps=neutral","X-Google-DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed;\n\td=1e100.net; s=20230601; t=1699614001; x=1700218801;\n\th=content-transfer-encoding:mime-version:references:in-reply-to\n\t:message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc\n\t:subject:date:message-id:reply-to;\n\tbh=93proqkiUMkkk25+FdjfHybOo3hIivrSKFMW3MZhICg=;\n\tb=SwY7sZaJA3ouAnRTtddkdpNdmtda4IDmILW8WNb81L1yxCCMgxW535JdcpY/Haj6nz\n\tXLcrSjp6UT4Llh/W4EfdhulT/bYIb76xqCax4vhlPIPySZnmsWirUlqBfiNLc6/i4UKU\n\tifScpmVdLyIBNST+VK4Fks0WmyFs/svA209b6uvRfEvZjV2Ain4uuni/gIHb33TRmKnt\n\tM7emwPPhkvdYlwmpJhS1i/zBZxMNAX3F4YN9I5NKPep0AfQxKqvTIT+OUxuHCHvC889c\n\tk3DvDyut4/PdB3TPH+yz3QPfq0TCmcEkBlPzyrmRYjBboAUrouHXt3uf8TEto0lEpl+1\n\t1zEg==","X-Gm-Message-State":"AOJu0YwZ+fwDSfutmn1iy2PRu0WNk1MM2Rts0zBIqr93DtF0fT9+3fOH\n\tSVb+CBgOocXEJrMGHAbAwRU+ndGLQr7SGf6btJd9QQ==","X-Google-Smtp-Source":"AGHT+IF5/GAIVtoWOfGc9fUb7PO0hOmaM1g2zVjcl/HiR6HQZ567njNDuveBEtPDxtdWFQTVybI7gQ==","X-Received":"by 2002:a05:600c:a4c:b0:409:718b:33e0 with SMTP id\n\tc12-20020a05600c0a4c00b00409718b33e0mr7741973wmq.16.1699614000672; \n\tFri, 10 Nov 2023 03:00:00 -0800 (PST)","To":"libcamera-devel@lists.libcamera.org","Date":"Fri, 10 Nov 2023 11:00:02 +0000","Message-Id":"<20231110110002.21381-6-naush@raspberrypi.com>","X-Mailer":"git-send-email 2.34.1","In-Reply-To":"<20231110110002.21381-1-naush@raspberrypi.com>","References":"<20231110110002.21381-1-naush@raspberrypi.com>","MIME-Version":"1.0","Content-Transfer-Encoding":"8bit","Subject":"[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":"Naushir Patuck via libcamera-devel\n\t","Reply-To":"Naushir Patuck ","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "},"content":"Add some documentation to the pipeline handler file describing how to\nimplement and handle vendor specific controls and properties with a\nsmall example.\n\nSigned-off-by: Naushir Patuck \n---\n Documentation/guides/pipeline-handler.rst | 53 +++++++++++++++++++++++\n 1 file changed, 53 insertions(+)","diff":"diff --git a/Documentation/guides/pipeline-handler.rst b/Documentation/guides/pipeline-handler.rst\nindex 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+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+Vendor specific controls and properties may be defined in a separate YMAL 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_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+\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+\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+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 \n","prefixes":["libcamera-devel","v1","5/5"]}