| Message ID | 20220610070711.32407-3-niranjana.vishwanathapura@intel.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | drm/doc/rfc: i915 VM_BIND feature design + uapi | expand |
On 10/06/2022 08:07, Niranjana Vishwanathapura wrote: > Add some missing i915 upai documentation which the new > i915 VM_BIND feature documentation will be refer to. > > Signed-off-by: Niranjana Vishwanathapura <niranjana.vishwanathapura@intel.com> Reviewed-by: Matthew Auld <matthew.auld@intel.com> This one looks to be standalone. If no objections should we go ahead and merge this one? > --- > include/uapi/drm/i915_drm.h | 203 ++++++++++++++++++++++++++++-------- > 1 file changed, 158 insertions(+), 45 deletions(-) > > diff --git a/include/uapi/drm/i915_drm.h b/include/uapi/drm/i915_drm.h > index de49b68b4fc8..9cf3bf47c7f2 100644 > --- a/include/uapi/drm/i915_drm.h > +++ b/include/uapi/drm/i915_drm.h > @@ -751,14 +751,27 @@ typedef struct drm_i915_irq_wait { > > /* Must be kept compact -- no holes and well documented */ > > -typedef struct drm_i915_getparam { > +/** > + * struct drm_i915_getparam - Driver parameter query structure. > + */ > +struct drm_i915_getparam { > + /** @param: Driver parameter to query. */ > __s32 param; > - /* > + > + /** > + * @value: Address of memory where queried value should be put. > + * > * WARNING: Using pointers instead of fixed-size u64 means we need to write > * compat32 code. Don't repeat this mistake. > */ > int __user *value; > -} drm_i915_getparam_t; > +}; > + > +/** > + * typedef drm_i915_getparam_t - Driver parameter query structure. > + * See struct drm_i915_getparam. > + */ > +typedef struct drm_i915_getparam drm_i915_getparam_t; > > /* Ioctl to set kernel params: > */ > @@ -1239,76 +1252,119 @@ struct drm_i915_gem_exec_object2 { > __u64 rsvd2; > }; > > +/** > + * struct drm_i915_gem_exec_fence - An input or output fence for the execbuf > + * ioctl. > + * > + * The request will wait for input fence to signal before submission. > + * > + * The returned output fence will be signaled after the completion of the > + * request. > + */ > struct drm_i915_gem_exec_fence { > - /** > - * User's handle for a drm_syncobj to wait on or signal. > - */ > + /** @handle: User's handle for a drm_syncobj to wait on or signal. */ > __u32 handle; > > + /** > + * @flags: Supported flags are: > + * > + * I915_EXEC_FENCE_WAIT: > + * Wait for the input fence before request submission. > + * > + * I915_EXEC_FENCE_SIGNAL: > + * Return request completion fence as output > + */ > + __u32 flags; > #define I915_EXEC_FENCE_WAIT (1<<0) > #define I915_EXEC_FENCE_SIGNAL (1<<1) > #define __I915_EXEC_FENCE_UNKNOWN_FLAGS (-(I915_EXEC_FENCE_SIGNAL << 1)) > - __u32 flags; > }; > > -/* > - * See drm_i915_gem_execbuffer_ext_timeline_fences. > - */ > -#define DRM_I915_GEM_EXECBUFFER_EXT_TIMELINE_FENCES 0 > - > -/* > +/** > + * struct drm_i915_gem_execbuffer_ext_timeline_fences - Timeline fences > + * for execbuf ioctl. > + * > * This structure describes an array of drm_syncobj and associated points for > * timeline variants of drm_syncobj. It is invalid to append this structure to > * the execbuf if I915_EXEC_FENCE_ARRAY is set. > */ > struct drm_i915_gem_execbuffer_ext_timeline_fences { > +#define DRM_I915_GEM_EXECBUFFER_EXT_TIMELINE_FENCES 0 > + /** @base: Extension link. See struct i915_user_extension. */ > struct i915_user_extension base; > > /** > - * Number of element in the handles_ptr & value_ptr arrays. > + * @fence_count: Number of elements in the @handles_ptr & @value_ptr > + * arrays. > */ > __u64 fence_count; > > /** > - * Pointer to an array of struct drm_i915_gem_exec_fence of length > - * fence_count. > + * @handles_ptr: Pointer to an array of struct drm_i915_gem_exec_fence > + * of length @fence_count. > */ > __u64 handles_ptr; > > /** > - * Pointer to an array of u64 values of length fence_count. Values > - * must be 0 for a binary drm_syncobj. A Value of 0 for a timeline > - * drm_syncobj is invalid as it turns a drm_syncobj into a binary one. > + * @values_ptr: Pointer to an array of u64 values of length > + * @fence_count. > + * Values must be 0 for a binary drm_syncobj. A Value of 0 for a > + * timeline drm_syncobj is invalid as it turns a drm_syncobj into a > + * binary one. > */ > __u64 values_ptr; > }; > > +/** > + * struct drm_i915_gem_execbuffer2 - Structure for DRM_I915_GEM_EXECBUFFER2 > + * ioctl. > + */ > struct drm_i915_gem_execbuffer2 { > - /** > - * List of gem_exec_object2 structs > - */ > + /** @buffers_ptr: Pointer to a list of gem_exec_object2 structs */ > __u64 buffers_ptr; > + > + /** @buffer_count: Number of elements in @buffers_ptr array */ > __u32 buffer_count; > > - /** Offset in the batchbuffer to start execution from. */ > + /** > + * @batch_start_offset: Offset in the batchbuffer to start execution > + * from. > + */ > __u32 batch_start_offset; > - /** Bytes used in batchbuffer from batch_start_offset */ > + > + /** > + * @batch_len: Length in bytes of the batch buffer, starting from the > + * @batch_start_offset. If 0, length is assumed to be the batch buffer > + * object size. > + */ > __u32 batch_len; > + > + /** @DR1: deprecated */ > __u32 DR1; > + > + /** @DR4: deprecated */ > __u32 DR4; > + > + /** @num_cliprects: See @cliprects_ptr */ > __u32 num_cliprects; > + > /** > - * This is a struct drm_clip_rect *cliprects if I915_EXEC_FENCE_ARRAY > - * & I915_EXEC_USE_EXTENSIONS are not set. > + * @cliprects_ptr: Kernel clipping was a DRI1 misfeature. > + * > + * It is invalid to use this field if I915_EXEC_FENCE_ARRAY or > + * I915_EXEC_USE_EXTENSIONS flags are not set. > * > * If I915_EXEC_FENCE_ARRAY is set, then this is a pointer to an array > - * of struct drm_i915_gem_exec_fence and num_cliprects is the length > - * of the array. > + * of &drm_i915_gem_exec_fence and @num_cliprects is the length of the > + * array. > * > * If I915_EXEC_USE_EXTENSIONS is set, then this is a pointer to a > - * single struct i915_user_extension and num_cliprects is 0. > + * single &i915_user_extension and num_cliprects is 0. > */ > __u64 cliprects_ptr; > + > + /** @flags: Execbuf flags */ > + __u64 flags; > #define I915_EXEC_RING_MASK (0x3f) > #define I915_EXEC_DEFAULT (0<<0) > #define I915_EXEC_RENDER (1<<0) > @@ -1326,10 +1382,6 @@ struct drm_i915_gem_execbuffer2 { > #define I915_EXEC_CONSTANTS_REL_GENERAL (0<<6) /* default */ > #define I915_EXEC_CONSTANTS_ABSOLUTE (1<<6) > #define I915_EXEC_CONSTANTS_REL_SURFACE (2<<6) /* gen4/5 only */ > - __u64 flags; > - __u64 rsvd1; /* now used for context info */ > - __u64 rsvd2; > -}; > > /** Resets the SO write offset registers for transform feedback on gen7. */ > #define I915_EXEC_GEN7_SOL_RESET (1<<8) > @@ -1432,9 +1484,23 @@ struct drm_i915_gem_execbuffer2 { > * drm_i915_gem_execbuffer_ext enum. > */ > #define I915_EXEC_USE_EXTENSIONS (1 << 21) > - > #define __I915_EXEC_UNKNOWN_FLAGS (-(I915_EXEC_USE_EXTENSIONS << 1)) > > + /** @rsvd1: Context id */ > + __u64 rsvd1; > + > + /** > + * @rsvd2: in and out sync_file file descriptors. > + * > + * When I915_EXEC_FENCE_IN or I915_EXEC_FENCE_SUBMIT flag is set, the > + * lower 32 bits of this field will have the in sync_file fd (input). > + * > + * When I915_EXEC_FENCE_OUT flag is set, the upper 32 bits of this > + * field will have the out sync_file fd (output). > + */ > + __u64 rsvd2; > +}; > + > #define I915_EXEC_CONTEXT_ID_MASK (0xffffffff) > #define i915_execbuffer2_set_context_id(eb2, context) \ > (eb2).rsvd1 = context & I915_EXEC_CONTEXT_ID_MASK > @@ -1814,19 +1880,56 @@ struct drm_i915_gem_context_create { > __u32 pad; > }; > > +/** > + * struct drm_i915_gem_context_create_ext - Structure for creating contexts. > + */ > struct drm_i915_gem_context_create_ext { > - __u32 ctx_id; /* output: id of new context*/ > + /** @ctx_id: Id of the created context (output) */ > + __u32 ctx_id; > + > + /** > + * @flags: Supported flags are: > + * > + * I915_CONTEXT_CREATE_FLAGS_USE_EXTENSIONS: > + * Extensions may be appended to this structure and driver must check > + * for those. See @extensions. > + * > + * I915_CONTEXT_CREATE_FLAGS_SINGLE_TIMELINE: > + * Created context will have single timeline. > + */ > __u32 flags; > #define I915_CONTEXT_CREATE_FLAGS_USE_EXTENSIONS (1u << 0) > #define I915_CONTEXT_CREATE_FLAGS_SINGLE_TIMELINE (1u << 1) > #define I915_CONTEXT_CREATE_FLAGS_UNKNOWN \ > (-(I915_CONTEXT_CREATE_FLAGS_SINGLE_TIMELINE << 1)) > + > + /** > + * @extensions: Zero-terminated chain of extensions. > + * > + * I915_CONTEXT_CREATE_EXT_SETPARAM: > + * Context parameter to set or query during context creation. > + * See struct drm_i915_gem_context_create_ext_setparam. > + * > + * I915_CONTEXT_CREATE_EXT_CLONE: > + * This extension has been removed. On the off chance someone somewhere > + * has attempted to use it, never re-use this extension number. > + */ > __u64 extensions; > +#define I915_CONTEXT_CREATE_EXT_SETPARAM 0 > +#define I915_CONTEXT_CREATE_EXT_CLONE 1 > }; > > +/** > + * struct drm_i915_gem_context_param - Context parameter to set or query. > + */ > struct drm_i915_gem_context_param { > + /** @ctx_id: Context id */ > __u32 ctx_id; > + > + /** @size: Size of the parameter @value > __u32 size; > + > + /** @param: Parameter to set or query */ > __u64 param; > #define I915_CONTEXT_PARAM_BAN_PERIOD 0x1 > /* I915_CONTEXT_PARAM_NO_ZEROMAP has been removed. On the off chance > @@ -1973,6 +2076,7 @@ struct drm_i915_gem_context_param { > #define I915_CONTEXT_PARAM_PROTECTED_CONTENT 0xd > /* Must be kept compact -- no holes and well documented */ > > + /** @value: Context parameter value to be set or queried */ > __u64 value; > }; > > @@ -2371,23 +2475,29 @@ struct i915_context_param_engines { > struct i915_engine_class_instance engines[N__]; \ > } __attribute__((packed)) name__ > > +/** > + * struct drm_i915_gem_context_create_ext_setparam - Context parameter > + * to set or query during context creation. > + */ > struct drm_i915_gem_context_create_ext_setparam { > -#define I915_CONTEXT_CREATE_EXT_SETPARAM 0 > + /** @base: Extension link. See struct i915_user_extension. */ > struct i915_user_extension base; > + > + /** > + * @param: Context parameter to set or query. > + * See struct drm_i915_gem_context_param. > + */ > struct drm_i915_gem_context_param param; > }; > > -/* This API has been removed. On the off chance someone somewhere has > - * attempted to use it, never re-use this extension number. > - */ > -#define I915_CONTEXT_CREATE_EXT_CLONE 1 > - > struct drm_i915_gem_context_destroy { > __u32 ctx_id; > __u32 pad; > }; > > -/* > +/** > + * struct drm_i915_gem_vm_control - Structure to create or destroy VM. > + * > * DRM_I915_GEM_VM_CREATE - > * > * Create a new virtual memory address space (ppGTT) for use within a context > @@ -2397,20 +2507,23 @@ struct drm_i915_gem_context_destroy { > * The id of new VM (bound to the fd) for use with I915_CONTEXT_PARAM_VM is > * returned in the outparam @id. > * > - * No flags are defined, with all bits reserved and must be zero. > - * > * An extension chain maybe provided, starting with @extensions, and terminated > * by the @next_extension being 0. Currently, no extensions are defined. > * > * DRM_I915_GEM_VM_DESTROY - > * > - * Destroys a previously created VM id, specified in @id. > + * Destroys a previously created VM id, specified in @vm_id. > * > * No extensions or flags are allowed currently, and so must be zero. > */ > struct drm_i915_gem_vm_control { > + /** @extensions: Zero-terminated chain of extensions. */ > __u64 extensions; > + > + /** @flags: reserved for future usage, currently MBZ */ > __u32 flags; > + > + /** @vm_id: Id of the VM created or to be destroyed */ > __u32 vm_id; > }; >
On Fri, Jun 10, 2022 at 12:01:24PM +0100, Matthew Auld wrote: >On 10/06/2022 08:07, Niranjana Vishwanathapura wrote: >>Add some missing i915 upai documentation which the new >>i915 VM_BIND feature documentation will be refer to. >> >>Signed-off-by: Niranjana Vishwanathapura <niranjana.vishwanathapura@intel.com> >Reviewed-by: Matthew Auld <matthew.auld@intel.com> > >This one looks to be standalone. If no objections should we go ahead >and merge this one? Yah, I agree. Niranjana > >>--- >> include/uapi/drm/i915_drm.h | 203 ++++++++++++++++++++++++++++-------- >> 1 file changed, 158 insertions(+), 45 deletions(-) >> >>diff --git a/include/uapi/drm/i915_drm.h b/include/uapi/drm/i915_drm.h >>index de49b68b4fc8..9cf3bf47c7f2 100644 >>--- a/include/uapi/drm/i915_drm.h >>+++ b/include/uapi/drm/i915_drm.h >>@@ -751,14 +751,27 @@ typedef struct drm_i915_irq_wait { >> /* Must be kept compact -- no holes and well documented */ >>-typedef struct drm_i915_getparam { >>+/** >>+ * struct drm_i915_getparam - Driver parameter query structure. >>+ */ >>+struct drm_i915_getparam { >>+ /** @param: Driver parameter to query. */ >> __s32 param; >>- /* >>+ >>+ /** >>+ * @value: Address of memory where queried value should be put. >>+ * >> * WARNING: Using pointers instead of fixed-size u64 means we need to write >> * compat32 code. Don't repeat this mistake. >> */ >> int __user *value; >>-} drm_i915_getparam_t; >>+}; >>+ >>+/** >>+ * typedef drm_i915_getparam_t - Driver parameter query structure. >>+ * See struct drm_i915_getparam. >>+ */ >>+typedef struct drm_i915_getparam drm_i915_getparam_t; >> /* Ioctl to set kernel params: >> */ >>@@ -1239,76 +1252,119 @@ struct drm_i915_gem_exec_object2 { >> __u64 rsvd2; >> }; >>+/** >>+ * struct drm_i915_gem_exec_fence - An input or output fence for the execbuf >>+ * ioctl. >>+ * >>+ * The request will wait for input fence to signal before submission. >>+ * >>+ * The returned output fence will be signaled after the completion of the >>+ * request. >>+ */ >> struct drm_i915_gem_exec_fence { >>- /** >>- * User's handle for a drm_syncobj to wait on or signal. >>- */ >>+ /** @handle: User's handle for a drm_syncobj to wait on or signal. */ >> __u32 handle; >>+ /** >>+ * @flags: Supported flags are: >>+ * >>+ * I915_EXEC_FENCE_WAIT: >>+ * Wait for the input fence before request submission. >>+ * >>+ * I915_EXEC_FENCE_SIGNAL: >>+ * Return request completion fence as output >>+ */ >>+ __u32 flags; >> #define I915_EXEC_FENCE_WAIT (1<<0) >> #define I915_EXEC_FENCE_SIGNAL (1<<1) >> #define __I915_EXEC_FENCE_UNKNOWN_FLAGS (-(I915_EXEC_FENCE_SIGNAL << 1)) >>- __u32 flags; >> }; >>-/* >>- * See drm_i915_gem_execbuffer_ext_timeline_fences. >>- */ >>-#define DRM_I915_GEM_EXECBUFFER_EXT_TIMELINE_FENCES 0 >>- >>-/* >>+/** >>+ * struct drm_i915_gem_execbuffer_ext_timeline_fences - Timeline fences >>+ * for execbuf ioctl. >>+ * >> * This structure describes an array of drm_syncobj and associated points for >> * timeline variants of drm_syncobj. It is invalid to append this structure to >> * the execbuf if I915_EXEC_FENCE_ARRAY is set. >> */ >> struct drm_i915_gem_execbuffer_ext_timeline_fences { >>+#define DRM_I915_GEM_EXECBUFFER_EXT_TIMELINE_FENCES 0 >>+ /** @base: Extension link. See struct i915_user_extension. */ >> struct i915_user_extension base; >> /** >>- * Number of element in the handles_ptr & value_ptr arrays. >>+ * @fence_count: Number of elements in the @handles_ptr & @value_ptr >>+ * arrays. >> */ >> __u64 fence_count; >> /** >>- * Pointer to an array of struct drm_i915_gem_exec_fence of length >>- * fence_count. >>+ * @handles_ptr: Pointer to an array of struct drm_i915_gem_exec_fence >>+ * of length @fence_count. >> */ >> __u64 handles_ptr; >> /** >>- * Pointer to an array of u64 values of length fence_count. Values >>- * must be 0 for a binary drm_syncobj. A Value of 0 for a timeline >>- * drm_syncobj is invalid as it turns a drm_syncobj into a binary one. >>+ * @values_ptr: Pointer to an array of u64 values of length >>+ * @fence_count. >>+ * Values must be 0 for a binary drm_syncobj. A Value of 0 for a >>+ * timeline drm_syncobj is invalid as it turns a drm_syncobj into a >>+ * binary one. >> */ >> __u64 values_ptr; >> }; >>+/** >>+ * struct drm_i915_gem_execbuffer2 - Structure for DRM_I915_GEM_EXECBUFFER2 >>+ * ioctl. >>+ */ >> struct drm_i915_gem_execbuffer2 { >>- /** >>- * List of gem_exec_object2 structs >>- */ >>+ /** @buffers_ptr: Pointer to a list of gem_exec_object2 structs */ >> __u64 buffers_ptr; >>+ >>+ /** @buffer_count: Number of elements in @buffers_ptr array */ >> __u32 buffer_count; >>- /** Offset in the batchbuffer to start execution from. */ >>+ /** >>+ * @batch_start_offset: Offset in the batchbuffer to start execution >>+ * from. >>+ */ >> __u32 batch_start_offset; >>- /** Bytes used in batchbuffer from batch_start_offset */ >>+ >>+ /** >>+ * @batch_len: Length in bytes of the batch buffer, starting from the >>+ * @batch_start_offset. If 0, length is assumed to be the batch buffer >>+ * object size. >>+ */ >> __u32 batch_len; >>+ >>+ /** @DR1: deprecated */ >> __u32 DR1; >>+ >>+ /** @DR4: deprecated */ >> __u32 DR4; >>+ >>+ /** @num_cliprects: See @cliprects_ptr */ >> __u32 num_cliprects; >>+ >> /** >>- * This is a struct drm_clip_rect *cliprects if I915_EXEC_FENCE_ARRAY >>- * & I915_EXEC_USE_EXTENSIONS are not set. >>+ * @cliprects_ptr: Kernel clipping was a DRI1 misfeature. >>+ * >>+ * It is invalid to use this field if I915_EXEC_FENCE_ARRAY or >>+ * I915_EXEC_USE_EXTENSIONS flags are not set. >> * >> * If I915_EXEC_FENCE_ARRAY is set, then this is a pointer to an array >>- * of struct drm_i915_gem_exec_fence and num_cliprects is the length >>- * of the array. >>+ * of &drm_i915_gem_exec_fence and @num_cliprects is the length of the >>+ * array. >> * >> * If I915_EXEC_USE_EXTENSIONS is set, then this is a pointer to a >>- * single struct i915_user_extension and num_cliprects is 0. >>+ * single &i915_user_extension and num_cliprects is 0. >> */ >> __u64 cliprects_ptr; >>+ >>+ /** @flags: Execbuf flags */ >>+ __u64 flags; >> #define I915_EXEC_RING_MASK (0x3f) >> #define I915_EXEC_DEFAULT (0<<0) >> #define I915_EXEC_RENDER (1<<0) >>@@ -1326,10 +1382,6 @@ struct drm_i915_gem_execbuffer2 { >> #define I915_EXEC_CONSTANTS_REL_GENERAL (0<<6) /* default */ >> #define I915_EXEC_CONSTANTS_ABSOLUTE (1<<6) >> #define I915_EXEC_CONSTANTS_REL_SURFACE (2<<6) /* gen4/5 only */ >>- __u64 flags; >>- __u64 rsvd1; /* now used for context info */ >>- __u64 rsvd2; >>-}; >> /** Resets the SO write offset registers for transform feedback on gen7. */ >> #define I915_EXEC_GEN7_SOL_RESET (1<<8) >>@@ -1432,9 +1484,23 @@ struct drm_i915_gem_execbuffer2 { >> * drm_i915_gem_execbuffer_ext enum. >> */ >> #define I915_EXEC_USE_EXTENSIONS (1 << 21) >>- >> #define __I915_EXEC_UNKNOWN_FLAGS (-(I915_EXEC_USE_EXTENSIONS << 1)) >>+ /** @rsvd1: Context id */ >>+ __u64 rsvd1; >>+ >>+ /** >>+ * @rsvd2: in and out sync_file file descriptors. >>+ * >>+ * When I915_EXEC_FENCE_IN or I915_EXEC_FENCE_SUBMIT flag is set, the >>+ * lower 32 bits of this field will have the in sync_file fd (input). >>+ * >>+ * When I915_EXEC_FENCE_OUT flag is set, the upper 32 bits of this >>+ * field will have the out sync_file fd (output). >>+ */ >>+ __u64 rsvd2; >>+}; >>+ >> #define I915_EXEC_CONTEXT_ID_MASK (0xffffffff) >> #define i915_execbuffer2_set_context_id(eb2, context) \ >> (eb2).rsvd1 = context & I915_EXEC_CONTEXT_ID_MASK >>@@ -1814,19 +1880,56 @@ struct drm_i915_gem_context_create { >> __u32 pad; >> }; >>+/** >>+ * struct drm_i915_gem_context_create_ext - Structure for creating contexts. >>+ */ >> struct drm_i915_gem_context_create_ext { >>- __u32 ctx_id; /* output: id of new context*/ >>+ /** @ctx_id: Id of the created context (output) */ >>+ __u32 ctx_id; >>+ >>+ /** >>+ * @flags: Supported flags are: >>+ * >>+ * I915_CONTEXT_CREATE_FLAGS_USE_EXTENSIONS: >>+ * Extensions may be appended to this structure and driver must check >>+ * for those. See @extensions. >>+ * >>+ * I915_CONTEXT_CREATE_FLAGS_SINGLE_TIMELINE: >>+ * Created context will have single timeline. >>+ */ >> __u32 flags; >> #define I915_CONTEXT_CREATE_FLAGS_USE_EXTENSIONS (1u << 0) >> #define I915_CONTEXT_CREATE_FLAGS_SINGLE_TIMELINE (1u << 1) >> #define I915_CONTEXT_CREATE_FLAGS_UNKNOWN \ >> (-(I915_CONTEXT_CREATE_FLAGS_SINGLE_TIMELINE << 1)) >>+ >>+ /** >>+ * @extensions: Zero-terminated chain of extensions. >>+ * >>+ * I915_CONTEXT_CREATE_EXT_SETPARAM: >>+ * Context parameter to set or query during context creation. >>+ * See struct drm_i915_gem_context_create_ext_setparam. >>+ * >>+ * I915_CONTEXT_CREATE_EXT_CLONE: >>+ * This extension has been removed. On the off chance someone somewhere >>+ * has attempted to use it, never re-use this extension number. >>+ */ >> __u64 extensions; >>+#define I915_CONTEXT_CREATE_EXT_SETPARAM 0 >>+#define I915_CONTEXT_CREATE_EXT_CLONE 1 >> }; >>+/** >>+ * struct drm_i915_gem_context_param - Context parameter to set or query. >>+ */ >> struct drm_i915_gem_context_param { >>+ /** @ctx_id: Context id */ >> __u32 ctx_id; >>+ >>+ /** @size: Size of the parameter @value >> __u32 size; >>+ >>+ /** @param: Parameter to set or query */ >> __u64 param; >> #define I915_CONTEXT_PARAM_BAN_PERIOD 0x1 >> /* I915_CONTEXT_PARAM_NO_ZEROMAP has been removed. On the off chance >>@@ -1973,6 +2076,7 @@ struct drm_i915_gem_context_param { >> #define I915_CONTEXT_PARAM_PROTECTED_CONTENT 0xd >> /* Must be kept compact -- no holes and well documented */ >>+ /** @value: Context parameter value to be set or queried */ >> __u64 value; >> }; >>@@ -2371,23 +2475,29 @@ struct i915_context_param_engines { >> struct i915_engine_class_instance engines[N__]; \ >> } __attribute__((packed)) name__ >>+/** >>+ * struct drm_i915_gem_context_create_ext_setparam - Context parameter >>+ * to set or query during context creation. >>+ */ >> struct drm_i915_gem_context_create_ext_setparam { >>-#define I915_CONTEXT_CREATE_EXT_SETPARAM 0 >>+ /** @base: Extension link. See struct i915_user_extension. */ >> struct i915_user_extension base; >>+ >>+ /** >>+ * @param: Context parameter to set or query. >>+ * See struct drm_i915_gem_context_param. >>+ */ >> struct drm_i915_gem_context_param param; >> }; >>-/* This API has been removed. On the off chance someone somewhere has >>- * attempted to use it, never re-use this extension number. >>- */ >>-#define I915_CONTEXT_CREATE_EXT_CLONE 1 >>- >> struct drm_i915_gem_context_destroy { >> __u32 ctx_id; >> __u32 pad; >> }; >>-/* >>+/** >>+ * struct drm_i915_gem_vm_control - Structure to create or destroy VM. >>+ * >> * DRM_I915_GEM_VM_CREATE - >> * >> * Create a new virtual memory address space (ppGTT) for use within a context >>@@ -2397,20 +2507,23 @@ struct drm_i915_gem_context_destroy { >> * The id of new VM (bound to the fd) for use with I915_CONTEXT_PARAM_VM is >> * returned in the outparam @id. >> * >>- * No flags are defined, with all bits reserved and must be zero. >>- * >> * An extension chain maybe provided, starting with @extensions, and terminated >> * by the @next_extension being 0. Currently, no extensions are defined. >> * >> * DRM_I915_GEM_VM_DESTROY - >> * >>- * Destroys a previously created VM id, specified in @id. >>+ * Destroys a previously created VM id, specified in @vm_id. >> * >> * No extensions or flags are allowed currently, and so must be zero. >> */ >> struct drm_i915_gem_vm_control { >>+ /** @extensions: Zero-terminated chain of extensions. */ >> __u64 extensions; >>+ >>+ /** @flags: reserved for future usage, currently MBZ */ >> __u32 flags; >>+ >>+ /** @vm_id: Id of the VM created or to be destroyed */ >> __u32 vm_id; >> };
diff --git a/include/uapi/drm/i915_drm.h b/include/uapi/drm/i915_drm.h index de49b68b4fc8..9cf3bf47c7f2 100644 --- a/include/uapi/drm/i915_drm.h +++ b/include/uapi/drm/i915_drm.h @@ -751,14 +751,27 @@ typedef struct drm_i915_irq_wait { /* Must be kept compact -- no holes and well documented */ -typedef struct drm_i915_getparam { +/** + * struct drm_i915_getparam - Driver parameter query structure. + */ +struct drm_i915_getparam { + /** @param: Driver parameter to query. */ __s32 param; - /* + + /** + * @value: Address of memory where queried value should be put. + * * WARNING: Using pointers instead of fixed-size u64 means we need to write * compat32 code. Don't repeat this mistake. */ int __user *value; -} drm_i915_getparam_t; +}; + +/** + * typedef drm_i915_getparam_t - Driver parameter query structure. + * See struct drm_i915_getparam. + */ +typedef struct drm_i915_getparam drm_i915_getparam_t; /* Ioctl to set kernel params: */ @@ -1239,76 +1252,119 @@ struct drm_i915_gem_exec_object2 { __u64 rsvd2; }; +/** + * struct drm_i915_gem_exec_fence - An input or output fence for the execbuf + * ioctl. + * + * The request will wait for input fence to signal before submission. + * + * The returned output fence will be signaled after the completion of the + * request. + */ struct drm_i915_gem_exec_fence { - /** - * User's handle for a drm_syncobj to wait on or signal. - */ + /** @handle: User's handle for a drm_syncobj to wait on or signal. */ __u32 handle; + /** + * @flags: Supported flags are: + * + * I915_EXEC_FENCE_WAIT: + * Wait for the input fence before request submission. + * + * I915_EXEC_FENCE_SIGNAL: + * Return request completion fence as output + */ + __u32 flags; #define I915_EXEC_FENCE_WAIT (1<<0) #define I915_EXEC_FENCE_SIGNAL (1<<1) #define __I915_EXEC_FENCE_UNKNOWN_FLAGS (-(I915_EXEC_FENCE_SIGNAL << 1)) - __u32 flags; }; -/* - * See drm_i915_gem_execbuffer_ext_timeline_fences. - */ -#define DRM_I915_GEM_EXECBUFFER_EXT_TIMELINE_FENCES 0 - -/* +/** + * struct drm_i915_gem_execbuffer_ext_timeline_fences - Timeline fences + * for execbuf ioctl. + * * This structure describes an array of drm_syncobj and associated points for * timeline variants of drm_syncobj. It is invalid to append this structure to * the execbuf if I915_EXEC_FENCE_ARRAY is set. */ struct drm_i915_gem_execbuffer_ext_timeline_fences { +#define DRM_I915_GEM_EXECBUFFER_EXT_TIMELINE_FENCES 0 + /** @base: Extension link. See struct i915_user_extension. */ struct i915_user_extension base; /** - * Number of element in the handles_ptr & value_ptr arrays. + * @fence_count: Number of elements in the @handles_ptr & @value_ptr + * arrays. */ __u64 fence_count; /** - * Pointer to an array of struct drm_i915_gem_exec_fence of length - * fence_count. + * @handles_ptr: Pointer to an array of struct drm_i915_gem_exec_fence + * of length @fence_count. */ __u64 handles_ptr; /** - * Pointer to an array of u64 values of length fence_count. Values - * must be 0 for a binary drm_syncobj. A Value of 0 for a timeline - * drm_syncobj is invalid as it turns a drm_syncobj into a binary one. + * @values_ptr: Pointer to an array of u64 values of length + * @fence_count. + * Values must be 0 for a binary drm_syncobj. A Value of 0 for a + * timeline drm_syncobj is invalid as it turns a drm_syncobj into a + * binary one. */ __u64 values_ptr; }; +/** + * struct drm_i915_gem_execbuffer2 - Structure for DRM_I915_GEM_EXECBUFFER2 + * ioctl. + */ struct drm_i915_gem_execbuffer2 { - /** - * List of gem_exec_object2 structs - */ + /** @buffers_ptr: Pointer to a list of gem_exec_object2 structs */ __u64 buffers_ptr; + + /** @buffer_count: Number of elements in @buffers_ptr array */ __u32 buffer_count; - /** Offset in the batchbuffer to start execution from. */ + /** + * @batch_start_offset: Offset in the batchbuffer to start execution + * from. + */ __u32 batch_start_offset; - /** Bytes used in batchbuffer from batch_start_offset */ + + /** + * @batch_len: Length in bytes of the batch buffer, starting from the + * @batch_start_offset. If 0, length is assumed to be the batch buffer + * object size. + */ __u32 batch_len; + + /** @DR1: deprecated */ __u32 DR1; + + /** @DR4: deprecated */ __u32 DR4; + + /** @num_cliprects: See @cliprects_ptr */ __u32 num_cliprects; + /** - * This is a struct drm_clip_rect *cliprects if I915_EXEC_FENCE_ARRAY - * & I915_EXEC_USE_EXTENSIONS are not set. + * @cliprects_ptr: Kernel clipping was a DRI1 misfeature. + * + * It is invalid to use this field if I915_EXEC_FENCE_ARRAY or + * I915_EXEC_USE_EXTENSIONS flags are not set. * * If I915_EXEC_FENCE_ARRAY is set, then this is a pointer to an array - * of struct drm_i915_gem_exec_fence and num_cliprects is the length - * of the array. + * of &drm_i915_gem_exec_fence and @num_cliprects is the length of the + * array. * * If I915_EXEC_USE_EXTENSIONS is set, then this is a pointer to a - * single struct i915_user_extension and num_cliprects is 0. + * single &i915_user_extension and num_cliprects is 0. */ __u64 cliprects_ptr; + + /** @flags: Execbuf flags */ + __u64 flags; #define I915_EXEC_RING_MASK (0x3f) #define I915_EXEC_DEFAULT (0<<0) #define I915_EXEC_RENDER (1<<0) @@ -1326,10 +1382,6 @@ struct drm_i915_gem_execbuffer2 { #define I915_EXEC_CONSTANTS_REL_GENERAL (0<<6) /* default */ #define I915_EXEC_CONSTANTS_ABSOLUTE (1<<6) #define I915_EXEC_CONSTANTS_REL_SURFACE (2<<6) /* gen4/5 only */ - __u64 flags; - __u64 rsvd1; /* now used for context info */ - __u64 rsvd2; -}; /** Resets the SO write offset registers for transform feedback on gen7. */ #define I915_EXEC_GEN7_SOL_RESET (1<<8) @@ -1432,9 +1484,23 @@ struct drm_i915_gem_execbuffer2 { * drm_i915_gem_execbuffer_ext enum. */ #define I915_EXEC_USE_EXTENSIONS (1 << 21) - #define __I915_EXEC_UNKNOWN_FLAGS (-(I915_EXEC_USE_EXTENSIONS << 1)) + /** @rsvd1: Context id */ + __u64 rsvd1; + + /** + * @rsvd2: in and out sync_file file descriptors. + * + * When I915_EXEC_FENCE_IN or I915_EXEC_FENCE_SUBMIT flag is set, the + * lower 32 bits of this field will have the in sync_file fd (input). + * + * When I915_EXEC_FENCE_OUT flag is set, the upper 32 bits of this + * field will have the out sync_file fd (output). + */ + __u64 rsvd2; +}; + #define I915_EXEC_CONTEXT_ID_MASK (0xffffffff) #define i915_execbuffer2_set_context_id(eb2, context) \ (eb2).rsvd1 = context & I915_EXEC_CONTEXT_ID_MASK @@ -1814,19 +1880,56 @@ struct drm_i915_gem_context_create { __u32 pad; }; +/** + * struct drm_i915_gem_context_create_ext - Structure for creating contexts. + */ struct drm_i915_gem_context_create_ext { - __u32 ctx_id; /* output: id of new context*/ + /** @ctx_id: Id of the created context (output) */ + __u32 ctx_id; + + /** + * @flags: Supported flags are: + * + * I915_CONTEXT_CREATE_FLAGS_USE_EXTENSIONS: + * Extensions may be appended to this structure and driver must check + * for those. See @extensions. + * + * I915_CONTEXT_CREATE_FLAGS_SINGLE_TIMELINE: + * Created context will have single timeline. + */ __u32 flags; #define I915_CONTEXT_CREATE_FLAGS_USE_EXTENSIONS (1u << 0) #define I915_CONTEXT_CREATE_FLAGS_SINGLE_TIMELINE (1u << 1) #define I915_CONTEXT_CREATE_FLAGS_UNKNOWN \ (-(I915_CONTEXT_CREATE_FLAGS_SINGLE_TIMELINE << 1)) + + /** + * @extensions: Zero-terminated chain of extensions. + * + * I915_CONTEXT_CREATE_EXT_SETPARAM: + * Context parameter to set or query during context creation. + * See struct drm_i915_gem_context_create_ext_setparam. + * + * I915_CONTEXT_CREATE_EXT_CLONE: + * This extension has been removed. On the off chance someone somewhere + * has attempted to use it, never re-use this extension number. + */ __u64 extensions; +#define I915_CONTEXT_CREATE_EXT_SETPARAM 0 +#define I915_CONTEXT_CREATE_EXT_CLONE 1 }; +/** + * struct drm_i915_gem_context_param - Context parameter to set or query. + */ struct drm_i915_gem_context_param { + /** @ctx_id: Context id */ __u32 ctx_id; + + /** @size: Size of the parameter @value __u32 size; + + /** @param: Parameter to set or query */ __u64 param; #define I915_CONTEXT_PARAM_BAN_PERIOD 0x1 /* I915_CONTEXT_PARAM_NO_ZEROMAP has been removed. On the off chance @@ -1973,6 +2076,7 @@ struct drm_i915_gem_context_param { #define I915_CONTEXT_PARAM_PROTECTED_CONTENT 0xd /* Must be kept compact -- no holes and well documented */ + /** @value: Context parameter value to be set or queried */ __u64 value; }; @@ -2371,23 +2475,29 @@ struct i915_context_param_engines { struct i915_engine_class_instance engines[N__]; \ } __attribute__((packed)) name__ +/** + * struct drm_i915_gem_context_create_ext_setparam - Context parameter + * to set or query during context creation. + */ struct drm_i915_gem_context_create_ext_setparam { -#define I915_CONTEXT_CREATE_EXT_SETPARAM 0 + /** @base: Extension link. See struct i915_user_extension. */ struct i915_user_extension base; + + /** + * @param: Context parameter to set or query. + * See struct drm_i915_gem_context_param. + */ struct drm_i915_gem_context_param param; }; -/* This API has been removed. On the off chance someone somewhere has - * attempted to use it, never re-use this extension number. - */ -#define I915_CONTEXT_CREATE_EXT_CLONE 1 - struct drm_i915_gem_context_destroy { __u32 ctx_id; __u32 pad; }; -/* +/** + * struct drm_i915_gem_vm_control - Structure to create or destroy VM. + * * DRM_I915_GEM_VM_CREATE - * * Create a new virtual memory address space (ppGTT) for use within a context @@ -2397,20 +2507,23 @@ struct drm_i915_gem_context_destroy { * The id of new VM (bound to the fd) for use with I915_CONTEXT_PARAM_VM is * returned in the outparam @id. * - * No flags are defined, with all bits reserved and must be zero. - * * An extension chain maybe provided, starting with @extensions, and terminated * by the @next_extension being 0. Currently, no extensions are defined. * * DRM_I915_GEM_VM_DESTROY - * - * Destroys a previously created VM id, specified in @id. + * Destroys a previously created VM id, specified in @vm_id. * * No extensions or flags are allowed currently, and so must be zero. */ struct drm_i915_gem_vm_control { + /** @extensions: Zero-terminated chain of extensions. */ __u64 extensions; + + /** @flags: reserved for future usage, currently MBZ */ __u32 flags; + + /** @vm_id: Id of the VM created or to be destroyed */ __u32 vm_id; };
Add some missing i915 upai documentation which the new i915 VM_BIND feature documentation will be refer to. Signed-off-by: Niranjana Vishwanathapura <niranjana.vishwanathapura@intel.com> --- include/uapi/drm/i915_drm.h | 203 ++++++++++++++++++++++++++++-------- 1 file changed, 158 insertions(+), 45 deletions(-)