{"id":10368,"url":"https://patchwork.libcamera.org/api/patches/10368/?format=json","web_url":"https://patchwork.libcamera.org/patch/10368/","project":{"id":1,"url":"https://patchwork.libcamera.org/api/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":"<20201106103707.49660-21-paul.elder@ideasonboard.com>","date":"2020-11-06T10:36:50","name":"[libcamera-devel,v4,20/37] libcamera: IPAInterface: remove ipa_context and functions from documentation","commit_ref":null,"pull_url":null,"state":"superseded","archived":false,"hash":"419a67ed9d157dee5aa327ff4f9fcb642514e4bc","submitter":{"id":17,"url":"https://patchwork.libcamera.org/api/people/17/?format=json","name":"Paul Elder","email":"paul.elder@ideasonboard.com"},"delegate":null,"mbox":"https://patchwork.libcamera.org/patch/10368/mbox/","series":[{"id":1448,"url":"https://patchwork.libcamera.org/api/series/1448/?format=json","web_url":"https://patchwork.libcamera.org/project/libcamera/list/?series=1448","date":"2020-11-06T10:36:30","name":"IPA isolation implementation","version":4,"mbox":"https://patchwork.libcamera.org/series/1448/mbox/"}],"comments":"https://patchwork.libcamera.org/api/patches/10368/comments/","check":"pending","checks":"https://patchwork.libcamera.org/api/patches/10368/checks/","tags":{},"headers":{"Return-Path":"<libcamera-devel-bounces@lists.libcamera.org>","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 C5957BDB89\n\tfor <parsemail@patchwork.libcamera.org>;\n\tFri,  6 Nov 2020 10:38:06 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 9009962D2E;\n\tFri,  6 Nov 2020 11:38:06 +0100 (CET)","from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[213.167.242.64])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id EB88662D22\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tFri,  6 Nov 2020 11:38:04 +0100 (CET)","from pyrite.rasen.tech (unknown\n\t[IPv6:2400:4051:61:600:2c71:1b79:d06d:5032])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id 84612A19;\n\tFri,  6 Nov 2020 11:38:03 +0100 (CET)"],"Authentication-Results":"lancelot.ideasonboard.com;\n\tdkim=fail reason=\"signature verification failed\" (1024-bit key;\n\tunprotected) header.d=ideasonboard.com header.i=@ideasonboard.com\n\theader.b=\"mAqiGqlT\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1604659084;\n\tbh=7zVAPaa6ffoCX/yV5kXbu/bpM1ylgSR92CjaLJJzrA4=;\n\th=From:To:Cc:Subject:Date:In-Reply-To:References:From;\n\tb=mAqiGqlTGlb9u3JHLvIVVo3pN8qYJndspBmrwODWBptu1U7Xjo0JEs1tOXxdWyX2n\n\trR0FeFXsy/SO5KIZX2yzEquyU46e5v+LubnlZKKkrSOQBYxxfjPa65OaebThF212eG\n\tw37r80cX0FayDixIbD2gE2QLO7SUlDQ8r/PS8Nvo=","From":"Paul Elder <paul.elder@ideasonboard.com>","To":"libcamera-devel@lists.libcamera.org","Date":"Fri,  6 Nov 2020 19:36:50 +0900","Message-Id":"<20201106103707.49660-21-paul.elder@ideasonboard.com>","X-Mailer":"git-send-email 2.27.0","In-Reply-To":"<20201106103707.49660-1-paul.elder@ideasonboard.com>","References":"<20201106103707.49660-1-paul.elder@ideasonboard.com>","MIME-Version":"1.0","Subject":"[libcamera-devel] [PATCH v4 20/37] libcamera: IPAInterface: remove\n\tipa_context and functions from documentation","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"<libcamera-devel.lists.libcamera.org>","List-Unsubscribe":"<https://lists.libcamera.org/options/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=unsubscribe>","List-Archive":"<https://lists.libcamera.org/pipermail/libcamera-devel/>","List-Post":"<mailto:libcamera-devel@lists.libcamera.org>","List-Help":"<mailto:libcamera-devel-request@lists.libcamera.org?subject=help>","List-Subscribe":"<https://lists.libcamera.org/listinfo/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=subscribe>","Content-Type":"text/plain; charset=\"us-ascii\"","Content-Transfer-Encoding":"7bit","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" <libcamera-devel-bounces@lists.libcamera.org>"},"content":"Remove all the documentation related to ipa_context and the C IPA API,\nas well as the documentation about the functions in the IPAInterface.\n\nSigned-off-by: Paul Elder <paul.elder@ideasonboard.com>\n\n---\nNo change in v4\n\nNo change in v3\n\nNew in v2\n---\n src/libcamera/ipa_interface.cpp | 517 +++-----------------------------\n 1 file changed, 34 insertions(+), 483 deletions(-)","diff":"diff --git a/src/libcamera/ipa_interface.cpp b/src/libcamera/ipa_interface.cpp\nindex 23fc56d7..d989c75d 100644\n--- a/src/libcamera/ipa_interface.cpp\n+++ b/src/libcamera/ipa_interface.cpp\n@@ -15,371 +15,52 @@\n  * an Image Processing Algorithm (IPA) module. An IPA module is developed for a\n  * specific pipeline handler and each pipeline handler may be compatible with\n  * multiple IPA implementations, both open and closed source. To support this,\n- * libcamera communicates with IPA modules through a standard plain C interface.\n+ * libcamera communicates with IPA modules through a customizable C++ interface.\n  *\n  * IPA modules shall expose a public function named ipaCreate() with the\n  * following prototype.\n  *\n  * \\code{.c}\n- * struct ipa_context *ipaCreate();\n+ * IPAInterface *ipaCreate();\n  * \\endcode\n  *\n- * The ipaCreate() function creates an instance of an IPA context, which models\n+ * The ipaCreate() function creates an instance of an IPA interface, which models\n  * a context of execution for the IPA. IPA modules shall support creating one\n  * context per camera, as required by their associated pipeline handler.\n  *\n- * The IPA module context operations are defined in the struct ipa_context_ops.\n- * They model a low-level interface to configure the IPA, notify it of events,\n- * and receive IPA actions through callbacks. An IPA module stores a pointer to\n- * the operations corresponding to its context in the ipa_context::ops field.\n- * That pointer is immutable for the lifetime of the context, and may differ\n- * between different contexts created by the same IPA module.\n+ * The IPA module interface operations are defined in the mojom file\n+ * corresponding to the pipeline handler, in\n+ * include/libcamera/ipa/{pipeline_name}.mojom. These interface operations and\n+ * their parameters are completely customizable, and are meant to be written\n+ * by the pipeline author.\n  *\n  * The IPA interface defines base data types and functions to exchange data. On\n  * top of this, each pipeline handler is responsible for defining the set of\n  * events and actions used to communicate with their IPA. These are collectively\n  * referred to as IPA operations and define the pipeline handler-specific IPA\n  * protocol. Each operation defines the data that it carries, and how that data\n- * is encoded in the ipa_context_ops functions arguments.\n+ * is encoded in the mojom file.\n  *\n  * \\todo Add reference to how pipelines shall document their protocol.\n  *\n  * IPAs can be isolated in a separate process. This implies that arguments to\n- * the IPA interface functions may need to be transferred over IPC. All\n- * arguments use Plain Old Data types and are documented either in the form of C\n- * data types, or as a textual description of byte arrays for types that can't\n- * be expressed using C data types (such as arrays of mixed data types). IPA\n- * modules can thus use the C API without calling into libcamera to access the\n- * data passed to the IPA context operations.\n+ * the IPA interface functions may need to be transferred over IPC. An IPA\n+ * proxy is auto-generated based on the mojom file, which abstracts away the\n+ * de/serialization from the pipeline handler and the IPA implementation. Thus\n+ * any C++ struct that is defined in the mojom file, or the C++ libcamera\n+ * objects that are mentioned in core.mojom, can be used directly.\n  *\n  * Due to IPC, synchronous communication between pipeline handlers and IPAs can\n- * be costly. For that reason, the interface operates asynchronously. This\n- * implies that methods don't return a status, and that all methods may copy\n- * their arguments.\n+ * be costly. For that reason, functions that cannot afford the high cost\n+ * should be marked as [async] in the mojom file, and they will operate\n+ * asynchronously. This implies that these methods don't return a status, and\n+ * that all methods may copy their arguments. Synchronous functions are still\n+ * allowed, but should be used with caution.\n  *\n- * The IPAInterface class is a C++ representation of the ipa_context_ops, using\n- * C++ data classes provided by libcamera. This is the API exposed to pipeline\n- * handlers to communicate with IPA modules. IPA modules may use the\n- * IPAInterface API internally if they want to benefit from the data and helper\n- * classes offered by libcamera.\n- *\n- * When an IPA module is loaded directly into the libcamera process and uses\n- * the IPAInterface API internally, short-circuiting the path to the\n- * ipa_context_ops and back to IPAInterface is desirable. To support this, IPA\n- * modules may implement the ipa_context_ops::get_interface function to return a\n- * pointer to their internal IPAInterface.\n- */\n-\n-/**\n- * \\struct ipa_context\n- * \\brief IPA module context of execution\n- *\n- * This structure models a context of execution for an IPA module. It is\n- * instantiated by the IPA module ipaCreate() function. IPA modules allocate\n- * context instances in an implementation-defined way, contexts shall thus be\n- * destroyed using the ipa_operation::destroy function only.\n- *\n- * The ipa_context structure provides a pointer to the IPA context operations.\n- * It shall otherwise be treated as a constant black-box cookie and passed\n- * unmodified to the functions defined in struct ipa_context_ops.\n- *\n- * IPA modules are expected to extend struct ipa_context by inheriting from it,\n- * either through structure embedding to model inheritance in plain C, or\n- * through C++ class inheritance. A simple example of the latter is available\n- * in the IPAContextWrapper class implementation.\n- *\n- * \\var ipa_context::ops\n- * \\brief The IPA context operations\n- */\n-\n-/**\n- * \\struct ipa_settings\n- * \\brief IPA initialization settings for the IPA context operations\n- * \\sa IPASettings\n- *\n- * \\var ipa_settings::configuration_file\n- * \\brief The name of the IPA configuration file (may be null or point to an\n- * empty string)\n- */\n-\n-/**\n- * \\struct ipa_sensor_info\n- * \\brief Camera sensor information for the IPA context operations\n- * \\sa libcamera::CameraSensorInfo\n- *\n- * \\var ipa_sensor_info::model\n- * \\brief The camera sensor model name\n- * \\todo Remove this field as soon as no IPA depends on it anymore\n- *\n- * \\var ipa_sensor_info::bits_per_pixel\n- * \\brief The camera sensor image format bit depth\n- * \\sa libcamera::CameraSensorInfo::bitsPerPixel\n- *\n- * \\var ipa_sensor_info::active_area.width\n- * \\brief The camera sensor pixel array active area width\n- * \\sa libcamera::CameraSensorInfo::activeAreaSize\n- *\n- * \\var ipa_sensor_info::active_area.height\n- * \\brief The camera sensor pixel array active area height\n- * \\sa libcamera::CameraSensorInfo::activeAreaSize\n- *\n- * \\var ipa_sensor_info::active_area\n- * \\brief The camera sensor pixel array active size\n- * \\sa libcamera::CameraSensorInfo::activeAreaSize\n- *\n- * \\var ipa_sensor_info::analog_crop.left\n- * \\brief The left coordinate of the analog crop rectangle, relative to the\n- * pixel array active area\n- * \\sa libcamera::CameraSensorInfo::analogCrop\n- *\n- * \\var ipa_sensor_info::analog_crop.top\n- * \\brief The top coordinate of the analog crop rectangle, relative to the pixel\n- * array active area\n- * \\sa libcamera::CameraSensorInfo::analogCrop\n- *\n- * \\var ipa_sensor_info::analog_crop.width\n- * \\brief The horizontal size of the analog crop rectangle\n- * \\sa libcamera::CameraSensorInfo::analogCrop\n- *\n- * \\var ipa_sensor_info::analog_crop.height\n- * \\brief The vertical size of the analog crop rectangle\n- * \\sa libcamera::CameraSensorInfo::analogCrop\n- *\n- * \\var ipa_sensor_info::analog_crop\n- * \\brief The analog crop rectangle\n- * \\sa libcamera::CameraSensorInfo::analogCrop\n- *\n- * \\var ipa_sensor_info::output_size.width\n- * \\brief The horizontal size of the output image\n- * \\sa libcamera::CameraSensorInfo::outputSize\n- *\n- * \\var ipa_sensor_info::output_size.height\n- * \\brief The vertical size of the output image\n- * \\sa libcamera::CameraSensorInfo::outputSize\n- *\n- * \\var ipa_sensor_info::output_size\n- * \\brief The size of the output image\n- * \\sa libcamera::CameraSensorInfo::outputSize\n- *\n- * \\var ipa_sensor_info::pixel_rate\n- * \\brief The number of pixel produced in a second\n- * \\sa libcamera::CameraSensorInfo::pixelRate\n- *\n- * \\var ipa_sensor_info::line_length\n- * \\brief The full line length, including blanking, in pixel units\n- * \\sa libcamera::CameraSensorInfo::lineLength\n- */\n-\n-/**\n- * \\struct ipa_stream\n- * \\brief Stream information for the IPA context operations\n- *\n- * \\var ipa_stream::id\n- * \\brief Identifier for the stream, defined by the IPA protocol\n- *\n- * \\var ipa_stream::pixel_format\n- * \\brief The stream pixel format, as defined by the PixelFormat class\n- *\n- * \\var ipa_stream::width\n- * \\brief The stream width in pixels\n- *\n- * \\var ipa_stream::height\n- * \\brief The stream height in pixels\n- */\n-\n-/**\n- * \\struct ipa_control_info_map\n- * \\brief ControlInfoMap description for the IPA context operations\n- *\n- * \\var ipa_control_info_map::id\n- * \\brief Identifier for the ControlInfoMap, defined by the IPA protocol\n- *\n- * \\var ipa_control_info_map::data\n- * \\brief Pointer to a control packet for the ControlInfoMap\n- * \\sa ipa_controls.h\n- *\n- * \\var ipa_control_info_map::size\n- * \\brief The size of the control packet in bytes\n- */\n-\n-/**\n- * \\struct ipa_buffer_plane\n- * \\brief A plane for an ipa_buffer\n- *\n- * \\var ipa_buffer_plane::dmabuf\n- * \\brief The dmabuf file descriptor for the plane (-1 for unused planes)\n- *\n- * \\var ipa_buffer_plane::length\n- * \\brief The plane length in bytes (0 for unused planes)\n- */\n-\n-/**\n- * \\struct ipa_buffer\n- * \\brief Buffer information for the IPA context operations\n- *\n- * \\var ipa_buffer::id\n- * \\brief The buffer unique ID (see \\ref libcamera::IPABuffer::id)\n- *\n- * \\var ipa_buffer::num_planes\n- * \\brief The number of used planes in the ipa_buffer::planes array\n- *\n- * \\var ipa_buffer::planes\n- * \\brief The buffer planes (up to 3)\n- */\n-\n-/**\n- * \\struct ipa_control_list\n- * \\brief ControlList description for the IPA context operations\n- *\n- * \\var ipa_control_list::data\n- * \\brief Pointer to a control packet for the ControlList\n- * \\sa ipa_controls.h\n- *\n- * \\var ipa_control_list::size\n- * \\brief The size of the control packet in bytes\n- */\n-\n-/**\n- * \\struct ipa_operation_data\n- * \\brief IPA operation data for the IPA context operations\n- * \\sa libcamera::IPAOperationData\n- *\n- * \\var ipa_operation_data::operation\n- * \\brief IPA protocol operation\n- *\n- * \\var ipa_operation_data::data\n- * \\brief Pointer to the operation data array\n- *\n- * \\var ipa_operation_data::num_data\n- * \\brief Number of entries in the ipa_operation_data::data array\n- *\n- * \\var ipa_operation_data::lists\n- * \\brief Pointer to an array of ipa_control_list\n- *\n- * \\var ipa_operation_data::num_lists\n- * \\brief Number of entries in the ipa_control_list array\n- */\n-\n-/**\n- * \\struct ipa_callback_ops\n- * \\brief IPA context operations as a set of function pointers\n- */\n-\n-/**\n- * \\var ipa_callback_ops::queue_frame_action\n- * \\brief Queue an action associated with a frame to the pipeline handler\n- * \\param[in] cb_ctx The callback context registered with\n- * ipa_context_ops::register_callbacks\n- * \\param[in] frame The frame number\n- *\n- * \\sa libcamera::IPAInterface::queueFrameAction\n- */\n-\n-/**\n- * \\struct ipa_context_ops\n- * \\brief IPA context operations as a set of function pointers\n- *\n- * To allow for isolation of IPA modules in separate processes, the functions\n- * defined in the ipa_context_ops structure return only data related to the\n- * libcamera side of the operations. In particular, error related to the\n- * libcamera side of the IPC may be returned. Data returned by the IPA,\n- * including status information, shall be provided through callbacks from the\n- * IPA to libcamera.\n- */\n-\n-/**\n- * \\var ipa_context_ops::destroy\n- * \\brief Destroy the IPA context created by the module's ipaCreate() function\n- * \\param[in] ctx The IPA context\n- */\n-\n-/**\n- * \\var ipa_context_ops::get_interface\n- * \\brief Retrieve the IPAInterface implemented by the ipa_context (optional)\n- * \\param[in] ctx The IPA context\n- *\n- * IPA modules may implement this function to expose their internal\n- * IPAInterface, if any. When implemented, libcamera may at its sole discretion\n- * call it and then bypass the ipa_context_ops API by calling the IPAInterface\n- * methods directly. IPA modules shall still implement and support the full\n- * ipa_context_ops API.\n- */\n-\n-/**\n- * \\var ipa_context_ops::init\n- * \\brief Initialise the IPA context\n- * \\param[in] ctx The IPA context\n- * \\param[in] settings The IPA initialization settings\n- *\n- * \\sa libcamera::IPAInterface::init()\n- */\n-\n-/**\n- * \\var ipa_context_ops::start\n- * \\brief Start the IPA context\n- *\n- * \\sa libcamera::IPAInterface::start()\n- */\n-\n-/**\n- * \\var ipa_context_ops::stop\n- * \\brief Stop the IPA context\n- *\n- * \\sa libcamera::IPAInterface::stop()\n- */\n-\n-/**\n- * \\var ipa_context_ops::register_callbacks\n- * \\brief Register callback operation from the IPA to the pipeline handler\n- * \\param[in] ctx The IPA context\n- * \\param[in] callback The IPA callback operations\n- * \\param[in] cb_ctx The callback context, passed to all callback operations\n- */\n-\n-/**\n- * \\var ipa_context_ops::configure\n- * \\brief Configure the IPA stream and sensor settings\n- * \\param[in] ctx The IPA context\n- * \\param[in] sensor_info Camera sensor information\n- * \\param[in] streams Configuration of all active streams\n- * \\param[in] num_streams The number of entries in the \\a streams array\n- * \\param[in] maps Controls provided by the pipeline entities\n- * \\param[in] num_maps The number of entries in the \\a maps array\n- *\n- * \\sa libcamera::IPAInterface::configure()\n- */\n-\n-/**\n- * \\var ipa_context_ops::map_buffers\n- * \\brief Map buffers shared between the pipeline handler and the IPA\n- * \\param[in] ctx The IPA context\n- * \\param[in] buffers The buffers to map\n- * \\param[in] num_buffers The number of entries in the \\a buffers array\n- *\n- * The dmabuf file descriptors provided in \\a buffers are borrowed from the\n- * caller and are only guaranteed to be valid during the map_buffers() call.\n- * Should the callee need to store a copy of the file descriptors, it shall\n- * duplicate them first with ::%dup().\n- *\n- * \\sa libcamera::IPAInterface::mapBuffers()\n- */\n-\n-/**\n- * \\var ipa_context_ops::unmap_buffers\n- * \\brief Unmap buffers shared by the pipeline to the IPA\n- * \\param[in] ctx The IPA context\n- * \\param[in] ids The IDs of the buffers to unmap\n- * \\param[in] num_buffers The number of entries in the \\a ids array\n- *\n- * \\sa libcamera::IPAInterface::unmapBuffers()\n- */\n-\n-/**\n- * \\var ipa_context_ops::process_event\n- * \\brief Process an event from the pipeline handler\n- * \\param[in] ctx The IPA context\n- *\n- * \\sa libcamera::IPAInterface::processEvent()\n+ * The IPA interface, as defined in the respective mojom file, is the API\n+ * exposed to pipeline handlers to communicate with IPA modules. IPA modules\n+ * may use the IPAInterface API internally if they want to benefit from the\n+ * data and helper classes offered by libcamera.\n  */\n \n /**\n@@ -387,9 +68,10 @@\n  * \\brief Entry point to the IPA modules\n  *\n  * This function is the entry point to the IPA modules. It is implemented by\n- * every IPA module, and called by libcamera to create a new IPA context.\n+ * every IPA module, and called by libcamera to create a new IPA interface\n+ * instance.\n  *\n- * \\return A newly created IPA context\n+ * \\return A newly created IPA interface instance\n  */\n \n namespace libcamera {\n@@ -499,157 +181,26 @@ namespace libcamera {\n  * \\class IPAInterface\n  * \\brief C++ Interface for IPA implementation\n  *\n- * This pure virtual class defines a C++ API corresponding to the ipa_context,\n- * ipa_context_ops and ipa_callback_ops API. It is used by pipeline handlers to\n+ * This pure virtual class defines a skeletal C++ API for IPA modules.\n+ * Specializations of this class must be defined in a mojom file in\n+ * include/libcamera/ipa/ (see include/libcamera/ipa/core.mojom for details\n+ * on how to do so). The specialized class is used by pipeline handlers to\n  * interact with IPA modules, and may be used internally in IPA modules if\n  * desired to benefit from the data and helper classes provided by libcamera.\n  *\n- * Functions defined in the ipa_context_ops structure are mapped to IPAInterface\n- * methods, while functions defined in the ipa_callback_ops are mapped to\n- * IPAInterface signals. As with the C API, the IPA C++ interface uses\n- * serializable data types only. It reuses structures defined by the C API, or\n- * defines corresponding classes using C++ containers when required.\n- *\n  * Due to process isolation all arguments to the IPAInterface methods and\n  * signals may need to be transferred over IPC. The class thus uses serializable\n  * data types only. The IPA C++ interface defines custom data structures that\n  * mirror core libcamera structures when the latter are not suitable, such as\n  * IPAStream to carry StreamConfiguration data.\n  *\n- * As for the functions defined in struct ipa_context_ops, the methods defined\n- * by this class shall not return data from the IPA.\n+ * Custom data structures may also be defined in the mojom file, in which case\n+ * the de/serialization will automatically be generated. If any other libcamera\n+ * structures are to be used as parameters, then a de/serializer for them must\n+ * be implemented in IPADataSerializer.\n  *\n  * The pipeline handler shall use the IPAManager to locate a compatible\n  * IPAInterface. The interface may then be used to interact with the IPA module.\n  */\n \n-/**\n- * \\fn IPAInterface::init()\n- * \\brief Initialise the IPAInterface\n- * \\param[in] settings The IPA initialization settings\n- *\n- * This function initializes the IPA interface. It shall be called before any\n- * other function of the IPAInterface. The \\a settings carry initialization\n- * parameters that are valid for the whole life time of the IPA interface.\n- */\n-\n-/**\n- * \\fn IPAInterface::start()\n- * \\brief Start the IPA\n- *\n- * This method informs the IPA module that the camera is about to be started.\n- * The IPA module shall prepare any resources it needs to operate.\n- *\n- * \\return 0 on success or a negative error code otherwise\n- */\n-\n-/**\n- * \\fn IPAInterface::stop()\n- * \\brief Stop the IPA\n- *\n- * This method informs the IPA module that the camera is stopped. The IPA module\n- * shall release resources prepared in start().\n- */\n-\n-/**\n- * \\fn IPAInterface::configure()\n- * \\brief Configure the IPA stream and sensor settings\n- * \\param[in] sensorInfo Camera sensor information\n- * \\param[in] streamConfig Configuration of all active streams\n- * \\param[in] entityControls Controls provided by the pipeline entities\n- * \\param[in] ipaConfig Pipeline-handler-specific configuration data\n- * \\param[out] result Pipeline-handler-specific configuration result\n- *\n- * This method shall be called when the camera is started to inform the IPA of\n- * the camera's streams and the sensor settings. The meaning of the numerical\n- * keys in the \\a streamConfig and \\a entityControls maps is defined by the IPA\n- * protocol.\n- *\n- * The \\a sensorInfo conveys information about the camera sensor settings that\n- * the pipeline handler has selected for the configuration. The IPA may use\n- * that information to tune its algorithms.\n- *\n- * The \\a ipaConfig and \\a result parameters carry custom data passed by the\n- * pipeline handler to the IPA and back. The pipeline handler may set the \\a\n- * result parameter to null if the IPA protocol doesn't need to pass a result\n- * back through the configure() function.\n- */\n-\n-/**\n- * \\fn IPAInterface::mapBuffers()\n- * \\brief Map buffers shared between the pipeline handler and the IPA\n- * \\param[in] buffers List of buffers to map\n- *\n- * This method informs the IPA module of memory buffers set up by the pipeline\n- * handler that the IPA needs to access. It provides dmabuf file handles for\n- * each buffer, and associates the buffers with unique numerical IDs.\n- *\n- * IPAs shall map the dmabuf file handles to their address space and keep a\n- * cache of the mappings, indexed by the buffer numerical IDs. The IDs are used\n- * in all other IPA interface methods to refer to buffers, including the\n- * unmapBuffers() method.\n- *\n- * All buffers that the pipeline handler wishes to share with an IPA shall be\n- * mapped with this method. Buffers may be mapped all at once with a single\n- * call, or mapped and unmapped dynamically at runtime, depending on the IPA\n- * protocol. Regardless of the protocol, all buffers mapped at a given time\n- * shall have unique numerical IDs.\n- *\n- * The numerical IDs have no meaning defined by the IPA interface, and IPA\n- * protocols shall not give them any specific meaning either. They should be\n- * treated as opaque handles by IPAs, with the only exception that ID zero is\n- * invalid.\n- *\n- * \\sa unmapBuffers()\n- *\n- * \\todo Provide a generic implementation of mapBuffers and unmapBuffers for\n- * IPAs\n- */\n-\n-/**\n- * \\fn IPAInterface::unmapBuffers()\n- * \\brief Unmap buffers shared by the pipeline to the IPA\n- * \\param[in] ids List of buffer IDs to unmap\n- *\n- * This method removes mappings set up with mapBuffers(). Buffers may be\n- * unmapped all at once with a single call, or selectively at runtime, depending\n- * on the IPA protocol. Numerical IDs of unmapped buffers may be reused when\n- * mapping new buffers.\n- *\n- * \\sa mapBuffers()\n- */\n-\n-/**\n- * \\fn IPAInterface::processEvent()\n- * \\brief Process an event from the pipeline handler\n- * \\param[in] data IPA operation data\n- *\n- * This operation is used by pipeline handlers to inform the IPA module of\n- * events that occurred during the on-going capture operation.\n- *\n- * The event notified by the pipeline handler with this method is handled by the\n- * IPA, which interprets the operation parameters according to the separately\n- * documented IPA protocol.\n- */\n-\n-/**\n- * \\var IPAInterface::queueFrameAction\n- * \\brief Queue an action associated with a frame to the pipeline handler\n- * \\param[in] frame The frame number for the action\n- * \\param[in] data IPA operation data\n- *\n- * This signal is emitted when the IPA wishes to queue a FrameAction on the\n- * pipeline. The pipeline is still responsible for the scheduling of the action\n- * on its timeline.\n- *\n- * This signal is emitted by the IPA to queue an action to be executed by the\n- * pipeline handler on a frame. The type of action is identified by the\n- * \\a data.operation field, as defined by the IPA protocol, and the rest of the\n- * \\a data is interpreted accordingly. The pipeline handler shall queue the\n- * action and execute it as appropriate.\n- *\n- * The signal is only emitted when the IPA is running, that is after start() and\n- * before stop() have been called.\n- */\n-\n } /* namespace libcamera */\n","prefixes":["libcamera-devel","v4","20/37"]}