From patchwork Fri Nov 24 12:37:13 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Naushir Patuck X-Patchwork-Id: 19240 Return-Path: X-Original-To: parsemail@patchwork.libcamera.org Delivered-To: parsemail@patchwork.libcamera.org Received: from lancelot.ideasonboard.com (lancelot.ideasonboard.com [92.243.16.209]) by patchwork.libcamera.org (Postfix) with ESMTPS id 5FC7CC32B7 for ; Fri, 24 Nov 2023 12:37:27 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id E79C9629D4; Fri, 24 Nov 2023 13:37:26 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org; s=mail; t=1700829446; bh=eGqs129EM6+J8Mws/VYo52jC5pwtv4hgfPnByXcVwC0=; h=To:Date:In-Reply-To:References:Subject:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=PdzMDKnJc8QSn1/Mbx1uZyl9CadujJX5eAHvE/d/g8TBPL/e8UZ34hsyX6uNf7ZbP H0AoKvPnP15CQbNlJSSwFEr6U51nsS4ZtEwRRfpHhtNu9WwLX5c3df3TTXStarbK9S oLdZzlO3HL9FgxmuE12V8YIXxuC/hWFn3m6pCWPc3H31RGsnetY0CTMQyuEHBk+Ma5 veF6rQNumRUjucoo2qhEI9YtWxY0VLdahOJKGUcTsBSmOt9hfLQGutJ4VSpjR9lT3/ 93KHXc3anT/4SRUh3o2b7IHwZe0JbgoCwlxYphSkjzZYguIkwgjuBBr5v6lfttLZBH QlI05GG46nO8w== Received: from mail-wm1-x331.google.com (mail-wm1-x331.google.com [IPv6:2a00:1450:4864:20::331]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id C9787629C8 for ; Fri, 24 Nov 2023 13:37:23 +0100 (CET) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (2048-bit key; unprotected) header.d=raspberrypi.com header.i=@raspberrypi.com header.b="hoLwH1Va"; dkim-atps=neutral Received: by mail-wm1-x331.google.com with SMTP id 5b1f17b1804b1-4083f613272so13113745e9.1 for ; Fri, 24 Nov 2023 04:37:23 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=raspberrypi.com; s=google; t=1700829443; x=1701434243; darn=lists.libcamera.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=kQC94eTP69cZcBBoIV68TpVGNbbk+m4+pPQAyOU5+U8=; b=hoLwH1VaATjiR2vD70pe+b1p/2vDrZNppmkH9oduTGJ4dGg4xV122ZPT4oF0Gcwh5H CO58VUzdb2wn0BckJ2dWuuu7oUAipDAZcNsocO1c6PoYhXk12ZomJRz2XfYcGEKAr6Da MARM/j/mJAtVfO1m3niqiHT5sDj4J5yVqfPcuCVa+18QwMoDRr8fuKLh71zoBQcO4NlU B0X4M/Jui/RIJbagB9oDFB4I5Q5Umsn9vDHQBCFOjF40Cj7GLXAY35oSl8ePn1HCCTlS CCqGwPGRwHVm9QQXAFwuiTQzWfasiFhXYSq/7tdN7u3tdWcP5zhxEosYyKB4K4z7rCDm /aJA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1700829443; x=1701434243; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=kQC94eTP69cZcBBoIV68TpVGNbbk+m4+pPQAyOU5+U8=; b=U7pyEz5SHiv+wThHztHHkG25ia+UW6SRAP/r5hJTNOQbQ99kUHsOs1VS0vWxYASKbB sluySNLk8g5fC0NVAXASLpBP/EEHi3flqR2g/vA0YXrTBShYxQ68ehVziBZJuXXmZ84R sGR1AsbDAMnd/TL64+6aM1dfgO3AoYJP7l9ZKnXumo++6V/B/ol1x0ABk/zsBjDqdn4z Rd0yl5slb2jisHYXmspnSRjuCMBdBFvWn3x4w33S/K2i9fNG+wOpaHOvAwNUk2JlG2Sh or03KSRy++WRsXAhLAoiXQrmC6Xgdj6FUi83E+fMRNN/0tIWslcdp0aH/uBzd/X6FhHJ 2xfg== X-Gm-Message-State: AOJu0Yxy+GgPx4oGZQPkMhloHCoAG7zIreQ3WZJNB/tqY1XqlFlxi0aO W/+e3VRB2Qot9PSlXukEuxdF5oHoOUShM+QucwwG/A== X-Google-Smtp-Source: AGHT+IFF/nzYuQObldNmcy6aHIUUzCIoWBEKza8Rdn5pMmpz3HzBlpV85AWMfJq5ztzrJRJyj4VipA== X-Received: by 2002:a05:600c:4f90:b0:40b:36e5:e1e9 with SMTP id n16-20020a05600c4f9000b0040b36e5e1e9mr1993845wmq.24.1700829443250; Fri, 24 Nov 2023 04:37:23 -0800 (PST) Received: from localhost.localdomain ([93.93.133.154]) by smtp.gmail.com with ESMTPSA id v11-20020a05600c444b00b0040b3867a297sm3303690wmn.36.2023.11.24.04.37.22 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 24 Nov 2023 04:37:22 -0800 (PST) To: libcamera-devel@lists.libcamera.org Date: Fri, 24 Nov 2023 12:37:13 +0000 Message-Id: <20231124123713.22519-8-naush@raspberrypi.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20231124123713.22519-1-naush@raspberrypi.com> References: <20231124123713.22519-1-naush@raspberrypi.com> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH v3 7/7] documentation: Document vendor specific controls and properties handling X-BeenThere: libcamera-devel@lists.libcamera.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Naushir Patuck via libcamera-devel From: Naushir Patuck Reply-To: Naushir Patuck Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" Add some documentation to the pipeline handler file describing how to implement and handle vendor specific controls and properties with a small example. Signed-off-by: Naushir Patuck Reviewed-by: Laurent Pinchart Reviewed-by: Kieran Bingham --- Documentation/guides/pipeline-handler.rst | 48 +++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/Documentation/guides/pipeline-handler.rst b/Documentation/guides/pipeline-handler.rst index 66d428a19c4f..5a3d00b1b879 100644 --- a/Documentation/guides/pipeline-handler.rst +++ b/Documentation/guides/pipeline-handler.rst @@ -672,6 +672,54 @@ handling controls: #include #include +Vendor-specific controls and properties +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Vendor-specific controls and properties must be defined in a separate YAML file +and included in the build by defining the pipeline handler to file mapping in +include/libcamera/meson.build. + +For example, adding a Raspberry Pi vendor control file for the PiSP pipeline +handler is done with the following mapping: + +.. code-block:: meson + + controls_map = { + 'controls': { + 'draft': 'control_ids_draft.yaml', + 'libcamera': 'control_ids.yaml', + 'rpi/pisp': 'control_ids_rpi.yaml', + }, + + 'properties': { + 'draft': 'property_ids_draft.yaml', + 'libcamera': 'property_ids.yaml', + } + } + +Vendor-specific controls and properties must contain a `vendor: ` +tag in the YAML file. Every unique vendor tag must define a unique and +non-overlapping range of reserved control IDs in src/libcamera/control_ranges.yaml. + +For example, the following block defines a vendor-specific control with the +`rpi` vendor tag: + +.. code-block:: yaml + + vendor: rpi + controls: + - PispConfigDumpFile: + type: string + description: | + Triggers the Raspberry Pi PiSP pipeline handler to generate a JSON + formatted dump of the Backend configuration to the filename given by the + value of the control. + +This controls will be generated in the vendor-specific namespace +`libcamera::controls::rpi`. Additionally a `#define +LIBCAMERA_HAS_RPI_VENDOR_CONTROLS` will be available to allow applications to +test for the availability of these controls. + Generating a default configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~