<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<body>
<div dir="auto">
<div dir="auto"><span style="font-size: 12pt;">On April 16, 2021 05:37:52 Matthew Auld <matthew.auld@intel.com> wrote:</span></div><div id="aqm-original" style="color: black;">
<div><br></div>
<blockquote type="cite" class="gmail_quote" style="margin: 0 0 0 0.75ex; border-left: 1px solid #808080; padding-left: 0.75ex;">
<div dir="auto">Add some example usage for the extension chaining also, which is quite</div>
<div dir="auto">nifty.</div>
<div dir="auto"><br></div>
<div dir="auto">v2: (Daniel)</div>
<div dir="auto"> - clarify that the name is just some integer, also document that the</div>
<div dir="auto"> name space is not global</div>
<div dir="auto"><br></div>
<div dir="auto">Suggested-by: Daniel Vetter <daniel@ffwll.ch></div>
<div dir="auto">Signed-off-by: Matthew Auld <matthew.auld@intel.com></div>
<div dir="auto">Cc: Joonas Lahtinen <joonas.lahtinen@linux.intel.com></div>
<div dir="auto">Cc: Jordan Justen <jordan.l.justen@intel.com></div>
<div dir="auto">Cc: Daniel Vetter <daniel.vetter@intel.com></div>
<div dir="auto">Cc: Kenneth Graunke <kenneth@whitecape.org></div>
<div dir="auto">Cc: Jason Ekstrand <jason@jlekstrand.net></div>
<div dir="auto">Cc: Dave Airlie <airlied@gmail.com></div>
<div dir="auto">Cc: dri-devel@lists.freedesktop.org</div>
<div dir="auto">Cc: mesa-dev@lists.freedesktop.org</div>
<div dir="auto">Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch></div>
<div dir="auto">---</div>
<div dir="auto"> include/uapi/drm/i915_drm.h | 54 ++++++++++++++++++++++++++++++++++---</div>
<div dir="auto"> 1 file changed, 50 insertions(+), 4 deletions(-)</div>
<div dir="auto"><br></div>
<div dir="auto">diff --git a/include/uapi/drm/i915_drm.h b/include/uapi/drm/i915_drm.h</div>
<div dir="auto">index 92da48e935d1..d79b51c12ff2 100644</div>
<div dir="auto">--- a/include/uapi/drm/i915_drm.h</div>
<div dir="auto">+++ b/include/uapi/drm/i915_drm.h</div>
<div dir="auto">@@ -62,8 +62,8 @@ extern "C" {</div>
<div dir="auto"> #define I915_ERROR_UEVENT "ERROR"</div>
<div dir="auto"> #define I915_RESET_UEVENT "RESET"</div>
<div dir="auto"> </div>
<div dir="auto">-/*</div>
<div dir="auto">- * i915_user_extension: Base class for defining a chain of extensions</div>
<div dir="auto">+/**</div>
<div dir="auto">+ * struct i915_user_extension - Base class for defining a chain of extensions</div>
<div dir="auto"> *</div>
<div dir="auto"> * Many interfaces need to grow over time. In most cases we can simply</div>
<div dir="auto"> * extend the struct and have userspace pass in more data. Another option,</div>
<div dir="auto">@@ -76,12 +76,58 @@ extern "C" {</div>
<div dir="auto"> * increasing complexity, and for large parts of that interface to be</div>
<div dir="auto"> * entirely optional. The downside is more pointer chasing; chasing across</div>
<div dir="auto"> * the __user boundary with pointers encapsulated inside u64.</div>
<div dir="auto">+ *</div>
<div dir="auto">+ * Example chaining:</div>
<div dir="auto">+ *</div>
<div dir="auto">+ * .. code-block:: C</div>
<div dir="auto">+ *</div>
<div dir="auto">+ * struct i915_user_extension ext3 {</div>
<div dir="auto">+ * .next_extension = 0, // end</div>
<div dir="auto">+ * .name = ...,</div>
<div dir="auto">+ * };</div>
<div dir="auto">+ * struct i915_user_extension ext2 {</div>
<div dir="auto">+ * .next_extension = (uintptr_t)&ext3,</div>
<div dir="auto">+ * .name = ...,</div>
<div dir="auto">+ * };</div>
<div dir="auto">+ * struct i915_user_extension ext1 {</div>
<div dir="auto">+ * .next_extension = (uintptr_t)&ext2,</div>
<div dir="auto">+ * .name = ...,</div>
<div dir="auto">+ * };</div>
<div dir="auto">+ *</div>
<div dir="auto">+ * Typically the i915_user_extension would be embedded in some uAPI struct, and</div>
<div dir="auto">+ * in this case we would feed it the head of the chain(i.e ext1), which would</div>
<div dir="auto">+ * then apply all of the above extensions.</div>
<div dir="auto">+ *</div>
<div dir="auto"> */</div>
<div dir="auto"> struct i915_user_extension {</div>
<div dir="auto">+ /**</div>
<div dir="auto">+ * @next_extension:</div>
<div dir="auto">+ *</div>
<div dir="auto">+ * Pointer to the next struct i915_user_extension, or zero if the end.</div>
<div dir="auto">+ */</div>
<div dir="auto"> __u64 next_extension;</div>
<div dir="auto">+ /**</div>
<div dir="auto">+ * @name: Name of the extension.</div>
<div dir="auto">+ *</div>
<div dir="auto">+ * Note that the name here is just some integer.</div>
<div dir="auto">+ *</div>
<div dir="auto">+ * Also note that the name space for this is not global for the whole</div>
<div dir="auto">+ * driver, but rather its scope/meaning is limited to the specific piece</div>
<div dir="auto">+ * of uAPI which has embedded the struct i915_user_extension.</div></blockquote></div><div dir="auto"><br></div><div dir="auto">We may want to rethink this decision. In Vulkan, we have several cases where we use the same extension multiple places. Given that the only extensible thing currently landed is context creation, we still could make this global. Then again, forcing us to go through the exercise of redefining every time has its advantages too.</div><div dir="auto"><br></div><div dir="auto">In any case, this is a correct description of the current state of affairs, so</div><div dir="auto"><br></div><div dir="auto">Reviewed-by: Jason Ekstrand <jason@jlekstrand.net></div><div dir="auto"><br></div><div dir="auto"><br></div><div id="aqm-original" style="color: black;" dir="auto"><blockquote type="cite" class="gmail_quote" style="margin: 0 0 0 0.75ex; border-left: 1px solid #808080; padding-left: 0.75ex;"><div dir="auto"></div>
<div dir="auto">+ */</div>
<div dir="auto"> __u32 name;</div>
<div dir="auto">- __u32 flags; /* All undefined bits must be zero. */</div>
<div dir="auto">- __u32 rsvd[4]; /* Reserved for future use; must be zero. */</div>
<div dir="auto">+ /**</div>
<div dir="auto">+ * @flags: MBZ</div>
<div dir="auto">+ *</div>
<div dir="auto">+ * All undefined bits must be zero.</div>
<div dir="auto">+ */</div>
<div dir="auto">+ __u32 flags;</div>
<div dir="auto">+ /**</div>
<div dir="auto">+ * @rsvd: MBZ</div>
<div dir="auto">+ *</div>
<div dir="auto">+ * Reserved for future use; must be zero.</div>
<div dir="auto">+ */</div>
<div dir="auto">+ __u32 rsvd[4];</div>
<div dir="auto"> };</div>
<div dir="auto"> </div>
<div dir="auto"> /*</div>
<div dir="auto">-- </div>
<div dir="auto">2.26.3</div>
</blockquote>
</div><div dir="auto"><br></div>
</div></body>
</html>