[{"id":19653,"web_url":"https://patchwork.libcamera.org/comment/19653/","msgid":"","date":"2021-09-14T03:37:31","subject":"Re: [libcamera-devel] [PATCH 04/11] ipa: ipu3: Document the IPAIPU3\n\tclass","submitter":{"id":2,"url":"https://patchwork.libcamera.org/api/people/2/","name":"Laurent Pinchart","email":"laurent.pinchart@ideasonboard.com"},"content":"Hi Jean-Michel,\n\nThank you for the patch.\n\nOn Mon, Sep 13, 2021 at 04:58:03PM +0200, Jean-Michel Hautbois wrote:\n> Clarify the roles and interactions between the pipeline handler events\n> and the algorithm calls by documenting all the remaining functions of\n> the class.\n> \n> Signed-off-by: Jean-Michel Hautbois \n> Signed-off-by: Kieran Bingham \n> ---\n> src/ipa/ipu3/ipu3.cpp | 65 +++++++++++++++++++++++++++++++++++++++++--\n> 1 file changed, 62 insertions(+), 3 deletions(-)\n> \n> diff --git a/src/ipa/ipu3/ipu3.cpp b/src/ipa/ipu3/ipu3.cpp\n> index c0004ea6..df64b0f1 100644\n> --- a/src/ipa/ipu3/ipu3.cpp\n> +++ b/src/ipa/ipu3/ipu3.cpp\n> @@ -262,7 +262,7 @@ private:\n> };\n> \n> /**\n> - * Initialize the IPA module and its controls.\n> + * \\brief Initialize the IPA module and its controls.\n\ns/.$//\n\nSame below.\n\n> *\n> * This function receives the camera sensor information from the pipeline\n> * handler, computes the limits of the controls it handles and returns\n> @@ -337,8 +337,15 @@ int IPAIPU3::init(const IPASettings &settings,\n> \treturn 0;\n> }\n> \n> +/**\n> + * \\brief Perform any processing required before the first frame.\n> + */\n> int IPAIPU3::start()\n> {\n> +\t/*\n> +\t * Set the sensors V4L2 controls before the first frame to ensure that\n> +\t * we have an expected and known configuration from the start.\n> +\t */\n> \tsetControls(0);\n> \n> \treturn 0;\n> @@ -474,6 +481,10 @@ int IPAIPU3::configure(const IPAConfigInfo &configInfo)\n> \treturn 0;\n> }\n> \n> +/**\n> + * \\brief Map the parameters and stats buffers allocated in the Pipeline Handler\n> + * \\param[out] buffers A vector with param and stat buffers\n\nIsn't it an in param ? I' also write \"The vector containing all the\nbuffers to map\", or just \"The buffers to map\" (I'm not a big fan of\nstating the container type explicitly when it doesn't matter\nparticularly, as Doxygen shows types already).\n\n> + */\n> void IPAIPU3::mapBuffers(const std::vector &buffers)\n> {\n> \tfor (const IPABuffer &buffer : buffers) {\n> @@ -483,6 +494,10 @@ void IPAIPU3::mapBuffers(const std::vector &buffers)\n> \t}\n> }\n> \n> +/**\n> + * \\brief Unmap the parameters and stats buffers\n> + * \\param[in] ids A list of buffer ids\n\n\"The IDs of the buffers to unmap\" ?\n\n> + */\n> void IPAIPU3::unmapBuffers(const std::vector &ids)\n> {\n> \tfor (unsigned int id : ids) {\n> @@ -494,6 +509,10 @@ void IPAIPU3::unmapBuffers(const std::vector &ids)\n> \t}\n> }\n> \n> +/**\n> + * \\brief Process events generated by the Pipeline Handler\n\n\"Process an event\" as the function processes a single event.\n\n> + * \\param[in] event An event sent from Pipeline Handler\n\ns/An/The/\n\n> + */\n> void IPAIPU3::processEvent(const IPU3Event &event)\n> {\n> \tswitch (event.op) {\n> @@ -535,12 +554,26 @@ void IPAIPU3::processEvent(const IPU3Event &event)\n> \t}\n> }\n> \n> +/**\n> + * \\brief Process a control list for a request from the application\n> + *\n> + * Parse the request to handle any IPA managed controls that were set from the\n\ns/IPA managed/IPA-managed/\n\n> + * application such as manual sensor settings.\n> + */\n> void IPAIPU3::processControls([[maybe_unused]] unsigned int frame,\n> \t\t\t [[maybe_unused]] const ControlList &controls)\n> {\n> \t/* \\todo Start processing for 'frame' based on 'controls'. */\n> }\n> \n> +/**\n> + * \\brief Fill the ImgU parameter buffer for the next frame\n> + * \\param[in] frame The current frame number\n\nIs it the current frame number or the next frame number ? We'll probably\nhave to document \"current\" and \"next\" at some point, when we'll match\nper-frame controls with the corresponding frame.\n\n> + * \\param[inout] params the parameter buffer to update\n\ns/the/The/\ns/update/fill/\n\nIsn't it an out parameter ?\n\n> + *\n> + * Algorithms are expected to fill the IPU3 parameter buffer for the next\n> + * frame given their most recent processing of the ImgU statistics.\n> + */\n> void IPAIPU3::fillParams(unsigned int frame, ipu3_uapi_params *params)\n> {\n> \tfor (auto const &algo : algorithms_)\n> @@ -552,6 +585,16 @@ void IPAIPU3::fillParams(unsigned int frame, ipu3_uapi_params *params)\n> \tqueueFrameAction.emit(frame, op);\n> }\n> \n> +/**\n> + * \\brief Process the statistics generated by the ImgU\n> + * \\param[in] frame The current frame number\n> + * \\param[in] frameTimestamp The current frame timestamp\n> + * \\param[in] stats The IPU3 statistics and ISP results\n> + *\n> + * Parse the most recently processed image statistics from the ImgU. The\n> + * statistics are passed to each algorithm module to run their calculations and\n> + * update their state accordingly.\n> + */\n> void IPAIPU3::parseStatistics(unsigned int frame,\n> \t\t\t [[maybe_unused]] int64_t frameTimestamp,\n> \t\t\t [[maybe_unused]] const ipu3_uapi_stats_3a *stats)\n> @@ -579,6 +622,13 @@ void IPAIPU3::parseStatistics(unsigned int frame,\n> \tqueueFrameAction.emit(frame, op);\n> }\n> \n> +/**\n> + * \\brief Handle V4L2 controls for a given \\a frame number\n> + * \\param[in] frame The frame on which the V4L2 controls should be set\n\ns/V4L2/sensor/ in both lines.\n\n> + *\n> + * Send the desired sensor control values to the Pipeline handler to request\n\ns/Pipeline/pipeline/\n\nI would also write \"pipeline handler\" instead of \"Pipeline Handler\"\nabove.\n\n> + * that they are applied on the Camera sensor.\n\ns/Camera/camera/ (we don't need a link to the Camera class here :-))\n\n> + */\n> void IPAIPU3::setControls(unsigned int frame)\n> {\n> \tIPU3Action op;\n> @@ -597,10 +647,15 @@ void IPAIPU3::setControls(unsigned int frame)\n> \n> } /* namespace ipa::ipu3 */\n> \n> -/*\n> +/**\n> * External IPA module interface\n\nMissing \"\\brief\".\n\n> + *\n> + * The IPAModuleInfo is required to match an IPA module construction against the\n> + * intented pipeline handler with the module. The API and Pipeline handler\n\ns/Pipeline/pipeline/\n\n> + * versions must match the corresponding IPA interface and pipeline handler.\n> + *\n> + * \\sa struct IPAModuleInfo\n> */\n> -\n> extern \"C\" {\n> const struct IPAModuleInfo ipaModuleInfo = {\n> \tIPA_MODULE_API_VERSION,\n> @@ -609,6 +664,10 @@ const struct IPAModuleInfo ipaModuleInfo = {\n> \t\"ipu3\",\n> };\n> \n> +/**\n> + * When matched against with a pipeline handler, the IPAManager will construct\n> + * an IPA instance for each associated Camera.\n\nMissing \\brief too.\n\nShould we document this from the point of view of the IPA module first,\nand then mention the usage pattern ? I mean something along those lines:\n\n * \\brief Create an instance of the IPA interface\n *\n * This function is the entry point of the IPA module. It is called by the IPA\n * manager to create an instance of the IPA interface for each camera.\n\n> + */\n> IPAInterface *ipaCreate()\n> {\n> \treturn new ipa::ipu3::IPAIPU3();","headers":{"Return-Path":"","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 85AE1BDB1D\n\tfor ;\n\tTue, 14 Sep 2021 03:37:58 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id DFA6769187;\n\tTue, 14 Sep 2021 05:37:57 +0200 (CEST)","from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 3CAEC6916F\n\tfor ;\n\tTue, 14 Sep 2021 05:37:56 +0200 (CEST)","from pendragon.ideasonboard.com (62-78-145-57.bb.dnainternet.fi\n\t[62.78.145.57])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id AF7202A5;\n\tTue, 14 Sep 2021 05:37:55 +0200 (CEST)"],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (1024-bit key;\n\tunprotected) header.d=ideasonboard.com header.i=@ideasonboard.com\n\theader.b=\"OJ7cAwvh\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1631590675;\n\tbh=gz9pZ5TPrpKmcZORvGbwJKcLilkewLe9fI6TYBXDI3E=;\n\th=Date:From:To:Cc:Subject:References:In-Reply-To:From;\n\tb=OJ7cAwvhVxeDoOmpaAAp8oZtW31OLcAjycNmPxSulekmZN+KnYXhUHKx5ojsh8Hwt\n\tHmB9FNLvIpqQuRp4ff+UlHqnHX4Ah4UZBsIQz8IhV9tlr9oITVdrP55oW91pT0RkpB\n\trbuEcW/KMQNjEvOplxhZxR6laP5uOflWCKJag71I=","Date":"Tue, 14 Sep 2021 06:37:31 +0300","From":"Laurent Pinchart ","To":"Jean-Michel Hautbois ","Message-ID":"","References":"<20210913145810.66515-1-jeanmichel.hautbois@ideasonboard.com>\n\t<20210913145810.66515-5-jeanmichel.hautbois@ideasonboard.com>","MIME-Version":"1.0","Content-Type":"text/plain; charset=utf-8","Content-Disposition":"inline","In-Reply-To":"<20210913145810.66515-5-jeanmichel.hautbois@ideasonboard.com>","Subject":"Re: [libcamera-devel] [PATCH 04/11] ipa: ipu3: Document the IPAIPU3\n\tclass","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","Cc":"libcamera-devel@lists.libcamera.org","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "}}]