diff options
author | Matthew Auld <matthew.auld@intel.com> | 2021-04-19 11:57:40 +0100 |
---|---|---|
committer | Matthew Auld <matthew.auld@intel.com> | 2021-04-20 10:11:00 +0100 |
commit | 19d053d477a145069bc2c38b28dcee773690c804 (patch) | |
tree | 68795c7637068c37b20bb104598ffac305ecfaf9 | |
parent | 2ef6a01fb636997bfec57b015d4e4b5a745ef38a (diff) | |
download | linux-stable-19d053d477a145069bc2c38b28dcee773690c804.tar.gz linux-stable-19d053d477a145069bc2c38b28dcee773690c804.tar.bz2 linux-stable-19d053d477a145069bc2c38b28dcee773690c804.zip |
drm/i915/uapi: convert i915_user_extension to kernel doc
Add some example usage for the extension chaining also, which is quite
nifty.
v2: (Daniel)
- clarify that the name is just some integer, also document that the
name space is not global
v3: prefer kernel-doc references for structs
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
Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Reviewed-by: Jason Ekstrand <jason@jlekstrand.net>
Link: https://patchwork.freedesktop.org/patch/msgid/20210419105741.27844-3-matthew.auld@intel.com
-rw-r--r-- | include/uapi/drm/i915_drm.h | 54 |
1 files changed, 50 insertions, 4 deletions
diff --git a/include/uapi/drm/i915_drm.h b/include/uapi/drm/i915_drm.h index 92da48e935d1..e2867d8cd5e3 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,58 @@ 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 struct 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 struct i915_user_extension, or zero if the end. + */ __u64 next_extension; + /** + * @name: Name of the extension. + * + * Note that the name here is just some integer. + * + * Also note that the name space for this is not global for the whole + * driver, but rather its scope/meaning is limited to the specific piece + * of uAPI which has embedded the struct i915_user_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]; }; /* |