gpu: nvgpu: init: SWUD documentation

Add doxygen documentation for nvgpu.common.init

JIRA NVGPU-2385

Change-Id: Id305c3ba873431576c93909c959173afb4edb932
Signed-off-by: Philip Elcan <pelcan@nvidia.com>
Reviewed-on: https://git-master.nvidia.com/r/2156460
Reviewed-by: mobile promotions <svcmobile_promotions@nvidia.com>
Tested-by: mobile promotions <svcmobile_promotions@nvidia.com>

drivers/gpu/nvgpu/common/init/nvgpu_init.c

@@ -664,14 +664,6 @@ static void gk20a_free_cb(struct nvgpu_ref *refcount)
 	}
 }
 
-/**
- * nvgpu_get() - Increment ref count on driver
- *
- * @g The driver to increment
- * This will fail if the driver is in the process of being released. In that
- * case it will return NULL. Otherwise a pointer to the driver passed in will
- * be returned.
- */
 struct gk20a * __must_check nvgpu_get(struct gk20a *g)
 {
 	int success;
@@ -691,14 +683,6 @@ struct gk20a * __must_check nvgpu_get(struct gk20a *g)
 	return (success != 0) ? g : NULL;
 }
 
-/**
- * nvgpu_put() - Decrement ref count on driver
- *
- * @g - The driver to decrement
- *
- * Decrement the driver ref-count. If neccesary also free the underlying driver
- * memory
- */
 void nvgpu_put(struct gk20a *g)
 {
 	/*

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

@@ -36,6 +36,7 @@
  *   - @ref unit-mm
  *   - @ref unit-fifo
  *   - @ref unit-sdl
+ *   - @ref unit-init
  *   - Etc, etc.
  *
  * nvgpu-driver Level Requirements Table

drivers/gpu/nvgpu/include/nvgpu/hal_init.h

@@ -1,7 +1,7 @@
 /*
  * NVIDIA GPU Hardware Abstraction Layer functions definitions.
  *
- * Copyright (c) 2014-2018, NVIDIA CORPORATION.  All rights reserved.
+ * Copyright (c) 2014-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"),
@@ -28,6 +28,19 @@
 struct gk20a;
 
 int nvgpu_init_hal(struct gk20a *g);
+
+/**
+ * @brief Detect GPU and initialize the HAL.
+ *
+ * @param g [in] The GPU
+ *
+ * Initializes GPU units in the GPU driver. Each sub-unit is responsible for HW
+ * initialization.
+ *
+ * Note: Requires the GPU is already powered on.
+ *
+ * @return 0 in case of success, < 0 in case of failure.
+ */
 int nvgpu_detect_chip(struct gk20a *g);
 
 #endif /* NVGPU_HAL_INIT_H */

drivers/gpu/nvgpu/include/nvgpu/nvgpu_init.h

@@ -23,17 +23,127 @@
 #ifndef NVGPU_INIT_H
 #define NVGPU_INIT_H
 
+/**
+ * @file
+ * @page unit-init Unit Init
+ *
+ * Overview
+ * ========
+ *
+ * The Init unit is called by OS (QNX, Linux) to initialize or teardown the
+ * driver. The Init unit ensures all the other sub-units are initialized so the
+ * driver is able to provide general functionality to the application.
+ *
+ * Static Design
+ * =============
+ *
+ * HAL Initialization
+ * ------------------
+ * The HAL must be initialized before the nvgpu_finalize_poweron() is called.
+ * This is accomplished by calling nvgpu_detect_chip() which will determine
+ * which GPU is in the system and configure the HAL interfaces.
+ *
+ * Common Initialization
+ * ---------------------
+ * The main driver initialization occurs by calling nvgpu_finalize_poweron()
+ * which will initialize all of the common units in the driver and must be done
+ * before the driver is ready to provide full functionality.
+ *
+ * Common Teardown
+ * ---------------
+ * If the GPU is unused, the driver can be torn down by calling
+ * nvgpu_prepare_poweroff().
+ *
+ * External APIs
+ * -------------
+ * + nvgpu_detect_chip() - Called to initialize the HAL.
+ * + nvgpu_finalize_poweron() - Called to initialize nvgpu driver.
+ * + nvgpu_prepare_poweroff() - Called before powering off GPU HW.
+ * + nvgpu_init_gpu_characteristics() - Called during HAL init for enable flag
+ * processing.
+ *
+ * Dynamic Design
+ * ==============
+ * After initialization, the Init unit provides a number of APIs to track state
+ * and usage count.
+ *
+ * External APIs
+ * -------------
+ * + nvgpu_get() / nvgpu_put() - Maintains ref count for usage.
+ * + nvgpu_can_busy() - Check to make sure driver is ready to go busy.
+ * + nvgpu_check_gpu_state() - Restart if the state is invalid.
+ */
+
+/**
+ * @brief Final driver initialization
+ *
+ * @param g [in] The GPU
+ *
+ * Initializes GPU units in the GPU driver. Each sub-unit is responsible for HW
+ * initialization.
+ *
+ * Note: Requires the GPU is already powered on and the HAL is initialized.
+ *
+ * @return 0 in case of success, < 0 in case of failure.
+ */
 int nvgpu_finalize_poweron(struct gk20a *g);
+
+/**
+ * @brief Prepare driver for poweroff
+ *
+ * @param g [in] The GPU
+ *
+ * Prepare the driver subsystems and HW for powering off GPU.
+ *
+ * @return 0 in case of success, < 0 in case of failure.
+ */
 int nvgpu_prepare_poweroff(struct gk20a *g);
 
+/**
+ * @brief Check if the device can go busy
+ *
+ * @param g [in] The GPU
+ *
+ * @return 1 if it ok to go busy, 0 if it is not ok to go busy.
+ */
 int nvgpu_can_busy(struct gk20a *g);
 
+/**
+ * @brief Increment ref count on driver.
+ *
+ * @param g [in] The GPU
+ *
+ * This will fail if the driver is in the process of being released.
+ *
+ * @return pointer to g if successful, otherwise 0.
+ */
 struct gk20a * __must_check nvgpu_get(struct gk20a *g);
+
+/**
+ * @brief Decrement ref count on driver.
+ *
+ * @param g [in] The GPU
+ *
+ * Will free underlying driver memory if driver is no longer in use.
+ */
 void nvgpu_put(struct gk20a *g);
 
-/* register accessors */
+/**
+ * @brief Check driver state and restart if the state is invalid
+ *
+ * @param g [in] The GPU
+ *
+ * If driver state is invalid, makes OS call to restart driver.
+ */
 void nvgpu_check_gpu_state(struct gk20a *g);
 
+/**
+ * @brief Configure initial GPU "enable" state and setup SM arch.
+ *
+ * @param g [in] The GPU
+ *
+ * This is called during HAL initialization.
+ */
 void nvgpu_init_gpu_characteristics(struct gk20a *g);
 
 #endif /* NVGPU_INIT_H */