From patchwork Thu Sep 30 09:54:58 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: 13999 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 9EFB1C3243 for ; Thu, 30 Sep 2021 09:55:26 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 1A261691AC; Thu, 30 Sep 2021 11:55:24 +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="SehyQ1Nw"; 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 EE5DD69189 for ; Thu, 30 Sep 2021 11:55:17 +0200 (CEST) Received: from tatooine.ideasonboard.com (unknown [IPv6:2a01:e0a:169:7140:bab4:22c5:662d:e478]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 9B9E92A8; Thu, 30 Sep 2021 11:55:17 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1632995717; bh=yOsB8XT62JX49W8dhh3QMzEYUCAFAnIt6NiUF1eqDns=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=SehyQ1Nwc31LLrYFBAlhr6tPdfrAPoL5P52BMmX7ABtUnNmjIHehnO00lEpfyeBgI VohZIfDIGRcxpv+6dJPJn2JrtnCxWVP9PGMcsq8ra6TW+h93KgoUYersJz4KGlBGJu 8K7WEoHIO5ZYcTpmWw3NUNT/JQk78ybZVuJVPYwU= From: Jean-Michel Hautbois To: libcamera-devel@lists.libcamera.org Date: Thu, 30 Sep 2021 11:54:58 +0200 Message-Id: <20210930095513.76213-4-jeanmichel.hautbois@ideasonboard.com> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20210930095513.76213-1-jeanmichel.hautbois@ideasonboard.com> References: <20210930095513.76213-1-jeanmichel.hautbois@ideasonboard.com> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH 03/18] 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 b4c889f1..147b40ab 100644 --- a/src/ipa/ipu3/ipu3.cpp +++ b/src/ipa/ipu3/ipu3.cpp @@ -274,7 +274,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 @@ -350,8 +350,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; @@ -491,6 +498,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) { @@ -500,6 +511,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) { @@ -511,6 +526,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) { @@ -552,12 +571,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) { /* @@ -580,6 +613,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) @@ -607,6 +650,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; @@ -625,10 +675,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, @@ -637,6 +692,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();