| Message ID | 20210415155958.391624-2-matthew.auld@intel.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [v3,1/4] drm/i915/uapi: hide kernel doc warnings | expand |
On Thu, Apr 15, 2021 at 04:59:56PM +0100, Matthew Auld wrote: > Add some example usage for the extension chaining also, which is quite > nifty. > > Suggested-by: Daniel Vetter <daniel@ffwll.ch> > Signed-off-by: Matthew Auld <matthew.auld@intel.com> > Cc: Joonas Lahtinen <joonas.lahtinen@linux.intel.com> > Cc: Jordan Justen <jordan.l.justen@intel.com> > Cc: Daniel Vetter <daniel.vetter@intel.com> > Cc: Kenneth Graunke <kenneth@whitecape.org> > Cc: Jason Ekstrand <jason@jlekstrand.net> > Cc: Dave Airlie <airlied@gmail.com> > Cc: dri-devel@lists.freedesktop.org > Cc: mesa-dev@lists.freedesktop.org > --- > include/uapi/drm/i915_drm.h | 46 +++++++++++++++++++++++++++++++++---- > 1 file changed, 42 insertions(+), 4 deletions(-) > > diff --git a/include/uapi/drm/i915_drm.h b/include/uapi/drm/i915_drm.h > index a50257cde9ff..d9c954a5a456 100644 > --- a/include/uapi/drm/i915_drm.h > +++ b/include/uapi/drm/i915_drm.h > @@ -62,8 +62,8 @@ extern "C" { > #define I915_ERROR_UEVENT "ERROR" > #define I915_RESET_UEVENT "RESET" > > -/* > - * i915_user_extension: Base class for defining a chain of extensions > +/** > + * struct i915_user_extension - Base class for defining a chain of extensions > * > * Many interfaces need to grow over time. In most cases we can simply > * extend the struct and have userspace pass in more data. Another option, > @@ -76,12 +76,50 @@ extern "C" { > * increasing complexity, and for large parts of that interface to be > * entirely optional. The downside is more pointer chasing; chasing across > * the __user boundary with pointers encapsulated inside u64. > + * > + * Example chaining: > + * > + * .. code-block:: C > + * > + * struct i915_user_extension ext3 { > + * .next_extension = 0, // end > + * .name = ..., > + * }; > + * struct i915_user_extension ext2 { > + * .next_extension = (uintptr_t)&ext3, > + * .name = ..., > + * }; > + * struct i915_user_extension ext1 { > + * .next_extension = (uintptr_t)&ext2, > + * .name = ..., > + * }; > + * > + * Typically the i915_user_extension would be embedded in some uAPI struct, and > + * in this case we would feed it the head of the chain(i.e ext1), which would > + * then apply all of the above extensions. > + * > */ > struct i915_user_extension { > + /** > + * @next_extension: > + * > + * Pointer to the next i915_user_extension, or zero if the end. > + */ > __u64 next_extension; > + /** @name: Name of the extension */ Maybe clarify that the namespace here is per ioctl, not global. And maybe also that the name is just an integer #define or something like that. Either this is solid documentation, either way: Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch> > __u32 name; > - __u32 flags; /* All undefined bits must be zero. */ > - __u32 rsvd[4]; /* Reserved for future use; must be zero. */ > + /** > + * @flags: MBZ > + * > + * All undefined bits must be zero. > + */ > + __u32 flags; > + /** > + * @rsvd: MBZ > + * > + * Reserved for future use; must be zero. > + */ > + __u32 rsvd[4]; > }; > > /* > -- > 2.26.3 >
diff --git a/include/uapi/drm/i915_drm.h b/include/uapi/drm/i915_drm.h index a50257cde9ff..d9c954a5a456 100644 --- a/include/uapi/drm/i915_drm.h +++ b/include/uapi/drm/i915_drm.h @@ -62,8 +62,8 @@ extern "C" { #define I915_ERROR_UEVENT "ERROR" #define I915_RESET_UEVENT "RESET" -/* - * i915_user_extension: Base class for defining a chain of extensions +/** + * struct i915_user_extension - Base class for defining a chain of extensions * * Many interfaces need to grow over time. In most cases we can simply * extend the struct and have userspace pass in more data. Another option, @@ -76,12 +76,50 @@ extern "C" { * increasing complexity, and for large parts of that interface to be * entirely optional. The downside is more pointer chasing; chasing across * the __user boundary with pointers encapsulated inside u64. + * + * Example chaining: + * + * .. code-block:: C + * + * struct i915_user_extension ext3 { + * .next_extension = 0, // end + * .name = ..., + * }; + * struct i915_user_extension ext2 { + * .next_extension = (uintptr_t)&ext3, + * .name = ..., + * }; + * struct i915_user_extension ext1 { + * .next_extension = (uintptr_t)&ext2, + * .name = ..., + * }; + * + * Typically the i915_user_extension would be embedded in some uAPI struct, and + * in this case we would feed it the head of the chain(i.e ext1), which would + * then apply all of the above extensions. + * */ struct i915_user_extension { + /** + * @next_extension: + * + * Pointer to the next i915_user_extension, or zero if the end. + */ __u64 next_extension; + /** @name: Name of the extension */ __u32 name; - __u32 flags; /* All undefined bits must be zero. */ - __u32 rsvd[4]; /* Reserved for future use; must be zero. */ + /** + * @flags: MBZ + * + * All undefined bits must be zero. + */ + __u32 flags; + /** + * @rsvd: MBZ + * + * Reserved for future use; must be zero. + */ + __u32 rsvd[4]; }; /*
Add some example usage for the extension chaining also, which is quite nifty. Suggested-by: Daniel Vetter <daniel@ffwll.ch> Signed-off-by: Matthew Auld <matthew.auld@intel.com> Cc: Joonas Lahtinen <joonas.lahtinen@linux.intel.com> Cc: Jordan Justen <jordan.l.justen@intel.com> Cc: Daniel Vetter <daniel.vetter@intel.com> Cc: Kenneth Graunke <kenneth@whitecape.org> Cc: Jason Ekstrand <jason@jlekstrand.net> Cc: Dave Airlie <airlied@gmail.com> Cc: dri-devel@lists.freedesktop.org Cc: mesa-dev@lists.freedesktop.org --- include/uapi/drm/i915_drm.h | 46 +++++++++++++++++++++++++++++++++---- 1 file changed, 42 insertions(+), 4 deletions(-)