Commit 19d053d4 authored by Matthew Auld's avatar Matthew Auld
Browse files

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: default avatarDaniel Vetter <daniel@ffwll.ch>
Signed-off-by: default avatarMatthew 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: default avatarDaniel Vetter <daniel.vetter@ffwll.ch>
Reviewed-by: default avatarJason Ekstrand <jason@jlekstrand.net>
Link: https://patchwork.freedesktop.org/patch/msgid/20210419105741.27844-3-matthew.auld@intel.com
parent 2ef6a01f

include/uapi/drm/i915_drm.h

+50 −4
Original line number Diff line number Diff line
@@ -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];

};



/*