gpu: nvgpu: doxygen for usermode HAL

Add documentation for usermode HALs that are called
from other units:
- base
- doorbell_token

Jira NVGPU-4040

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

arch/nvgpu-common.yaml

@@ -376,6 +376,10 @@ fifo:
                  include/nvgpu/gops_fifo.h,
                  include/nvgpu/fifo.h ]
 
+    usermode:
+      safe: yes
+      sources: [ include/nvgpu/gops_usermode.h ]
+
 gr:
   safe: yes
   owner: Deepak N

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

@@ -110,6 +110,14 @@
  *
  *   + include/nvgpu/gops_sync.h
  *
+ * Usermode
+ * --------
+ *
+ * TODO
+ *
+ *   + include/nvgpu/gops_usermode.h
+ *
+ *
  * Data Structures
  * ===============
  *

drivers/gpu/nvgpu/include/nvgpu/gk20a.h

@@ -144,6 +144,7 @@ enum nvgpu_unit;
 #include <nvgpu/gops_sync.h>
 #include <nvgpu/gops_channel.h>
 #include <nvgpu/gops_tsg.h>
+#include <nvgpu/gops_usermode.h>
 #include <nvgpu/gops_mm.h>
 #include <nvgpu/gops_therm.h>
 
@@ -446,13 +447,7 @@ struct gpu_ops {
 	struct gops_sync sync;
 	struct gops_channel channel;
 	struct gops_tsg tsg;
-	struct {
-		void (*setup_hw)(struct gk20a *g);
-		void (*ring_doorbell)(struct nvgpu_channel *ch);
-		u32 (*doorbell_token)(struct nvgpu_channel *ch);
-		u64 (*base)(struct gk20a *g);
-		u64 (*bus_base)(struct gk20a *g);
-	} usermode;
+	struct gops_usermode usermode;
 	struct gops_engine_status engine_status;
 	struct gops_pbdma_status pbdma_status;
 	struct {

drivers/gpu/nvgpu/include/nvgpu/gops_usermode.h

@@ -0,0 +1,80 @@
+/*
+ * Copyright (c) 2019, NVIDIA CORPORATION.  All rights reserved.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a
+ * copy of this software and associated documentation files (the "Software"),
+ * to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+ * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ * DEALINGS IN THE SOFTWARE.
+ */
+#ifndef NVGPU_GOPS_USERMODE_H
+#define NVGPU_GOPS_USERMODE_H
+
+#include <nvgpu/types.h>
+
+/**
+ * @file
+ *
+ * Usermode HAL interface.
+ */
+struct gk20a;
+struct nvgpu_channel;
+
+/**
+ * @file
+ *
+ * Usermode HAL operations.
+ */
+struct gops_usermode {
+
+	/**
+	 * @brief Base address for usermode drivers.
+	 *
+	 * @param g [in]	Pointer to GPU driver struct.
+	 *
+	 * Usermode is a mappable range of registers for use by usermode
+	 * drivers.
+	 *
+	 * @return 64-bit base address for usermode accessible registers.
+	 */
+	u64 (*base)(struct gk20a *g);
+
+	/**
+	 * @brief Doorbell token.
+	 *
+	 * @param ch [in]	Channel Pointer.
+	 *
+	 * The function builds a doorbell token for channel \a ch.
+	 *
+	 * This token is used to notify H/W that new work is available for
+	 * a given channel. This allows "usermode submit", where application
+	 * handles GP and PB entries by itself, then writes token to submit
+	 * work, without intervention of nvgpu rm.
+	 *
+	 * @return 32-bit token to ring doorbell for channel \a ch.
+	 */
+	u32 (*doorbell_token)(struct nvgpu_channel *ch);
+
+/** @cond DOXYGEN_SHOULD_SKIP_THIS */
+
+	void (*setup_hw)(struct gk20a *g);
+	void (*ring_doorbell)(struct nvgpu_channel *ch);
+	u64 (*bus_base)(struct gk20a *g);
+
+/** @endcond DOXYGEN_SHOULD_SKIP_THIS */
+};
+
+
+#endif