gpu: nvgpu: Doxygen comments for FBP unit

Add doxygen comments to all the FUSA public APIs and HALS

The APIs identified as NON-FUSA are -
a. nvgpu_fbp_get_num_fbps()
b. nvgpu_fbp_get_rop_l2_en_mask()

Add @cond ... @endcond to skip NON FUSA functions from
design document.

The FBP HAL fbp.fbp_init_support() is redundant and will be replaced
by calls to nvgpu_fbp_init_support() directly.

JIRA NVGPU-4140

Change-Id: I08ec79dfcab7b898b40491997963466938e5e4cd
Signed-off-by: Tejal Kudav <tkudav@nvidia.com>
Reviewed-on: https://git-master.nvidia.com/r/2221967
Reviewed-by: svc-mobile-coverity <svc-mobile-coverity@nvidia.com>
Reviewed-by: svc-mobile-misra <svc-mobile-misra@nvidia.com>
Reviewed-by: svc-mobile-cert <svc-mobile-cert@nvidia.com>
GVS: Gerrit_Virtual_Submit
Reviewed-by: Seema Khowala <seemaj@nvidia.com>
Reviewed-by: Alex Waterman <alexw@nvidia.com>
Reviewed-by: mobile promotions <svcmobile_promotions@nvidia.com>
Tested-by: mobile promotions <svcmobile_promotions@nvidia.com>

drivers/gpu/nvgpu/common/fbp/fbp.c

@@ -100,11 +100,6 @@ void nvgpu_fbp_remove_support(struct gk20a *g)
 	g->fbp = NULL;
 }
 
-u32 nvgpu_fbp_get_num_fbps(struct nvgpu_fbp *fbp)
-{
-	return fbp->num_fbps;
-}
-
 u32 nvgpu_fbp_get_max_fbps_count(struct nvgpu_fbp *fbp)
 {
 	return fbp->max_fbps_count;
@@ -115,8 +110,15 @@ u32 nvgpu_fbp_get_fbp_en_mask(struct nvgpu_fbp *fbp)
 	return fbp->fbp_en_mask;
 }
 
+#ifdef CONFIG_NVGPU_NON_FUSA
+u32 nvgpu_fbp_get_num_fbps(struct nvgpu_fbp *fbp)
+{
+	return fbp->num_fbps;
+}
+
 u32 *nvgpu_fbp_get_rop_l2_en_mask(struct nvgpu_fbp *fbp)
 {
 	return fbp->fbp_rop_l2_en_mask;
 }
+#endif
 

drivers/gpu/nvgpu/include/nvgpu/fbp.h

@@ -23,17 +23,83 @@
 #ifndef NVGPU_FBP_H
 #define NVGPU_FBP_H
 
+/**
+ * @file
+ *
+ * Declares the Public APIs exposed by common.fbp unit.
+ */
 #include <nvgpu/types.h>
 
 struct gk20a;
 struct nvgpu_fbp;
 
+/**
+ * @brief Read and initialize FBP configuration information in struct nvgpu_fbp.
+ *
+ * @param g [in]	Pointer to GPU driver struct.
+ *
+ * This API reads various FBP related configuration information like:
+ * 1. Number of FBPs from PPRIV_MASTER_RING_ENUMERATE_RESULTS_FBP_COUNT
+ * 2. Maximum number of FBPs from PTOP_SCAL_NUM_FBPS
+ * 3. Active FBP mask from the fuse(accessed from GPU MMIO register space)
+ * 4. Mask of Rop_L2 for each FBP from fuse(accessed from GPU MMIO register
+ * 					    space)
+ *
+ * All the above configuration information is stored in a struct nvgpu_fbp
+ * and exposed to other units through APIs.
+ *
+ * @return 0 for success and <0 value for failure.
+ */
 int nvgpu_fbp_init_support(struct gk20a *g);
+
+/**
+ * @brief Removes all the FBP related stored configuration information.
+ *
+ * @param g [in]	Pointer to GPU driver struct.
+ *
+ * This API frees up all the memory used to store FBP configuration information
+ * and sets the pointer to FBP structure in \a g to NULL.
+ */
 void nvgpu_fbp_remove_support(struct gk20a *g);
 
-u32 nvgpu_fbp_get_num_fbps(struct nvgpu_fbp *fbp);
-u32 nvgpu_fbp_get_max_fbps_count(struct nvgpu_fbp *fbp);
-u32 nvgpu_fbp_get_fbp_en_mask(struct nvgpu_fbp *fbp);
-u32 *nvgpu_fbp_get_rop_l2_en_mask(struct nvgpu_fbp *fbp);
 
+/**
+ * @brief Get the maximum number of FBPs as stored in \a fbp.
+ *
+ * @param fbp [in]	Pointer to FBP configuration structure.
+ *
+ * This API helps retrieve the FBP data namely maximum number of FBPs from the
+ * information stored in \a fbp.
+ * During initialization, \a fbp is populated with all the configuration
+ * information like max_fbps_count and APIs like this are used to get data from
+ * FBP's private structure (struct nvgpu_fbp).
+ *
+ * @return Maximum number of FBPs as stored in \a fbp.
+ */
+u32 nvgpu_fbp_get_max_fbps_count(struct nvgpu_fbp *fbp);
+
+/**
+ * @brief Gets the active FBP mask as stored in \a fbp.
+ *
+ * @param fbp [in]	Pointer to FBP configuration structure.
+ *
+ * This API helps retrieve the FBP data namely active FBP mask from the
+ * information stored in \a fbp.
+ * During initialization, \a fbp is populated with all the configuration
+ * information like fbp_en_mask and APIs like this are used to get data from
+ * FBP's private structure (struct nvgpu_fbp).
+ *
+ * @return Mask corresponding to active FBPs as stored in \a fbp.
+ */
+u32 nvgpu_fbp_get_fbp_en_mask(struct nvgpu_fbp *fbp);
+
+/** @cond DOXYGEN_SHOULD_SKIP_THIS */
+
+#ifdef CONFIG_NVGPU_NON_FUSA
+u32 nvgpu_fbp_get_num_fbps(struct nvgpu_fbp *fbp);
+u32 *nvgpu_fbp_get_rop_l2_en_mask(struct nvgpu_fbp *fbp);
 #endif
+
+/** @endcond DOXYGEN_SHOULD_SKIP_THIS */
+
+#endif /* NVGPU_FBP_H */