From cbb2711e952b18d5b671d491bb79ae70dfd3aa25 Mon Sep 17 00:00:00 2001 From: Jonathan Sachs Date: Mon, 24 Aug 2020 10:23:15 -0700 Subject: [Docs] Add Doxygen commments Add Doxygen comments to gmsl-link.h, max9295.h, & max9296.h. Bug 3053489 Signed-off-by: Jonathan Sachs Change-Id: I37320f1af3440b79f2058e0c7669cc32814d4089 Reviewed-on: https://git-master.nvidia.com/r/c/linux-nvidia/+/2403126 Reviewed-by: automaticguardword Reviewed-by: Kathy Stone Reviewed-by: Bibek Basu Reviewed-by: mobile promotions Tested-by: mobile promotions GVS: Gerrit_Virtual_Submit --- include/media/gmsl-link.h | 62 +++++++++++++++++++----- include/media/max9295.h | 67 +++++++++++++++++++++++++ include/media/max9296.h | 121 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 237 insertions(+), 13 deletions(-) (limited to 'include') 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 . */ +/** + * @file GMSL API: Gigabit Multimedia Serial Link protocol + * + * @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 . */ +/** + * @file MAX9295 API: For Maxim Integrated MAX9295 serializer. + * + * @b Description: Defines elements used to set up and use a + * Maxim Integrated MAX9295 serializer. + */ + #ifndef __MAX9295_H__ #define __MAX9295_H__ #include +/** + * \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 . */ +/** + * @file MAX9296 API: For Maxim Integrated MAX9295 deserializer. + * + * @b Description: Defines elements used to set up and use a + * Maxim Integrated MAX9296 deserializer. + */ + #ifndef __MAX9296_H__ #define __MAX9296_H__ #include +/** + * \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__ */ -- cgit v1.2.2