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, Daniel Vetter <daniel.vetter@ffwll.ch>, Kenneth Graunke <kenneth@whitecape.org>, Jason Ekstrand <jason@jlekstrand.net>, mesa-dev@lists.freedesktop.org, Daniel Vetter <daniel.vetter@intel.com> Subject: [PATCH 3/4] drm/i915/uapi: convert i915_user_extension to kernel doc Date: Fri, 16 Apr 2021 11:37:17 +0100 [thread overview] Message-ID: <20210416103718.460830-3-matthew.auld@intel.com> (raw) In-Reply-To: <20210416103718.460830-1-matthew.auld@intel.com> 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 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> --- include/uapi/drm/i915_drm.h | 54 ++++++++++++++++++++++++++++++++++--- 1 file changed, 50 insertions(+), 4 deletions(-) diff --git a/include/uapi/drm/i915_drm.h b/include/uapi/drm/i915_drm.h index 92da48e935d1..d79b51c12ff2 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 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]; }; /* -- 2.26.3 _______________________________________________ dri-devel mailing list dri-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/dri-devel
WARNING: multiple messages have this Message-ID (diff)
From: Matthew Auld <matthew.auld@intel.com> To: intel-gfx@lists.freedesktop.org Cc: dri-devel@lists.freedesktop.org, Daniel Vetter <daniel.vetter@ffwll.ch>, Kenneth Graunke <kenneth@whitecape.org>, mesa-dev@lists.freedesktop.org, Daniel Vetter <daniel.vetter@intel.com> Subject: [Intel-gfx] [PATCH 3/4] drm/i915/uapi: convert i915_user_extension to kernel doc Date: Fri, 16 Apr 2021 11:37:17 +0100 [thread overview] Message-ID: <20210416103718.460830-3-matthew.auld@intel.com> (raw) In-Reply-To: <20210416103718.460830-1-matthew.auld@intel.com> 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 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> --- include/uapi/drm/i915_drm.h | 54 ++++++++++++++++++++++++++++++++++--- 1 file changed, 50 insertions(+), 4 deletions(-) diff --git a/include/uapi/drm/i915_drm.h b/include/uapi/drm/i915_drm.h index 92da48e935d1..d79b51c12ff2 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 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]; }; /* -- 2.26.3 _______________________________________________ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/intel-gfx
next prev parent reply other threads:[~2021-04-16 10:38 UTC|newest] Thread overview: 18+ messages / expand[flat|nested] mbox.gz Atom feed top 2021-04-16 10:37 [PATCH 1/4] drm/i915/uapi: fix kernel doc warnings Matthew Auld 2021-04-16 10:37 ` [Intel-gfx] " Matthew Auld 2021-04-16 10:37 ` [PATCH 2/4] drm/doc: add section for driver uAPI Matthew Auld 2021-04-16 10:37 ` [Intel-gfx] " Matthew Auld 2021-04-16 14:05 ` Daniel Vetter 2021-04-16 14:05 ` [Intel-gfx] " Daniel Vetter 2021-04-16 10:37 ` Matthew Auld [this message] 2021-04-16 10:37 ` [Intel-gfx] [PATCH 3/4] drm/i915/uapi: convert i915_user_extension to kernel doc Matthew Auld 2021-04-16 18:29 ` Jason Ekstrand 2021-04-16 18:29 ` [Intel-gfx] " Jason Ekstrand 2021-04-16 10:37 ` [PATCH 4/4] drm/i915/uapi: convert i915_query and friend " Matthew Auld 2021-04-16 10:37 ` [Intel-gfx] " Matthew Auld 2021-04-16 18:32 ` Jason Ekstrand 2021-04-16 18:32 ` [Intel-gfx] " Jason Ekstrand 2021-04-16 11:10 ` [Intel-gfx] ✗ Fi.CI.CHECKPATCH: warning for series starting with [1/4] drm/i915/uapi: fix kernel doc warnings Patchwork 2021-04-16 11:16 ` [Intel-gfx] ✗ Fi.CI.DOCS: " Patchwork 2021-04-16 11:41 ` [Intel-gfx] ✓ Fi.CI.BAT: success " Patchwork 2021-04-16 13:00 ` [Intel-gfx] ✓ Fi.CI.IGT: " Patchwork
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=20210416103718.460830-3-matthew.auld@intel.com \ --to=matthew.auld@intel.com \ --cc=daniel.vetter@ffwll.ch \ --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: linkBe sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.