[libcamera-devel,03/18] ipa: ipu3: Document the IPAIPU3 class
diff mbox series

Message ID 20210930095513.76213-4-jeanmichel.hautbois@ideasonboard.com
State Changes Requested
Headers show
Series
  • Document IPU3 IPA
Related show

Commit Message

Jean-Michel Hautbois Sept. 30, 2021, 9:54 a.m. UTC
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@ideasonboard.com>
Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
---
 src/ipa/ipu3/ipu3.cpp | 65 +++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 62 insertions(+), 3 deletions(-)

Patch
diff mbox series

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<IPABuffer> &buffers)
 {
 	for (const IPABuffer &buffer : buffers) {
@@ -500,6 +511,10 @@  void IPAIPU3::mapBuffers(const std::vector<IPABuffer> &buffers)
 	}
 }
 
+/**
+ * \brief Unmap the parameters and stats buffers
+ * \param[in] ids A list of buffer ids
+ */
 void IPAIPU3::unmapBuffers(const std::vector<unsigned int> &ids)
 {
 	for (unsigned int id : ids) {
@@ -511,6 +526,10 @@  void IPAIPU3::unmapBuffers(const std::vector<unsigned int> &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();