From patchwork Tue Oct 26 09:55:18 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jean-Michel Hautbois X-Patchwork-Id: 14314 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 95F14BDB1C for ; Tue, 26 Oct 2021 09:55:53 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 53BAC6487C; Tue, 26 Oct 2021 11:55:51 +0200 (CEST) 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="EiuzhUyq"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 0C67764878 for ; Tue, 26 Oct 2021 11:55:45 +0200 (CEST) Received: from tatooine.ideasonboard.com (unknown [IPv6:2a01:e0a:169:7140:dce3:eb54:18d7:6f3d]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id BB35D3F0; Tue, 26 Oct 2021 11:55:44 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1635242144; bh=DxJ5Yo4Uw6l/zUlCftN9xwt2kYJ68GXJScJGBUT4QEY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=EiuzhUyqyluBpyaLO4vTLLxQ1HEXLUawJEcKjiVdmXm+xW6OBlxHMZZ3KhIgPSfr5 3ejo1RCz4ZobgEFh7grTsl2xdLhql5tAGNNgQB507icMSk7lz2BNW/Fxx1LCGo9JMf DHeOKnABi7q21M2upjcyYzNBESaB2xzxObDxJGh4= From: Jean-Michel Hautbois To: libcamera-devel@lists.libcamera.org Date: Tue, 26 Oct 2021 11:55:18 +0200 Message-Id: <20211026095534.90348-4-jeanmichel.hautbois@ideasonboard.com> X-Mailer: git-send-email 2.32.0 In-Reply-To: <20211026095534.90348-1-jeanmichel.hautbois@ideasonboard.com> References: <20211026095534.90348-1-jeanmichel.hautbois@ideasonboard.com> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH v4 03/19] ipa: ipu3: Document the IPAIPU3 class 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" Clarify the roles and interactions between the pipeline handler events and the algorithm calls by documenting all the remaining functions of the class. Signed-off-by: Jean-Michel Hautbois Signed-off-by: Kieran Bingham Reviewed-by: Laurent Pinchart Reviewed-by: Kieran Bingham Reviewed-by: Umang Jain --- src/ipa/ipu3/ipu3.cpp | 87 +++++++++++++++++++++++++++++++++++++------ 1 file changed, 76 insertions(+), 11 deletions(-) diff --git a/src/ipa/ipu3/ipu3.cpp b/src/ipa/ipu3/ipu3.cpp index 1f501821..177b67b0 100644 --- a/src/ipa/ipu3/ipu3.cpp +++ b/src/ipa/ipu3/ipu3.cpp @@ -305,9 +305,9 @@ private: struct IPAContext context_; }; -/* - * Compute IPASessionConfiguration using the sensor information and the sensor - * v4l2 controls. +/** + * \brief Compute IPASessionConfiguration using the sensor information and the + * sensor V4L2 controls */ void IPAIPU3::updateSessionConfiguration(const IPACameraSensorInfo &sensorInfo, const ControlInfoMap &sensorControls) @@ -336,9 +336,9 @@ void IPAIPU3::updateSessionConfiguration(const IPACameraSensorInfo &sensorInfo, context_.configuration.agc.maxAnalogueGain = camHelper_->gain(maxGain); } -/* - * Compute camera controls using the sensor information and the sensor - * v4l2 controls. +/** + * \brief Compute camera controls using the sensor information and the sensor + * V4L2 controls * * Some of the camera controls are computed by the pipeline handler, some others * by the IPA module which is in charge of handling, for example, the exposure @@ -399,7 +399,7 @@ void IPAIPU3::updateControls(const IPACameraSensorInfo &sensorInfo, } /** - * Initialize the IPA module and its controls. + * \brief Initialize the IPA module and its controls * * This function receives the camera sensor information from the pipeline * handler, computes the limits of the controls it handles and returns @@ -430,8 +430,15 @@ int IPAIPU3::init(const IPASettings &settings, return 0; } +/** + * \brief Perform any processing required before the first frame + */ int IPAIPU3::start() { + /* + * Set the sensors V4L2 controls before the first frame to ensure that + * we have an expected and known configuration from the start. + */ setControls(0); return 0; @@ -512,7 +519,7 @@ void IPAIPU3::calculateBdsGrid(const Size &bdsOutputSize) * handler * \param[in] ipaControls The IPA controls to update * - * Calculate the best grid for the statistics based on the Pipeline Handler BDS + * Calculate the best grid for the statistics based on the pipeline handler BDS * output, and parse the minimum and maximum exposure and analogue gain control * values. * @@ -585,6 +592,10 @@ int IPAIPU3::configure(const IPAConfigInfo &configInfo, return 0; } +/** + * \brief Map the parameters and stats buffers allocated in the pipeline handler + * \param[in] buffers The buffers to map + */ void IPAIPU3::mapBuffers(const std::vector &buffers) { for (const IPABuffer &buffer : buffers) { @@ -594,6 +605,10 @@ void IPAIPU3::mapBuffers(const std::vector &buffers) } } +/** + * \brief Unmap the parameters and stats buffers + * \param[in] ids The IDs of the buffers to unmap + */ void IPAIPU3::unmapBuffers(const std::vector &ids) { for (unsigned int id : ids) { @@ -605,6 +620,10 @@ void IPAIPU3::unmapBuffers(const std::vector &ids) } } +/** + * \brief Process an event generated by the pipeline handler + * \param[in] event The event sent from pipeline handler + */ void IPAIPU3::processEvent(const IPU3Event &event) { switch (event.op) { @@ -646,12 +665,28 @@ void IPAIPU3::processEvent(const IPU3Event &event) } } +/** + * \brief Process a control list for a request from the application + * \param[in] frame The number of the frame which will be processed next + * \param[in] controls The controls for the \a frame + * + * Parse the request to handle any IPA-managed controls that were set from the + * application such as manual sensor settings. + */ void IPAIPU3::processControls([[maybe_unused]] unsigned int frame, [[maybe_unused]] const ControlList &controls) { /* \todo Start processing for 'frame' based on 'controls'. */ } +/** + * \brief Fill the ImgU parameter buffer for the next frame + * \param[in] frame The number of the latest frame processed + * \param[out] params The parameter buffer to fill + * + * Algorithms are expected to fill the IPU3 parameter buffer for the next + * frame given their most recent processing of the ImgU statistics. + */ void IPAIPU3::fillParams(unsigned int frame, ipu3_uapi_params *params) { /* @@ -674,6 +709,16 @@ void IPAIPU3::fillParams(unsigned int frame, ipu3_uapi_params *params) queueFrameAction.emit(frame, op); } +/** + * \brief Process the statistics generated by the ImgU + * \param[in] frame The number of the latest frame processed + * \param[in] frameTimestamp The current frame timestamp + * \param[in] stats The IPU3 statistics and ISP results + * + * Parse the most recently processed image statistics from the ImgU. The + * statistics are passed to each algorithm module to run their calculations and + * update their state accordingly. + */ void IPAIPU3::parseStatistics(unsigned int frame, [[maybe_unused]] int64_t frameTimestamp, [[maybe_unused]] const ipu3_uapi_stats_3a *stats) @@ -697,6 +742,13 @@ void IPAIPU3::parseStatistics(unsigned int frame, queueFrameAction.emit(frame, op); } +/** + * \brief Handle sensor controls for a given \a frame number + * \param[in] frame The frame on which the sensor controls should be set + * + * Send the desired sensor control values to the pipeline handler to request + * that they are applied on the camera sensor. + */ void IPAIPU3::setControls(unsigned int frame) { IPU3Action op; @@ -715,10 +767,15 @@ void IPAIPU3::setControls(unsigned int frame) } /* namespace ipa::ipu3 */ -/* - * External IPA module interface +/** + * \brief External IPA module interface + * + * The IPAModuleInfo is required to match an IPA module construction against the + * intented pipeline handler with the module. The API and pipeline handler + * versions must match the corresponding IPA interface and pipeline handler. + * + * \sa struct IPAModuleInfo */ - extern "C" { const struct IPAModuleInfo ipaModuleInfo = { IPA_MODULE_API_VERSION, @@ -727,6 +784,14 @@ const struct IPAModuleInfo ipaModuleInfo = { "ipu3", }; +/** + * \brief Create an instance of the IPA interface + * + * This function is the entry point of the IPA module. It is called by the IPA + * manager to create an instance of the IPA interface for each camera. When + * matched against with a pipeline handler, the IPAManager will construct an IPA + * instance for each associated Camera. + */ IPAInterface *ipaCreate() { return new ipa::ipu3::IPAIPU3();