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.*/- /** @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