From patchwork Mon Sep 13 14:58:03 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: 13832 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 BA8FFBDB1D for ; Mon, 13 Sep 2021 14:58:21 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 4119A6919F; Mon, 13 Sep 2021 16:58:19 +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="rmPeNcXo"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [213.167.242.64]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id C68706024C for ; Mon, 13 Sep 2021 16:58:14 +0200 (CEST) Received: from tatooine.ideasonboard.com (unknown [IPv6:2a01:e0a:169:7140:edc5:688b:2ede:8b4b]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 7C259510; Mon, 13 Sep 2021 16:58:14 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1631545094; bh=VxYWF6HJHNZTL376kV1ThaRo0SvqX+/qsp0LUYzhs7g=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=rmPeNcXo1ZY0WRMt/JQOwIPQKjbxNO4VWoKyjiqdeqDaAXysQ7u24q2MA0uFgOQ6L FrCwEMgIeTLAAKTIi1HQbj1ufmJRH5yz4vNC3sc8j26DZEUh/NiUqRPFUYLUq3JLqs tAfieUmWsfdpw1Jd4zY4eesff/nur1XukiGaApik= From: Jean-Michel Hautbois To: libcamera-devel@lists.libcamera.org Date: Mon, 13 Sep 2021 16:58:03 +0200 Message-Id: <20210913145810.66515-5-jeanmichel.hautbois@ideasonboard.com> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20210913145810.66515-1-jeanmichel.hautbois@ideasonboard.com> References: <20210913145810.66515-1-jeanmichel.hautbois@ideasonboard.com> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH 04/11] 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 --- src/ipa/ipu3/ipu3.cpp | 65 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 62 insertions(+), 3 deletions(-) diff --git a/src/ipa/ipu3/ipu3.cpp b/src/ipa/ipu3/ipu3.cpp index c0004ea6..df64b0f1 100644 --- a/src/ipa/ipu3/ipu3.cpp +++ b/src/ipa/ipu3/ipu3.cpp @@ -262,7 +262,7 @@ private: }; /** - * 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 @@ -337,8 +337,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; @@ -474,6 +481,10 @@ int IPAIPU3::configure(const IPAConfigInfo &configInfo) return 0; } +/** + * \brief Map the parameters and stats buffers allocated in the Pipeline Handler + * \param[out] buffers A vector with param and stat buffers + */ void IPAIPU3::mapBuffers(const std::vector &buffers) { for (const IPABuffer &buffer : buffers) { @@ -483,6 +494,10 @@ void IPAIPU3::mapBuffers(const std::vector &buffers) } } +/** + * \brief Unmap the parameters and stats buffers + * \param[in] ids A list of buffer ids + */ void IPAIPU3::unmapBuffers(const std::vector &ids) { for (unsigned int id : ids) { @@ -494,6 +509,10 @@ void IPAIPU3::unmapBuffers(const std::vector &ids) } } +/** + * \brief Process events generated by the Pipeline Handler + * \param[in] event An event sent from Pipeline Handler + */ void IPAIPU3::processEvent(const IPU3Event &event) { switch (event.op) { @@ -535,12 +554,26 @@ void IPAIPU3::processEvent(const IPU3Event &event) } } +/** + * \brief Process a control list for a request from the application + * + * 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 current frame number + * \param[inout] params the parameter buffer to update + * + * 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) { for (auto const &algo : algorithms_) @@ -552,6 +585,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 current frame number + * \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) @@ -579,6 +622,13 @@ void IPAIPU3::parseStatistics(unsigned int frame, queueFrameAction.emit(frame, op); } +/** + * \brief Handle V4L2 controls for a given \a frame number + * \param[in] frame The frame on which the V4L2 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; @@ -597,10 +647,15 @@ void IPAIPU3::setControls(unsigned int frame) } /* namespace ipa::ipu3 */ -/* +/** * 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, @@ -609,6 +664,10 @@ const struct IPAModuleInfo ipaModuleInfo = { "ipu3", }; +/** + * 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();