From 41f38d8a5b972c15320b22778ff88484dc441a15 Mon Sep 17 00:00:00 2001 From: Tejal Kudav Date: Fri, 18 Oct 2019 18:39:30 +0530 Subject: [PATCH] gpu: nvgpu: Update common.top doxygen comments Add more details on how we parse the device_info table. Add @defgroup to pull in the external #defines related documentaion into SWUD. JIRA NVGPU-2500 Change-Id: I293631a7c19d5e73b4fbe164b11a94ebdb6acd82 Signed-off-by: Tejal Kudav Reviewed-on: https://git-master.nvidia.com/r/2221229 Reviewed-by: Deepak Nibade GVS: Gerrit_Virtual_Submit Reviewed-by: Vijayakumar Subbu Reviewed-by: mobile promotions Tested-by: mobile promotions --- drivers/gpu/nvgpu/include/nvgpu/gops_top.h | 37 +++++++++++++++++--- drivers/gpu/nvgpu/include/nvgpu/top.h | 40 +++++++++++++++++++--- 2 files changed, 68 insertions(+), 9 deletions(-) diff --git a/drivers/gpu/nvgpu/include/nvgpu/gops_top.h b/drivers/gpu/nvgpu/include/nvgpu/gops_top.h index 5007707b3..22c7c7642 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/gops_top.h +++ b/drivers/gpu/nvgpu/include/nvgpu/gops_top.h @@ -81,11 +81,12 @@ struct gops_top { * @param engine_type [in] Engine enumeration value * @param inst_id [in] Engine's instance identification number * - * Device_info table contains the engine specific data like it's - * interrupt enum, reset enum, pri_base etc. This HAL reads such engine - * information from table after matching the \a engine_type and - * \a inst_id and then populates the read information in \a dev_info - * struct. + * Device_info table is an array of registers which contains the engine + * specific data like interrupt enum, reset enum, pri_base etc. + * This HAL reads such engine information from table after matching the + * \a engine_type and \a inst_id and then populates the read information + * in \a dev_info struct. + * * List of valid engine enumeration values: * NVGPU_ENGINE_GRAPHICS 0 * NVGPU_ENGINE_COPY0 1 @@ -93,6 +94,32 @@ struct gops_top { * NVGPU_ENGINE_COPY2 3 * NVGPU_ENGINE_IOCTRL 18 * NVGPU_ENGINE_LCE 19 + + * In the device_info table, more than one register is required to + * denote information for a specific engine. So they use multiple + * consecutive registers in the array to represent a specific engine. + * The MSB (called chain bit) in each register denotes if the next + * register talks the same engine as present the one. All the registers + * in the device info table can be classified in one of 4 types - + * 1. Not_valid : We ignore these registers + * 2. Data: This type of register contains pri_base, fault_id etc + * 3. Enum: This type of register contains intr_enum, reset_enum + * 4. Engine_type: This type of register contains the engine name which + * is being described. + * + * So, in the parsing code, + * 1. We loop through the array + * 2. Ignore the invalid entries + * 3. Store the “linked” register values in temporary variables until + * chain_bit is set. This helps us get all the data for particular + * engine type. [This is needed because the engine name may not be + * part of the first register representing the engine. So we can’t + * just read the first register and determine if the group represents + * the engine we are interested in]. Once the chain_bit is disabled, + * we know the next register read would represent a new engine. + * 4. So we parse the stored variables to get engine_name, + * intr/reset_enums, pri base etc. Here we check if the engine type + * is the one we are interested in. * * @return 0 in case of success and < 0 in case of failure */ diff --git a/drivers/gpu/nvgpu/include/nvgpu/top.h b/drivers/gpu/nvgpu/include/nvgpu/top.h index 466fda3fe..c896338f6 100644 --- a/drivers/gpu/nvgpu/include/nvgpu/top.h +++ b/drivers/gpu/nvgpu/include/nvgpu/top.h @@ -31,16 +31,48 @@ struct gk20a; -/** Engine enum type graphics as defined by h/w. */ +/** + * @defgroup NVGPU_TOP_DEVICE_INFO_DEFINES + * + * List of engine enumeration values supported for device_info parsing + */ + +/** + * @ingroup NVGPU_TOP_DEVICE_INFO_DEFINES + * Engine type enum for graphics engine as defined by h/w. + */ #define NVGPU_ENGINE_GRAPHICS 0U -/** Obsolete from Pascal and beyond architecture. */ + +/** + * @ingroup NVGPU_TOP_DEVICE_INFO_DEFINES + * Engine type enum for copy engine instance 0 as defined by h/w. + * Obsolete for Pascal and chips beyond it. + */ #define NVGPU_ENGINE_COPY0 1U -/** Obsolete from Pascal and beyond architecture. */ + +/** + * @ingroup NVGPU_TOP_DEVICE_INFO_DEFINES + * Engine type enum for copy engine instance 1 as defined by h/w. + * Obsolete for Pascal and chips beyond it. + */ #define NVGPU_ENGINE_COPY1 2U -/** Obsolete from Pascal and beyond architecture. */ + +/** + * @ingroup NVGPU_TOP_DEVICE_INFO_DEFINES + * Engine type enum for copy engine instance 2 as defined by h/w. + * Obsolete for Pascal and chips beyond it. + */ #define NVGPU_ENGINE_COPY2 3U + #define NVGPU_ENGINE_IOCTRL 18U + +/** + * @ingroup NVGPU_TOP_DEVICE_INFO_DEFINES + * Engine type enum for all copy engine as defined by h/w. + * This enum type is used for copy engines on Pascal and chips beyond it. + */ /** Engine enum type lce as defined by h/w. */ + #define NVGPU_ENGINE_LCE 19U /**