From: Matthew Auld <matthew.auld@intel.com>
To: intel-gfx@lists.freedesktop.org
Cc: Jordan Justen <jordan.l.justen@intel.com>,
dri-devel@lists.freedesktop.org,
Kenneth Graunke <kenneth@whitecape.org>,
Jason Ekstrand <jason@jlekstrand.net>,
mesa-dev@lists.freedesktop.org,
Daniel Vetter <daniel.vetter@intel.com>
Subject: [PATCH v3 2/4] drm/i915/uapi: convert i915_user_extension to kernel doc
Date: Thu, 15 Apr 2021 16:59:56 +0100 [thread overview]
Message-ID: <20210415155958.391624-2-matthew.auld@intel.com> (raw)
In-Reply-To: <20210415155958.391624-1-matthew.auld@intel.com>
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 */
__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
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
next prev parent reply other threads:[~2021-04-15 16:04 UTC|newest]
Thread overview: 27+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-04-15 15:59 [PATCH v3 1/4] drm/i915/uapi: hide kernel doc warnings Matthew Auld
2021-04-15 15:59 ` Matthew Auld [this message]
2021-04-16 8:46 ` [PATCH v3 2/4] drm/i915/uapi: convert i915_user_extension to kernel doc Daniel Vetter
2021-04-15 15:59 ` [PATCH v3 3/4] drm/i915/uapi: convert i915_query and friend " Matthew Auld
2021-04-15 22:25 ` [Mesa-dev] " Ian Romanick
2021-04-16 8:59 ` Daniel Vetter
2021-04-16 19:04 ` Jonathan Corbet
2021-04-16 7:57 ` [Intel-gfx] " Tvrtko Ursulin
2021-04-16 8:49 ` Daniel Vetter
2021-04-15 15:59 ` [PATCH v3 4/4] drm/doc/rfc: i915 DG1 uAPI Matthew Auld
2021-04-16 9:15 ` Daniel Vetter
2021-04-16 16:38 ` Jason Ekstrand
2021-04-16 17:02 ` Daniel Vetter
2021-04-16 17:33 ` Daniele Ceraolo Spurio
2021-04-19 12:02 ` Matthew Auld
2021-04-19 15:19 ` Jason Ekstrand
2021-04-20 16:34 ` Tvrtko Ursulin
2021-04-20 17:00 ` Jason Ekstrand
2021-04-21 8:22 ` Tvrtko Ursulin
2021-04-21 13:54 ` Jason Ekstrand
2021-04-21 14:25 ` Tvrtko Ursulin
2021-04-21 17:17 ` Jason Ekstrand
2021-04-21 18:28 ` Tvrtko Ursulin
2021-04-21 19:23 ` [Mesa-dev] " Daniel Vetter
2021-04-26 15:22 ` Jason Ekstrand
2021-04-16 8:44 ` [PATCH v3 1/4] drm/i915/uapi: hide kernel doc warnings Daniel Vetter
2021-04-16 8:54 ` Daniel Vetter
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20210415155958.391624-2-matthew.auld@intel.com \
--to=matthew.auld@intel.com \
--cc=daniel.vetter@intel.com \
--cc=dri-devel@lists.freedesktop.org \
--cc=intel-gfx@lists.freedesktop.org \
--cc=jason@jlekstrand.net \
--cc=jordan.l.justen@intel.com \
--cc=kenneth@whitecape.org \
--cc=mesa-dev@lists.freedesktop.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).