From 6fa3e7f4186adbdcf9332d24c49d9b36c1f33f3f Mon Sep 17 00:00:00 2001 From: Philip Elcan Date: Thu, 18 Jul 2019 13:59:21 -0400 Subject: [PATCH] gpu: nvgpu: init: SWUD documentation Add doxygen documentation for nvgpu.common.init JIRA NVGPU-2385 Change-Id: Id305c3ba873431576c93909c959173afb4edb932 Signed-off-by: Philip Elcan Reviewed-on: https://git-master.nvidia.com/r/2156460 Reviewed-by: mobile promotions Tested-by: mobile promotions --- drivers/gpu/nvgpu/common/init/nvgpu_init.c | 16 --- drivers/gpu/nvgpu/include/nvgpu/gk20a.h | 1 + drivers/gpu/nvgpu/include/nvgpu/hal_init.h | 15 ++- drivers/gpu/nvgpu/include/nvgpu/nvgpu_init.h | 112 ++++++++++++++++++- 4 files changed, 126 insertions(+), 18 deletions(-) diff --git a/drivers/gpu/nvgpu/common/init/nvgpu_init.c b/drivers/gpu/nvgpu/common/init/nvgpu_init.c index cf30b2c38..bac11fb06 100644 --- a/drivers/gpu/nvgpu/common/init/nvgpu_init.c +++ b/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) { /* diff --git a/drivers/gpu/nvgpu/include/nvgpu/gk20a.h b/drivers/gpu/nvgpu/include/nvgpu/gk20a.h index 4e0c14354..a40bed25d 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/gk20a.h +++ b/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 diff --git a/drivers/gpu/nvgpu/include/nvgpu/hal_init.h b/drivers/gpu/nvgpu/include/nvgpu/hal_init.h index 06e58e706..96611a9cd 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/hal_init.h +++ b/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 */ diff --git a/drivers/gpu/nvgpu/include/nvgpu/nvgpu_init.h b/drivers/gpu/nvgpu/include/nvgpu/nvgpu_init.h index 7a21f0c8f..46502bf2e 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/nvgpu_init.h +++ b/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 */