{"id":19254,"url":"https://patchwork.libcamera.org/api/1.1/patches/19254/?format=json","web_url":"https://patchwork.libcamera.org/patch/19254/","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":"<20231130142534.2075-7-naush@raspberrypi.com>","date":"2023-11-30T14:25:34","name":"[libcamera-devel,v4,6/6] documentation: Document vendor specific controls and properties handling","commit_ref":"cbfbab48a7c0b479c2281cceaf11fcd2afed1093","pull_url":null,"state":"accepted","archived":false,"hash":"48a50298f1db346ab13527f61532e0774e342f40","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/19254/mbox/","series":[{"id":4091,"url":"https://patchwork.libcamera.org/api/1.1/series/4091/?format=json","web_url":"https://patchwork.libcamera.org/project/libcamera/list/?series=4091","date":"2023-11-30T14:25:28","name":"Vendor controls and properties","version":4,"mbox":"https://patchwork.libcamera.org/series/4091/mbox/"}],"comments":"https://patchwork.libcamera.org/api/patches/19254/comments/","check":"pending","checks":"https://patchwork.libcamera.org/api/patches/19254/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 1DA3EC32BC\n\tfor ;\n\tThu, 30 Nov 2023 14:25:51 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id C5037629DF;\n\tThu, 30 Nov 2023 15:25:50 +0100 (CET)","from mail-ej1-x62a.google.com (mail-ej1-x62a.google.com\n\t[IPv6:2a00:1450:4864:20::62a])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 03A04629D8\n\tfor ;\n\tThu, 30 Nov 2023 15:25:47 +0100 (CET)","by mail-ej1-x62a.google.com with SMTP id\n\ta640c23a62f3a-a013d22effcso145617666b.2\n\tfor ;\n\tThu, 30 Nov 2023 06:25:46 -0800 (PST)","from localhost.localdomain ([88.97.53.79])\n\tby smtp.gmail.com with ESMTPSA id\n\ta5-20020a17090640c500b009e50ea0a05asm725577ejk.99.2023.11.30.06.25.45\n\t(version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);\n\tThu, 30 Nov 2023 06:25:45 -0800 (PST)"],"DKIM-Signature":["v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org;\n\ts=mail; t=1701354350;\n\tbh=aYEL16EU4f1meZaubhLC/2GV16YruyYUTEjQrOaXxfA=;\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=pBapQ6ijXWapbLET7srysUUHw6++kE/83FOlvhsR9GfCNK4VDF3qfvV0LH3OOLmS4\n\tCZHe1SQyLcFf1FjDy1JykboQs0aMYYjvdeXnXSjlH6x7uEawc5CTsKglg8lNXuoU6k\n\tEbMpLaO2gxJnUh9IUu9yFlk5LCVyjko12MeVhmevHdjop6dRffix8mIe3ParZOHxJx\n\tjY0md3KspU4KEyzDVrFgdLN2nCrPYO0jB+5/mP//zi6WXtbs5Ne4EosqPU3k2SCBGe\n\tA65w1875D9CkEG7/Ibm8sJFNk90d4b9hyIY17F78W0d6qGsbgp/kvYcw0S60pWhzer\n\tRyQ5hcYeLMhVg==","v=1; a=rsa-sha256; c=relaxed/relaxed;\n\td=raspberrypi.com; s=google; t=1701354346; x=1701959146;\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=WwhMFv7q7fH7OsEGATrEeBD17BE3B4zAPb96dSvEZdg=;\n\tb=I0iB4DvHT9cYKdwk8zEJ49AGCe/iKF63NoDd0+KF3xH+c1WwMQpuh3QtC4ptLf7WNT\n\tU/jjeGuBAAItjeqdABkJxKbP+cxTqHyjke+lBxVBOWfqlec5U/vnZ4TwaRIFSJbO5Jok\n\tXi9s14g9aHUDd25sNWrDVukncAQBmhoL7c3O3SAt4yWTq6qVoXnr+2CfP0Yd5q+9U/AT\n\taTuBthDTWC+3XCYcbJ8RJ61aTYCkz0rqGUFbNL/VinhvVYAM5/+rqUiY+cLzgHZImg1s\n\t4HyyJbivqccSI5PzJjcFsMquxru9xD0hL22OEmuLf8fOkcHvCySd1+OVS6VUF/1jUNHL\n\t5icw=="],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (2048-bit key; \n\tunprotected) header.d=raspberrypi.com\n\theader.i=@raspberrypi.com\n\theader.b=\"I0iB4DvH\"; dkim-atps=neutral","X-Google-DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed;\n\td=1e100.net; s=20230601; t=1701354346; x=1701959146;\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=WwhMFv7q7fH7OsEGATrEeBD17BE3B4zAPb96dSvEZdg=;\n\tb=eVtYeTg2elcC+Q522vGqe0xaCiRLMC2pEovSCsnCN1pWwJfFgT6EQkgBqK6SN9PCAc\n\ttuNJvL8ZXjS8eRbGxwzAeqBOK/bXSz5wfMBrvvvao41FYW8s7ci+Ya75rQ5FRlIHd+k1\n\twpWjXvpJudTt8BNJSFZ2NNyHCCLlj7JnmMfv3qkyUarpSLFwC1FpSmUXApa0he6W9AyU\n\tNJq/c7hahzWCJzi6Ee2KgrXM7/pvpYPXxOoSgKtwAZ4nksONDmE0dK8rBZIaKtjtZfz6\n\tzwBp9tPUm4hJj9Mlk0CqtnUK7HveMroUnTqROOhbV7qGKrzEumrXOipikdSiR3sepCiG\n\tdg7A==","X-Gm-Message-State":"AOJu0Yy0qSCiybehWEdaoXJ9222nSXEv1wS7MhBTIq8xjdV/Myid93Yf\n\tm706nXNMN/HrC6YJ81JROLT6Xc6aasBTRQrf8iCJrA==","X-Google-Smtp-Source":"AGHT+IFlkPwSH52DXn5fq8LIqnBROsVa9Vkp4ZH+vKBVeZSMPcH917fA6biqlulbCNrFobuWFxPfqg==","X-Received":"by 2002:a17:906:2d7:b0:a14:d6e2:fb1f with SMTP id\n\t23-20020a17090602d700b00a14d6e2fb1fmr6772295ejk.10.1701354346273; \n\tThu, 30 Nov 2023 06:25:46 -0800 (PST)","To":"libcamera-devel@lists.libcamera.org","Date":"Thu, 30 Nov 2023 14:25:34 +0000","Message-Id":"<20231130142534.2075-7-naush@raspberrypi.com>","X-Mailer":"git-send-email 2.34.1","In-Reply-To":"<20231130142534.2075-1-naush@raspberrypi.com>","References":"<20231130142534.2075-1-naush@raspberrypi.com>","MIME-Version":"1.0","Content-Transfer-Encoding":"8bit","Subject":"[libcamera-devel] [PATCH v4 6/6] documentation: Document vendor\n\tspecific controls 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 \nReviewed-by: Laurent Pinchart \nReviewed-by: Kieran Bingham \n---\n Documentation/guides/pipeline-handler.rst | 52 +++++++++++++++++++++++\n 1 file changed, 52 insertions(+)","diff":"diff --git a/Documentation/guides/pipeline-handler.rst b/Documentation/guides/pipeline-handler.rst\nindex 66d428a19c4f..26dc93589382 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. These YAML files live in the src/libcamera\n+directory.\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+ controls_map = {\n+ 'controls': {\n+ 'draft': 'control_ids_draft.yaml',\n+ 'libcamera': 'control_ids_core.yaml',\n+ 'rpi/pisp': 'control_ids_rpi.yaml',\n+ },\n+\n+ 'properties': {\n+ 'draft': 'property_ids_draft.yaml',\n+ 'libcamera': 'property_ids_core.yaml',\n+ }\n+ }\n+\n+The pipeline handler named above must match the pipeline handler option string\n+specified in the meson build configuration.\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+\n+The 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 Generating a default configuration\n ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n","prefixes":["libcamera-devel","v4","6/6"]}