History

drm/xe/uapi: Make constant comments visible in kernel doc

As there is no direct way to make comments of constants directly visible in the kernel doc, move them to the description of the structure where they can be used. By doing so they appear in the "Description" section of the struct documentation. v2: Remove DRM_XE_UFENCE_WAIT_MASK_* (Francois Dugast)

Francois Dugast committed 2 years ago

Commit 801989b1 parent 37958601 file · +155 −116Browse files

Showing the changes to include/uapi (1 of 1 file). Show all

Unified · Split

include/uapi/drm/xe_drm.h+155−116
@@ -128,6 +128,16 @@ struct drm_xe_user_extension { · 127 unmodified lines
128128 * It is returned as part of the @drm_xe_engine, but it also is used as
129129 * the input of engine selection for both @drm_xe_exec_queue_create and
130130 * @drm_xe_query_engine_cycles
131+ *
132+ * The @engine_class can be:
133+ * - %DRM_XE_ENGINE_CLASS_RENDER
134+ * - %DRM_XE_ENGINE_CLASS_COPY
135+ * - %DRM_XE_ENGINE_CLASS_VIDEO_DECODE
136+ * - %DRM_XE_ENGINE_CLASS_VIDEO_ENHANCE
137+ * - %DRM_XE_ENGINE_CLASS_COMPUTE
138+ * - %DRM_XE_ENGINE_CLASS_VM_BIND - Kernel only classes (not actual
139+ * hardware engine class). Used for creating ordered queues of VM
140+ * bind operations.
131141 */
132142 struct drm_xe_engine_class_instance {
133143 #define DRM_XE_ENGINE_CLASS_RENDER 0
@@ -135,10 +145,6 @@ struct drm_xe_engine_class_instance { · 1 unmodified line
135145 #define DRM_XE_ENGINE_CLASS_VIDEO_DECODE 2
136146 #define DRM_XE_ENGINE_CLASS_VIDEO_ENHANCE 3
137147 #define DRM_XE_ENGINE_CLASS_COMPUTE 4
138− /*
139− * Kernel only classes (not actual hardware engine class). Used for
140− * creating ordered queues of VM bind operations.
141− */
142148 #define DRM_XE_ENGINE_CLASS_VM_BIND 5
143149 /** @engine_class: engine class id */
144150 __u16 engine_class;
@@ -342,6 +348,19 @@ struct drm_xe_query_mem_regions { · 197 unmodified lines
342348 * is equal to DRM_XE_DEVICE_QUERY_CONFIG, then the reply uses
343349 * struct drm_xe_query_config in .data.
344350 *
351+ * The index in @info can be:
352+ * - %DRM_XE_QUERY_CONFIG_REV_AND_DEVICE_ID - Device ID (lower 16 bits)
353+ * and the device revision (next 8 bits)
354+ * - %DRM_XE_QUERY_CONFIG_FLAGS - Flags describing the device
355+ * configuration, see list below
356+ *
357+ * - %DRM_XE_QUERY_CONFIG_FLAG_HAS_VRAM - Flag is set if the device
358+ * has usable VRAM
359+ * - %DRM_XE_QUERY_CONFIG_MIN_ALIGNMENT - Minimal memory alignment
360+ * required by this device, typically SZ_4K or SZ_64K
361+ * - %DRM_XE_QUERY_CONFIG_VA_BITS - Maximum bits of a virtual address
362+ * - %DRM_XE_QUERY_CONFIG_MAX_EXEC_QUEUE_PRIORITY - Value of the highest
363+ * available exec queue priority
345364 */
346365 struct drm_xe_query_config {
347366 /** @num_params: number of parameters returned in info */
@@ -350,31 +369,11 @@ struct drm_xe_query_config { · 2 unmodified lines
350369 /** @pad: MBZ */
351370 __u32 pad;
352371
353− /*
354− * Device ID (lower 16 bits) and the device revision (next
355− * 8 bits)
356− */
357372 #define DRM_XE_QUERY_CONFIG_REV_AND_DEVICE_ID 0
358− /*
359− * Flags describing the device configuration, see list below
360− */
361373 #define DRM_XE_QUERY_CONFIG_FLAGS 1
362− /*
363− * Flag is set if the device has usable VRAM
364− */
365374 #define DRM_XE_QUERY_CONFIG_FLAG_HAS_VRAM (1 << 0)
366− /*
367− * Minimal memory alignment required by this device,
368− * typically SZ_4K or SZ_64K
369− */
370375 #define DRM_XE_QUERY_CONFIG_MIN_ALIGNMENT 2
371− /*
372− * Maximum bits of a virtual address
373− */
374376 #define DRM_XE_QUERY_CONFIG_VA_BITS 3
375− /*
376− * Value of the highest available exec queue priority
377− */
378377 #define DRM_XE_QUERY_CONFIG_MAX_EXEC_QUEUE_PRIORITY 4
379378 /** @info: array of elements containing the config info */
380379 __u64 info[];
@@ -387,6 +386,10 @@ struct drm_xe_query_config { · 6 unmodified lines
387386 * existing GT individual descriptions.
388387 * Graphics Technology (GT) is a subset of a GPU/tile that is responsible for
389388 * implementing graphics and/or media operations.
389+ *
390+ * The index in @type can be:
391+ * - %DRM_XE_QUERY_GT_TYPE_MAIN
392+ * - %DRM_XE_QUERY_GT_TYPE_MEDIA
390393 */
391394 struct drm_xe_gt {
392395 #define DRM_XE_QUERY_GT_TYPE_MAIN 0
@@ -444,34 +447,30 @@ struct drm_xe_query_gt_list { · 51 unmodified lines
444447 * If a query is made with a struct drm_xe_device_query where .query
445448 * is equal to DRM_XE_DEVICE_QUERY_GT_TOPOLOGY, then the reply uses
446449 * struct drm_xe_query_topology_mask in .data.
450+ *
451+ * The @type can be:
452+ * - %DRM_XE_TOPO_DSS_GEOMETRY - To query the mask of Dual Sub Slices
453+ * (DSS) available for geometry operations. For example a query response
454+ * containing the following in mask:
455+ * ``DSS_GEOMETRY ff ff ff ff 00 00 00 00``
456+ * means 32 DSS are available for geometry.
457+ * - %DRM_XE_TOPO_DSS_COMPUTE - To query the mask of Dual Sub Slices
458+ * (DSS) available for compute operations. For example a query response
459+ * containing the following in mask:
460+ * ``DSS_COMPUTE ff ff ff ff 00 00 00 00``
461+ * means 32 DSS are available for compute.
462+ * - %DRM_XE_TOPO_EU_PER_DSS - To query the mask of Execution Units (EU)
463+ * available per Dual Sub Slices (DSS). For example a query response
464+ * containing the following in mask:
465+ * ``EU_PER_DSS ff ff 00 00 00 00 00 00``
466+ * means each DSS has 16 EU.
447467 */
448468 struct drm_xe_query_topology_mask {
449469 /** @gt_id: GT ID the mask is associated with */
450470 __u16 gt_id;
451471
452− /*
453− * To query the mask of Dual Sub Slices (DSS) available for geometry
454− * operations. For example a query response containing the following
455− * in mask:
456− * DSS_GEOMETRY ff ff ff ff 00 00 00 00
457− * means 32 DSS are available for geometry.
458− */
459472 #define DRM_XE_TOPO_DSS_GEOMETRY (1 << 0)
460− /*
461− * To query the mask of Dual Sub Slices (DSS) available for compute
462− * operations. For example a query response containing the following
463− * in mask:
464− * DSS_COMPUTE ff ff ff ff 00 00 00 00
465− * means 32 DSS are available for compute.
466− */
467473 #define DRM_XE_TOPO_DSS_COMPUTE (1 << 1)
468− /*
469− * To query the mask of Execution Units (EU) available per Dual Sub
470− * Slices (DSS). For example a query response containing the following
471− * in mask:
472− * EU_PER_DSS ff ff 00 00 00 00 00 00
473− * means each DSS has 16 EU.
474− */
475474 #define DRM_XE_TOPO_EU_PER_DSS (1 << 2)
476475 /** @type: type of mask */
477476 __u16 type;
@@ -491,6 +490,18 @@ struct drm_xe_query_topology_mask { · 13 unmodified lines
491490 * and sets the value in the query member. This determines the type of
492491 * the structure provided by the driver in data, among struct drm_xe_query_*.
493492 *
493+ * The @query can be:
494+ * - %DRM_XE_DEVICE_QUERY_ENGINES
495+ * - %DRM_XE_DEVICE_QUERY_MEM_REGIONS
496+ * - %DRM_XE_DEVICE_QUERY_CONFIG
497+ * - %DRM_XE_DEVICE_QUERY_GT_LIST
498+ * - %DRM_XE_DEVICE_QUERY_HWCONFIG - Query type to retrieve the hardware
499+ * configuration of the device such as information on slices, memory,
500+ * caches, and so on. It is provided as a table of key / value
501+ * attributes.
502+ * - %DRM_XE_DEVICE_QUERY_GT_TOPOLOGY
503+ * - %DRM_XE_DEVICE_QUERY_ENGINE_CYCLES
504+ *
494505 * If size is set to 0, the driver fills it with the required size for
495506 * the requested type of data to query. If size is equal to the required
496507 * size, the queried information is copied into data. If size is set to
@@ -537,11 +548,6 @@ struct drm_xe_device_query { · 40 unmodified lines
537548 #define DRM_XE_DEVICE_QUERY_MEM_REGIONS 1
538549 #define DRM_XE_DEVICE_QUERY_CONFIG 2
539550 #define DRM_XE_DEVICE_QUERY_GT_LIST 3
540− /*
541− * Query type to retrieve the hardware configuration of the device
542− * such as information on slices, memory, caches, and so on. It is
543− * provided as a table of attributes (key / value).
544− */
545551 #define DRM_XE_DEVICE_QUERY_HWCONFIG 4
546552 #define DRM_XE_DEVICE_QUERY_GT_TOPOLOGY 5
547553 #define DRM_XE_DEVICE_QUERY_ENGINE_CYCLES 6
@@ -561,6 +567,33 @@ struct drm_xe_device_query { · 13 unmodified lines
561567 /**
562568 * struct drm_xe_gem_create - Input of &DRM_IOCTL_XE_GEM_CREATE - A structure for
563569 * gem creation
570+ *
571+ * The @flags can be:
572+ * - %DRM_XE_GEM_CREATE_FLAG_DEFER_BACKING
573+ * - %DRM_XE_GEM_CREATE_FLAG_SCANOUT
574+ * - %DRM_XE_GEM_CREATE_FLAG_NEEDS_VISIBLE_VRAM - When using VRAM as a
575+ * possible placement, ensure that the corresponding VRAM allocation
576+ * will always use the CPU accessible part of VRAM. This is important
577+ * for small-bar systems (on full-bar systems this gets turned into a
578+ * noop).
579+ * Note1: System memory can be used as an extra placement if the kernel
580+ * should spill the allocation to system memory, if space can't be made
581+ * available in the CPU accessible part of VRAM (giving the same
582+ * behaviour as the i915 interface, see
583+ * I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS).
584+ * Note2: For clear-color CCS surfaces the kernel needs to read the
585+ * clear-color value stored in the buffer, and on discrete platforms we
586+ * need to use VRAM for display surfaces, therefore the kernel requires
587+ * setting this flag for such objects, otherwise an error is thrown on
588+ * small-bar systems.
589+ *
590+ * @cpu_caching supports the following values:
591+ * - %DRM_XE_GEM_CPU_CACHING_WB - Allocate the pages with write-back
592+ * caching. On iGPU this can't be used for scanout surfaces. Currently
593+ * not allowed for objects placed in VRAM.
594+ * - %DRM_XE_GEM_CPU_CACHING_WC - Allocate the pages as write-combined. This
595+ * is uncached. Scanout surfaces should likely use this. All objects
596+ * that can be placed in VRAM must use this.
564597 */
565598 struct drm_xe_gem_create {
566599 /** @extensions: Pointer to the first extension struct, if any */
@@ -577,21 +610,6 @@ struct drm_xe_gem_create { · 10 unmodified lines
577610
578611 #define DRM_XE_GEM_CREATE_FLAG_DEFER_BACKING (1 << 0)
579612 #define DRM_XE_GEM_CREATE_FLAG_SCANOUT (1 << 1)
580−/*
581− * When using VRAM as a possible placement, ensure that the corresponding VRAM
582− * allocation will always use the CPU accessible part of VRAM. This is important
583− * for small-bar systems (on full-bar systems this gets turned into a noop).
584− *
585− * Note: System memory can be used as an extra placement if the kernel should
586− * spill the allocation to system memory, if space can't be made available in
587− * the CPU accessible part of VRAM (giving the same behaviour as the i915
588− * interface, see I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS).
589− *
590− * Note: For clear-color CCS surfaces the kernel needs to read the clear-color
591− * value stored in the buffer, and on discrete platforms we need to use VRAM for
592− * display surfaces, therefore the kernel requires setting this flag for such
593− * objects, otherwise an error is thrown on small-bar systems.
594− */
595613 #define DRM_XE_GEM_CREATE_FLAG_NEEDS_VISIBLE_VRAM (1 << 2)
596614 /**
597615 * @flags: Flags, currently a mask of memory instances of where BO can
@@ -619,16 +637,6 @@ struct drm_xe_gem_create { · 21 unmodified lines
619637 /**
620638 * @cpu_caching: The CPU caching mode to select for this object. If
621639 * mmaping the object the mode selected here will also be used.
622− *
623− * Supported values:
624− *
625− * DRM_XE_GEM_CPU_CACHING_WB: Allocate the pages with write-back
626− * caching. On iGPU this can't be used for scanout surfaces. Currently
627− * not allowed for objects placed in VRAM.
628− *
629− * DRM_XE_GEM_CPU_CACHING_WC: Allocate the pages as write-combined. This
630− * is uncached. Scanout surfaces should likely use this. All objects
631− * that can be placed in VRAM must use this.
632640 */
633641 #define DRM_XE_GEM_CPU_CACHING_WB 1
634642 #define DRM_XE_GEM_CPU_CACHING_WC 2
@@ -682,34 +690,33 @@ struct drm_xe_ext_set_property { · 47 unmodified lines
682690
683691 /**
684692 * struct drm_xe_vm_create - Input of &DRM_IOCTL_XE_VM_CREATE
693+ *
694+ * The @flags can be:
695+ * - %DRM_XE_VM_CREATE_FLAG_SCRATCH_PAGE
696+ * - %DRM_XE_VM_CREATE_FLAG_LR_MODE - An LR, or Long Running VM accepts
697+ * exec submissions to its exec_queues that don't have an upper time
698+ * limit on the job execution time. But exec submissions to these
699+ * don't allow any of the flags DRM_XE_SYNC_FLAG_SYNCOBJ,
700+ * DRM_XE_SYNC_FLAG_TIMELINE_SYNCOBJ, DRM_XE_SYNC_FLAG_DMA_BUF,
701+ * used as out-syncobjs, that is, together with DRM_XE_SYNC_FLAG_SIGNAL.
702+ * LR VMs can be created in recoverable page-fault mode using
703+ * DRM_XE_VM_CREATE_FLAG_FAULT_MODE, if the device supports it.
704+ * If that flag is omitted, the UMD can not rely on the slightly
705+ * different per-VM overcommit semantics that are enabled by
706+ * DRM_XE_VM_CREATE_FLAG_FAULT_MODE (see below), but KMD may
707+ * still enable recoverable pagefaults if supported by the device.
708+ * - %DRM_XE_VM_CREATE_FLAG_FAULT_MODE - Requires also
709+ * DRM_XE_VM_CREATE_FLAG_LR_MODE. It allows memory to be allocated on
710+ * demand when accessed, and also allows per-VM overcommit of memory.
711+ * The xe driver internally uses recoverable pagefaults to implement
712+ * this.
685713 */
686714 struct drm_xe_vm_create {
687715 /** @extensions: Pointer to the first extension struct, if any */
688716 __u64 extensions;
689717
690718 #define DRM_XE_VM_CREATE_FLAG_SCRATCH_PAGE (1 << 0)
691− /*
692− * An LR, or Long Running VM accepts exec submissions
693− * to its exec_queues that don't have an upper time limit on
694− * the job execution time. But exec submissions to these
695− * don't allow any of the flags DRM_XE_SYNC_FLAG_SYNCOBJ,
696− * DRM_XE_SYNC_FLAG_TIMELINE_SYNCOBJ, DRM_XE_SYNC_FLAG_DMA_BUF,
697− * used as out-syncobjs, that is, together with DRM_XE_SYNC_FLAG_SIGNAL.
698− * LR VMs can be created in recoverable page-fault mode using
699− * DRM_XE_VM_CREATE_FLAG_FAULT_MODE, if the device supports it.
700− * If that flag is omitted, the UMD can not rely on the slightly
701− * different per-VM overcommit semantics that are enabled by
702− * DRM_XE_VM_CREATE_FLAG_FAULT_MODE (see below), but KMD may
703− * still enable recoverable pagefaults if supported by the device.
704− */
705719 #define DRM_XE_VM_CREATE_FLAG_LR_MODE (1 << 1)
706− /*
707− * DRM_XE_VM_CREATE_FLAG_FAULT_MODE requires also
708− * DRM_XE_VM_CREATE_FLAG_LR_MODE. It allows memory to be allocated
709− * on demand when accessed, and also allows per-VM overcommit of memory.
710− * The xe driver internally uses recoverable pagefaults to implement
711− * this.
712− */
713720 #define DRM_XE_VM_CREATE_FLAG_FAULT_MODE (1 << 2)
714721 /** @flags: Flags */
715722 __u32 flags;
@@ -736,7 +743,27 @@ struct drm_xe_vm_destroy { · 20 unmodified lines
736743 };
737744
738745 /**
739− * struct drm_xe_vm_bind_op
746+ * struct drm_xe_vm_bind_op - run bind operations
747+ *
748+ * The @op can be:
749+ * - %DRM_XE_VM_BIND_OP_MAP
750+ * - %DRM_XE_VM_BIND_OP_UNMAP
751+ * - %DRM_XE_VM_BIND_OP_MAP_USERPTR
752+ * - %DRM_XE_VM_BIND_OP_UNMAP_ALL
753+ * - %DRM_XE_VM_BIND_OP_PREFETCH
754+ *
755+ * and the @flags can be:
756+ * - %DRM_XE_VM_BIND_FLAG_READONLY
757+ * - %DRM_XE_VM_BIND_FLAG_ASYNC
758+ * - %DRM_XE_VM_BIND_FLAG_IMMEDIATE - Valid on a faulting VM only, do the
759+ * MAP operation immediately rather than deferring the MAP to the page
760+ * fault handler.
761+ * - %DRM_XE_VM_BIND_FLAG_NULL - When the NULL flag is set, the page
762+ * tables are setup with a special bit which indicates writes are
763+ * dropped and all reads return zero. In the future, the NULL flags
764+ * will only be valid for DRM_XE_VM_BIND_OP_MAP operations, the BO
765+ * handle MBZ, and the BO offset MBZ. This flag is intended to
766+ * implement VK sparse bindings.
740767 */
741768 struct drm_xe_vm_bind_op {
742769 /** @extensions: Pointer to the first extension struct, if any */
@@ -824,18 +851,7 @@ struct drm_xe_vm_bind_op { · 81 unmodified lines
824851 __u32 op;
825852
826853 #define DRM_XE_VM_BIND_FLAG_READONLY (1 << 0)
827− /*
828− * Valid on a faulting VM only, do the MAP operation immediately rather
829− * than deferring the MAP to the page fault handler.
830− */
831854 #define DRM_XE_VM_BIND_FLAG_IMMEDIATE (1 << 1)
832− /*
833− * When the NULL flag is set, the page tables are setup with a special
834− * bit which indicates writes are dropped and all reads return zero. In
835− * the future, the NULL flags will only be valid for DRM_XE_VM_BIND_OP_MAP
836− * operations, the BO handle MBZ, and the BO offset MBZ. This flag is
837− * intended to implement VK sparse bindings.
838− */
839855 #define DRM_XE_VM_BIND_FLAG_NULL (1 << 2)
840856 /** @flags: Bind flags */
841857 __u32 flags;
@@ -962,6 +978,9 @@ struct drm_xe_exec_queue_create { · 120 unmodified lines
962978
963979 /**
964980 * struct drm_xe_exec_queue_get_property - Input of &DRM_IOCTL_XE_EXEC_QUEUE_GET_PROPERTY
981+ *
982+ * The @property can be:
983+ * - %DRM_XE_EXEC_QUEUE_GET_PROPERTY_BAN
965984 */
966985 struct drm_xe_exec_queue_get_property {
967986 /** @extensions: Pointer to the first extension struct, if any */
@@ -996,7 +1015,15 @@ struct drm_xe_exec_queue_destroy { · 28 unmodified lines
9961015 };
9971016
9981017 /**
999− * struct drm_xe_sync
1018+ * struct drm_xe_sync - sync object
1019+ *
1020+ * The @type can be:
1021+ * - %DRM_XE_SYNC_TYPE_SYNCOBJ
1022+ * - %DRM_XE_SYNC_TYPE_TIMELINE_SYNCOBJ
1023+ * - %DRM_XE_SYNC_TYPE_USER_FENCE
1024+ *
1025+ * and the @flags can be:
1026+ * - %DRM_XE_SYNC_FLAG_SIGNAL
10001027 */
10011028 struct drm_xe_sync {
10021029 /** @extensions: Pointer to the first extension struct, if any */
@@ -1078,6 +1105,24 @@ struct drm_xe_exec { · 75 unmodified lines
10781105 * (*addr & MASK) OP (VALUE & MASK)
10791106 *
10801107 * Returns to user on user fence completion or timeout.
1108+ *
1109+ * The @op can be:
1110+ * - %DRM_XE_UFENCE_WAIT_OP_EQ
1111+ * - %DRM_XE_UFENCE_WAIT_OP_NEQ
1112+ * - %DRM_XE_UFENCE_WAIT_OP_GT
1113+ * - %DRM_XE_UFENCE_WAIT_OP_GTE
1114+ * - %DRM_XE_UFENCE_WAIT_OP_LT
1115+ * - %DRM_XE_UFENCE_WAIT_OP_LTE
1116+ *
1117+ * and the @flags can be:
1118+ * - %DRM_XE_UFENCE_WAIT_FLAG_ABSTIME
1119+ * - %DRM_XE_UFENCE_WAIT_FLAG_SOFT_OP
1120+ *
1121+ * The @mask values can be for example:
1122+ * - 0xffu for u8
1123+ * - 0xffffu for u16
1124+ * - 0xffffffffu for u32
1125+ * - 0xffffffffffffffffu for u64
10811126 */
10821127 struct drm_xe_wait_user_fence {
10831128 /** @extensions: Pointer to the first extension struct, if any */
@@ -1107,13 +1152,7 @@ struct drm_xe_wait_user_fence { · 23 unmodified lines
11071152 /** @value: compare value */
11081153 __u64 value;
11091154
1110− /**
1111− * @mask: comparison mask, values can be for example:
1112− * - 0xffu for u8
1113− * - 0xffffu for u16
1114− * - 0xffffffffu for u32
1115− * - 0xffffffffffffffffu for u64
1116− */
1155+ /** @mask: comparison mask */
11171156 __u64 mask;
11181157
11191158 /**

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t