From patchwork Thu Dec 24 08:15:34 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Paul Elder X-Patchwork-Id: 10723 X-Patchwork-Delegate: paul.elder@ideasonboard.com 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 9D625C0F1A for ; Thu, 24 Dec 2020 08:16:09 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 5E3F962005; Thu, 24 Dec 2020 09:16:09 +0100 (CET) Authentication-Results: lancelot.ideasonboard.com; dkim=fail reason="signature verification failed" (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="rpHKFYFD"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [213.167.242.64]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 166AF61FF6 for ; Thu, 24 Dec 2020 09:16:08 +0100 (CET) Received: from pyrite.rasen.tech (unknown [IPv6:2400:4051:61:600:2c71:1b79:d06d:5032]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 532DEDFC; Thu, 24 Dec 2020 09:16:06 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1608797767; bh=LOqr38i7O+YVn2Y3J9i1bCN9rXsqr7jSRXhLKHGgn/w=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=rpHKFYFDSOQwBBl5FZsYxEmaffdlHGI1tdd9+lPFiVPN0VFnSSQ0EqIQk3Chabey/ ebZ21KOLwy2npo8g1sXINiU9FLaQHViQP6JaaDtgyINyAxOz26lYkCDl1lXKOJvfKU c8C1UKa5+vdWdVZK02XjN+IDXFJHDxCB9eWv9A08= From: Paul Elder To: libcamera-devel@lists.libcamera.org Date: Thu, 24 Dec 2020 17:15:34 +0900 Message-Id: <20201224081534.41601-10-paul.elder@ideasonboard.com> X-Mailer: git-send-email 2.27.0 In-Reply-To: <20201224081534.41601-1-paul.elder@ideasonboard.com> References: <20201224081534.41601-1-paul.elder@ideasonboard.com> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH v6 9/9] ipa: Add core.mojom 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: , Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" Add a base mojom file to contain empty mojom definitions of libcamera objects, as well as documentation for the IPA interfaces that need to be defined in the mojom files. Signed-off-by: Paul Elder Reviewed-by: Niklas Söderlund Reviewed-by: Laurent Pinchart --- Changes in v6: - expand documentation on what can and can't be done in mojom - add definitions for geometry.h structs, and the structs that used to be in ipa_interface.h, including their documentation - remove documentation for start() Changes in v5: - add todo for defining some libcamera ipa structs in mojom - remove ipa_mojom_core from dependencies of everything in the generator stage - add documentation for the base IPA functions (init, stop, start) Changes in v4: - move docs to IPA guide Changes in v3: - add doc that structs need to be defined - add doc to recommend namespacing - change indentation - add requirement that base controls *must* be defined in libcamera::{pipeline_name}::Controls New in v2 --- include/libcamera/ipa/core.mojom | 208 +++++++++++++++++++++++++++++++ 1 file changed, 208 insertions(+) create mode 100644 include/libcamera/ipa/core.mojom diff --git a/include/libcamera/ipa/core.mojom b/include/libcamera/ipa/core.mojom new file mode 100644 index 00000000..d707508b --- /dev/null +++ b/include/libcamera/ipa/core.mojom @@ -0,0 +1,208 @@ +/* SPDX-License-Identifier: LGPL-2.1-or-later */ + +/* + * Things that can be defined here (and in other mojom files): + * - consts + * - enums + * - structs + * + * Attributes: + * - genHeader - structs only + * - designate that this struct needs a C++ header definition to be generated + * - not necessary if this struct is already defined in a C++ header + * - genSerdes - structs only + * - designate that this struct needs a (de)serializer to be generated + * - all fields need a (de)serializer to be defined, either hand-written + * in ipa_data_serializer.h, or designated here with genSerdes + * - hasFd - struct fields or empty structs only + * - designate that this field or empty struct contains a FileDescriptor + * + * Rules: + * - Any struct that is used in a struct definition in mojom must also be + * defined in mojom + * - If the struct has both a definition in a C++ header and a (de)serializer + * in ipa_data_serializer.h, then the struct shall be declared as empty + * - If the struct only has a definition in a C++ header, but no + * (de)serializer, then the struct definition should have the [genSerdes] + * attribute + * - If the struct has neither a definition in a C++ header nor a + * (de)serializer, then the struct definition should have both the + * [genHeader] and [genSerdes] attributes + * - Nested structures (eg. FrameBuffer::Plane) cannot be defined in mojom. + * - Avoid them, by defining them in a header in C++ and a (de)serializer in + * ipa_data_serializer.h + * - If a struct is in an array/map inside a struct, then the struct that is + * the member of the array/map does not need a mojom definition. + * - This can be used to embed nested structures. The C++ double dolon is + * replaced with a dot (eg. FrameBuffer::Plane -> FrameBuffer.Plane) + * - The struct must still be defined in a header in C++ and a (de)serializer + * implemented in ipa_data_serializer.h, as it cannot be defined in mojom + * - [genHeader] and [genSerdes] only work here in core.mojom. Any struct defined + * in other mojom files will implicitly have both attributes. + * - If a struct definition does not have genHeader, then the header where the + * struct is defined must be #included (or the struct forward-declared) in + * ipa_interface.h + * - If a field in a struct has a FileDescriptor, but is not explicitly + * defined so in mojom, then the field must be marked with the [hasFd] + * attribute. + */ +struct ControlInfoMap {}; +struct ControlList {}; +struct FileDescriptor {}; + +[genSerdes] struct Point { + int32 x; + int32 y; +}; + +[genSerdes] struct Size { + uint32 width; + uint32 height; +}; + +[genSerdes] struct SizeRange { + Size min; + Size max; + uint32 hStep; + uint32 vStep; +}; + +[genSerdes] struct Rectangle { + int32 x; + int32 y; + uint32 width; + uint32 height; +}; + +[genSerdes] struct CameraSensorInfo { + string model; + + uint32 bitsPerPixel; + + Size activeAreaSize; + Rectangle analogCrop; + Size outputSize; + + uint64 pixelRate; + uint32 lineLength; +}; + +/** + * \struct IPABuffer + * \brief Buffer information for the IPA interface + * + * The IPABuffer structure associates buffer memory with a unique ID. It is + * used to map buffers to the IPA with IPAInterface::mapBuffers(), after which + * buffers will be identified by their ID in the IPA interface. + */ + +/** + * \var IPABuffer::id + * \brief The buffer unique ID + * + * Buffers mapped to the IPA are identified by numerical unique IDs. The IDs + * are chosen by the pipeline handler to fulfil the following constraints: + * + * - IDs shall be positive integers different than zero + * - IDs shall be unique among all mapped buffers + * + * When buffers are unmapped with IPAInterface::unmapBuffers() their IDs are + * freed and may be reused for new buffer mappings. + */ + +/** + * \var IPABuffer::planes + * \brief The buffer planes description + * + * Stores the dmabuf handle and length for each plane of the buffer. + */ + +/** + * \class IPAInterface + * \brief C++ Interface for IPA implementation + * + * This pure virtual class defines a skeletal C++ API for IPA modules. + * Specializations of this class must be defined in a mojom file in + * include/libcamera/ipa/ (see the IPA Writers Guide for details + * on how to do so). + * + * Due to process isolation all arguments to the IPAInterface methods and + * signals may need to be transferred over IPC. The class thus uses serializable + * data types only. The IPA C++ interface defines custom data structures that + * mirror core libcamera structures when the latter are not suitable, such as + * IPAStream to carry StreamConfiguration data. + * + * Custom data structures may also be defined in the mojom file, in which case + * the (de)serialization will automatically be generated. If any other libcamera + * structures are to be used as parameters, then a de/serializer for them must + * be implemented in IPADataSerializer. + * + * The pipeline handler shall use the IPAManager to locate a compatible + * IPAInterface. The interface may then be used to interact with the IPA module. + */ +[genHeader, genSerdes] struct IPABuffer { + uint32 id; + [hasFd] array planes; +}; + +/** + * \struct IPASettings + * \brief IPA interface initialization settings + * + * The IPASettings structure stores data passed to the IPAInterface::init() + * function. The data contains settings that don't depend on a particular camera + * or pipeline configuration and are valid for the whole life time of the IPA + * interface. + */ + +/** + * \var IPASettings::configurationFile + * \brief The name of the IPA configuration file + * + * This field may be an empty string if the IPA doesn't require a configuration + * file. + */ +[genHeader, genSerdes] struct IPASettings { + string configurationFile; +}; + +/** + * \struct IPAStream + * \brief Stream configuration for the IPA interface + * + * The IPAStream structure stores stream configuration parameters needed by the + * IPAInterface::configure() method. It mirrors the StreamConfiguration class + * that is not suitable for this purpose due to not being serializable. + */ + +/** + * \var IPAStream::pixelFormat + * \brief The stream pixel format + */ + +/** + * \var IPAStream::size + * \brief The stream size in pixels + */ +[genHeader, genSerdes] struct IPAStream { + uint32 pixelFormat; + Size size; +}; + +/** + * \fn init() + * \brief Initialise the IPAInterface + * \param[in] settings The IPA initialization settings + * + * This function initializes the IPA interface. It shall be called before any + * other function of the IPAInterface. The \a settings carry initialization + * parameters that are valid for the whole life time of the IPA interface. + */ + +/** + * \fn stop() + * \brief Stop the IPA + * + * This method informs the IPA module that the camera is stopped. The IPA module + * shall release resources prepared in start(). + */