From patchwork Fri Oct 22 15:12:02 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: 14269 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 DAA35BF415 for ; Fri, 22 Oct 2021 15:12:32 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 96FFF68F78; Fri, 22 Oct 2021 17:12:29 +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="VNNp0AS4"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [213.167.242.64]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 4A2CF68F59 for ; Fri, 22 Oct 2021 17:12:23 +0200 (CEST) Received: from tatooine.ideasonboard.com (unknown [IPv6:2a01:e0a:169:7140:22cc:3af6:5ccb:8367]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 0FE4351D; Fri, 22 Oct 2021 17:12:23 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1634915543; bh=pNgbVFKKknOgR3FSFlOW42jzqNL66l/hekBY7m/7azQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=VNNp0AS4MQBTUFblzSv80twlExaBc8wJEkmenLuCobkDe7O80tLxoDR1XiaO2vROU 9Y7HKwgHE3hauIxG8GfgcORRHoX1k4UADHPW/1k1z+GpWFKdbr19ZwLTsxyLr2++gZ 3lpjthFVgVRKpLuZf9Jr4oSJX5gcgxJ88EZ8KtG0= From: Jean-Michel Hautbois To: libcamera-devel@lists.libcamera.org Date: Fri, 22 Oct 2021 17:12:02 +0200 Message-Id: <20211022151218.111966-4-jeanmichel.hautbois@ideasonboard.com> X-Mailer: git-send-email 2.32.0 In-Reply-To: <20211022151218.111966-1-jeanmichel.hautbois@ideasonboard.com> References: <20211022151218.111966-1-jeanmichel.hautbois@ideasonboard.com> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH v3 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 --- src/ipa/ipu3/ipu3.cpp | 83 +++++++++++++++++++++++++++++++++++++------ 1 file changed, 73 insertions(+), 10 deletions(-) diff --git a/src/ipa/ipu3/ipu3.cpp b/src/ipa/ipu3/ipu3.cpp index 6e28a5aa..c5461d8e 100644 --- a/src/ipa/ipu3/ipu3.cpp +++ b/src/ipa/ipu3/ipu3.cpp @@ -301,9 +301,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) @@ -332,9 +332,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 @@ -395,7 +395,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 @@ -426,8 +426,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; @@ -581,6 +588,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) { @@ -590,6 +601,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) { @@ -601,6 +616,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) { @@ -642,12 +661,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) { /* @@ -670,6 +703,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) @@ -693,6 +736,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; @@ -711,10 +761,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, @@ -723,6 +778,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();