From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mgamail.intel.com (mgamail.intel.com [192.55.52.88]) by gabe.freedesktop.org (Postfix) with ESMTPS id 7BC3D10E886 for ; Wed, 11 Oct 2023 14:19:08 +0000 (UTC) From: Francois Dugast To: igt-dev@lists.freedesktop.org Date: Wed, 11 Oct 2023 14:18:30 +0000 Message-Id: <20231011141841.7-10-francois.dugast@intel.com> In-Reply-To: <20231011141841.7-1-francois.dugast@intel.com> References: <20231011141841.7-1-francois.dugast@intel.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: [igt-dev] [RFC v1 09/20] drm-uapi/xe: Make constant comments visible in kernel doc List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: igt-dev-bounces@lists.freedesktop.org Sender: "igt-dev" List-ID: Align with commit ("Make constant comments visible in kernel doc") Signed-off-by: Francois Dugast --- include/drm-uapi/xe_drm.h | 274 +++++++++++++++++++++----------------- 1 file changed, 155 insertions(+), 119 deletions(-) diff --git a/include/drm-uapi/xe_drm.h b/include/drm-uapi/xe_drm.h index 7d0a5adc5..250f955cc 100644 --- a/include/drm-uapi/xe_drm.h +++ b/include/drm-uapi/xe_drm.h @@ -126,23 +126,40 @@ struct xe_user_extension { #define DRM_IOCTL_XE_WAIT_USER_FENCE DRM_IOWR(DRM_COMMAND_BASE + DRM_XE_WAIT_USER_FENCE, struct drm_xe_wait_user_fence) #define DRM_IOCTL_XE_VM_MADVISE DRM_IOW(DRM_COMMAND_BASE + DRM_XE_VM_MADVISE, struct drm_xe_vm_madvise) -/** struct drm_xe_engine_class_instance - instance of an engine class */ +/** + * struct drm_xe_engine_class_instance - instance of an engine class + * + * The @engine_class can be: + * - %DRM_XE_ENGINE_CLASS_RENDER + * - %DRM_XE_ENGINE_CLASS_COPY + * - %DRM_XE_ENGINE_CLASS_VIDEO_DECODE + * - %DRM_XE_ENGINE_CLASS_VIDEO_ENHANCE + * - %DRM_XE_ENGINE_CLASS_COMPUTE + * - %DRM_XE_ENGINE_CLASS_VM_BIND_ASYNC - Kernel only class (not actual + * hardware engine class) used for creating ordered queues of + * asynchronous VM bind operations. + * - %DRM_XE_ENGINE_CLASS_VM_BIND_SYNC - Kernel only class (not actual + * synchronous VM bind operations. + * + */ struct drm_xe_engine_class_instance { #define DRM_XE_ENGINE_CLASS_RENDER 0 #define DRM_XE_ENGINE_CLASS_COPY 1 #define DRM_XE_ENGINE_CLASS_VIDEO_DECODE 2 #define DRM_XE_ENGINE_CLASS_VIDEO_ENHANCE 3 #define DRM_XE_ENGINE_CLASS_COMPUTE 4 - /* - * Kernel only classes (not actual hardware engine class). Used for - * creating ordered queues of VM bind operations. - */ #define DRM_XE_ENGINE_CLASS_VM_BIND_ASYNC 5 #define DRM_XE_ENGINE_CLASS_VM_BIND_SYNC 6 + /** + * @engine_class: Class of this instance among possible + * DRM_XE_ENGINE_CLASS_* + */ __u16 engine_class; - + /** @engine_instance: Engine instance */ __u16 engine_instance; + /** @gt_id: GT ID the instance is associated with */ __u16 gt_id; + /** @rsvd: Reserved */ __u16 rsvd; }; @@ -313,44 +330,36 @@ struct drm_xe_query_mem_usage { * If a query is made with a struct drm_xe_device_query where .query * is equal to DRM_XE_DEVICE_QUERY_CONFIG, then the reply uses * struct drm_xe_query_config in .data. + * + * The index in @info can be: + * - %DRM_XE_QUERY_CONFIG_REV_AND_DEVICE_ID - Device ID (lower 16 bits) + * and the device revision (next 8 bits) + * - %DRM_XE_QUERY_CONFIG_FLAGS - Flags describing the device + * configuration, see list below + * + * - %DRM_XE_QUERY_CONFIG_FLAGS_HAS_VRAM - Flag is set if the device + * has usable VRAM + * - %DRM_XE_QUERY_CONFIG_MIN_ALIGNMENT - Minimal memory alignment + * required by this device, typically SZ_4K or SZ_64K + * - %DRM_XE_QUERY_CONFIG_VA_BITS - Maximum bits of a virtual address + * - %DRM_XE_QUERY_CONFIG_GT_COUNT - Total number of GTs for the entire + * device + * - %DRM_XE_QUERY_CONFIG_MEM_REGION_COUNT - Total number of accessible + * memory regions + * - %DRM_XE_QUERY_CONFIG_MAX_EXEC_QUEUE_PRIORITY - Value of the highest + * available exec queue priority */ struct drm_xe_query_config { /** @pad: MBZ */ __u32 pad; - /* - * Device ID (lower 16 bits) and the device revision (next - * 8 bits) - */ #define DRM_XE_QUERY_CONFIG_REV_AND_DEVICE_ID 0 - /* - * Flags describing the device configuration, see list below - */ #define DRM_XE_QUERY_CONFIG_FLAGS 1 - /* - * Flag is set if the device has usable VRAM - */ #define DRM_XE_QUERY_CONFIG_FLAGS_HAS_VRAM (0x1 << 0) - /* - * Minimal memory alignment required by this device, - * typically SZ_4K or SZ_64K - */ #define DRM_XE_QUERY_CONFIG_MIN_ALIGNMENT 2 - /* - * Maximum bits of a virtual address - */ #define DRM_XE_QUERY_CONFIG_VA_BITS 3 - /* - * Total number of GTs for the entire device - */ #define DRM_XE_QUERY_CONFIG_GT_COUNT 4 - /* - * Total number of accessible memory regions - */ #define DRM_XE_QUERY_CONFIG_MEM_REGION_COUNT 5 - /* - * Value of the highest available exec queue priority - */ #define DRM_XE_QUERY_CONFIG_MAX_EXEC_QUEUE_PRIORITY 6 /** @info: array of elements containing the config info */ __u64 info[]; @@ -363,6 +372,7 @@ struct drm_xe_query_config { * existing GT individual descriptions. * Graphics Technology (GT) is a subset of a GPU/tile that is responsible for * implementing graphics and/or media operations. + * */ struct drm_xe_query_gt { #define DRM_XE_QUERY_GT_TYPE_MAIN 0 @@ -420,34 +430,31 @@ struct drm_xe_query_gt_list { * If a query is made with a struct drm_xe_device_query where .query * is equal to DRM_XE_DEVICE_QUERY_GT_TOPOLOGY, then the reply uses * struct drm_xe_query_topology_mask in .data. + * + * The @type can be: + * - %DRM_XE_TOPO_DSS_GEOMETRY - To query the mask of Dual Sub Slices + * (DSS) available for geometry operations. For example a query response + * containing the following in mask: + * ``DSS_GEOMETRY ff ff ff ff 00 00 00 00`` + * means 32 DSS are available for geometry. + * - %DRM_XE_TOPO_DSS_COMPUTE - To query the mask of Dual Sub Slices + * (DSS) available for compute operations. For example a query response + * containing the following in mask: + * ``DSS_COMPUTE ff ff ff ff 00 00 00 00`` + * means 32 DSS are available for compute. + * - %DRM_XE_TOPO_EU_PER_DSS - To query the mask of Execution Units (EU) + * available per Dual Sub Slices (DSS). For example a query response + * containing the following in mask: + * ``EU_PER_DSS ff ff 00 00 00 00 00 00`` + * means each DSS has 16 EU. + * */ struct drm_xe_query_topology_mask { /** @gt_id: GT ID the mask is associated with */ __u16 gt_id; - /* - * To query the mask of Dual Sub Slices (DSS) available for geometry - * operations. For example a query response containing the following - * in mask: - * DSS_GEOMETRY ff ff ff ff 00 00 00 00 - * means 32 DSS are available for geometry. - */ #define DRM_XE_TOPO_DSS_GEOMETRY (1 << 0) - /* - * To query the mask of Dual Sub Slices (DSS) available for compute - * operations. For example a query response containing the following - * in mask: - * DSS_COMPUTE ff ff ff ff 00 00 00 00 - * means 32 DSS are available for compute. - */ #define DRM_XE_TOPO_DSS_COMPUTE (1 << 1) - /* - * To query the mask of Execution Units (EU) available per Dual Sub - * Slices (DSS). For example a query response containing the following - * in mask: - * EU_PER_DSS ff ff 00 00 00 00 00 00 - * means each DSS has 16 EU. - */ #define DRM_XE_TOPO_EU_PER_DSS (1 << 2) /** @type: type of mask */ __u16 type; @@ -466,7 +473,7 @@ struct drm_xe_query_topology_mask { * of the micro-controller firmware. */ struct drm_xe_query_uc_fw_version { - /** @uc: The micro-controller type to query firmware version */ + /** @uc_type: The micro-controller type to query firmware version */ #define DRM_XE_QUERY_UC_TYPE_GUC 0 #define DRM_XE_QUERY_UC_TYPE_HUC 1 __u16 uc_type; @@ -474,13 +481,13 @@ struct drm_xe_query_uc_fw_version { /** @pad: MBZ */ __u16 pad; - /* @major_ver: major uc fw version */ + /** @major_ver: major uc fw version */ __u32 major_ver; - /* @minor_ver: minor uc fw version */ + /** @minor_ver: minor uc fw version */ __u32 minor_ver; - /* @patch_ver: patch uc fw version */ + /** @patch_ver: patch uc fw version */ __u32 patch_ver; - /* @branch_ver: branch uc fw version */ + /** @branch_ver: branch uc fw version */ __u32 branch_ver; /** @pad2: MBZ */ @@ -497,6 +504,19 @@ struct drm_xe_query_uc_fw_version { * and sets the value in the query member. This determines the type of * the structure provided by the driver in data, among struct drm_xe_query_*. * + * The @query can be: + * - %DRM_XE_DEVICE_QUERY_ENGINES + * - %DRM_XE_DEVICE_QUERY_MEM_USAGE + * - %DRM_XE_DEVICE_QUERY_CONFIG + * - %DRM_XE_DEVICE_QUERY_GT_LIST - Query type to retrieve the hardware + * configuration of the device such as information on slices, memory, + * caches, and so on. It is provided as a table of key / value + * attributes. + * - %DRM_XE_DEVICE_QUERY_HWCONFIG + * - %DRM_XE_DEVICE_QUERY_GT_TOPOLOGY + * - %DRM_XE_DEVICE_QUERY_ENGINE_CYCLES + * - %DRM_XE_DEVICE_QUERY_UC_FW_VERSION + * * If size is set to 0, the driver fills it with the required size for * the requested type of data to query. If size is equal to the required * size, the queried information is copied into data. If size is set to @@ -539,11 +559,6 @@ struct drm_xe_device_query { #define DRM_XE_DEVICE_QUERY_MEM_USAGE 1 #define DRM_XE_DEVICE_QUERY_CONFIG 2 #define DRM_XE_DEVICE_QUERY_GT_LIST 3 - /* - * Query type to retrieve the hardware configuration of the device - * such as information on slices, memory, caches, and so on. It is - * provided as a table of attributes (key / value). - */ #define DRM_XE_DEVICE_QUERY_HWCONFIG 4 #define DRM_XE_DEVICE_QUERY_GT_TOPOLOGY 5 #define DRM_XE_DEVICE_QUERY_ENGINE_CYCLES 6 @@ -561,6 +576,29 @@ struct drm_xe_device_query { __u64 reserved[2]; }; +/** + * struct drm_xe_gem_create - structure for gem creation + * + * The @flags can be: + * - %DRM_XE_GEM_CREATE_FLAG_DEFER_BACKING + * - %DRM_XE_GEM_CREATE_FLAG_SCANOUT + * - %DRM_XE_GEM_CREATE_FLAG_NEEDS_VISIBLE_VRAM - When using VRAM as a + * possible placement, ensure that the corresponding VRAM allocation + * will always use the CPU accessible part of VRAM. This is important + * for small-bar systems (on full-bar systems this gets turned into a + * noop). + * Note1: System memory can be used as an extra placement if the kernel + * should spill the allocation to system memory, if space can't be made + * available in the CPU accessible part of VRAM (giving the same + * behaviour as the i915 interface, see + * I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS). + * Note2: For clear-color CCS surfaces the kernel needs to read the + * clear-color value stored in the buffer, and on discrete platforms we + * need to use VRAM for display surfaces, therefore the kernel requires + * setting this flag for such objects, otherwise an error is thrown on + * small-bar systems. + * + */ struct drm_xe_gem_create { /** @extensions: Pointer to the first extension struct, if any */ __u64 extensions; @@ -574,21 +612,6 @@ struct drm_xe_gem_create { #define DRM_XE_GEM_CREATE_FLAG_DEFER_BACKING (0x1 << 24) #define DRM_XE_GEM_CREATE_FLAG_SCANOUT (0x1 << 25) -/* - * When using VRAM as a possible placement, ensure that the corresponding VRAM - * allocation will always use the CPU accessible part of VRAM. This is important - * for small-bar systems (on full-bar systems this gets turned into a noop). - * - * Note: System memory can be used as an extra placement if the kernel should - * spill the allocation to system memory, if space can't be made available in - * the CPU accessible part of VRAM (giving the same behaviour as the i915 - * interface, see I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS). - * - * Note: For clear-color CCS surfaces the kernel needs to read the clear-color - * value stored in the buffer, and on discrete platforms we need to use VRAM for - * display surfaces, therefore the kernel requires setting this flag for such - * objects, otherwise an error is thrown on small-bar systems. - */ #define DRM_XE_GEM_CREATE_FLAG_NEEDS_VISIBLE_VRAM (0x1 << 26) /** * @flags: Flags, currently a mask of memory instances of where BO can @@ -685,6 +708,30 @@ struct drm_xe_vm_destroy { __u64 reserved[2]; }; +/** + * struct drm_xe_vm_bind_op - run bind operations + * + * The @op can be: + * - %DRM_XE_VM_BIND_OP_MAP + * - %DRM_XE_VM_BIND_OP_UNMAP + * - %DRM_XE_VM_BIND_OP_MAP_USERPTR + * - %DRM_XE_VM_BIND_OP_UNMAP_ALL + * - %DRM_XE_VM_BIND_OP_PREFETCH + * + * and the @flags can be: + * - %DRM_XE_VM_BIND_FLAG_READONLY + * - %DRM_XE_VM_BIND_FLAG_ASYNC + * - %DRM_XE_VM_BIND_FLAG_IMMEDIATE - Valid on a faulting VM only, do the + * MAP operation immediately rather than deferring the MAP to the page + * fault handler. + * - %DRM_XE_VM_BIND_FLAG_NULL - When the NULL flag is set, the page + * tables are setup with a special bit which indicates writes are + * dropped and all reads return zero. In the future, the NULL flags + * will only be valid for DRM_XE_VM_BIND_OP_MAP operations, the BO + * handle MBZ, and the BO offset MBZ. This flag is intended to + * implement VK sparse bindings. + * + */ struct drm_xe_vm_bind_op { /** @extensions: Pointer to the first extension struct, if any */ __u64 extensions; @@ -732,23 +779,12 @@ struct drm_xe_vm_bind_op { #define DRM_XE_VM_BIND_FLAG_READONLY (0x1 << 0) #define DRM_XE_VM_BIND_FLAG_ASYNC (0x1 << 1) - /* - * Valid on a faulting VM only, do the MAP operation immediately rather - * than deferring the MAP to the page fault handler. - */ #define DRM_XE_VM_BIND_FLAG_IMMEDIATE (0x1 << 2) - /* - * When the NULL flag is set, the page tables are setup with a special - * bit which indicates writes are dropped and all reads return zero. In - * the future, the NULL flags will only be valid for DRM_XE_VM_BIND_OP_MAP - * operations, the BO handle MBZ, and the BO offset MBZ. This flag is - * intended to implement VK sparse bindings. - */ #define DRM_XE_VM_BIND_FLAG_NULL (0x1 << 3) /** @flags: Bind flags */ __u32 flags; - /** @mem_region: Memory region to prefetch VMA to, instance not a mask */ + /** @region: Memory region to prefetch VMA to, instance not a mask */ __u32 region; /** @reserved: Reserved */ @@ -1034,6 +1070,35 @@ struct drm_xe_wait_user_fence { __u64 reserved[2]; }; +/** + * struct drm_xe_vm_madvise - give advice about use of memory + * + * The @property can be: + * - %DRM_XE_VM_MADVISE_PREFERRED_MEM_CLASS - Setting the preferred + * location will trigger a migrate of the VMA backing store to new + * location if the backing store is already allocated. + * For DRM_XE_VM_MADVISE_PREFERRED_MEM_CLASS usage, see enum + * drm_xe_memory_class. + * - %DRM_XE_VM_MADVISE_PREFERRED_GT + * - %DRM_XE_VM_MADVISE_PREFERRED_MEM_CLASS_GT - In this case lower 32 bits + * are mem class, upper 32 are GT. Combination provides a single IOCTL + * plus migrate VMA to preferred location. + * - %DRM_XE_VM_MADVISE_CPU_ATOMIC - The CPU will do atomic memory + * operations to this VMA. Must be set on some devices for atomics to + * behave correctly. + * - %DRM_XE_VM_MADVISE_DEVICE_ATOMIC - The device will do atomic memory + * operations to this VMA. Must be set on some devices for atomics to + * behave correctly. + * - %DRM_XE_VM_MADVISE_PRIORITY - Priority WRT to eviction (moving from + * preferred memory location due to memory pressure). The lower the + * priority, the more likely to be evicted. + * + * - %DRM_XE_VMA_PRIORITY_LOW + * - %DRM_XE_VMA_PRIORITY_NORMAL - Default + * - %DRM_XE_VMA_PRIORITY_HIGH - Must be user with elevated privileges + * - %DRM_XE_VM_MADVISE_PIN - Pin the VMA in memory, must be user with + * elevated privileges + */ struct drm_xe_vm_madvise { /** @extensions: Pointer to the first extension struct, if any */ __u64 extensions; @@ -1050,44 +1115,15 @@ struct drm_xe_vm_madvise { /** @addr: Address of the VMA to operation on */ __u64 addr; - /* - * Setting the preferred location will trigger a migrate of the VMA - * backing store to new location if the backing store is already - * allocated. - * - * For DRM_XE_VM_MADVISE_PREFERRED_MEM_CLASS usage, see enum - * drm_xe_memory_class. - */ #define DRM_XE_VM_MADVISE_PREFERRED_MEM_CLASS 0 #define DRM_XE_VM_MADVISE_PREFERRED_GT 1 - /* - * In this case lower 32 bits are mem class, upper 32 are GT. - * Combination provides a single IOCTL plus migrate VMA to preferred - * location. - */ #define DRM_XE_VM_MADVISE_PREFERRED_MEM_CLASS_GT 2 - /* - * The CPU will do atomic memory operations to this VMA. Must be set on - * some devices for atomics to behave correctly. - */ #define DRM_XE_VM_MADVISE_CPU_ATOMIC 3 - /* - * The device will do atomic memory operations to this VMA. Must be set - * on some devices for atomics to behave correctly. - */ #define DRM_XE_VM_MADVISE_DEVICE_ATOMIC 4 - /* - * Priority WRT to eviction (moving from preferred memory location due - * to memory pressure). The lower the priority, the more likely to be - * evicted. - */ #define DRM_XE_VM_MADVISE_PRIORITY 5 #define DRM_XE_VMA_PRIORITY_LOW 0 - /* Default */ #define DRM_XE_VMA_PRIORITY_NORMAL 1 - /* Must be user with elevated privileges */ #define DRM_XE_VMA_PRIORITY_HIGH 2 - /* Pin the VMA in memory, must be user with elevated privileges */ #define DRM_XE_VM_MADVISE_PIN 6 /** @property: property to set */ __u32 property; -- 2.34.1