History

drm/xe/uapi: More uAPI documentation additions and cosmetic updates

No functional change in this patch. Let's ensure all of our structs are documented and with a certain standard. Also, let's have an overview and list of IOCTLs as the very beginning of the generated HTML doc. v2: Nits (Lucas De Marchi)

Rodrigo Vivi committed 2 years ago

Commit 4b437891 parent 76ca3a21 file · +40 −7Browse files

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

Unified · Split

include/uapi/drm/xe_drm.h+40−7
@@ -23,6 +23,27 @@ extern "C" { · 22 unmodified lines
2323 * 5. uEvents
2424 */
2525
26+/**
27+ * DOC: Xe uAPI Overview
28+ *
29+ * This section aims to describe the Xe's IOCTL entries, its structs, and other
30+ * Xe related uAPI such as uevents and PMU (Platform Monitoring Unit) related
31+ * entries and usage.
32+ *
33+ * List of supported IOCTLs:
34+ * - &DRM_IOCTL_XE_DEVICE_QUERY
35+ * - &DRM_IOCTL_XE_GEM_CREATE
36+ * - &DRM_IOCTL_XE_GEM_MMAP_OFFSET
37+ * - &DRM_IOCTL_XE_VM_CREATE
38+ * - &DRM_IOCTL_XE_VM_DESTROY
39+ * - &DRM_IOCTL_XE_VM_BIND
40+ * - &DRM_IOCTL_XE_EXEC_QUEUE_CREATE
41+ * - &DRM_IOCTL_XE_EXEC_QUEUE_DESTROY
42+ * - &DRM_IOCTL_XE_EXEC_QUEUE_GET_PROPERTY
43+ * - &DRM_IOCTL_XE_EXEC
44+ * - &DRM_IOCTL_XE_WAIT_USER_FENCE
45+ */
46+
2647 /*
2748 * xe specific ioctls.
2849 *
@@ -56,7 +77,10 @@ extern "C" { · 27 unmodified lines
5677 #define DRM_IOCTL_XE_WAIT_USER_FENCE DRM_IOWR(DRM_COMMAND_BASE + DRM_XE_WAIT_USER_FENCE, struct drm_xe_wait_user_fence)
5778
5879 /**
59− * struct drm_xe_user_extension - Base class for defining a chain of extensions
80+ * DOC: Xe IOCTL Extensions
81+ *
82+ * Before detailing the IOCTLs and its structs, it is important to highlight
83+ * that every IOCTL in Xe is extensible.
6084 *
6185 * Many interfaces need to grow over time. In most cases we can simply
6286 * extend the struct and have userspace pass in more data. Another option,
@@ -90,7 +114,10 @@ extern "C" { · 27 unmodified lines
90114 * Typically the struct drm_xe_user_extension would be embedded in some uAPI
91115 * struct, and in this case we would feed it the head of the chain(i.e ext1),
92116 * which would then apply all of the above extensions.
93− *
117+*/
118+
119+/**
120+ * struct drm_xe_user_extension - Base class for defining a chain of extensions
94121 */
95122 struct drm_xe_user_extension {
96123 /**
@@ -120,7 +147,10 @@ struct drm_xe_user_extension { · 23 unmodified lines
120147 };
121148
122149 /**
123− * struct drm_xe_ext_set_property - XE set property extension
150+ * struct drm_xe_ext_set_property - Generic set property extension
151+ *
152+ * A generic struct that allows any of the Xe's IOCTL to be extended
153+ * with a set_property operation.
124154 */
125155 struct drm_xe_ext_set_property {
126156 /** @base: base user extension */
@@ -287,7 +317,7 @@ struct drm_xe_mem_region { · 160 unmodified lines
287317 * here will always be zero).
288318 */
289319 __u64 cpu_visible_used;
290− /** @reserved: MBZ */
320+ /** @reserved: Reserved */
291321 __u64 reserved[6];
292322 };
293323
@@ -1041,8 +1071,8 @@ struct drm_xe_sync { · 747 unmodified lines
10411071 __u32 handle;
10421072
10431073 /**
1044− * @addr: Address of user fence. When sync passed in via exec
1045− * IOCTL this a GPU address in the VM. When sync passed in via
1074+ * @addr: Address of user fence. When sync is passed in via exec
1075+ * IOCTL this is a GPU address in the VM. When sync passed in via
10461076 * VM bind IOCTL this is a user pointer. In either case, it is
10471077 * the users responsibility that this address is present and
10481078 * mapped when the user fence is signalled. Must be qword
@@ -1051,7 +1081,10 @@ struct drm_xe_sync { · 2 unmodified lines
10511081 __u64 addr;
10521082 };
10531083
1054− /** @timeline_value: Timeline point of the sync object */
1084+ /**
1085+ * @timeline_value: Input for the timeline sync object. Needs to be
1086+ * different than 0 when used with %DRM_XE_SYNC_FLAG_TIMELINE_SYNCOBJ.
1087+ */
10551088 __u64 timeline_value;
10561089
10571090 /** @reserved: Reserved */

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