From patchwork Tue Nov 21 14:53:50 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Naushir Patuck X-Patchwork-Id: 19221 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 9CB62C328F for ; Tue, 21 Nov 2023 14:54:06 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 48A2B629C6; Tue, 21 Nov 2023 15:54:06 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org; s=mail; t=1700578446; bh=VCa2KmEboVJanCSpihCW3DXtXj0h/UBsipooWVda5uA=; 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=uDD1f2omAEld30O76lq12o4fCgyqJqm+9AMNq4qPe39U3YJ3MfqeyJQ073VaT1/8o lE+42i0y0l0XY9QXu6c3eAv90VvcIekIbGnoFXmgakmaTcC/gR/t79mOsfCtfaqDy8 vbSumPAI1FmP5kjG8Atsu0bkmSAHW4UqjHxfCl1RQ3gla8qrwmfMVCEO3nIg7LcT6T MpUH8axQPVNbkNVgqeXW5O37mVRtq/z5PkklTWpEx4JJE3wyCs2PUoujXo732GEtNY oZ6Z9JnIYWkG6Eg6zKbNCAMfnCzLZ2knn0x6RRC4wMO+9x16MQ7Bqgn3usp8MfEJWZ +hwtmFDbShE1w== Received: from mail-wm1-x332.google.com (mail-wm1-x332.google.com [IPv6:2a00:1450:4864:20::332]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 56487629C7 for ; Tue, 21 Nov 2023 15:54:04 +0100 (CET) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (2048-bit key; unprotected) header.d=raspberrypi.com header.i=@raspberrypi.com header.b="RHDdelsN"; dkim-atps=neutral Received: by mail-wm1-x332.google.com with SMTP id 5b1f17b1804b1-4084b0223ccso26071715e9.2 for ; Tue, 21 Nov 2023 06:54:04 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=raspberrypi.com; s=google; t=1700578443; x=1701183243; 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=c6L1W2HLRfk9Spk6pPsjQsBwMqr3C4mCLeQWt4Cm0dw=; b=RHDdelsNgeGnsmXmu2LW+LO+FelKDn9GFjHSRvc4JrVOu+IG8+1uG+5ratg3kT6ncF yAx5hNc8YlAtu5vyQKnvifcOkC+7QSLv4z2L7ZX4Js5W8NeslXCGVuHWhuXOssBHBubw xB+euny02xzMv7+Hp4krw612baxBeX+/h4v5asnn3uB1Rb5VwR3ti91ep8Qap00blyep KE3bZtRkKxiPzgoRonv3HDZyyPN00CW8a2EjD0VOsCFEKUPzhHi3m7+hkMUJnXW3N5lq wpt/eCotnC4qgK2GSA3kTVGhTILqW6MtAtEuYQJN2wAsAPGpkH+ej2ZSK3Oep4D2R/70 2aKw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1700578443; x=1701183243; 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=c6L1W2HLRfk9Spk6pPsjQsBwMqr3C4mCLeQWt4Cm0dw=; b=ZQV2YcepwiZd6PoitejhS9/uY5jK+cqivPgt9n2d+QVgPcDla0eMZg2zy9Q029UyAN 1avECvwEjxbC+8Wbz6NPH/IiLahXCB8/OC4Brd95sLz3q0Ca+XCIChPl6JqDUGu+gzwn SStKK8hfb76YZNSPvz4hmzsM2qy5H0G7mzIUqGXOaiSKrlFUPitj1NHS1Nxk937Pe/Ad bIu0PIA66K4g6I2btOBLL0MW0v/ul74hgmUZmNb5aq2XRp28GkIqJxXUiFGkN7ZPAWDU hLxBT4M5bcqfW5DtkJ7L0lXi0kV9O37NKsM7/UZ8mYnJZK4F2Qd6bQrl7ANfWqiIl/eW mHGw== X-Gm-Message-State: AOJu0YxUpijKlvUBkIoXRYy4SumQqEslAejyWLwXaDKuKxrstBRjhclk RDxoIu6Igl221a3gwacPW35HPf4TS2Zg6nA6qHzvYg== X-Google-Smtp-Source: AGHT+IEpbXnb4sDiusV2bk3QMZvVJbu52VklRBmtiTNzi7qKZSaO1n26InngkKAvaVtxH7zYHAsPdA== X-Received: by 2002:a05:600c:19cc:b0:406:f832:6513 with SMTP id u12-20020a05600c19cc00b00406f8326513mr8107884wmq.3.1700578443600; Tue, 21 Nov 2023 06:54:03 -0800 (PST) Received: from localhost.localdomain ([93.93.133.154]) by smtp.gmail.com with ESMTPSA id h18-20020a05600c351200b004063ea92492sm17570968wmq.22.2023.11.21.06.54.01 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 21 Nov 2023 06:54:02 -0800 (PST) To: libcamera-devel@lists.libcamera.org Date: Tue, 21 Nov 2023 14:53:50 +0000 Message-Id: <20231121145350.5956-7-naush@raspberrypi.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20231121145350.5956-1-naush@raspberrypi.com> References: <20231121145350.5956-1-naush@raspberrypi.com> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH v2 6/6] documentation: Document vendor specific control 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 --- Documentation/guides/pipeline-handler.rst | 52 +++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/Documentation/guides/pipeline-handler.rst b/Documentation/guides/pipeline-handler.rst index 10b9c75c2a7f..26977164accf 100644 --- a/Documentation/guides/pipeline-handler.rst +++ b/Documentation/guides/pipeline-handler.rst @@ -672,6 +672,58 @@ 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 + + vendor_controls_mapping = { + # Mapping of vendor (pipeline handler) specific controls files + 'controls': + { + 'rpi/pisp': 'control_ids_rpi.yaml', + }, + # Mapping of vendor (pipeline handler) specific properties files + 'properties': + { + + } + } + +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. + +Note that libcamera core controls are defined with the `vendor: libcamera` tag +and libcamera draft controls are defined with the `vendor: draft` tag. + Generating a default configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~