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)
Showing the changes to include/uapi (1 of 1 file). Show all
Unified · Split
| @@ -23,6 +23,27 @@ extern "C" { · 22 unmodified lines | ||
| 23 | 23 | * 5. uEvents |
| 24 | 24 | */ |
| 25 | 25 | |
| 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 | + | |
| 26 | 47 | /* |
| 27 | 48 | * xe specific ioctls. |
| 28 | 49 | * |
| @@ -56,7 +77,10 @@ extern "C" { · 27 unmodified lines | ||
| 56 | 77 | #define DRM_IOCTL_XE_WAIT_USER_FENCE DRM_IOWR(DRM_COMMAND_BASE + DRM_XE_WAIT_USER_FENCE, struct drm_xe_wait_user_fence) |
| 57 | 78 | |
| 58 | 79 | /** |
| 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. | |
| 60 | 84 | * |
| 61 | 85 | * Many interfaces need to grow over time. In most cases we can simply |
| 62 | 86 | * extend the struct and have userspace pass in more data. Another option, |
| @@ -90,7 +114,10 @@ extern "C" { · 27 unmodified lines | ||
| 90 | 114 | * Typically the struct drm_xe_user_extension would be embedded in some uAPI |
| 91 | 115 | * struct, and in this case we would feed it the head of the chain(i.e ext1), |
| 92 | 116 | * 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 | |
| 94 | 121 | */ |
| 95 | 122 | struct drm_xe_user_extension { |
| 96 | 123 | /** |
| @@ -120,7 +147,10 @@ struct drm_xe_user_extension { · 23 unmodified lines | ||
| 120 | 147 | }; |
| 121 | 148 | |
| 122 | 149 | /** |
| 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. | |
| 124 | 154 | */ |
| 125 | 155 | struct drm_xe_ext_set_property { |
| 126 | 156 | /** @base: base user extension */ |
| @@ -287,7 +317,7 @@ struct drm_xe_mem_region { · 160 unmodified lines | ||
| 287 | 317 | * here will always be zero). |
| 288 | 318 | */ |
| 289 | 319 | __u64 cpu_visible_used; |
| 290 | − /** @reserved: MBZ */ | |
| 320 | + /** @reserved: Reserved */ | |
| 291 | 321 | __u64 reserved[6]; |
| 292 | 322 | }; |
| 293 | 323 | |
| @@ -1041,8 +1071,8 @@ struct drm_xe_sync { · 747 unmodified lines | ||
| 1041 | 1071 | __u32 handle; |
| 1042 | 1072 | |
| 1043 | 1073 | /** |
| 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 | |
| 1046 | 1076 | * VM bind IOCTL this is a user pointer. In either case, it is |
| 1047 | 1077 | * the users responsibility that this address is present and |
| 1048 | 1078 | * mapped when the user fence is signalled. Must be qword |
| @@ -1051,7 +1081,10 @@ struct drm_xe_sync { · 2 unmodified lines | ||
| 1051 | 1081 | __u64 addr; |
| 1052 | 1082 | }; |
| 1053 | 1083 | |
| 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 | + */ | |
| 1055 | 1088 | __u64 timeline_value; |
| 1056 | 1089 | |
| 1057 | 1090 | /** @reserved: Reserved */ |