gpu: nvgpu: doxygen for fifo HAL

Add documentation for fifo HALs that are called
from other units.
- fifo_init_support
- fifo_suspend
- preempt_tsg
- preempt_runlists_for_rc
- intr_0_isr
- intr_1_isr

Jira NVGPU-4104

Change-Id: I7a7bc4384ef3d9cb5f0b4a6a3ecf0c9ad2de85da
Signed-off-by: Thomas Fleury <tfleury@nvidia.com>
Reviewed-on: https://git-master.nvidia.com/r/2213611
Reviewed-by: mobile promotions <svcmobile_promotions@nvidia.com>
Tested-by: mobile promotions <svcmobile_promotions@nvidia.com>

drivers/gpu/nvgpu/common/fifo/fifo.c

@@ -276,7 +276,7 @@ void nvgpu_fifo_sw_quiesce(struct gk20a *g)
 			0U, ID_TYPE_UNKNOWN, 0U, 0U);
 	g->ops.runlist.write_state(g, runlist_mask, RUNLIST_DISABLED);
 
-	/* Preempt all runlists (runlist->reset_eng_bitmask will be ignored)*/
+	/* Preempt all runlists */
 	g->ops.fifo.preempt_runlists_for_rc(g, runlist_mask);
 
 	nvgpu_channel_sw_quiesce(g);

drivers/gpu/nvgpu/hal/fifo/preempt_gv11b_fusa.c

@@ -86,13 +86,14 @@ static int gv11b_fifo_preempt_locked(struct gk20a *g, u32 id,
  */
 void gv11b_fifo_preempt_runlists_for_rc(struct gk20a *g, u32 runlists_mask)
 {
-	struct nvgpu_fifo *f = &g->fifo;
-	struct nvgpu_runlist_info *runlist;
 #ifdef CONFIG_NVGPU_LS_PMU
 	u32 token = PMU_INVALID_MUTEX_OWNER_ID;
 	int mutex_ret = 0;
 #endif
+#ifdef CONFIG_NVGPU_RECOVERY
+	struct nvgpu_fifo *f = &g->fifo;
 	u32 i;
+#endif
 
 	/* runlist_lock are locked by teardown and sched are disabled too */
 	nvgpu_log_fn(g, "preempt runlists_mask:0x%08x", runlists_mask);
@@ -103,12 +104,15 @@ void gv11b_fifo_preempt_runlists_for_rc(struct gk20a *g, u32 runlists_mask)
 	/* issue runlist preempt */
 	gv11b_fifo_issue_runlist_preempt(g, runlists_mask);
 
+#ifdef CONFIG_NVGPU_RECOVERY
 	/*
 	 * Preemption will never complete in RC due to some fatal condition.
 	 * Do not poll for preemption to complete. Reset engines served by
 	 * runlists.
 	 */
 	for (i = 0U; i < f->num_runlists; i++) {
+		struct nvgpu_runlist_info *runlist;
+
 		runlist = &f->active_runlist_info[i];
 
 		if ((fifo_runlist_preempt_runlist_m(runlist->runlist_id) &
@@ -116,6 +120,7 @@ void gv11b_fifo_preempt_runlists_for_rc(struct gk20a *g, u32 runlists_mask)
 			runlist->reset_eng_bitmask = runlist->eng_bitmask;
 		}
 	}
+#endif
 #ifdef CONFIG_NVGPU_LS_PMU
 	if (mutex_ret == 0) {
 		int err = nvgpu_pmu_lock_release(g, g->pmu, PMU_MUTEX_ID_FIFO,

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

@@ -47,7 +47,8 @@
  *
  * The FIFO unit TODO.
  *
- * See include/nvgpu/fifo.h for more details.
+ *   + include/nvgpu/fifo.h
+ *   + include/nvgpu/gops_fifo.h
  *
  * Runlist
  * -------

drivers/gpu/nvgpu/include/nvgpu/gops_fifo.h

@@ -24,21 +24,160 @@
 
 #include <nvgpu/types.h>
 
+/**
+ * @file
+ *
+ * FIFO HAL interface.
+ */
 struct gk20a;
 struct nvgpu_channel;
 struct nvgpu_tsg;
 struct mmu_fault_info;
 
 struct gops_fifo {
+	/**
+ 	 * @brief Initialize FIFO unit.
+ 	 *
+ 	 * @param g [in]	Pointer to GPU driver struct.
+ 	 *
+	 * This HAL is used to initialize FIFO software context,
+	 * then do GPU h/w initializations. It always maps to
+	 * #nvpgu_fifo_init_support, except for vgpu case.
+	 *
+ 	 * @return 0 in case of success, < 0 in case of failure.
+ 	 */
 	int (*fifo_init_support)(struct gk20a *g);
+
+	/**
+ 	 * @brief Suspend FIFO unit.
+ 	 *
+ 	 * @param g [in]	Pointer to GPU driver struct.
+ 	 *
+	 * - Disable BAR1 snooping when supported.
+	 * - Disable FIFO interrupts
+	 *   - Disable FIFO stalling interrupts
+	 *   - Disable ctxsw timeout detection, and clear any pending
+	 *     ctxsw timeout interrupt.
+	 *   - Disable PBDMA interrupts.
+	 *   - Disable FIFO non-stalling interrupts.
+	 *
+ 	 * @return 0 in case of success, < 0 in case of failure.
+ 	 */
 	int (*fifo_suspend)(struct gk20a *g);
+
+	/**
+ 	 * @brief Preempt TSG.
+ 	 *
+ 	 * @param g [in]	Pointer to GPU driver struct.
+	 * @param tsg [in]	Pointer to TSG struct.
+ 	 *
+	 * Preempt TSG:
+	 * - Acquire lock for active runlist.
+	 * - Write h/w register to trigger TSG preempt for \a tsg.
+	 * - Preemption mode (e.g. CTA or WFI) depends on the preemption
+	 *   mode configured in the GR context.
+	 * - Release lock acquired for active runlist.
+	 * - Poll PBDMAs and engines status until preemption is complete,
+	 *   or poll timeout occurs.
+	 *
+	 * On some chips, it is also needed to disable scheduling
+	 * before preempting TSG.
+	 *
+	 * @see nvgpu_preempt_get_timeout
+	 * @see nvgpu_gr_ctx::compute_preempt_mode
+	 *
+ 	 * @return 0 in case preemption succeeded, < 0 in case of failure.
+	 * @retval -ETIMEDOUT when preemption was triggered, but did not
+	 *         complete within preemption poll timeout.
+ 	 */
+	int (*preempt_tsg)(struct gk20a *g, struct nvgpu_tsg *tsg);
+
+	/**
+ 	 * @brief Preempt a set of runlists.
+ 	 *
+ 	 * @param g [in]		Pointer to GPU driver struct.
+	 * @param runlists_mask [in]	Bitmask of runlists to preempt.
+ 	 *
+	 * Preempt runlists in \a runlists_mask:
+	 * - Write h/w register to trigger preempt on runlists.
+	 * - All TSG in those runlists are preempted.
+	 *
+	 * @note This HAL is called in case of critical error, and does
+	 * not poll PBDMAs or engines to wait for preempt completion.
+	 *
+	 * @note This HAL should be called with runlist lock held for all
+	 * the runlists in \a runlists_mask.
+ 	 */
+	void (*preempt_runlists_for_rc)(struct gk20a *g,
+			u32 runlists_bitmask);
+
+	/**
+	 * @brief Enable and configure FIFO.
+	 *
+	 * @param g [in]		Pointer to GPU driver struct.
+	 *
+	 * Enable and configure h/w settings for FIFO:
+	 * - Enable PMC FIFO.
+	 * - Configure clock gating:
+	 *   - Set SLCG settings for CE2 and FIFO.
+	 *   - Set BLCG settings for FIFO.
+	 * - Set FB timeout for FIFO initiated requests.
+	 * - Setup PBDMA timeouts.
+	 * - Enable stalling and non-stalling interrupts.
+	 *
+	 * @return 0 in case of success, < 0 in case of failure.
+	 */
+	int (*reset_enable_hw)(struct gk20a *g);
+
+	/**
+	 * @brief ISR for stalling interrupts.
+	 *
+	 * @param g [in]		Pointer to GPU driver struct.
+	 *
+	 * Interrupt Service Routine for FIFO stalling interrupts:
+	 * - Read interrupt status.
+	 * - If sw_ready is false, clear interrupts and return, else
+	 * - Acquire FIFO ISR mutex
+	 * - Handle interrupts:
+	 *  - Handle error interrupts:
+	 *    - Report bind, chw, memop timeout and lb errors.
+	 *  - Handle runlist event interrupts:
+	 *    - Log and clear runlist events.
+	 *  - Handle PBDMA interrupts:
+	 *    - Set error notifier and reset method (if needed).
+	 *    - Report timeout, extra, pb, method, signature, hce and
+	 *      preempt errors.
+	 *  - Handle scheduling errors interrupts:
+	 *    - Log and report sched error.
+	 *  - Handle ctxsw timeout interrupts:
+	 *    - Get engines with ctxsw timeout.
+	 *    - Report error for TSGs on those engines.
+	 * - Release FIFO ISR mutex.
+	 * - Clear interrupts.
+	 *
+	 * @note: This HAL is called from a threaded interrupt context.
+	 */
+	void (*intr_0_isr)(struct gk20a *g);
+
+	/**
+	 * @brief ISR for non-stalling interrupts.
+	 *
+	 * @param g [in]		Pointer to GPU driver struct.
+	 *
+	 * Interrupt Service Routine for FIFO non-stalling interrupts:
+	 * - Read interrupt status.
+	 * - Clear channel interrupt if pending.
+	 *
+	 * @return: #GK20A_NONSTALL_OPS_WAKEUP_SEMAPHORE
+	 */
+	u32  (*intr_1_isr)(struct gk20a *g);
+
+	/** @cond DOXYGEN_SHOULD_SKIP_THIS */
+
 	int (*setup_sw)(struct gk20a *g);
 	void (*cleanup_sw)(struct gk20a *g);
 	int (*init_fifo_setup_hw)(struct gk20a *g);
 	int (*preempt_channel)(struct gk20a *g, struct nvgpu_channel *ch);
-	int (*preempt_tsg)(struct gk20a *g, struct nvgpu_tsg *tsg);
-	void (*preempt_runlists_for_rc)(struct gk20a *g,
-			u32 runlists_bitmask);
 	void (*preempt_trigger)(struct gk20a *g,
 			u32 id, unsigned int id_type);
 	int (*preempt_poll_pbdma)(struct gk20a *g, u32 tsgid,
@@ -47,13 +186,10 @@ struct gops_fifo {
 			u32 *pbdma_map, u32 num_pbdma);
 	int (*is_preempt_pending)(struct gk20a *g, u32 id,
 		unsigned int id_type);
-	int (*reset_enable_hw)(struct gk20a *g);
 	void (*intr_set_recover_mask)(struct gk20a *g);
 	void (*intr_unset_recover_mask)(struct gk20a *g);
 	void (*intr_0_enable)(struct gk20a *g, bool enable);
-	void (*intr_0_isr)(struct gk20a *g);
 	void (*intr_1_enable)(struct gk20a *g, bool enable);
-	u32  (*intr_1_isr)(struct gk20a *g);
 	bool (*handle_sched_error)(struct gk20a *g);
 	void (*ctxsw_timeout_enable)(struct gk20a *g, bool enable);
 	bool (*handle_ctxsw_timeout)(struct gk20a *g);
@@ -83,6 +219,8 @@ struct gops_fifo {
 			u32 exception_mask);
 #endif
 
+	/** @endcond DOXYGEN_SHOULD_SKIP_THIS */
+
 };
 
 #endif