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 | * 5. uEvents | 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 | * xe specific ioctls. | 48 | * xe specific ioctls. |
| 28 | * | 49 | * |
| @@ -56,7 +77,10 @@ extern "C" { · 27 unmodified lines | |||
| 56 | #define DRM_IOCTL_XE_WAIT_USER_FENCE DRM_IOWR(DRM_COMMAND_BASE + DRM_XE_WAIT_USER_FENCE, struct drm_xe_wait_user_fence) | 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 | * Many interfaces need to grow over time. In most cases we can simply | 85 | * Many interfaces need to grow over time. In most cases we can simply |
| 62 | * extend the struct and have userspace pass in more data. Another option, | 86 | * extend the struct and have userspace pass in more data. Another option, |
| @@ -90,7 +114,10 @@ extern "C" { · 27 unmodified lines | |||
| 90 | * Typically the struct drm_xe_user_extension would be embedded in some uAPI | 114 | * Typically the struct drm_xe_user_extension would be embedded in some uAPI |
| 91 | * struct, and in this case we would feed it the head of the chain(i.e ext1), | 115 | * struct, and in this case we would feed it the head of the chain(i.e ext1), |
| 92 | * which would then apply all of the above extensions. | 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 | struct drm_xe_user_extension { | 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 | struct drm_xe_ext_set_property { | 155 | struct drm_xe_ext_set_property { |
| 126 | /** @base: base user extension */ | 156 | /** @base: base user extension */ |
| @@ -287,7 +317,7 @@ struct drm_xe_mem_region { · 160 unmodified lines | |||
| 287 | * here will always be zero). | 317 | * here will always be zero). |
| 288 | */ | 318 | */ |
| 289 | __u64 cpu_visible_used; | 319 | __u64 cpu_visible_used; |
| 290 | /** @reserved: MBZ */ | 320 | /** @reserved: Reserved */ |
| 291 | __u64 reserved[6]; | 321 | __u64 reserved[6]; |
| 292 | }; | 322 | }; |
| 293 | 323 | ||
| @@ -1041,8 +1071,8 @@ struct drm_xe_sync { · 747 unmodified lines | |||
| 1041 | __u32 handle; | 1071 | __u32 handle; |
| 1042 | 1072 | ||
| 1043 | /** | 1073 | /** |
| 1044 | * @addr: Address of user fence. When sync passed in via exec | 1074 | * @addr: Address of user fence. When sync is passed in via exec |
| 1045 | * IOCTL this a GPU address in the VM. When sync passed in via | 1075 | * IOCTL this is a GPU address in the VM. When sync passed in via |
| 1046 | * VM bind IOCTL this is a user pointer. In either case, it is | 1076 | * VM bind IOCTL this is a user pointer. In either case, it is |
| 1047 | * the users responsibility that this address is present and | 1077 | * the users responsibility that this address is present and |
| 1048 | * mapped when the user fence is signalled. Must be qword | 1078 | * mapped when the user fence is signalled. Must be qword |
| @@ -1051,7 +1081,10 @@ struct drm_xe_sync { · 2 unmodified lines | |||
| 1051 | __u64 addr; | 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 | __u64 timeline_value; | 1088 | __u64 timeline_value; |
| 1056 | 1089 | ||
| 1057 | /** @reserved: Reserved */ | 1090 | /** @reserved: Reserved */ |