From 93e7bb67b5ccf914982ba219c3d4c17f1a8c246e Mon Sep 17 00:00:00 2001 From: Seema Khowala Date: Mon, 10 Jun 2019 10:43:56 -0700 Subject: [PATCH] gpu: nvgpu: Add doxygen documentation in engine_status.h JIRA NVGPU-3590 Change-Id: I91eb1df2b19923dd008b613e831b7143bca333d4 Signed-off-by: Seema Khowala Reviewed-on: https://git-master.nvidia.com/r/2133735 GVS: Gerrit_Virtual_Submit Reviewed-by: Alex Waterman Reviewed-by: mobile promotions Tested-by: mobile promotions --- .../gpu/nvgpu/include/nvgpu/engine_status.h | 159 +++++++++++++++++- 1 file changed, 157 insertions(+), 2 deletions(-) diff --git a/drivers/gpu/nvgpu/include/nvgpu/engine_status.h b/drivers/gpu/nvgpu/include/nvgpu/engine_status.h index ff92bd060..79e0446e4 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/engine_status.h +++ b/drivers/gpu/nvgpu/include/nvgpu/engine_status.h @@ -22,7 +22,11 @@ #ifndef NVGPU_ENGINE_STATUS_H #define NVGPU_ENGINE_STATUS_H - +/** + * @file + * + * Abstract interface for interpreting engine status info read from h/w. + */ #define ENGINE_STATUS_CTX_ID_TYPE_CHID 0U #define ENGINE_STATUS_CTX_ID_TYPE_TSGID 1U #define ENGINE_STATUS_CTX_ID_TYPE_INVALID (~U32(0U)) @@ -35,46 +39,197 @@ #define ENGINE_STATUS_CTX_NEXT_ID_INVALID ENGINE_STATUS_CTX_ID_INVALID enum nvgpu_engine_status_ctx_status { + /** Context is not loaded on engine. Both id and next_id are invalid. */ NVGPU_CTX_STATUS_INVALID, + /** + * Context is loaded on the engine. id field of engine_status + * h/w register is valid. Since no context is on deck for switching, + * next_id is not valid. + */ NVGPU_CTX_STATUS_VALID, + /** + * Host is loading a new context and the previous context is + * invalid. In this state only next_id is valid. + */ NVGPU_CTX_STATUS_CTXSW_LOAD, + /** + * Host is saving the current context and not loading a new one. + * In this state only id is valid. + */ NVGPU_CTX_STATUS_CTXSW_SAVE, + /** + * Host is switching between two valid contexts. In this state both + * id and next_id are valid. + */ NVGPU_CTX_STATUS_CTXSW_SWITCH, }; struct nvgpu_engine_status_info { + /** Engine status h/w register's read value. */ u32 reg_data; + /** Channel or tsg id that is currently assigned to the engine. */ u32 ctx_id; + /** Ctx_status field of engine_status h/w register. */ u32 ctxsw_state; + /** Specifies whether ctx_id is of channel or tsg type. */ u32 ctx_id_type; + /** Channel or tsg id that will be assigned to the engine. */ u32 ctx_next_id; + /** Specifies whether ctx_next_id is of channel or tsg type. */ u32 ctx_next_id_type; - + /** + * Field, is_faulted is applicable for ce engine only and should be + * ignored for other types of engines. This is set when host + * receives a fault message from ce engine. + */ bool is_faulted; + /** + * Field, is_busy is set if engine is not idle. Host will report + * non-idle if Host is about to send methods as well as when a context + * request is outstanding to the engine, even when the engine itself is + * idle. + */ bool is_busy; + /** + * Set to true if host is switching between two valid contexts. + */ bool ctxsw_in_progress; + /** + * This is applicable to gr and ce engines. + * if #in_reload_status is set to true and #ctxsw_status is + * #NVGPU_CTX_STATUS_VALID, it indicates that the context currently on + * the engine was reloaded. + * if #in_reload_status is set to true and #ctxsw_status is + * #NVGPU_CTX_STATUS_INVALID, it indicates that the last context on the + * channel was reloaded. + */ bool in_reload_status; + /** Enum for ctx_status field of engine_status h/w register */ enum nvgpu_engine_status_ctx_status ctxsw_status; }; +/** + * nvgpu_engine_status_is_ctxsw_switch - Check if #ctxsw_status is set to + * switch. + * + * @param engine_status - Pointer to struct containing engine_status h/w + * reg/field value. + * + * This interprets #engine_status and returns true if channel + * status is set to #NVGPU_CTX_STATUS_CTXSW_SWITCH. + */ bool nvgpu_engine_status_is_ctxsw_switch(struct nvgpu_engine_status_info *engine_status); +/** + * nvgpu_engine_status_is_ctxsw_load - Check if #ctxsw_status is set to load. + * + * @param engine_status - Pointer to struct containing engine_status h/w + * reg/field value. + * + * This interprets #engine_status and returns true if channel + * status is set to #NVGPU_CTX_STATUS_CTXSW_LOAD. + */ bool nvgpu_engine_status_is_ctxsw_load(struct nvgpu_engine_status_info *engine_status); +/** + * nvgpu_engine_status_is_ctxsw_save - Check if #ctxsw_status is set to save. + * + * @param engine_status - Pointer to struct containing engine_status h/w + * reg/field value. + * + * This interprets #engine_status and returns true if channel + * status is set to #NVGPU_CTX_STATUS_CTXSW_SAVE. + */ bool nvgpu_engine_status_is_ctxsw_save(struct nvgpu_engine_status_info *engine_status); +/** + * nvgpu_engine_status_is_ctxsw - Check if #ctxsw_status is set to switch + * or load or save. + * + * @param engine_status - Pointer to struct containing engine_status h/w + * reg/field value. + * + * This interprets #engine_status and returns true if channel + * status is set to #NVGPU_CTX_STATUS_CTXSW_SWITCH or + * #NVGPU_CTX_STATUS_CTXSW_LOAD or #NVGPU_CTX_STATUS_CTXSW_SAVE. + */ bool nvgpu_engine_status_is_ctxsw(struct nvgpu_engine_status_info *engine_status); +/** + * nvgpu_engine_status_is_ctxsw_invalid - Check if #ctxsw_status is set to + * invalid. + * + * @param engine_status - Pointer to struct containing engine_status h/w + * reg/field value. + * + * This interprets #engine_status and returns true if channel + * status is set to #NVGPU_CTX_STATUS_INVALID. + */ bool nvgpu_engine_status_is_ctxsw_invalid(struct nvgpu_engine_status_info *engine_status); +/** + * nvgpu_engine_status_is_ctxsw_valid - Check if #ctxsw_status is set to + * valid. + * + * @param engine_status - Pointer to struct containing engine_status h/w + * reg/field value. + * + * This interprets #engine_status and returns true if channel + * status is set to #NVGPU_CTX_STATUS_VALID. + */ bool nvgpu_engine_status_is_ctxsw_valid(struct nvgpu_engine_status_info *engine_status); +/** + * nvgpu_engine_status_is_ctx_type_tsg - Check if #ctx_id_type is tsg. + * + * @param engine_status - Pointer to struct containing engine_status h/w + * reg/field value. + * + * This interprets #engine_status and returns true if #ctx_id_type + * is #ENGINE_STATUS_CTX_ID_TYPE_TSGID. + */ bool nvgpu_engine_status_is_ctx_type_tsg(struct nvgpu_engine_status_info *engine_status); +/** + * nvgpu_engine_status_is_next_ctx_type_tsg - Check if #ctx_next_id_type is tsg. + * + * @param engine_status - Pointer to struct containing engine_status h/w + * reg/field value. + * + * This interprets #engine_status and returns true if + * #ctx_next_id_type is #ENGINE_STATUS_CTX_NEXT_ID_TYPE_TSGID. + */ bool nvgpu_engine_status_is_next_ctx_type_tsg(struct nvgpu_engine_status_info *engine_status); +/** + * nvgpu_engine_status_get_ctx_id_type - get ctx_id and ctx_id_type info. + * + * @param engine_status - Pointer to struct containing engine_status h/w + * reg/field value. + * @param ctx_id - Pointer that is updated with #ctx_id as set in + * input param #engine_status. + * @param ctx_type - Pointer that is updated with #ctx_id_type as set + * in input param #engine_status. + * + * This interprets #engine_status and updates input params #ctx_id + * and #ctx_type. + */ void nvgpu_engine_status_get_ctx_id_type(struct nvgpu_engine_status_info *engine_status, u32 *ctx_id, u32 *ctx_type); +/** + * nvgpu_engine_status_get_next_ctx_id_type - get next_ctx_id and + * next_ctx_id_type info. + * + * @param engine_status - Pointer to struct containing engine_status h/w + * reg/field value. + * @param ctx_next_id - Pointer that is updated with #ctx_next_id as set + * in input param #engine_status. + * @param ctx_next_type - Pointer that is updated with #ctx_next_id_type + * as set in input param #engine_status. + * + * This interprets #engine_status and updates input params + * #ctx_next_id and #ctx_next_type. + */ void nvgpu_engine_status_get_next_ctx_id_type(struct nvgpu_engine_status_info *engine_status, u32 *ctx_next_id, u32 *ctx_next_type);