gpu: nvgpu: update doxygen for common.fifo

- Add doxygen comments for nvgpu_tsg_open_common().
- Update return and return value description for
1.	nvgpu_fifo_init_support()
2.	nvgpu_fifo_setup_sw()
3.	nvgpu_fifo_setup_sw_common()
4.	nvgpu_channel_init_support()
5.	gops_fifo.reset_enable_hw()
6.	nvgpu_runlist_get_runlists_mask()

Jira NVGPU-6222

Signed-off-by: Vedashree Vidwans <vvidwans@nvidia.com>
Change-Id: I2ef150d41695afca303f1e083f559d31895ba602
Reviewed-on: https://git-master.nvidia.com/r/c/linux-nvgpu/+/2482062
GVS: Gerrit_Virtual_Submit
Tested-by: mobile promotions <svcmobile_promotions@nvidia.com>
Reviewed-by: Alex Waterman <alexw@nvidia.com>
Reviewed-by: mobile promotions <svcmobile_promotions@nvidia.com>

drivers/gpu/nvgpu/include/nvgpu/channel.h

@@ -657,6 +657,11 @@ void nvgpu_channel_commit_va(struct nvgpu_channel *c);
  * This includes mutexes and list nodes initialization.
  *
  * @return 0 in case of success, < 0 in case of failure.
+ * @retval -ENOMEM in case there is not enough memory to allocate channels.
+ * @retval -EINVAL for invalid condition variable value.
+ * @retval -EBUSY in case reference condition variable pointer isn't NULL.
+ * @retval -EFAULT in case any faults occurred while accessing condition
+ * variable or attribute.
  */
 int nvgpu_channel_init_support(struct gk20a *g, u32 chid);
 
@@ -671,6 +676,10 @@ int nvgpu_channel_init_support(struct gk20a *g, u32 chid);
  *
  * @return 0 in case of success, < 0 in case of failure.
  * @retval -ENOMEM in case there is not enough memory to allocate channels.
+ * @retval -EINVAL for invalid condition variable value.
+ * @retval -EBUSY in case reference condition variable pointer isn't NULL.
+ * @retval -EFAULT in case any faults occurred while accessing condition
+ * variable or attribute.
  */
 int nvgpu_channel_setup_sw(struct gk20a *g);
 

drivers/gpu/nvgpu/include/nvgpu/fifo.h

@@ -423,7 +423,11 @@ static inline const char *nvgpu_id_type_to_str(unsigned int id_type)
  * care of h/w specific setup related to FIFO module.
  *
  * @return 0 in case of success, < 0 in case of failure.
- * @retval Error returned by setup_sw and setup_hw routines.
+ * @retval -ENOMEM in case there is not enough memory available.
+ * @retval -EINVAL in case condition variable has invalid value.
+ * @retval -EBUSY in case reference condition variable pointer isn't NULL.
+ * @retval -EFAULT in case any faults occurred while accessing condition
+ * variable or attribute.
  */
 int nvgpu_fifo_init_support(struct gk20a *g);
 
@@ -439,6 +443,11 @@ int nvgpu_fifo_init_support(struct gk20a *g);
  * Mark FIFO s/w ready by setting #nvgpu_fifo.sw_ready to true.
  *
  * @return 0 in case of success, < 0 in case of failure.
+ * @retval -ENOMEM in case there is not enough memory available.
+ * @retval -EINVAL in case condition variable has invalid value.
+ * @retval -EBUSY in case reference condition variable pointer isn't NULL.
+ * @retval -EFAULT in case any faults occurred while accessing condition
+ * variable or attribute.
  */
 int nvgpu_fifo_setup_sw(struct gk20a *g);
 
@@ -456,9 +465,14 @@ int nvgpu_fifo_setup_sw(struct gk20a *g);
  * - Do userd.setup_sw.
  * - Init #nvgpu_fifo.remove_support function pointer.
  *
- * @return 0 in case of success, < 0 in case of failure.
  * @note In case of failure, cleanup_sw for the blocks that are already
  *       initialized is also taken care of by this function.
+ * @return 0 in case of success, < 0 in case of failure.
+ * @retval -ENOMEM in case there is not enough memory available.
+ * @retval -EINVAL in case condition variable has invalid value.
+ * @retval -EBUSY in case reference condition variable pointer isn't NULL.
+ * @retval -EFAULT in case any faults occurred while accessing condition
+ * variable or attribute.
  */
 int nvgpu_fifo_setup_sw_common(struct gk20a *g);
 

drivers/gpu/nvgpu/include/nvgpu/runlist.h

@@ -344,11 +344,11 @@ void nvgpu_runlist_unlock_runlists(struct gk20a *g, u32 runlists_mask);
  * looks up for the runlist servicing related channel/TSG.
  *
  * @return A bitmask of runlists servicing specified engines/PBDMAs/channel/TSG.
- * @retval If both #id_type and engine/PBDMAs are known, the function returns
- *         the set of runlist servicing #id or engine/PBDMA.
- * @retval If both #id_type and engines/PBDMAs are unknown (i.e.
- *         #ID_TYPE_UNKNOWN and both #act_eng_bitmask and #pbdma_bitmask are
- *         equal to 0), the function returns a bitmask of all active runlists.
+ * @retval Runlist_mask of runlist servicing \a id or engine/PBDMA, if both
+ *         \a id_type and engine/PBDMAs are known.
+ * @retval Runlist_mask of all active runlists, if both \a id_type and
+ *         engines/PBDMAs are unknown (i.e. #ID_TYPE_UNKNOWN and both
+ *         \a act_eng_bitmask and #pbdma_bitmask are equal to 0).
  */
 u32 nvgpu_runlist_get_runlists_mask(struct gk20a *g, u32 id,
 	unsigned int id_type, u32 act_eng_bitmask, u32 pbdma_bitmask);

drivers/gpu/nvgpu/include/nvgpu/tsg.h

@@ -210,6 +210,19 @@ struct nvgpu_tsg {
 #endif
 };
 
+/**
+ * @brief Initialize given TSG
+ *
+ * @param g [in]		The GPU driver struct.
+ * @param pid [in]		The PID of the process.
+ *
+ * - Set s/w context of the given TSG.
+ * - Update given TSG struct with init pointers.
+ *
+ * @return 0 in case of success, < 0 in case of failure.
+ * @retval -EINVAL if there is no SM.
+ * @retval -ENOMEM if not enough memory is available.
+ */
 int nvgpu_tsg_open_common(struct gk20a *g, struct nvgpu_tsg *tsg, pid_t pid);
 /**
  * @brief Open and initialize unused TSG