From patchwork Thu Nov 30 14:25:34 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Naushir Patuck X-Patchwork-Id: 19254 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 1DA3EC32BC for ; Thu, 30 Nov 2023 14:25:51 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id C5037629DF; Thu, 30 Nov 2023 15:25:50 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org; s=mail; t=1701354350; bh=aYEL16EU4f1meZaubhLC/2GV16YruyYUTEjQrOaXxfA=; 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=pBapQ6ijXWapbLET7srysUUHw6++kE/83FOlvhsR9GfCNK4VDF3qfvV0LH3OOLmS4 CZHe1SQyLcFf1FjDy1JykboQs0aMYYjvdeXnXSjlH6x7uEawc5CTsKglg8lNXuoU6k EbMpLaO2gxJnUh9IUu9yFlk5LCVyjko12MeVhmevHdjop6dRffix8mIe3ParZOHxJx jY0md3KspU4KEyzDVrFgdLN2nCrPYO0jB+5/mP//zi6WXtbs5Ne4EosqPU3k2SCBGe A65w1875D9CkEG7/Ibm8sJFNk90d4b9hyIY17F78W0d6qGsbgp/kvYcw0S60pWhzer RyQ5hcYeLMhVg== Received: from mail-ej1-x62a.google.com (mail-ej1-x62a.google.com [IPv6:2a00:1450:4864:20::62a]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 03A04629D8 for ; Thu, 30 Nov 2023 15:25:47 +0100 (CET) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (2048-bit key; unprotected) header.d=raspberrypi.com header.i=@raspberrypi.com header.b="I0iB4DvH"; dkim-atps=neutral Received: by mail-ej1-x62a.google.com with SMTP id a640c23a62f3a-a013d22effcso145617666b.2 for ; Thu, 30 Nov 2023 06:25:46 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=raspberrypi.com; s=google; t=1701354346; x=1701959146; 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=WwhMFv7q7fH7OsEGATrEeBD17BE3B4zAPb96dSvEZdg=; b=I0iB4DvHT9cYKdwk8zEJ49AGCe/iKF63NoDd0+KF3xH+c1WwMQpuh3QtC4ptLf7WNT U/jjeGuBAAItjeqdABkJxKbP+cxTqHyjke+lBxVBOWfqlec5U/vnZ4TwaRIFSJbO5Jok Xi9s14g9aHUDd25sNWrDVukncAQBmhoL7c3O3SAt4yWTq6qVoXnr+2CfP0Yd5q+9U/AT aTuBthDTWC+3XCYcbJ8RJ61aTYCkz0rqGUFbNL/VinhvVYAM5/+rqUiY+cLzgHZImg1s 4HyyJbivqccSI5PzJjcFsMquxru9xD0hL22OEmuLf8fOkcHvCySd1+OVS6VUF/1jUNHL 5icw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1701354346; x=1701959146; 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=WwhMFv7q7fH7OsEGATrEeBD17BE3B4zAPb96dSvEZdg=; b=eVtYeTg2elcC+Q522vGqe0xaCiRLMC2pEovSCsnCN1pWwJfFgT6EQkgBqK6SN9PCAc tuNJvL8ZXjS8eRbGxwzAeqBOK/bXSz5wfMBrvvvao41FYW8s7ci+Ya75rQ5FRlIHd+k1 wpWjXvpJudTt8BNJSFZ2NNyHCCLlj7JnmMfv3qkyUarpSLFwC1FpSmUXApa0he6W9AyU NJq/c7hahzWCJzi6Ee2KgrXM7/pvpYPXxOoSgKtwAZ4nksONDmE0dK8rBZIaKtjtZfz6 zwBp9tPUm4hJj9Mlk0CqtnUK7HveMroUnTqROOhbV7qGKrzEumrXOipikdSiR3sepCiG dg7A== X-Gm-Message-State: AOJu0Yy0qSCiybehWEdaoXJ9222nSXEv1wS7MhBTIq8xjdV/Myid93Yf m706nXNMN/HrC6YJ81JROLT6Xc6aasBTRQrf8iCJrA== X-Google-Smtp-Source: AGHT+IFlkPwSH52DXn5fq8LIqnBROsVa9Vkp4ZH+vKBVeZSMPcH917fA6biqlulbCNrFobuWFxPfqg== X-Received: by 2002:a17:906:2d7:b0:a14:d6e2:fb1f with SMTP id 23-20020a17090602d700b00a14d6e2fb1fmr6772295ejk.10.1701354346273; Thu, 30 Nov 2023 06:25:46 -0800 (PST) Received: from localhost.localdomain ([88.97.53.79]) by smtp.gmail.com with ESMTPSA id a5-20020a17090640c500b009e50ea0a05asm725577ejk.99.2023.11.30.06.25.45 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 30 Nov 2023 06:25:45 -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 Subject: [libcamera-devel] [PATCH v4 6/6] 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 | 52 +++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/Documentation/guides/pipeline-handler.rst b/Documentation/guides/pipeline-handler.rst index 66d428a19c4f..26dc93589382 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. These YAML files live in the src/libcamera +directory. + +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_core.yaml', + 'rpi/pisp': 'control_ids_rpi.yaml', + }, + + 'properties': { + 'draft': 'property_ids_draft.yaml', + 'libcamera': 'property_ids_core.yaml', + } + } + +The pipeline handler named above must match the pipeline handler option string +specified in the meson build configuration. + +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. + +The 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~