On 18.05.2018 23:33, Thierry Reding wrote:
> From: Thierry Reding <treding@xxxxxxxxxx>
>
> Document the userspace ABI with kerneldoc to provide some information on
> how to use it.
>
> v2:
> - keep GEM object creation flags for ABI compatibility
> - fix typo in struct drm_tegra_syncpt_incr kerneldoc
> - fix typos in struct drm_tegra_submit kerneldoc
> - reworded some descriptions as suggested
>
> Signed-off-by: Thierry Reding <treding@xxxxxxxxxx>
> ---
> include/uapi/drm/tegra_drm.h | 480 ++++++++++++++++++++++++++++++++++-
> 1 file changed, 471 insertions(+), 9 deletions(-)
>
> diff --git a/include/uapi/drm/tegra_drm.h b/include/uapi/drm/tegra_drm.h
> index 99e15d82d1e9..7e121c69cd9a 100644
> --- a/include/uapi/drm/tegra_drm.h
> +++ b/include/uapi/drm/tegra_drm.h
> @@ -32,143 +32,605 @@ extern "C" {
> #define DRM_TEGRA_GEM_CREATE_TILED (1 << 0)
> #define DRM_TEGRA_GEM_CREATE_BOTTOM_UP (1 << 1)
>
> +/**
> + * struct drm_tegra_gem_create - parameters for the GEM object creation IOCTL
> + */
> struct drm_tegra_gem_create {
> + /**
> + * @size:
> + *
> + * The size, in bytes, of the buffer object to be created.
> + */
> __u64 size;
> +
> + /**
> + * @flags:
> + *
> + * A bitmask of flags that influence the creation of GEM objects:
> + *
> + * DRM_TEGRA_GEM_CREATE_TILED
> + * Use the 16x16 tiling format for this buffer.
> + *
> + * DRM_TEGRA_GEM_CREATE_BOTTOM_UP
> + * The buffer has a bottom-up layout.
> + */
> __u32 flags;
> +
> + /**
> + * @handle:
> + *
> + * The handle of the created GEM object. Set by the kernel upon
> + * successful completion of the IOCTL.
> + */
> __u32 handle;
> };
>
> +/**
> + * struct drm_tegra_gem_mmap - parameters for the GEM mmap IOCTL
> + */
> struct drm_tegra_gem_mmap {
> + /**
> + * @handle:
> + *
> + * Handle of the GEM object to obtain an mmap offset for.
> + */
> __u32 handle;
> +
> + /**
> + * @pad:
> + *
> + * Structure padding that may be used in the future. Must be 0.
> + */
> __u32 pad;
> +
> + /**
> + * @offset:
> + *
> + * The mmap offset for the given GEM object. Set by the kernel upon
> + * successful completion of the IOCTL.
> + */
> __u64 offset;
> };
>
> +/**
> + * struct drm_tegra_syncpt_read - parameters for the read syncpoint IOCTL
> + */
> struct drm_tegra_syncpt_read {
> + /**
> + * @id:
> + *
> + * ID of the syncpoint to read the current value from.
> + */
> __u32 id;
> +
> + /**
> + * @value:
> + *
> + * The current syncpoint value. Set by the kernel upon successful
> + * completion of the IOCTL.
> + */
> __u32 value;
> };
>
> +/**
> + * struct drm_tegra_syncpt_incr - parameters for the increment syncpoint IOCTL
> + */
> struct drm_tegra_syncpt_incr {
> + /**
> + * @id:
> + *
> + * ID of the syncpoint to increment.
> + */
> __u32 id;
> +
> + /**
> + * @pad:
> + *
> + * Structure padding that may be used in the future. Must be 0.
> + */
> __u32 pad;
> };
>
> +/**
> + * struct drm_tegra_syncpt_wait - parameters for the wait syncpoint IOCTL
> + */
> struct drm_tegra_syncpt_wait {
> + /**
> + * @id:
> + *
> + * ID of the syncpoint to wait on.
> + */
> __u32 id;
> +
> + /**
> + * @thresh:
> + *
> + * Threshold value for which to wait.
> + */
> __u32 thresh;
> +
> + /**
> + * @timeout:
> + *
> + * Timeout, in milliseconds, to wait.
> + */
> __u32 timeout;
> +
> + /**
> + * @value:
> + *
> + * The new syncpoint value after the wait. Set by the kernel upon
> + * successful completion of the IOCTL.
> + */
> __u32 value;
> };
>
> #define DRM_TEGRA_NO_TIMEOUT (0xffffffff)
>
> +/**
> + * struct drm_tegra_open_channel - parameters for the open channel IOCTL
> + */
> struct drm_tegra_open_channel {
> + /**
> + * @client:
> + *
> + * The client ID for this channel.
> + */
> __u32 client;
> +
> + /**
> + * @pad:
> + *
> + * Structure padding that may be used in the future. Must be 0.
> + */
> __u32 pad;
> +
> + /**
> + * @context:
> + *
> + * The application context of this channel. Set by the kernel upon
> + * successful completion of the IOCTL. This context needs to be passed
> + * to the DRM_TEGRA_CHANNEL_CLOSE or the DRM_TEGRA_SUBMIT IOCTLs.
> + */
> __u64 context;
> };
>
> +/**
> + * struct drm_tegra_close_channel - parameters for the close channel IOCTL
> + */
> struct drm_tegra_close_channel {
> + /**
> + * @context:
> + *
> + * The application context of this channel. This is obtained from the
> + * DRM_TEGRA_OPEN_CHANNEL IOCTL.
> + */
> __u64 context;
> };
>
> +/**
> + * struct drm_tegra_get_syncpt - parameters for the get syncpoint IOCTL
> + */
> struct drm_tegra_get_syncpt {
> + /**
> + * @context:
> + *
> + * The application context identifying the channel for which to obtain
> + * the syncpoint ID.
> + */
> __u64 context;
> +
> + /**
> + * @index:
> + *
> + * Index of the client syncpoint for which to obtain the ID.
> + */
> __u32 index;
> +
> + /**
> + * @id:
> + *
> + * The ID of the given syncpoint. Set by the kernel upon successful
> + * completion of the IOCTL.
> + */
> __u32 id;
> };
>
> +/**
> + * struct drm_tegra_get_syncpt_base - parameters for the get wait base IOCTL
> + */
> struct drm_tegra_get_syncpt_base {
> + /**
> + * @context:
> + *
> + * The application context identifying for which channel to obtain the
> + * wait base.
> + */
> __u64 context;
> +
> + /**
> + * @syncpt:
> + *
> + * ID of the syncpoint for which to obtain the wait base.
> + */
> __u32 syncpt;
> +
> + /**
> + * @id:
> + *
> + * The ID of the wait base corresponding to the client syncpoint. Set
> + * by the kernel upon successful completion of the IOCTL.
> + */
> __u32 id;
> };
>
> +/**
> + * struct drm_tegra_syncpt - syncpoint increment operation
> + */
> struct drm_tegra_syncpt {
> + /**
> + * @id:
> + *
> + * ID of the syncpoint to operate on.
> + */
> __u32 id;
> +
> + /**
> + * @incrs:
> + *
> + * Number of increments to perform for the syncpoint.
> + */
> __u32 incrs;
> };
>
> +/**
> + * struct drm_tegra_cmdbuf - structure describing a command buffer
> + */
> struct drm_tegra_cmdbuf {
> + /**
> + * @handle:
> + *
> + * Handle to a GEM object containing the command buffer.
> + */
> __u32 handle;
> +
> + /**
> + * @offset:
> + *
> + * Offset, in bytes, into the GEM object identified by @handle at
> + * which the command buffer starts.
> + */
> __u32 offset;
> +
> + /**
> + * @words:
> + *
> + * Number of 32-bit words in this command buffer.
> + */
> __u32 words;
> +
> + /**
> + * @pad:
> + *
> + * Structure padding that may be used in the future. Must be 0.
> + */
> __u32 pad;
> };
>
> +/**
> + * struct drm_tegra_reloc - GEM object relocation structure
> + */
> struct drm_tegra_reloc {
> struct {
> + /**
> + * @cmdbuf.handle:
> + *
> + * Handle to the GEM object containing the command buffer for
> + * which to perform this GEM object relocation.
> + */
> __u32 handle;
> +
> + /**
> + * @cmdbuf.offset:
> + *
> + * Offset, in bytes, into the command buffer at which to
> + * insert the relocated address.
> + */
> __u32 offset;
> } cmdbuf;
> struct {
> + /**
> + * @target.handle:
> + *
> + * Handle to the GEM object to be relocated.
> + */
> __u32 handle;
> +
> + /**
> + * @target.offset:
> + *
> + * Offset, in bytes, into the target GEM object at which the
> + * relocated data starts.
> + */
> __u32 offset;
> } target;
> +
> + /**
> + * @shift:
> + *
> + * The number of bits by which to shift relocated addresses.
> + */
> __u32 shift;
> +
> + /**
> + * @pad:
> + *
> + * Structure padding that may be used in the future. Must be 0.
> + */
> __u32 pad;
> };
>
> +/**
> + * struct drm_tegra_waitchk - wait check structure
> + */
> struct drm_tegra_waitchk {
> + /**
> + * @handle:
> + *
> + * Handle to the GEM object containing a command stream on which to
> + * perform the wait check.
> + */
> __u32 handle;
> +
> + /**
> + * @offset:
> + *
> + * Offset, in bytes, of the location in the command stream to perform
> + * the wait check on.
> + */
> __u32 offset;
> +
> + /**
> + * @syncpt:
> + *
> + * ID of the syncpoint to wait check.
> + */
> __u32 syncpt;
> +
> + /**
> + * @thresh:
> + *
> + * Threshold value for which to check.
> + */
> __u32 thresh;
> };
>
> +/**
> + * struct drm_tegra_submit - job submission structure
> + */
> struct drm_tegra_submit {
> + /**
> + * @context:
> + *
> + * The application context identifying the channel to use for the
> + * execution of this job.
> + */
> __u64 context;
> +
> + /**
> + * @num_syncpts:
> + *
> + * The number of syncpoints operated on by this job.
> + */
> __u32 num_syncpts;
> +
> + /**
> + * @num_cmdbufs:
> + *
> + * The number of command buffers to execute as part of this job.
> + */
> __u32 num_cmdbufs;
> +
> + /**
> + * @num_relocs:
> + *
> + * The number of relocations to perform before executing this job.
> + */
> __u32 num_relocs;
> +
> + /**
> + * @num_waitchks:
> + *
> + * The number of wait checks to perform as part of this job.
> + */
> __u32 num_waitchks;
> +
> + /**
> + * @waitchk_mask:
> + *
> + * Bitmask of valid wait checks.
> + */
> __u32 waitchk_mask;
> +
> + /**
> + * @timeout:
> + *
> + * Timeout, in milliseconds, before this job is cancelled.
> + */
> __u32 timeout;
> +
> + /**
> + * @syncpts:
> + *
> + * A pointer to @num_syncpts &struct drm_tegra_syncpt structures that
I'm not sure whether this "pointer to @num_syncpts" makes sense, shouldn't it be:
A pointer to &struct drm_tegra_syncpt structures that...
?
Same for the @cmdbufs/@relocs/@waitchks members.
The rest looks good to be, well done! And with the above nit being resolved:
Reviewed-by: Dmitry Osipenko <digetx@xxxxxxxxx>
> + * specify the syncpoint operations performed as part of this job.
> + */
> __u64 syncpts;
> +
> + /**
> + * @cmdbufs:
> + *
> + * A pointer to @num_cmdbufs &struct drm_tegra_cmdbuf structures that
> + * define the command buffers to execute as part of this job.
> + */
> __u64 cmdbufs;
> +
> + /**
> + * @relocs:
> + *
> + * A pointer to @num_relocs &struct drm_tegra_reloc structures that
> + * specify the relocations that need to be performed before executing
> + * this job.
> + */
> __u64 relocs;
> +
> + /**
> + * @waitchks:
> + *
> + * A pointer to @num_waitchks &struct drm_tegra_waitchk structures
> + * that specify the wait checks to be performed while executing this
> + * job.
> + */
> __u64 waitchks;
> - __u32 fence; /* Return value */
>
> - __u32 reserved[5]; /* future expansion */
> + /**
> + * @fence:
> + *
> + * The threshold of the syncpoint associated with this job after it
> + * has been completed. Set by the kernel upon successful completion of
> + * the IOCTL. This can be used with the DRM_TEGRA_SYNCPT_WAIT IOCTL to
> + * wait for this job to be finished.
> + */
> + __u32 fence;
> +
> + /**
> + * @reserved:
> + *
> + * This field is reserved for future use. Must be 0.
> + */
> + __u32 reserved[5];
> };
>
> #define DRM_TEGRA_GEM_TILING_MODE_PITCH 0
> #define DRM_TEGRA_GEM_TILING_MODE_TILED 1
> #define DRM_TEGRA_GEM_TILING_MODE_BLOCK 2
>
> +/**
> + * struct drm_tegra_gem_set_tiling - parameters for the set tiling IOCTL
> + */
> struct drm_tegra_gem_set_tiling {
> - /* input */
> + /**
> + * @handle:
> + *
> + * Handle to the GEM object for which to set the tiling parameters.
> + */
> __u32 handle;
> +
> + /**
> + * @mode:
> + *
> + * The tiling mode to set. Must be one of:
> + *
> + * DRM_TEGRA_GEM_TILING_MODE_PITCH
> + * pitch linear format
> + *
> + * DRM_TEGRA_GEM_TILING_MODE_TILED
> + * 16x16 tiling format
> + *
> + * DRM_TEGRA_GEM_TILING_MODE_BLOCK
> + * 16Bx2 tiling format
> + */
> __u32 mode;
> +
> + /**
> + * @value:
> + *
> + * The value to set for the tiling mode parameter.
> + */
> __u32 value;
> +
> + /**
> + * @pad:
> + *
> + * Structure padding that may be used in the future. Must be 0.
> + */
> __u32 pad;
> };
>
> +/**
> + * struct drm_tegra_gem_get_tiling - parameters for the get tiling IOCTL
> + */
> struct drm_tegra_gem_get_tiling {
> - /* input */
> + /**
> + * @handle:
> + *
> + * Handle to the GEM object for which to query the tiling parameters.
> + */
> __u32 handle;
> - /* output */
> +
> + /**
> + * @mode:
> + *
> + * The tiling mode currently associated with the GEM object. Set by
> + * the kernel upon successful completion of the IOCTL.
> + */
> __u32 mode;
> +
> + /**
> + * @value:
> + *
> + * The tiling mode parameter currently associated with the GEM object.
> + * Set by the kernel upon successful completion of the IOCTL.
> + */
> __u32 value;
> +
> + /**
> + * @pad:
> + *
> + * Structure padding that may be used in the future. Must be 0.
> + */
> __u32 pad;
> };
>
> #define DRM_TEGRA_GEM_BOTTOM_UP (1 << 0)
> #define DRM_TEGRA_GEM_FLAGS (DRM_TEGRA_GEM_BOTTOM_UP)
>
> +/**
> + * struct drm_tegra_gem_set_flags - parameters for the set flags IOCTL
> + */
> struct drm_tegra_gem_set_flags {
> - /* input */
> + /**
> + * @handle:
> + *
> + * Handle to the GEM object for which to set the flags.
> + */
> __u32 handle;
> - /* output */
> +
> + /**
> + * @flags:
> + *
> + * The flags to set for the GEM object.
> + */
> __u32 flags;
> };
>
> +/**
> + * struct drm_tegra_gem_get_flags - parameters for the get flags IOCTL
> + */
> struct drm_tegra_gem_get_flags {
> - /* input */
> + /**
> + * @handle:
> + *
> + * Handle to the GEM object for which to query the flags.
> + */
> __u32 handle;
> - /* output */
> +
> + /**
> + * @flags:
> + *
> + * The flags currently associated with the GEM object. Set by the
> + * kernel upon successful completion of the IOCTL.
> + */
> __u32 flags;
> };
>
>
_______________________________________________
dri-devel mailing list
dri-devel@xxxxxxxxxxxxxxxxxxxxx
https://lists.freedesktop.org/mailman/listinfo/dri-devel
