[Docs] Add Doxygen commments

Add Doxygen comments to gmsl-link.h, max9295.h, & max9296.h.

Bug 3053489

Signed-off-by: Jonathan Sachs <jsachs@nvidia.com>
Change-Id: I37320f1af3440b79f2058e0c7669cc32814d4089
Reviewed-on: https://git-master.nvidia.com/r/c/linux-nvidia/+/2403126
Reviewed-by: automaticguardword <automaticguardword@nvidia.com>
Reviewed-by: Kathy Stone <kstone@nvidia.com>
Reviewed-by: Bibek Basu <bbasu@nvidia.com>
Reviewed-by: mobile promotions <svcmobile_promotions@nvidia.com>
Tested-by: mobile promotions <svcmobile_promotions@nvidia.com>
GVS: Gerrit_Virtual_Submit

3 files changed, 237 insertions, 13 deletions

diff --git a/include/media/gmsl-link.h b/include/media/gmsl-link.h
index 94df6bf3f..4d565e951 100644
--- a/include/media/gmsl-link.h
+++ b/include/media/gmsl-link.h
@@ -14,7 +14,23 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * @file  <b>GMSL API: Gigabit Multimedia Serial Link protocol</b>
+ *
+ * @b Description: Defines elements used to set up and use a GMSL link.
+ */
+
 #ifndef __GMSL_LINK_H__
+/**
+ * \defgroup GMSL Gigabit Multimedia Serial Link (GMSL)
+ *
+ * Defines the interface used to control the MAX9295 serializer and
+ * MAX9296 deserializer modules.
+ *
+ * @ingroup serdes_group
+ * @{
+ */
+
 #define __GMSL_LINK_H__
 
 #define GMSL_CSI_1X4_MODE 0x1
@@ -39,29 +55,49 @@
 
 #define GMSL_ST_ID_UNUSED 0xFF
 
+/**
+ * Maximum number of data streams (\ref gmsl_stream elements) in a GMSL link
+ * (\ref gmsl_link_ctx).
+ */
 #define GMSL_DEV_MAX_NUM_DATA_STREAMS 4
 
+/**
+ * Holds information about a data stream in a GMSL link (\ref gmsl_link_ctx).
+ */
 struct gmsl_stream {
         __u32 st_id_sel;
         __u32 st_data_type;
         __u32 des_pipe;
 };
 
+/**
+ * Holds the configuration of the GMSL links from a sensor to its serializer to
+ * its deserializer.
+ */
 struct gmsl_link_ctx {
-        __u32 st_vc;
-        __u32 dst_vc;
-        __u32 src_csi_port;
-        __u32 dst_csi_port;
-        __u32 serdes_csi_link;
-        __u32 num_streams;
-        __u32 num_csi_lanes;
-        __u32 csi_mode;
-        __u32 ser_reg;
-        __u32 sdev_reg;
-        __u32 sdev_def;
-        bool serdev_found;
+        __u32 st_vc;            /**< Default sensor virtual channel. */
+        __u32 dst_vc;           /**< Destination virtual channel (user-defined). */
+        __u32 src_csi_port;     /**< Sensor to serializer CSI port connection. */
+        __u32 dst_csi_port;     /**< Deserializer to Jetson CSI port connection. */
+        __u32 serdes_csi_link;  /**< GMSL link between serializer and deserializer
+                                devices. */
+        __u32 num_streams;      /**< Number of active streams to be mapped
+                                from sensor. */
+        __u32 num_csi_lanes;    /**< Sensor's CSI lane configuration. */
+        __u32 csi_mode;         /**< Deserializer CSI mode. */
+        __u32 ser_reg;          /**< Serializer slave address. */
+        __u32 sdev_reg;         /**< Sensor proxy slave address. */
+        __u32 sdev_def;         /**< Sensor default slave address. */
+        bool serdev_found;      /**< Indicates whether the serializer device for
+                             the specified sensor source was found. Set by
+                             the serializer driver during setup; used by
+                             the deserializer driver to choose certain
+                             configuration settings during setup. */
         struct gmsl_stream streams[GMSL_DEV_MAX_NUM_DATA_STREAMS];
-        struct device *s_dev;
+        /*< An array of information about the data streams in the link. */
+        struct device *s_dev;   /**< Sensor device handle. */
 };
 
+/** @} */
+
 #endif  /* __GMSL_LINK_H__ */
diff --git a/include/media/max9295.h b/include/media/max9295.h
index bfdd75a33..c8ca6b589 100644
--- a/include/media/max9295.h
+++ b/include/media/max9295.h
@@ -14,19 +14,86 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * @file  <b>MAX9295 API: For Maxim Integrated MAX9295 serializer.</b>
+ *
+ * @b Description: Defines elements used to set up and use a
+ *  Maxim Integrated MAX9295 serializer.
+ */
+
 #ifndef __MAX9295_H__
 #define __MAX9295_H__
 
 #include <media/gmsl-link.h>
+/**
+ * \defgroup max9295 MAX9295 serializer driver
+ *
+ * Controls the MAX9295 serializer module.
+ *
+ * @ingroup serdes_group
+ * @{
+ */
+
 
+/**
+ * @brief  Powers on a serializer device and performs the I2C overrides
+ * for sensor and serializer devices.
+ *
+ * The I2C overrides include setting proxy I2C slave addresses for the devices.
+ *
+ * Before the client calls this function it must ensure that
+ * the deserializer device is in link_ex exclusive link mode
+ * by calling the deserializer driver's max9296_setup_link() function.
+ *
+ * @param  [in]  dev            The serializer device handle.
+ *
+ * @return  0 for success, or -1 otherwise.
+ */
 int max9295_setup_control(struct device *dev);
 
+/**
+ * Reverts I2C overrides and resets a serializer device.
+ *
+ * @param  [in]  dev            The serializer device handle.
+ *
+ * @return  0 for success, or -1 otherwise.
+ */
 int max9295_reset_control(struct device *dev);
 
+/**
+ * @brief  Pairs a sensor device with a serializer device.
+ *
+ * To be called by sensor client driver.
+ *
+ * @param  [in]  dev            The deserializer device handle.
+ * @param  [in]  g_ctx          The @ref gmsl_link_ctx structure handle.
+ *
+ * @return  0 for success, or -1 otherwise.
+ */
 int max9295_sdev_pair(struct device *dev, struct gmsl_link_ctx *g_ctx);
 
+/**
+ * @brief Unpairs a sensor device from a serializer device.
+ *
+ * To be called by sensor client driver.
+ *
+ * @param  [in]  dev            The serializer device handle.
+ * @param  [in]  s_dev          The sensor device handle.
+ *
+ * @return  0 for success, or -1 otherwise.
+ */
 int max9295_sdev_unpair(struct device *dev, struct device *s_dev);
 
+/**
+ * Sets up the serializer device's internal pipeline for a specified
+ * sensor/serializer pair.
+ *
+ * @param  [in]  dev            The serializer device handle.
+ *
+ * @return  0 for success, or -1 otherwise.
+ */
 int max9295_setup_streaming(struct device *dev);
 
+/** @} */
+
 #endif  /* __MAX9295_H__ */
diff --git a/include/media/max9296.h b/include/media/max9296.h
index 014af0af2..d7ea6178d 100644
--- a/include/media/max9296.h
+++ b/include/media/max9296.h
@@ -14,29 +14,150 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * @file  <b>MAX9296 API: For Maxim Integrated MAX9295 deserializer.</b>
+ *
+ * @b Description: Defines elements used to set up and use a
+ *  Maxim Integrated MAX9296 deserializer.
+ */
+
 #ifndef __MAX9296_H__
 #define __MAX9296_H__
 
 #include <media/gmsl-link.h>
+/**
+ * \defgroup max9296 MAX9296 deserializer driver
+ *
+ * Controls the MAX9296 deserializer module.
+ *
+ * @ingroup serdes_group
+ * @{
+ */
 
+/**
+ * Puts a deserializer device in single exclusive link mode, so link-specific
+ * I2C overrides can be performed for sensor and serializer devices.
+ *
+ * @param [in]  dev             The deserializer device handle.
+ * @param [in]  s_dev           The sensor device handle.
+ *
+ * @return  0 for success, or -1 otherwise.
+ */
 int max9296_setup_link(struct device *dev, struct device *s_dev);
 
+/**
+ * @brief  Sets up a deserializer link's control pipeline.
+ *
+ * Puts the deserializer in dual splitter mode. You must call this function
+ * during device boot, after max9296_setup_link().
+ *
+ * @param [in]  dev             The deserializer device handle.
+ * @param [in]  s_dev           The sensor device handle.
+ *
+ * @return  0 for success, or -1 otherwise.
+ */
 int max9296_setup_control(struct device *dev, struct device *s_dev);
 
+/**
+ * @brief  Resets a deserializer device's link control pipeline.
+ *
+ * The deserializer driver internally decrements the reference count and
+ * resets the deserializer device if all the source sensor devices are
+ * powered off, resetting all control and streaming configuration.
+ *
+ * @param [in]  dev             The deserializer device handle.
+ * @param [in]  s_dev           The sensor device handle.
+ *
+ * @return  0 for success, or -1 otherwise.
+ */
 int max9296_reset_control(struct device *dev, struct device *s_dev);
 
+/**
+ * @brief  Registers a source sensor device with a deserializer device.
+ *
+ * The deserializer driver internally checks all perquisites and compatibility
+ * factors. If it finds that the registration request is valid,
+ * it stores the source's @ref gmsl_link_ctx context handle in the source list
+ * maintained by the deserializer driver instance.
+ *
+ * @param [in]  dev             The deserializer device handle.
+ * @param [in]  g_ctx           A @c gmsl_link_ctx structure handle.
+ *
+ * @return  0 for success, or -1 otherwise.
+ */
 int max9296_sdev_register(struct device *dev, struct gmsl_link_ctx *g_ctx);
 
+/**
+ * Unregisters a source sensor device from its deserializer device.
+ *
+ * @param [in]  dev             The deserializer device handle.
+ * @param [in]  s_dev           The sensor device handle.
+ *
+ * @return  0 for success, or -1 otherwise.
+ */
 int max9296_sdev_unregister(struct device *dev, struct device *s_dev);
 
+/**
+ * Performs internal pipeline configuration for a link in context to set up
+ * streaming, and puts the deserializer link in ready-to-stream state.
+ *
+ * @param [in]  dev             The deserializer device handle.
+ * @param [in]  s_dev           The sensor device handle.
+ *
+ * @return  0 or success, or -1 otherwise.
+ */
 int max9296_setup_streaming(struct device *dev, struct device *s_dev);
 
+/**
+ * @brief Enables streaming.
+ *
+ * This function is to be called by the sensor client driver.
+ *
+ * @param [in]  dev             The deserializer device handle.
+ * @param [in]  s_dev           The sensor device handle.
+ *
+ * @return  0 for success, or -1 otherwise.
+ */
 int max9296_start_streaming(struct device *dev, struct device *s_dev);
 
+/**
+ * @brief Disables streaming.
+ *
+ * This function is to be called by the sensor client driver.
+ *
+ * @note  Both @c max9296_start_streaming and @c max9296_stop_streaming
+ * are mainly added to enable and disable sensor streaming on the fly
+ * while other sensors are active.
+ *
+ * @param [in]  dev             The deserializer device handle.
+ * @param [in]  s_dev           The sensor device handle.
+ *
+ * @return  0 for success, or -1 otherwise.
+ */
 int max9296_stop_streaming(struct device *dev, struct device *s_dev);
 
+/**
+ * @brief  Powers on the max9296 deserializer module.
+ *
+ * Asserts shared reset GPIO and powers on the regulator;
+ * maintains the reference count internally for source devices.
+ *
+ * @param [in]  dev             The deserializer device handle.
+ *
+ * @return  0 for success, or -1 otherwise.
+ */
 int max9296_power_on(struct device *dev);
 
+/**
+ * @brief  Powers off the max9296 deserializer module.
+ *
+ * Deasserts the shared reset GPIO and powers off the regulator based on
+ * the reference count.
+ *
+ * @param [in]  dev             The deserializer device handle.
+ */
 void max9296_power_off(struct device *dev);
 
+/** @} */
+
 #endif  /* __MAX9296_H__ */