[libcamera-devel] [PATCH v4 03/19] ipa: ipu3: Document the IPAIPU3 class

[Umang Jain]

Hi JM,

On 10/26/21 3:25 PM, Jean-Michel Hautbois wrote:
> 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 <jeanmichel.hautbois at ideasonboard.com>
> Signed-off-by: Kieran Bingham <kieran.bingham at ideasonboard.com>


Reviewed-by: Umang Jain <umang.jain at ideasonboard.com>
> ---
>   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<IPABuffer> &buffers)
>   {
>   	for (const IPABuffer &buffer : buffers) {
> @@ -594,6 +605,10 @@ void IPAIPU3::mapBuffers(const std::vector<IPABuffer> &buffers)
>   	}
>   }
>   
> +/**
> + * \brief Unmap the parameters and stats buffers
> + * \param[in] ids The IDs of the buffers to unmap
> + */
>   void IPAIPU3::unmapBuffers(const std::vector<unsigned int> &ids)
>   {
>   	for (unsigned int id : ids) {
> @@ -605,6 +620,10 @@ void IPAIPU3::unmapBuffers(const std::vector<unsigned int> &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();