Re: [Intel-gfx] [RFC v3 2/3] drm/i915: Update i915 uapi documentation
On Wed, Jun 08, 2022 at 12:24:04PM +0100, Matthew Auld wrote: On Tue, 17 May 2022 at 19:32, 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 --- include/uapi/drm/i915_drm.h | 153 +++- 1 file changed, 116 insertions(+), 37 deletions(-) diff --git a/include/uapi/drm/i915_drm.h b/include/uapi/drm/i915_drm.h index a2def7b27009..8c834a31b56f 100644 --- a/include/uapi/drm/i915_drm.h +++ b/include/uapi/drm/i915_drm.h @@ -751,9 +751,16 @@ typedef struct drm_i915_irq_wait { /* Must be kept compact -- no holes and well documented */ +/** + * typedef drm_i915_getparam_t - Driver parameter query structure. This one looks funny in the rendered html for some reason, since it doesn't seem to emit the @param and @value, I guess it doesn't really understand typedef ? Maybe make this "struct drm_i915_getparam - Driver parameter query structure." ? Thanks Matt. Yah, there doesn't seems to be a good way to add kernel doc for this kind of declaration. 'struct drm_i915_getparam' also didn't help. I was able to fix it by first defining the structure and then adding a typedef for it. Not sure if that has any value, but at least we can get kernel doc for that. + */ typedef 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. */ @@ -1239,76 +1246,114 @@ struct drm_i915_gem_exec_object2 { __u64 rsvd2; }; +/** + * struct drm_i915_gem_exec_fence - An input or output fence for the execbuff s/execbuff/execbuf/, at least that seems to be what we use elsewhere, AFAICT. + * 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, 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 execbuff. + * * 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 element in the @handles_ptr & @value_ptr s/element/elements/ +* 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 execbuff submission + */ 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 batchbu
Re: [Intel-gfx] [RFC v3 2/3] drm/i915: Update i915 uapi documentation
On Tue, 17 May 2022 at 19:32, 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 > --- > include/uapi/drm/i915_drm.h | 153 +++- > 1 file changed, 116 insertions(+), 37 deletions(-) > > diff --git a/include/uapi/drm/i915_drm.h b/include/uapi/drm/i915_drm.h > index a2def7b27009..8c834a31b56f 100644 > --- a/include/uapi/drm/i915_drm.h > +++ b/include/uapi/drm/i915_drm.h > @@ -751,9 +751,16 @@ typedef struct drm_i915_irq_wait { > > /* Must be kept compact -- no holes and well documented */ > > +/** > + * typedef drm_i915_getparam_t - Driver parameter query structure. This one looks funny in the rendered html for some reason, since it doesn't seem to emit the @param and @value, I guess it doesn't really understand typedef ? Maybe make this "struct drm_i915_getparam - Driver parameter query structure." ? > + */ > typedef 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. > */ > @@ -1239,76 +1246,114 @@ struct drm_i915_gem_exec_object2 { > __u64 rsvd2; > }; > > +/** > + * struct drm_i915_gem_exec_fence - An input or output fence for the execbuff s/execbuff/execbuf/, at least that seems to be what we use elsewhere, AFAICT. > + * 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, 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 execbuff. > + * > * 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 element in the @handles_ptr & @value_ptr s/element/elements/ > +* 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 execbuff submission > + */ > 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 > +* fr
[Intel-gfx] [RFC v3 2/3] drm/i915: Update i915 uapi documentation
Add some missing i915 upai documentation which the new i915 VM_BIND feature documentation will be refer to. Signed-off-by: Niranjana Vishwanathapura --- include/uapi/drm/i915_drm.h | 153 +++- 1 file changed, 116 insertions(+), 37 deletions(-) diff --git a/include/uapi/drm/i915_drm.h b/include/uapi/drm/i915_drm.h index a2def7b27009..8c834a31b56f 100644 --- a/include/uapi/drm/i915_drm.h +++ b/include/uapi/drm/i915_drm.h @@ -751,9 +751,16 @@ typedef struct drm_i915_irq_wait { /* Must be kept compact -- no holes and well documented */ +/** + * typedef drm_i915_getparam_t - Driver parameter query structure. + */ typedef 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. */ @@ -1239,76 +1246,114 @@ struct drm_i915_gem_exec_object2 { __u64 rsvd2; }; +/** + * struct drm_i915_gem_exec_fence - An input or output fence for the execbuff + * 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 execbuff. + * * 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 element 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 execbuff submission + */ 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: Bytes used in batchbuffer from batch_start_offset */ __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