[PATCH 0/7] drm/tegra: Preparation work for destaging ABI

[PATCH 0/7] drm/tegra: Preparation work for destaging ABI

[Thierry Reding]

From: Thierry Reding <treding@nvidia.com>

These patches are further preparation work to destage the job submission
ABI. Patch 1 fixes a typo in the argument to the close channel IOCTL and
isn't technically preparation work. Neither are patches 2 and 3 which do
some cleanup and add support for the rotation property. However, they do
touch areas close to the ABI and simplify subsequent patches.

Patches 4-6 add interface version information to the gr2d, gr3d and VIC
drivers which will be used by new ABI to let userspace know about which
interface it needs to program.

Finally, patch 7 adds kerneldoc for the current ABI.

Thierry

Thierry Reding (7):
  drm/tegra: Use proper arguments for DRM_TEGRA_CLOSE_CHANNEL IOCTL
  drm/tegra: gem: Fill in missing export info
  drm/tegra: dc: Support rotation property
  drm/tegra: gr2d: Track interface version
  drm/tegra: gr3d: Track interface version
  drm/tegra: vic: Track interface version
  drm/tegra: Add kerneldoc for UAPI

 drivers/gpu/drm/tegra/dc.c    |  18 +-
 drivers/gpu/drm/tegra/drm.h   |   1 -
 drivers/gpu/drm/tegra/fb.c    |  10 -
 drivers/gpu/drm/tegra/gem.c   |   6 +-
 drivers/gpu/drm/tegra/gr2d.c  |  22 +-
 drivers/gpu/drm/tegra/gr3d.c  |  28 +-
 drivers/gpu/drm/tegra/plane.c |   1 +
 drivers/gpu/drm/tegra/plane.h |   2 +
 drivers/gpu/drm/tegra/vic.c   |   5 +
 include/uapi/drm/tegra_drm.h  | 482 ++++++++++++++++++++++++++++++++--
 10 files changed, 541 insertions(+), 34 deletions(-)

-- 
2.17.0

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

[PATCH 1/7] drm/tegra: Use proper arguments for DRM_TEGRA_CLOSE_CHANNEL IOCTL

[Thierry Reding]

From: Thierry Reding <treding@nvidia.com>

A separate data structure exists for the DRM_TEGRA_CLOSE_CHANNEL IOCTL,
but it is currently unused. The IOCTL was using the data structure for
the DRM_TEGRA_OPEN_CHANNEL IOCTL.

Signed-off-by: Thierry Reding <treding@nvidia.com>
---
 include/uapi/drm/tegra_drm.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/uapi/drm/tegra_drm.h b/include/uapi/drm/tegra_drm.h
index d954f8c33321..99e15d82d1e9 100644
--- a/include/uapi/drm/tegra_drm.h
+++ b/include/uapi/drm/tegra_drm.h
@@ -193,7 +193,7 @@ struct drm_tegra_gem_get_flags {
 #define DRM_IOCTL_TEGRA_SYNCPT_INCR DRM_IOWR(DRM_COMMAND_BASE + DRM_TEGRA_SYNCPT_INCR, struct drm_tegra_syncpt_incr)
 #define DRM_IOCTL_TEGRA_SYNCPT_WAIT DRM_IOWR(DRM_COMMAND_BASE + DRM_TEGRA_SYNCPT_WAIT, struct drm_tegra_syncpt_wait)
 #define DRM_IOCTL_TEGRA_OPEN_CHANNEL DRM_IOWR(DRM_COMMAND_BASE + DRM_TEGRA_OPEN_CHANNEL, struct drm_tegra_open_channel)
-#define DRM_IOCTL_TEGRA_CLOSE_CHANNEL DRM_IOWR(DRM_COMMAND_BASE + DRM_TEGRA_CLOSE_CHANNEL, struct drm_tegra_open_channel)
+#define DRM_IOCTL_TEGRA_CLOSE_CHANNEL DRM_IOWR(DRM_COMMAND_BASE + DRM_TEGRA_CLOSE_CHANNEL, struct drm_tegra_close_channel)
 #define DRM_IOCTL_TEGRA_GET_SYNCPT DRM_IOWR(DRM_COMMAND_BASE + DRM_TEGRA_GET_SYNCPT, struct drm_tegra_get_syncpt)
 #define DRM_IOCTL_TEGRA_SUBMIT DRM_IOWR(DRM_COMMAND_BASE + DRM_TEGRA_SUBMIT, struct drm_tegra_submit)
 #define DRM_IOCTL_TEGRA_GET_SYNCPT_BASE DRM_IOWR(DRM_COMMAND_BASE + DRM_TEGRA_GET_SYNCPT_BASE, struct drm_tegra_get_syncpt_base)
-- 
2.17.0

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH 1/7] drm/tegra: Use proper arguments for DRM_TEGRA_CLOSE_CHANNEL IOCTL

[Dmitry Osipenko]

On 17.05.2018 18:41, Thierry Reding wrote:
> From: Thierry Reding <treding@nvidia.com>
> 
> A separate data structure exists for the DRM_TEGRA_CLOSE_CHANNEL IOCTL,
> but it is currently unused. The IOCTL was using the data structure for
> the DRM_TEGRA_OPEN_CHANNEL IOCTL.
> 
> Signed-off-by: Thierry Reding <treding@nvidia.com>
> ---
>  include/uapi/drm/tegra_drm.h | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/include/uapi/drm/tegra_drm.h b/include/uapi/drm/tegra_drm.h
> index d954f8c33321..99e15d82d1e9 100644
> --- a/include/uapi/drm/tegra_drm.h
> +++ b/include/uapi/drm/tegra_drm.h
> @@ -193,7 +193,7 @@ struct drm_tegra_gem_get_flags {
>  #define DRM_IOCTL_TEGRA_SYNCPT_INCR DRM_IOWR(DRM_COMMAND_BASE + DRM_TEGRA_SYNCPT_INCR, struct drm_tegra_syncpt_incr)
>  #define DRM_IOCTL_TEGRA_SYNCPT_WAIT DRM_IOWR(DRM_COMMAND_BASE + DRM_TEGRA_SYNCPT_WAIT, struct drm_tegra_syncpt_wait)
>  #define DRM_IOCTL_TEGRA_OPEN_CHANNEL DRM_IOWR(DRM_COMMAND_BASE + DRM_TEGRA_OPEN_CHANNEL, struct drm_tegra_open_channel)
> -#define DRM_IOCTL_TEGRA_CLOSE_CHANNEL DRM_IOWR(DRM_COMMAND_BASE + DRM_TEGRA_CLOSE_CHANNEL, struct drm_tegra_open_channel)
> +#define DRM_IOCTL_TEGRA_CLOSE_CHANNEL DRM_IOWR(DRM_COMMAND_BASE + DRM_TEGRA_CLOSE_CHANNEL, struct drm_tegra_close_channel)
>  #define DRM_IOCTL_TEGRA_GET_SYNCPT DRM_IOWR(DRM_COMMAND_BASE + DRM_TEGRA_GET_SYNCPT, struct drm_tegra_get_syncpt)
>  #define DRM_IOCTL_TEGRA_SUBMIT DRM_IOWR(DRM_COMMAND_BASE + DRM_TEGRA_SUBMIT, struct drm_tegra_submit)
>  #define DRM_IOCTL_TEGRA_GET_SYNCPT_BASE DRM_IOWR(DRM_COMMAND_BASE + DRM_TEGRA_GET_SYNCPT_BASE, struct drm_tegra_get_syncpt_base)
> 

Reviewed-by: Dmitry Osipenko <digetx@gmail.com>
Tested-by: Dmitry Osipenko <digetx@gmail.com>
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

[PATCH 2/7] drm/tegra: gem: Fill in missing export info

[Thierry Reding]

From: Thierry Reding <treding@nvidia.com>

Set the owner and name of the exported DMA-BUF in addition to the
already filled-in fields.

Signed-off-by: Thierry Reding <treding@nvidia.com>
---
 drivers/gpu/drm/tegra/gem.c | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/drivers/gpu/drm/tegra/gem.c b/drivers/gpu/drm/tegra/gem.c
index 8b0b4ff64bb4..387ba1dfbe0d 100644
--- a/drivers/gpu/drm/tegra/gem.c
+++ b/drivers/gpu/drm/tegra/gem.c
@@ -663,6 +663,8 @@ struct dma_buf *tegra_gem_prime_export(struct drm_device *drm,
 {
 	DEFINE_DMA_BUF_EXPORT_INFO(exp_info);
 
+	exp_info.exp_name = KBUILD_MODNAME;
+	exp_info.owner = drm->driver->fops->owner;
 	exp_info.ops = &tegra_gem_prime_dmabuf_ops;
 	exp_info.size = gem->size;
 	exp_info.flags = flags;
-- 
2.17.0

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH 2/7] drm/tegra: gem: Fill in missing export info

[Dmitry Osipenko]

On 17.05.2018 18:41, Thierry Reding wrote:
> From: Thierry Reding <treding@nvidia.com>
> 
> Set the owner and name of the exported DMA-BUF in addition to the
> already filled-in fields.
> 
> Signed-off-by: Thierry Reding <treding@nvidia.com>
> ---
>  drivers/gpu/drm/tegra/gem.c | 2 ++
>  1 file changed, 2 insertions(+)
> 
> diff --git a/drivers/gpu/drm/tegra/gem.c b/drivers/gpu/drm/tegra/gem.c
> index 8b0b4ff64bb4..387ba1dfbe0d 100644
> --- a/drivers/gpu/drm/tegra/gem.c
> +++ b/drivers/gpu/drm/tegra/gem.c
> @@ -663,6 +663,8 @@ struct dma_buf *tegra_gem_prime_export(struct drm_device *drm,
>  {
>  	DEFINE_DMA_BUF_EXPORT_INFO(exp_info);
>  
> +	exp_info.exp_name = KBUILD_MODNAME;
> +	exp_info.owner = drm->driver->fops->owner;
>  	exp_info.ops = &tegra_gem_prime_dmabuf_ops;
>  	exp_info.size = gem->size;
>  	exp_info.flags = flags;
> 

Reviewed-by: Dmitry Osipenko <digetx@gmail.com>
Tested-by: Dmitry Osipenko <digetx@gmail.com>
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

[PATCH 3/7] drm/tegra: dc: Support rotation property

[Thierry Reding]

From: Thierry Reding <treding@nvidia.com>

Currently only the DRM_MODE_REFLECT_Y rotation is supported. The driver
already supports reflection on the Y axis via a custom flag which is not
very useful because it requires custom userspace. Replace that flag by a
standard rotation property that supports 0 degree rotation and Y axis
reflection.

Signed-off-by: Thierry Reding <treding@nvidia.com>
---
 drivers/gpu/drm/tegra/dc.c    | 18 +++++++++++++++++-
 drivers/gpu/drm/tegra/drm.h   |  1 -
 drivers/gpu/drm/tegra/fb.c    | 10 ----------
 drivers/gpu/drm/tegra/plane.c |  1 +
 drivers/gpu/drm/tegra/plane.h |  2 ++
 5 files changed, 20 insertions(+), 12 deletions(-)

diff --git a/drivers/gpu/drm/tegra/dc.c b/drivers/gpu/drm/tegra/dc.c
index 9f83a65b5ea9..e2e574202ca3 100644
--- a/drivers/gpu/drm/tegra/dc.c
+++ b/drivers/gpu/drm/tegra/dc.c
@@ -451,6 +451,7 @@ static int tegra_plane_atomic_check(struct drm_plane *plane,
 				    struct drm_plane_state *state)
 {
 	struct tegra_plane_state *plane_state = to_tegra_plane_state(state);
+	unsigned int rotation = DRM_MODE_ROTATE_0 | DRM_MODE_REFLECT_Y;
 	struct tegra_bo_tiling *tiling = &plane_state->tiling;
 	struct tegra_plane *tegra = to_tegra_plane(plane);
 	struct tegra_dc *dc = to_tegra_dc(state->crtc);
@@ -498,6 +499,13 @@ static int tegra_plane_atomic_check(struct drm_plane *plane,
 		return -EINVAL;
 	}
 
+	rotation = drm_rotation_simplify(state->rotation, rotation);
+
+	if (rotation & DRM_MODE_REFLECT_Y)
+		plane_state->bottom_up = true;
+	else
+		plane_state->bottom_up = false;
+
 	/*
 	 * Tegra doesn't support different strides for U and V planes so we
 	 * error out if the user tries to display a framebuffer with such a
@@ -558,7 +566,7 @@ static void tegra_plane_atomic_update(struct drm_plane *plane,
 	window.dst.w = drm_rect_width(&plane->state->dst);
 	window.dst.h = drm_rect_height(&plane->state->dst);
 	window.bits_per_pixel = fb->format->cpp[0] * 8;
-	window.bottom_up = tegra_fb_is_bottom_up(fb);
+	window.bottom_up = state->bottom_up;
 
 	/* copy from state */
 	window.zpos = plane->state->normalized_zpos;
@@ -643,6 +651,14 @@ static struct drm_plane *tegra_primary_plane_create(struct drm_device *drm,
 	if (dc->soc->supports_blending)
 		drm_plane_create_zpos_property(&plane->base, 0, 0, 255);
 
+	err = drm_plane_create_rotation_property(&plane->base,
+						 DRM_MODE_ROTATE_0,
+						 DRM_MODE_ROTATE_0 |
+						 DRM_MODE_REFLECT_Y);
+	if (err < 0)
+		dev_err(dc->dev, "failed to create rotation property: %d\n",
+			err);
+
 	return &plane->base;
 }
 
diff --git a/drivers/gpu/drm/tegra/drm.h b/drivers/gpu/drm/tegra/drm.h
index 4f41aaec8530..84930d13e28d 100644
--- a/drivers/gpu/drm/tegra/drm.h
+++ b/drivers/gpu/drm/tegra/drm.h
@@ -177,7 +177,6 @@ int drm_dp_aux_train(struct drm_dp_aux *aux, struct drm_dp_link *link,
 /* from fb.c */
 struct tegra_bo *tegra_fb_get_plane(struct drm_framebuffer *framebuffer,
 				    unsigned int index);
-bool tegra_fb_is_bottom_up(struct drm_framebuffer *framebuffer);
 int tegra_fb_get_tiling(struct drm_framebuffer *framebuffer,
 			struct tegra_bo_tiling *tiling);
 struct drm_framebuffer *tegra_fb_create(struct drm_device *drm,
diff --git a/drivers/gpu/drm/tegra/fb.c b/drivers/gpu/drm/tegra/fb.c
index e69434909a42..35827c729462 100644
--- a/drivers/gpu/drm/tegra/fb.c
+++ b/drivers/gpu/drm/tegra/fb.c
@@ -38,16 +38,6 @@ struct tegra_bo *tegra_fb_get_plane(struct drm_framebuffer *framebuffer,
 	return fb->planes[index];
 }
 
-bool tegra_fb_is_bottom_up(struct drm_framebuffer *framebuffer)
-{
-	struct tegra_fb *fb = to_tegra_fb(framebuffer);
-
-	if (fb->planes[0]->flags & TEGRA_BO_BOTTOM_UP)
-		return true;
-
-	return false;
-}
-
 int tegra_fb_get_tiling(struct drm_framebuffer *framebuffer,
 			struct tegra_bo_tiling *tiling)
 {
diff --git a/drivers/gpu/drm/tegra/plane.c b/drivers/gpu/drm/tegra/plane.c
index 176ef46c615c..271729b2c653 100644
--- a/drivers/gpu/drm/tegra/plane.c
+++ b/drivers/gpu/drm/tegra/plane.c
@@ -53,6 +53,7 @@ tegra_plane_atomic_duplicate_state(struct drm_plane *plane)
 	copy->tiling = state->tiling;
 	copy->format = state->format;
 	copy->swap = state->swap;
+	copy->bottom_up = state->bottom_up;
 	copy->opaque = state->opaque;
 
 	for (i = 0; i < 3; i++)
diff --git a/drivers/gpu/drm/tegra/plane.h b/drivers/gpu/drm/tegra/plane.h
index 6938719e7e5d..867b9c32b1b6 100644
--- a/drivers/gpu/drm/tegra/plane.h
+++ b/drivers/gpu/drm/tegra/plane.h
@@ -41,6 +41,8 @@ struct tegra_plane_state {
 	u32 format;
 	u32 swap;
 
+	bool bottom_up;
+
 	/* used for legacy blending support only */
 	bool opaque;
 	bool dependent[3];
-- 
2.17.0

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH 3/7] drm/tegra: dc: Support rotation property

[Dmitry Osipenko]

On 17.05.2018 18:41, Thierry Reding wrote:
> From: Thierry Reding <treding@nvidia.com>
> 
> Currently only the DRM_MODE_REFLECT_Y rotation is supported. The driver
> already supports reflection on the Y axis via a custom flag which is not
> very useful because it requires custom userspace. Replace that flag by a
> standard rotation property that supports 0 degree rotation and Y axis
> reflection.
> 
> Signed-off-by: Thierry Reding <treding@nvidia.com>
> ---
>  drivers/gpu/drm/tegra/dc.c    | 18 +++++++++++++++++-
>  drivers/gpu/drm/tegra/drm.h   |  1 -
>  drivers/gpu/drm/tegra/fb.c    | 10 ----------
>  drivers/gpu/drm/tegra/plane.c |  1 +
>  drivers/gpu/drm/tegra/plane.h |  2 ++
>  5 files changed, 20 insertions(+), 12 deletions(-)
> 
> diff --git a/drivers/gpu/drm/tegra/dc.c b/drivers/gpu/drm/tegra/dc.c
> index 9f83a65b5ea9..e2e574202ca3 100644
> --- a/drivers/gpu/drm/tegra/dc.c
> +++ b/drivers/gpu/drm/tegra/dc.c
> @@ -451,6 +451,7 @@ static int tegra_plane_atomic_check(struct drm_plane *plane,
>  				    struct drm_plane_state *state)
>  {
>  	struct tegra_plane_state *plane_state = to_tegra_plane_state(state);
> +	unsigned int rotation = DRM_MODE_ROTATE_0 | DRM_MODE_REFLECT_Y;
>  	struct tegra_bo_tiling *tiling = &plane_state->tiling;
>  	struct tegra_plane *tegra = to_tegra_plane(plane);
>  	struct tegra_dc *dc = to_tegra_dc(state->crtc);
> @@ -498,6 +499,13 @@ static int tegra_plane_atomic_check(struct drm_plane *plane,
>  		return -EINVAL;
>  	}
>  
> +	rotation = drm_rotation_simplify(state->rotation, rotation);
> +
> +	if (rotation & DRM_MODE_REFLECT_Y)
> +		plane_state->bottom_up = true;
> +	else
> +		plane_state->bottom_up = false;
> +
>  	/*
>  	 * Tegra doesn't support different strides for U and V planes so we
>  	 * error out if the user tries to display a framebuffer with such a
> @@ -558,7 +566,7 @@ static void tegra_plane_atomic_update(struct drm_plane *plane,
>  	window.dst.w = drm_rect_width(&plane->state->dst);
>  	window.dst.h = drm_rect_height(&plane->state->dst);
>  	window.bits_per_pixel = fb->format->cpp[0] * 8;
> -	window.bottom_up = tegra_fb_is_bottom_up(fb);
> +	window.bottom_up = state->bottom_up;

This is ABI breakage. For now let's keep the tegra_fb_is_bottom_up() and change
the above line to:

	window.bottom_up = tegra_fb_is_bottom_up(fb) || state->bottom_up;

>  
>  	/* copy from state */
>  	window.zpos = plane->state->normalized_zpos;
> @@ -643,6 +651,14 @@ static struct drm_plane *tegra_primary_plane_create(struct drm_device *drm,
>  	if (dc->soc->supports_blending)
>  		drm_plane_create_zpos_property(&plane->base, 0, 0, 255);
>  
> +	err = drm_plane_create_rotation_property(&plane->base,
> +						 DRM_MODE_ROTATE_0,
> +						 DRM_MODE_ROTATE_0 |
> +						 DRM_MODE_REFLECT_Y);
> +	if (err < 0)
> +		dev_err(dc->dev, "failed to create rotation property: %d\n",
> +			err);
> +

The "rotation" property must be created for the overlay planes as well.

I've added "rotation" property support to the GRATE - works fine, so with the
above comments addressed:

Reviewed-by: Dmitry Osipenko <digetx@gmail.com>
Tested-by: Dmitry Osipenko <digetx@gmail.com>

>  	return &plane->base;
>  }
>  
> diff --git a/drivers/gpu/drm/tegra/drm.h b/drivers/gpu/drm/tegra/drm.h
> index 4f41aaec8530..84930d13e28d 100644
> --- a/drivers/gpu/drm/tegra/drm.h
> +++ b/drivers/gpu/drm/tegra/drm.h
> @@ -177,7 +177,6 @@ int drm_dp_aux_train(struct drm_dp_aux *aux, struct drm_dp_link *link,
>  /* from fb.c */
>  struct tegra_bo *tegra_fb_get_plane(struct drm_framebuffer *framebuffer,
>  				    unsigned int index);
> -bool tegra_fb_is_bottom_up(struct drm_framebuffer *framebuffer);
>  int tegra_fb_get_tiling(struct drm_framebuffer *framebuffer,
>  			struct tegra_bo_tiling *tiling);
>  struct drm_framebuffer *tegra_fb_create(struct drm_device *drm,
> diff --git a/drivers/gpu/drm/tegra/fb.c b/drivers/gpu/drm/tegra/fb.c
> index e69434909a42..35827c729462 100644
> --- a/drivers/gpu/drm/tegra/fb.c
> +++ b/drivers/gpu/drm/tegra/fb.c
> @@ -38,16 +38,6 @@ struct tegra_bo *tegra_fb_get_plane(struct drm_framebuffer *framebuffer,
>  	return fb->planes[index];
>  }
>  
> -bool tegra_fb_is_bottom_up(struct drm_framebuffer *framebuffer)
> -{
> -	struct tegra_fb *fb = to_tegra_fb(framebuffer);
> -
> -	if (fb->planes[0]->flags & TEGRA_BO_BOTTOM_UP)
> -		return true;
> -
> -	return false;
> -}
> -
>  int tegra_fb_get_tiling(struct drm_framebuffer *framebuffer,
>  			struct tegra_bo_tiling *tiling)
>  {
> diff --git a/drivers/gpu/drm/tegra/plane.c b/drivers/gpu/drm/tegra/plane.c
> index 176ef46c615c..271729b2c653 100644
> --- a/drivers/gpu/drm/tegra/plane.c
> +++ b/drivers/gpu/drm/tegra/plane.c
> @@ -53,6 +53,7 @@ tegra_plane_atomic_duplicate_state(struct drm_plane *plane)
>  	copy->tiling = state->tiling;
>  	copy->format = state->format;
>  	copy->swap = state->swap;
> +	copy->bottom_up = state->bottom_up;
>  	copy->opaque = state->opaque;
>  
>  	for (i = 0; i < 3; i++)
> diff --git a/drivers/gpu/drm/tegra/plane.h b/drivers/gpu/drm/tegra/plane.h
> index 6938719e7e5d..867b9c32b1b6 100644
> --- a/drivers/gpu/drm/tegra/plane.h
> +++ b/drivers/gpu/drm/tegra/plane.h
> @@ -41,6 +41,8 @@ struct tegra_plane_state {
>  	u32 format;
>  	u32 swap;
>  
> +	bool bottom_up;
> +
>  	/* used for legacy blending support only */
>  	bool opaque;
>  	bool dependent[3];
> 

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

[PATCH 4/7] drm/tegra: gr2d: Track interface version

[Thierry Reding]

From: Thierry Reding <treding@nvidia.com>

Set the interface version implemented by the gr2d module. This allows
userspace to pass the correct command stream when programming the gr2d
module.

Signed-off-by: Thierry Reding <treding@nvidia.com>
---
 drivers/gpu/drm/tegra/gr2d.c | 22 ++++++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

diff --git a/drivers/gpu/drm/tegra/gr2d.c b/drivers/gpu/drm/tegra/gr2d.c
index 9a8ea93016a9..d13752b0d915 100644
--- a/drivers/gpu/drm/tegra/gr2d.c
+++ b/drivers/gpu/drm/tegra/gr2d.c
@@ -7,16 +7,23 @@
  */
 
 #include <linux/clk.h>
+#include <linux/of_device.h>
 
 #include "drm.h"
 #include "gem.h"
 #include "gr2d.h"
 
+struct gr2d_soc {
+	unsigned int version;
+};
+
 struct gr2d {
 	struct tegra_drm_client client;
 	struct host1x_channel *channel;
 	struct clk *clk;
 
+	const struct gr2d_soc *soc;
+
 	DECLARE_BITMAP(addr_regs, GR2D_NUM_REGS);
 };
 
@@ -123,9 +130,17 @@ static const struct tegra_drm_client_ops gr2d_ops = {
 	.submit = tegra_drm_submit,
 };
 
+static const struct gr2d_soc tegra20_gr2d_soc = {
+	.version = 0x20,
+};
+
+static const struct gr2d_soc tegra30_gr2d_soc = {
+	.version = 0x30,
+};
+
 static const struct of_device_id gr2d_match[] = {
-	{ .compatible = "nvidia,tegra30-gr2d" },
-	{ .compatible = "nvidia,tegra20-gr2d" },
+	{ .compatible = "nvidia,tegra30-gr2d", .data = &tegra20_gr2d_soc },
+	{ .compatible = "nvidia,tegra20-gr2d", .data = &tegra30_gr2d_soc },
 	{ },
 };
 MODULE_DEVICE_TABLE(of, gr2d_match);
@@ -158,6 +173,8 @@ static int gr2d_probe(struct platform_device *pdev)
 	if (!gr2d)
 		return -ENOMEM;
 
+	gr2d->soc = of_device_get_match_data(dev);
+
 	syncpts = devm_kzalloc(dev, sizeof(*syncpts), GFP_KERNEL);
 	if (!syncpts)
 		return -ENOMEM;
@@ -178,6 +195,7 @@ static int gr2d_probe(struct platform_device *pdev)
 	gr2d->client.base.ops = &gr2d_client_ops;
 	gr2d->client.base.dev = dev;
 	gr2d->client.base.class = HOST1X_CLASS_GR2D;
+	gr2d->client.base.version = gr2d->soc->version;
 	gr2d->client.base.syncpts = syncpts;
 	gr2d->client.base.num_syncpts = 1;
 
-- 
2.17.0

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH 4/7] drm/tegra: gr2d: Track interface version

[Dmitry Osipenko]

On 17.05.2018 18:41, Thierry Reding wrote:
> From: Thierry Reding <treding@nvidia.com>
> 
> Set the interface version implemented by the gr2d module. This allows
> userspace to pass the correct command stream when programming the gr2d
> module.
> 
> Signed-off-by: Thierry Reding <treding@nvidia.com>
> ---
>  drivers/gpu/drm/tegra/gr2d.c | 22 ++++++++++++++++++++--
>  1 file changed, 20 insertions(+), 2 deletions(-)
> 
> diff --git a/drivers/gpu/drm/tegra/gr2d.c b/drivers/gpu/drm/tegra/gr2d.c
> index 9a8ea93016a9..d13752b0d915 100644
> --- a/drivers/gpu/drm/tegra/gr2d.c
> +++ b/drivers/gpu/drm/tegra/gr2d.c
> @@ -7,16 +7,23 @@
>   */
>  
>  #include <linux/clk.h>
> +#include <linux/of_device.h>
>  
>  #include "drm.h"
>  #include "gem.h"
>  #include "gr2d.h"
>  
> +struct gr2d_soc {
> +	unsigned int version;
> +};
> +
>  struct gr2d {
>  	struct tegra_drm_client client;
>  	struct host1x_channel *channel;
>  	struct clk *clk;
>  
> +	const struct gr2d_soc *soc;
> +
>  	DECLARE_BITMAP(addr_regs, GR2D_NUM_REGS);
>  };
>  
> @@ -123,9 +130,17 @@ static const struct tegra_drm_client_ops gr2d_ops = {
>  	.submit = tegra_drm_submit,
>  };
>  
> +static const struct gr2d_soc tegra20_gr2d_soc = {
> +	.version = 0x20,
> +};
> +
> +static const struct gr2d_soc tegra30_gr2d_soc = {
> +	.version = 0x30,
> +};
> +
>  static const struct of_device_id gr2d_match[] = {
> -	{ .compatible = "nvidia,tegra30-gr2d" },
> -	{ .compatible = "nvidia,tegra20-gr2d" },
> +	{ .compatible = "nvidia,tegra30-gr2d", .data = &tegra20_gr2d_soc },
> +	{ .compatible = "nvidia,tegra20-gr2d", .data = &tegra30_gr2d_soc },

Note: T114 also has GR2D according to the TRM, maybe it's worth add it here too
later.

>  	{ },
>  };
>  MODULE_DEVICE_TABLE(of, gr2d_match);
> @@ -158,6 +173,8 @@ static int gr2d_probe(struct platform_device *pdev)
>  	if (!gr2d)
>  		return -ENOMEM;
>  
> +	gr2d->soc = of_device_get_match_data(dev);
> +
>  	syncpts = devm_kzalloc(dev, sizeof(*syncpts), GFP_KERNEL);
>  	if (!syncpts)
>  		return -ENOMEM;
> @@ -178,6 +195,7 @@ static int gr2d_probe(struct platform_device *pdev)
>  	gr2d->client.base.ops = &gr2d_client_ops;
>  	gr2d->client.base.dev = dev;
>  	gr2d->client.base.class = HOST1X_CLASS_GR2D;
> +	gr2d->client.base.version = gr2d->soc->version;
>  	gr2d->client.base.syncpts = syncpts;
>  	gr2d->client.base.num_syncpts = 1;
>  
> 

Reviewed-by: Dmitry Osipenko <digetx@gmail.com>
Tested-by: Dmitry Osipenko <digetx@gmail.com>
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

[PATCH 5/7] drm/tegra: gr3d: Track interface version

[Thierry Reding]

From: Thierry Reding <treding@nvidia.com>

Set the interface version implemented by the gr3d module. This allows
userspace to pass the correct command stream when programming the gr3d
module.

Signed-off-by: Thierry Reding <treding@nvidia.com>
---
 drivers/gpu/drm/tegra/gr3d.c | 28 +++++++++++++++++++++++++---
 1 file changed, 25 insertions(+), 3 deletions(-)

diff --git a/drivers/gpu/drm/tegra/gr3d.c b/drivers/gpu/drm/tegra/gr3d.c
index 28c4ef63065b..0d4dce978eb2 100644
--- a/drivers/gpu/drm/tegra/gr3d.c
+++ b/drivers/gpu/drm/tegra/gr3d.c
@@ -10,6 +10,7 @@
 #include <linux/clk.h>
 #include <linux/host1x.h>
 #include <linux/module.h>
+#include <linux/of_device.h>
 #include <linux/platform_device.h>
 #include <linux/reset.h>
 
@@ -19,6 +20,10 @@
 #include "gem.h"
 #include "gr3d.h"
 
+struct gr3d_soc {
+	unsigned int version;
+};
+
 struct gr3d {
 	struct tegra_drm_client client;
 	struct host1x_channel *channel;
@@ -27,6 +32,8 @@ struct gr3d {
 	struct reset_control *rst_secondary;
 	struct reset_control *rst;
 
+	const struct gr3d_soc *soc;
+
 	DECLARE_BITMAP(addr_regs, GR3D_NUM_REGS);
 };
 
@@ -125,10 +132,22 @@ static const struct tegra_drm_client_ops gr3d_ops = {
 	.submit = tegra_drm_submit,
 };
 
+static const struct gr3d_soc tegra20_gr3d_soc = {
+	.version = 0x20,
+};
+
+static const struct gr3d_soc tegra30_gr3d_soc = {
+	.version = 0x30,
+};
+
+static const struct gr3d_soc tegra114_gr3d_soc = {
+	.version = 0x35,
+};
+
 static const struct of_device_id tegra_gr3d_match[] = {
-	{ .compatible = "nvidia,tegra114-gr3d" },
-	{ .compatible = "nvidia,tegra30-gr3d" },
-	{ .compatible = "nvidia,tegra20-gr3d" },
+	{ .compatible = "nvidia,tegra114-gr3d", .data = &tegra114_gr3d_soc },
+	{ .compatible = "nvidia,tegra30-gr3d", .data = &tegra30_gr3d_soc },
+	{ .compatible = "nvidia,tegra20-gr3d", .data = &tegra20_gr3d_soc },
 	{ }
 };
 MODULE_DEVICE_TABLE(of, tegra_gr3d_match);
@@ -250,6 +269,8 @@ static int gr3d_probe(struct platform_device *pdev)
 	if (!gr3d)
 		return -ENOMEM;
 
+	gr3d->soc = of_device_get_match_data(&pdev->dev);
+
 	syncpts = devm_kzalloc(&pdev->dev, sizeof(*syncpts), GFP_KERNEL);
 	if (!syncpts)
 		return -ENOMEM;
@@ -303,6 +324,7 @@ static int gr3d_probe(struct platform_device *pdev)
 	gr3d->client.base.ops = &gr3d_client_ops;
 	gr3d->client.base.dev = &pdev->dev;
 	gr3d->client.base.class = HOST1X_CLASS_GR3D;
+	gr3d->client.base.version = gr3d->soc->version;
 	gr3d->client.base.syncpts = syncpts;
 	gr3d->client.base.num_syncpts = 1;
 
-- 
2.17.0

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH 5/7] drm/tegra: gr3d: Track interface version

[Dmitry Osipenko]

On 17.05.2018 18:41, Thierry Reding wrote:
> From: Thierry Reding <treding@nvidia.com>
> 
> Set the interface version implemented by the gr3d module. This allows
> userspace to pass the correct command stream when programming the gr3d
> module.
> 
> Signed-off-by: Thierry Reding <treding@nvidia.com>
> ---
>  drivers/gpu/drm/tegra/gr3d.c | 28 +++++++++++++++++++++++++---
>  1 file changed, 25 insertions(+), 3 deletions(-)
> 
> diff --git a/drivers/gpu/drm/tegra/gr3d.c b/drivers/gpu/drm/tegra/gr3d.c
> index 28c4ef63065b..0d4dce978eb2 100644
> --- a/drivers/gpu/drm/tegra/gr3d.c
> +++ b/drivers/gpu/drm/tegra/gr3d.c
> @@ -10,6 +10,7 @@
>  #include <linux/clk.h>
>  #include <linux/host1x.h>
>  #include <linux/module.h>
> +#include <linux/of_device.h>
>  #include <linux/platform_device.h>
>  #include <linux/reset.h>
>  
> @@ -19,6 +20,10 @@
>  #include "gem.h"
>  #include "gr3d.h"
>  
> +struct gr3d_soc {
> +	unsigned int version;
> +};
> +
>  struct gr3d {
>  	struct tegra_drm_client client;
>  	struct host1x_channel *channel;
> @@ -27,6 +32,8 @@ struct gr3d {
>  	struct reset_control *rst_secondary;
>  	struct reset_control *rst;
>  
> +	const struct gr3d_soc *soc;
> +
>  	DECLARE_BITMAP(addr_regs, GR3D_NUM_REGS);
>  };
>  
> @@ -125,10 +132,22 @@ static const struct tegra_drm_client_ops gr3d_ops = {
>  	.submit = tegra_drm_submit,
>  };
>  
> +static const struct gr3d_soc tegra20_gr3d_soc = {
> +	.version = 0x20,
> +};
> +
> +static const struct gr3d_soc tegra30_gr3d_soc = {
> +	.version = 0x30,
> +};
> +
> +static const struct gr3d_soc tegra114_gr3d_soc = {
> +	.version = 0x35,
> +};
> +
>  static const struct of_device_id tegra_gr3d_match[] = {
> -	{ .compatible = "nvidia,tegra114-gr3d" },
> -	{ .compatible = "nvidia,tegra30-gr3d" },
> -	{ .compatible = "nvidia,tegra20-gr3d" },
> +	{ .compatible = "nvidia,tegra114-gr3d", .data = &tegra114_gr3d_soc },
> +	{ .compatible = "nvidia,tegra30-gr3d", .data = &tegra30_gr3d_soc },
> +	{ .compatible = "nvidia,tegra20-gr3d", .data = &tegra20_gr3d_soc },
>  	{ }
>  };
>  MODULE_DEVICE_TABLE(of, tegra_gr3d_match);
> @@ -250,6 +269,8 @@ static int gr3d_probe(struct platform_device *pdev)
>  	if (!gr3d)
>  		return -ENOMEM;
>  
> +	gr3d->soc = of_device_get_match_data(&pdev->dev);
> +
>  	syncpts = devm_kzalloc(&pdev->dev, sizeof(*syncpts), GFP_KERNEL);
>  	if (!syncpts)
>  		return -ENOMEM;
> @@ -303,6 +324,7 @@ static int gr3d_probe(struct platform_device *pdev)
>  	gr3d->client.base.ops = &gr3d_client_ops;
>  	gr3d->client.base.dev = &pdev->dev;
>  	gr3d->client.base.class = HOST1X_CLASS_GR3D;
> +	gr3d->client.base.version = gr3d->soc->version;
>  	gr3d->client.base.syncpts = syncpts;
>  	gr3d->client.base.num_syncpts = 1;
>  
> 

Reviewed-by: Dmitry Osipenko <digetx@gmail.com>
Tested-by: Dmitry Osipenko <digetx@gmail.com>
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

[PATCH 6/7] drm/tegra: vic: Track interface version

[Thierry Reding]

From: Thierry Reding <treding@nvidia.com>

Set the interface version implemented by the VIC module. This allows
userspace to pass the correct command stream when programming the VIC
module.

Signed-off-by: Thierry Reding <treding@nvidia.com>
---
 drivers/gpu/drm/tegra/vic.c | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/drivers/gpu/drm/tegra/vic.c b/drivers/gpu/drm/tegra/vic.c
index f5794dd49f3b..d739403045aa 100644
--- a/drivers/gpu/drm/tegra/vic.c
+++ b/drivers/gpu/drm/tegra/vic.c
@@ -25,6 +25,7 @@
 
 struct vic_config {
 	const char *firmware;
+	unsigned int version;
 };
 
 struct vic {
@@ -264,18 +265,21 @@ static const struct tegra_drm_client_ops vic_ops = {
 
 static const struct vic_config vic_t124_config = {
 	.firmware = NVIDIA_TEGRA_124_VIC_FIRMWARE,
+	.version = 0x40,
 };
 
 #define NVIDIA_TEGRA_210_VIC_FIRMWARE "nvidia/tegra210/vic04_ucode.bin"
 
 static const struct vic_config vic_t210_config = {
 	.firmware = NVIDIA_TEGRA_210_VIC_FIRMWARE,
+	.version = 0x21,
 };
 
 #define NVIDIA_TEGRA_186_VIC_FIRMWARE "nvidia/tegra186/vic04_ucode.bin"
 
 static const struct vic_config vic_t186_config = {
 	.firmware = NVIDIA_TEGRA_186_VIC_FIRMWARE,
+	.version = 0x18,
 };
 
 static const struct of_device_id vic_match[] = {
@@ -337,6 +341,7 @@ static int vic_probe(struct platform_device *pdev)
 	vic->client.base.ops = &vic_client_ops;
 	vic->client.base.dev = dev;
 	vic->client.base.class = HOST1X_CLASS_VIC;
+	vic->client.base.version = vic->config->version;
 	vic->client.base.syncpts = syncpts;
 	vic->client.base.num_syncpts = 1;
 	vic->dev = dev;
-- 
2.17.0

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH 6/7] drm/tegra: vic: Track interface version

[Dmitry Osipenko]

On 17.05.2018 18:41, Thierry Reding wrote:
> From: Thierry Reding <treding@nvidia.com>
> 
> Set the interface version implemented by the VIC module. This allows
> userspace to pass the correct command stream when programming the VIC
> module.
> 
> Signed-off-by: Thierry Reding <treding@nvidia.com>
> ---
>  drivers/gpu/drm/tegra/vic.c | 5 +++++
>  1 file changed, 5 insertions(+)
> 
> diff --git a/drivers/gpu/drm/tegra/vic.c b/drivers/gpu/drm/tegra/vic.c
> index f5794dd49f3b..d739403045aa 100644
> --- a/drivers/gpu/drm/tegra/vic.c
> +++ b/drivers/gpu/drm/tegra/vic.c
> @@ -25,6 +25,7 @@
>  
>  struct vic_config {
>  	const char *firmware;
> +	unsigned int version;
>  };
>  
>  struct vic {
> @@ -264,18 +265,21 @@ static const struct tegra_drm_client_ops vic_ops = {
>  
>  static const struct vic_config vic_t124_config = {
>  	.firmware = NVIDIA_TEGRA_124_VIC_FIRMWARE,
> +	.version = 0x40,
>  };
>  
>  #define NVIDIA_TEGRA_210_VIC_FIRMWARE "nvidia/tegra210/vic04_ucode.bin"
>  
>  static const struct vic_config vic_t210_config = {
>  	.firmware = NVIDIA_TEGRA_210_VIC_FIRMWARE,
> +	.version = 0x21,
>  };
>  
>  #define NVIDIA_TEGRA_186_VIC_FIRMWARE "nvidia/tegra186/vic04_ucode.bin"
>  
>  static const struct vic_config vic_t186_config = {
>  	.firmware = NVIDIA_TEGRA_186_VIC_FIRMWARE,
> +	.version = 0x18,
>  };
>  
>  static const struct of_device_id vic_match[] = {
> @@ -337,6 +341,7 @@ static int vic_probe(struct platform_device *pdev)
>  	vic->client.base.ops = &vic_client_ops;
>  	vic->client.base.dev = dev;
>  	vic->client.base.class = HOST1X_CLASS_VIC;
> +	vic->client.base.version = vic->config->version;
>  	vic->client.base.syncpts = syncpts;
>  	vic->client.base.num_syncpts = 1;
>  	vic->dev = dev;
> 

Reviewed-by: Dmitry Osipenko <digetx@gmail.com>
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

[PATCH 7/7] drm/tegra: Add kerneldoc for UAPI

[Thierry Reding]

From: Thierry Reding <treding@nvidia.com>

Document the userspace ABI with kerneldoc to provide some information on
how to use it.

Signed-off-by: Thierry Reding <treding@nvidia.com>
---
 drivers/gpu/drm/tegra/gem.c  |   4 +-
 include/uapi/drm/tegra_drm.h | 480 ++++++++++++++++++++++++++++++++++-
 2 files changed, 468 insertions(+), 16 deletions(-)

diff --git a/drivers/gpu/drm/tegra/gem.c b/drivers/gpu/drm/tegra/gem.c
index 387ba1dfbe0d..e2987a19541d 100644
--- a/drivers/gpu/drm/tegra/gem.c
+++ b/drivers/gpu/drm/tegra/gem.c
@@ -291,10 +291,10 @@ struct tegra_bo *tegra_bo_create(struct drm_device *drm, size_t size,
 	if (err < 0)
 		goto release;
 
-	if (flags & DRM_TEGRA_GEM_CREATE_TILED)
+	if (flags & DRM_TEGRA_GEM_TILED)
 		bo->tiling.mode = TEGRA_BO_TILING_MODE_TILED;
 
-	if (flags & DRM_TEGRA_GEM_CREATE_BOTTOM_UP)
+	if (flags & DRM_TEGRA_GEM_BOTTOM_UP)
 		bo->flags |= TEGRA_BO_BOTTOM_UP;
 
 	return bo;
diff --git a/include/uapi/drm/tegra_drm.h b/include/uapi/drm/tegra_drm.h
index 99e15d82d1e9..86a7b1e7559d 100644
--- a/include/uapi/drm/tegra_drm.h
+++ b/include/uapi/drm/tegra_drm.h
@@ -29,146 +29,598 @@
 extern "C" {
 #endif
 
-#define DRM_TEGRA_GEM_CREATE_TILED     (1 << 0)
-#define DRM_TEGRA_GEM_CREATE_BOTTOM_UP (1 << 1)
+#define DRM_TEGRA_GEM_TILED		(1 << 0)
+#define DRM_TEGRA_GEM_BOTTOM_UP		(1 << 1)
+#define DRM_TEGRA_GEM_FLAGS		(DRM_TEGRA_GEM_TILED | \
+					 DRM_TEGRA_GEM_BOTTOM_UP)
 
+/**
+ * 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_TILED
+	 *   Use the 16x16 tiling format for this buffer.
+	 *
+	 * DRM_TEGRA_GEM_BOTTOM_UP
+	 *   The buffer has a bottom-up layout.
+	 */
 	__u32 flags;
+
+	/**
+	 * @handle:
+	 *
+	 * Return location for the handle of the created GEM object.
+	 */
 	__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:
+	 *
+	 * Return location for the mmap offset for the given GEM object.
+	 */
 	__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:
+	 *
+	 * Return location for the current syncpoint value.
+	 */
 	__u32 value;
 };
 
+/**
+ * struct drm_tegra_syncpt_incr - parameters for the increment syncpoint IOCTL
+ */
 struct drm_tegra_syncpt_incr {
+	/**
+	 * @id:
+	 *
+	 * ID of the syncpoint to read the current value from.
+	 */
 	__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:
+	 *
+	 * Return value for the current syncpoint value.
+	 */
 	__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:
+	 *
+	 * Return location for the application context of this channel. 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:
+	 *
+	 * Channel-relative index of the syncpoint for which to obtain the ID.
+	 */
 	__u32 index;
+
+	/**
+	 * @id:
+	 *
+	 * Return location for the ID of the given syncpoint.
+	 */
 	__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:
+	 *
+	 * Return location for the ID of the wait base.
+	 */
 	__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 into the command buffer at which to insert the the
+		 * relocated address.
+		 */
 		__u32 offset;
 	} cmdbuf;
 	struct {
+		/**
+		 * @target.handle:
+		 *
+		 * Handle to the GEM object to be relocated.
+		 */
 		__u32 handle;
+
+		/**
+		 * @target.offset:
+		 *
+		 * Offset 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
+	 * specify the syncpoint operations performed as part of this job.
+	 */
 	__u64 syncpts;
+
+	/**
+	 * @cmdbufs:
+	 *
+	 * A pointer to @num_cmdbufs &struct drm_tegra_cmdbuf_legacy
+	 * 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_legacy 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:
+	 *
+	 * Return location for the threshold of the syncpoint associated with
+	 * this job. 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:
+	 *
+	 * Return location for the tiling mode.
+	 */
 	__u32 mode;
+
+	/**
+	 * @value:
+	 *
+	 * Return location for the tiling mode parameter.
+	 */
 	__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:
+	 *
+	 * Return location for the flags queried from the GEM object.
+	 */
 	__u32 flags;
 };
 
-- 
2.17.0

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH 7/7] drm/tegra: Add kerneldoc for UAPI

[Dmitry Osipenko]

On 17.05.2018 18:41, Thierry Reding wrote:
> From: Thierry Reding <treding@nvidia.com>
> 
> Document the userspace ABI with kerneldoc to provide some information on
> how to use it.
> 
> Signed-off-by: Thierry Reding <treding@nvidia.com>
> ---
>  drivers/gpu/drm/tegra/gem.c  |   4 +-
>  include/uapi/drm/tegra_drm.h | 480 ++++++++++++++++++++++++++++++++++-
>  2 files changed, 468 insertions(+), 16 deletions(-)
> 
> diff --git a/drivers/gpu/drm/tegra/gem.c b/drivers/gpu/drm/tegra/gem.c
> index 387ba1dfbe0d..e2987a19541d 100644
> --- a/drivers/gpu/drm/tegra/gem.c
> +++ b/drivers/gpu/drm/tegra/gem.c
> @@ -291,10 +291,10 @@ struct tegra_bo *tegra_bo_create(struct drm_device *drm, size_t size,
>  	if (err < 0)
>  		goto release;
>  
> -	if (flags & DRM_TEGRA_GEM_CREATE_TILED)
> +	if (flags & DRM_TEGRA_GEM_TILED)
>  		bo->tiling.mode = TEGRA_BO_TILING_MODE_TILED;
>  
> -	if (flags & DRM_TEGRA_GEM_CREATE_BOTTOM_UP)
> +	if (flags & DRM_TEGRA_GEM_BOTTOM_UP)
>  		bo->flags |= TEGRA_BO_BOTTOM_UP;
>  
>  	return bo;
> diff --git a/include/uapi/drm/tegra_drm.h b/include/uapi/drm/tegra_drm.h
> index 99e15d82d1e9..86a7b1e7559d 100644
> --- a/include/uapi/drm/tegra_drm.h
> +++ b/include/uapi/drm/tegra_drm.h
> @@ -29,146 +29,598 @@
>  extern "C" {
>  #endif
>  
> -#define DRM_TEGRA_GEM_CREATE_TILED     (1 << 0)
> -#define DRM_TEGRA_GEM_CREATE_BOTTOM_UP (1 << 1)
> +#define DRM_TEGRA_GEM_TILED		(1 << 0)
> +#define DRM_TEGRA_GEM_BOTTOM_UP		(1 << 1)
> +#define DRM_TEGRA_GEM_FLAGS		(DRM_TEGRA_GEM_TILED | \
> +					 DRM_TEGRA_GEM_BOTTOM_UP)

The current userspace won't compile with the above changes, so this is the ABI
breakage. Please keep the old DRM_TEGRA_GEM_CREATE_* DRM_TEGRA_GEM_* flags for now.

>  
> +/**
> + * 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_TILED
> +	 *   Use the 16x16 tiling format for this buffer.
> +	 *
> +	 * DRM_TEGRA_GEM_BOTTOM_UP
> +	 *   The buffer has a bottom-up layout.
> +	 */
>  	__u32 flags;
> +
> +	/**
> +	 * @handle:
> +	 *
> +	 * Return location for the handle of the created GEM object.
> +	 */
>  	__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:
> +	 *
> +	 * Return location for the mmap offset for the given GEM object.
> +	 */
>  	__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:
> +	 *
> +	 * Return location for the current syncpoint value.
> +	 */>  	__u32 value;
>  };

What about:

Returned value of the given syncpoint.

Could we replace "return location for the.." with just "Returned.." in other
places too? My mind is stuttering while reading "location for the value", though
I know that my english isn't ideal and maybe it's only me.

>  
> +/**
> + * struct drm_tegra_syncpt_incr - parameters for the increment syncpoint IOCTL
> + */
>  struct drm_tegra_syncpt_incr {
> +	/**
> +	 * @id:
> +	 *
> +	 * ID of the syncpoint to read the current value from.
> +	 */

Cut-n-pasted comment. Change to:

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:
> +	 *
> +	 * Return value for the current syncpoint value.
> +	 */
Just:

Returned value of the syncpoint.

>  	__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:
> +	 *
> +	 * Return location for the application context of this channel. 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:
> +	 *
> +	 * Channel-relative index of the syncpoint for which to obtain the ID.
> +	 */
>  	__u32 index;

Client-relative. And what about:

Clients syncpoint index for which to obtain the ID.

> +
> +	/**
> +	 * @id:
> +	 *
> +	 * Return location for the ID of the given syncpoint.
> +	 */
>  	__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:
> +	 *
> +	 * Return location for the ID of the wait base.
> +	 */
>  	__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 into the command buffer at which to insert the the

Offset, in bytes,

> +		 * relocated address.
> +		 */
>  		__u32 offset;
>  	} cmdbuf;
>  	struct {
> +		/**
> +		 * @target.handle:
> +		 *
> +		 * Handle to the GEM object to be relocated.
> +		 */
>  		__u32 handle;
> +
> +		/**
> +		 * @target.offset:
> +		 *
> +		 * Offset into the target GEM object at which the relocated

Offset, in bytes,

> +		 * 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
> +	 * specify the syncpoint operations performed as part of this job.
> +	 */
>  	__u64 syncpts;
> +
> +	/**
> +	 * @cmdbufs:
> +	 *
> +	 * A pointer to @num_cmdbufs &struct drm_tegra_cmdbuf_legacy

We don't have drm_tegra_cmdbuf_legacy yet, should be 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_legacy structures
> +	 * that specify the relocations that need to be performed before
> +	 * executing this job.
> +	 */

Same as for drm_tegra_cmdbuf_legacy.

>  	__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:
> +	 *
> +	 * Return location for the threshold of the syncpoint associated with
> +	 * this job. 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:
> +	 *
> +	 * Return location for the tiling mode.
> +	 */
>  	__u32 mode;
> +
> +	/**
> +	 * @value:
> +	 *
> +	 * Return location for the tiling mode parameter.
> +	 */
>  	__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:
> +	 *
> +	 * Return location for the flags queried from the GEM object.
> +	 */
>  	__u32 flags;
>  };
>  
> 

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH 7/7] drm/tegra: Add kerneldoc for UAPI

[Thierry Reding]

[-- Attachment #1.1: Type: text/plain, Size: 15703 bytes --]

On Fri, May 18, 2018 at 08:19:55PM +0300, Dmitry Osipenko wrote:
> On 17.05.2018 18:41, Thierry Reding wrote:
> > From: Thierry Reding <treding@nvidia.com>
> > 
> > Document the userspace ABI with kerneldoc to provide some information on
> > how to use it.
> > 
> > Signed-off-by: Thierry Reding <treding@nvidia.com>
> > ---
> >  drivers/gpu/drm/tegra/gem.c  |   4 +-
> >  include/uapi/drm/tegra_drm.h | 480 ++++++++++++++++++++++++++++++++++-
> >  2 files changed, 468 insertions(+), 16 deletions(-)
> > 
> > diff --git a/drivers/gpu/drm/tegra/gem.c b/drivers/gpu/drm/tegra/gem.c
> > index 387ba1dfbe0d..e2987a19541d 100644
> > --- a/drivers/gpu/drm/tegra/gem.c
> > +++ b/drivers/gpu/drm/tegra/gem.c
> > @@ -291,10 +291,10 @@ struct tegra_bo *tegra_bo_create(struct drm_device *drm, size_t size,
> >  	if (err < 0)
> >  		goto release;
> >  
> > -	if (flags & DRM_TEGRA_GEM_CREATE_TILED)
> > +	if (flags & DRM_TEGRA_GEM_TILED)
> >  		bo->tiling.mode = TEGRA_BO_TILING_MODE_TILED;
> >  
> > -	if (flags & DRM_TEGRA_GEM_CREATE_BOTTOM_UP)
> > +	if (flags & DRM_TEGRA_GEM_BOTTOM_UP)
> >  		bo->flags |= TEGRA_BO_BOTTOM_UP;
> >  
> >  	return bo;
> > diff --git a/include/uapi/drm/tegra_drm.h b/include/uapi/drm/tegra_drm.h
> > index 99e15d82d1e9..86a7b1e7559d 100644
> > --- a/include/uapi/drm/tegra_drm.h
> > +++ b/include/uapi/drm/tegra_drm.h
> > @@ -29,146 +29,598 @@
> >  extern "C" {
> >  #endif
> >  
> > -#define DRM_TEGRA_GEM_CREATE_TILED     (1 << 0)
> > -#define DRM_TEGRA_GEM_CREATE_BOTTOM_UP (1 << 1)
> > +#define DRM_TEGRA_GEM_TILED		(1 << 0)
> > +#define DRM_TEGRA_GEM_BOTTOM_UP		(1 << 1)
> > +#define DRM_TEGRA_GEM_FLAGS		(DRM_TEGRA_GEM_TILED | \
> > +					 DRM_TEGRA_GEM_BOTTOM_UP)
> 
> The current userspace won't compile with the above changes, so this is the ABI
> breakage. Please keep the old DRM_TEGRA_GEM_CREATE_* DRM_TEGRA_GEM_* flags for now.

It looks like I fumbled this during a rebase and didn't catch it. I've
left the original flags in.

[...]
> > +/**
> > + * 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:
> > +	 *
> > +	 * Return location for the current syncpoint value.
> > +	 */>  	__u32 value;
> >  };
> 
> What about:
> 
> Returned value of the given syncpoint.
> 
> Could we replace "return location for the.." with just "Returned.." in other
> places too? My mind is stuttering while reading "location for the value", though
> I know that my english isn't ideal and maybe it's only me.

How about something a little more explicit, like:

	The current value of the syncpoint. Will be set by the kernel
	upon successful completion of the IOCTL.

?

> >  
> > +/**
> > + * struct drm_tegra_syncpt_incr - parameters for the increment syncpoint IOCTL
> > + */
> >  struct drm_tegra_syncpt_incr {
> > +	/**
> > +	 * @id:
> > +	 *
> > +	 * ID of the syncpoint to read the current value from.
> > +	 */
> 
> Cut-n-pasted comment. Change to:
> 
> ID of the syncpoint to increment.

Good catch. Fixed.

> >  	__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:
> > +	 *
> > +	 * Return value for the current syncpoint value.
> > +	 */
> Just:
> 
> Returned value of the syncpoint.

Will reword this similar to the above.

> >  	__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:
> > +	 *
> > +	 * Return location for the application context of this channel. 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:
> > +	 *
> > +	 * Channel-relative index of the syncpoint for which to obtain the ID.
> > +	 */
> >  	__u32 index;
> 
> Client-relative. And what about:
> 
> Clients syncpoint index for which to obtain the ID.

I'll try to find some better wording for this.

> > +
> > +	/**
> > +	 * @id:
> > +	 *
> > +	 * Return location for the ID of the given syncpoint.
> > +	 */
> >  	__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:
> > +	 *
> > +	 * Return location for the ID of the wait base.
> > +	 */
> >  	__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 into the command buffer at which to insert the the
> 
> Offset, in bytes,

Done.

> > +		 * relocated address.
> > +		 */
> >  		__u32 offset;
> >  	} cmdbuf;
> >  	struct {
> > +		/**
> > +		 * @target.handle:
> > +		 *
> > +		 * Handle to the GEM object to be relocated.
> > +		 */
> >  		__u32 handle;
> > +
> > +		/**
> > +		 * @target.offset:
> > +		 *
> > +		 * Offset into the target GEM object at which the relocated
> 
> Offset, in bytes,

Done.

> > +		 * 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
> > +	 * specify the syncpoint operations performed as part of this job.
> > +	 */
> >  	__u64 syncpts;
> > +
> > +	/**
> > +	 * @cmdbufs:
> > +	 *
> > +	 * A pointer to @num_cmdbufs &struct drm_tegra_cmdbuf_legacy
> 
> We don't have drm_tegra_cmdbuf_legacy yet, should be drm_tegra_cmdbuf.

Done.

> > +	 * 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_legacy structures
> > +	 * that specify the relocations that need to be performed before
> > +	 * executing this job.
> > +	 */
> 
> Same as for drm_tegra_cmdbuf_legacy.

Done.

> >  	__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:
> > +	 *
> > +	 * Return location for the threshold of the syncpoint associated with
> > +	 * this job. 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:
> > +	 *
> > +	 * Return location for the tiling mode.
> > +	 */
> >  	__u32 mode;
> > +
> > +	/**
> > +	 * @value:
> > +	 *
> > +	 * Return location for the tiling mode parameter.
> > +	 */
> >  	__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:
> > +	 *
> > +	 * Return location for the flags queried from the GEM object.
> > +	 */
> >  	__u32 flags;
> >  };
> >  

Thanks for the review. I'm going to think about a better wording for
some of the descriptions and send out a new version of this patch
individually, for review.

Thierry

[-- Attachment #1.2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[-- Attachment #2: Type: text/plain, Size: 160 bytes --]

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH 7/7] drm/tegra: Add kerneldoc for UAPI

[Dmitry Osipenko]

On 18.05.2018 23:12, Thierry Reding wrote:
> On Fri, May 18, 2018 at 08:19:55PM +0300, Dmitry Osipenko wrote:
>> On 17.05.2018 18:41, Thierry Reding wrote:
>>> From: Thierry Reding <treding@nvidia.com>
>>>
>>> Document the userspace ABI with kerneldoc to provide some information on
>>> how to use it.
>>>
>>> Signed-off-by: Thierry Reding <treding@nvidia.com>
>>> ---
>>>  drivers/gpu/drm/tegra/gem.c  |   4 +-
>>>  include/uapi/drm/tegra_drm.h | 480 ++++++++++++++++++++++++++++++++++-
>>>  2 files changed, 468 insertions(+), 16 deletions(-)
>>>
>>> diff --git a/drivers/gpu/drm/tegra/gem.c b/drivers/gpu/drm/tegra/gem.c
>>> index 387ba1dfbe0d..e2987a19541d 100644
>>> --- a/drivers/gpu/drm/tegra/gem.c
>>> +++ b/drivers/gpu/drm/tegra/gem.c
>>> @@ -291,10 +291,10 @@ struct tegra_bo *tegra_bo_create(struct drm_device *drm, size_t size,
>>>  	if (err < 0)
>>>  		goto release;
>>>  
>>> -	if (flags & DRM_TEGRA_GEM_CREATE_TILED)
>>> +	if (flags & DRM_TEGRA_GEM_TILED)
>>>  		bo->tiling.mode = TEGRA_BO_TILING_MODE_TILED;
>>>  
>>> -	if (flags & DRM_TEGRA_GEM_CREATE_BOTTOM_UP)
>>> +	if (flags & DRM_TEGRA_GEM_BOTTOM_UP)
>>>  		bo->flags |= TEGRA_BO_BOTTOM_UP;
>>>  
>>>  	return bo;
>>> diff --git a/include/uapi/drm/tegra_drm.h b/include/uapi/drm/tegra_drm.h
>>> index 99e15d82d1e9..86a7b1e7559d 100644
>>> --- a/include/uapi/drm/tegra_drm.h
>>> +++ b/include/uapi/drm/tegra_drm.h
>>> @@ -29,146 +29,598 @@
>>>  extern "C" {
>>>  #endif
>>>  
>>> -#define DRM_TEGRA_GEM_CREATE_TILED     (1 << 0)
>>> -#define DRM_TEGRA_GEM_CREATE_BOTTOM_UP (1 << 1)
>>> +#define DRM_TEGRA_GEM_TILED		(1 << 0)
>>> +#define DRM_TEGRA_GEM_BOTTOM_UP		(1 << 1)
>>> +#define DRM_TEGRA_GEM_FLAGS		(DRM_TEGRA_GEM_TILED | \
>>> +					 DRM_TEGRA_GEM_BOTTOM_UP)
>>
>> The current userspace won't compile with the above changes, so this is the ABI
>> breakage. Please keep the old DRM_TEGRA_GEM_CREATE_* DRM_TEGRA_GEM_* flags for now.
> 
> It looks like I fumbled this during a rebase and didn't catch it. I've
> left the original flags in.
> 
> [...]
>>> +/**
>>> + * 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:
>>> +	 *
>>> +	 * Return location for the current syncpoint value.
>>> +	 */>  	__u32 value;
>>>  };
>>
>> What about:
>>
>> Returned value of the given syncpoint.
>>
>> Could we replace "return location for the.." with just "Returned.." in other
>> places too? My mind is stuttering while reading "location for the value", though
>> I know that my english isn't ideal and maybe it's only me.
> 
> How about something a little more explicit, like:
> 
> 	The current value of the syncpoint. Will be set by the kernel
> 	upon successful completion of the IOCTL.
> 
> ?

That's better.

Maybe we could also use format like this:

/**
 * struct drm_tegra_syncpt_read - parameters for the read syncpoint IOCTL
 * @id:		ID of the syncpoint to read the current value from.
 * @value:	Return current value of the syncpoint.
 */
struct drm_tegra_syncpt_read {
	__u32 id;
	__u32 value;
};

> 
>>>  
>>> +/**
>>> + * struct drm_tegra_syncpt_incr - parameters for the increment syncpoint IOCTL
>>> + */
>>>  struct drm_tegra_syncpt_incr {
>>> +	/**
>>> +	 * @id:
>>> +	 *
>>> +	 * ID of the syncpoint to read the current value from.
>>> +	 */
>>
>> Cut-n-pasted comment. Change to:
>>
>> ID of the syncpoint to increment.
> 
> Good catch. Fixed.
> 
>>>  	__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:
>>> +	 *
>>> +	 * Return value for the current syncpoint value.
>>> +	 */
>> Just:
>>
>> Returned value of the syncpoint.
> 
> Will reword this similar to the above.
> 
>>>  	__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:
>>> +	 *
>>> +	 * Return location for the application context of this channel. 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:
>>> +	 *
>>> +	 * Channel-relative index of the syncpoint for which to obtain the ID.
>>> +	 */
>>>  	__u32 index;
>>
>> Client-relative. And what about:
>>
>> Clients syncpoint index for which to obtain the ID.
> 
> I'll try to find some better wording for this.
> 
>>> +
>>> +	/**
>>> +	 * @id:
>>> +	 *
>>> +	 * Return location for the ID of the given syncpoint.
>>> +	 */
>>>  	__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:
>>> +	 *
>>> +	 * Return location for the ID of the wait base.
>>> +	 */
>>>  	__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 into the command buffer at which to insert the the
>>
>> Offset, in bytes,
> 
> Done.
> 
>>> +		 * relocated address.
>>> +		 */
>>>  		__u32 offset;
>>>  	} cmdbuf;
>>>  	struct {
>>> +		/**
>>> +		 * @target.handle:
>>> +		 *
>>> +		 * Handle to the GEM object to be relocated.
>>> +		 */
>>>  		__u32 handle;
>>> +
>>> +		/**
>>> +		 * @target.offset:
>>> +		 *
>>> +		 * Offset into the target GEM object at which the relocated
>>
>> Offset, in bytes,
> 
> Done.
> 
>>> +		 * 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
>>> +	 * specify the syncpoint operations performed as part of this job.
>>> +	 */
>>>  	__u64 syncpts;
>>> +
>>> +	/**
>>> +	 * @cmdbufs:
>>> +	 *
>>> +	 * A pointer to @num_cmdbufs &struct drm_tegra_cmdbuf_legacy
>>
>> We don't have drm_tegra_cmdbuf_legacy yet, should be drm_tegra_cmdbuf.
> 
> Done.
> 
>>> +	 * 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_legacy structures
>>> +	 * that specify the relocations that need to be performed before
>>> +	 * executing this job.
>>> +	 */
>>
>> Same as for drm_tegra_cmdbuf_legacy.
> 
> Done.
> 
>>>  	__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:
>>> +	 *
>>> +	 * Return location for the threshold of the syncpoint associated with
>>> +	 * this job. 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:
>>> +	 *
>>> +	 * Return location for the tiling mode.
>>> +	 */
>>>  	__u32 mode;
>>> +
>>> +	/**
>>> +	 * @value:
>>> +	 *
>>> +	 * Return location for the tiling mode parameter.
>>> +	 */
>>>  	__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:
>>> +	 *
>>> +	 * Return location for the flags queried from the GEM object.
>>> +	 */
>>>  	__u32 flags;
>>>  };
>>>  
> 
> Thanks for the review. I'm going to think about a better wording for
> some of the descriptions and send out a new version of this patch
> individually, for review.

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH 7/7] drm/tegra: Add kerneldoc for UAPI

[Thierry Reding]

[-- Attachment #1.1: Type: text/plain, Size: 3762 bytes --]

On Sat, May 19, 2018 at 12:07:15AM +0300, Dmitry Osipenko wrote:
> On 18.05.2018 23:12, Thierry Reding wrote:
> > On Fri, May 18, 2018 at 08:19:55PM +0300, Dmitry Osipenko wrote:
> >> On 17.05.2018 18:41, Thierry Reding wrote:
> >>> From: Thierry Reding <treding@nvidia.com>
> >>>
> >>> Document the userspace ABI with kerneldoc to provide some information on
> >>> how to use it.
> >>>
> >>> Signed-off-by: Thierry Reding <treding@nvidia.com>
> >>> ---
> >>>  drivers/gpu/drm/tegra/gem.c  |   4 +-
> >>>  include/uapi/drm/tegra_drm.h | 480 ++++++++++++++++++++++++++++++++++-
> >>>  2 files changed, 468 insertions(+), 16 deletions(-)
> >>>
> >>> diff --git a/drivers/gpu/drm/tegra/gem.c b/drivers/gpu/drm/tegra/gem.c
> >>> index 387ba1dfbe0d..e2987a19541d 100644
> >>> --- a/drivers/gpu/drm/tegra/gem.c
> >>> +++ b/drivers/gpu/drm/tegra/gem.c
> >>> @@ -291,10 +291,10 @@ struct tegra_bo *tegra_bo_create(struct drm_device *drm, size_t size,
> >>>  	if (err < 0)
> >>>  		goto release;
> >>>  
> >>> -	if (flags & DRM_TEGRA_GEM_CREATE_TILED)
> >>> +	if (flags & DRM_TEGRA_GEM_TILED)
> >>>  		bo->tiling.mode = TEGRA_BO_TILING_MODE_TILED;
> >>>  
> >>> -	if (flags & DRM_TEGRA_GEM_CREATE_BOTTOM_UP)
> >>> +	if (flags & DRM_TEGRA_GEM_BOTTOM_UP)
> >>>  		bo->flags |= TEGRA_BO_BOTTOM_UP;
> >>>  
> >>>  	return bo;
> >>> diff --git a/include/uapi/drm/tegra_drm.h b/include/uapi/drm/tegra_drm.h
> >>> index 99e15d82d1e9..86a7b1e7559d 100644
> >>> --- a/include/uapi/drm/tegra_drm.h
> >>> +++ b/include/uapi/drm/tegra_drm.h
> >>> @@ -29,146 +29,598 @@
> >>>  extern "C" {
> >>>  #endif
> >>>  
> >>> -#define DRM_TEGRA_GEM_CREATE_TILED     (1 << 0)
> >>> -#define DRM_TEGRA_GEM_CREATE_BOTTOM_UP (1 << 1)
> >>> +#define DRM_TEGRA_GEM_TILED		(1 << 0)
> >>> +#define DRM_TEGRA_GEM_BOTTOM_UP		(1 << 1)
> >>> +#define DRM_TEGRA_GEM_FLAGS		(DRM_TEGRA_GEM_TILED | \
> >>> +					 DRM_TEGRA_GEM_BOTTOM_UP)
> >>
> >> The current userspace won't compile with the above changes, so this is the ABI
> >> breakage. Please keep the old DRM_TEGRA_GEM_CREATE_* DRM_TEGRA_GEM_* flags for now.
> > 
> > It looks like I fumbled this during a rebase and didn't catch it. I've
> > left the original flags in.
> > 
> > [...]
> >>> +/**
> >>> + * 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:
> >>> +	 *
> >>> +	 * Return location for the current syncpoint value.
> >>> +	 */>  	__u32 value;
> >>>  };
> >>
> >> What about:
> >>
> >> Returned value of the given syncpoint.
> >>
> >> Could we replace "return location for the.." with just "Returned.." in other
> >> places too? My mind is stuttering while reading "location for the value", though
> >> I know that my english isn't ideal and maybe it's only me.
> > 
> > How about something a little more explicit, like:
> > 
> > 	The current value of the syncpoint. Will be set by the kernel
> > 	upon successful completion of the IOCTL.
> > 
> > ?
> 
> That's better.
> 
> Maybe we could also use format like this:
> 
> /**
>  * struct drm_tegra_syncpt_read - parameters for the read syncpoint IOCTL
>  * @id:		ID of the syncpoint to read the current value from.
>  * @value:	Return current value of the syncpoint.
>  */
> struct drm_tegra_syncpt_read {
> 	__u32 id;
> 	__u32 value;
> };

The per-field description blocks are preferred in the DRM subsystem. I
think primarily this is to decrease the chances of anyone forgetting to
update the documentation when the code changes.

Thierry

[-- Attachment #1.2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[-- Attachment #2: Type: text/plain, Size: 160 bytes --]

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

[PATCH v2] drm/tegra: Add kerneldoc for UAPI

[Thierry Reding]

From: Thierry Reding <treding@nvidia.com>

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@nvidia.com>
---
 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
+	 * 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;
 };
 
-- 
2.17.0

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH v2] drm/tegra: Add kerneldoc for UAPI

[Dmitry Osipenko]

On 18.05.2018 23:33, Thierry Reding wrote:
> From: Thierry Reding <treding@nvidia.com>
> 
> 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@nvidia.com>
> ---
>  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@gmail.com>

> +	 * 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@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH v2] drm/tegra: Add kerneldoc for UAPI

[Thierry Reding]

[-- Attachment #1.1: Type: text/plain, Size: 11517 bytes --]

On Sat, May 19, 2018 at 12:42:22AM +0300, Dmitry Osipenko wrote:
> On 18.05.2018 23:33, Thierry Reding wrote:
> > From: Thierry Reding <treding@nvidia.com>
> > 
> > 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@nvidia.com>
> > ---
> >  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.

I wanted to have the references to those fields in the text so that it
becomes obvious that num_syncpts defines the number of entries in this
syncpts array.

Perhaps a better formulation would be:

	A pointer to an array of @num_syncpts &struct drm_tegra_syncpt
	structure that...

?

Thierry

[-- Attachment #1.2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[-- Attachment #2: Type: text/plain, Size: 160 bytes --]

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH v2] drm/tegra: Add kerneldoc for UAPI

[Thierry Reding]

[-- Attachment #1.1: Type: text/plain, Size: 13200 bytes --]

On Fri, May 18, 2018 at 11:58:19PM +0200, Thierry Reding wrote:
> On Sat, May 19, 2018 at 12:42:22AM +0300, Dmitry Osipenko wrote:
> > On 18.05.2018 23:33, Thierry Reding wrote:
> > > From: Thierry Reding <treding@nvidia.com>
> > > 
> > > 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@nvidia.com>
> > > ---
> > >  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.
> 
> I wanted to have the references to those fields in the text so that it
> becomes obvious that num_syncpts defines the number of entries in this
> syncpts array.
> 
> Perhaps a better formulation would be:
> 
> 	A pointer to an array of @num_syncpts &struct drm_tegra_syncpt
> 	structure that...
> 
> ?

Another alternative may be:

	/**
	 * @syncpts:
	 *
	 * A pointer to an array of &struct drm_tegra_syncpt structure that
	 * specify the syncpoint operations performed as part of this job.
	 * The number of elements in the array must be equal to the value
	 * given by @num_syncpts.
	 */

That's slightly easier to read but also very explicit in relating both
fields to one another. Perhaps a two-way link can be established by
adding something like this to the description of @num_syncpts:

	/**
	 * @num_syncpts:
	 *
	 * The number of syncpoints operated on by this job. This defines
	 * the length of the array pointed to by @syncpts.
	 */

Thierry

[-- Attachment #1.2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[-- Attachment #2: Type: text/plain, Size: 160 bytes --]

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH v2] drm/tegra: Add kerneldoc for UAPI

[Dmitry Osipenko]

On 19.05.2018 01:13, Thierry Reding wrote:
> On Fri, May 18, 2018 at 11:58:19PM +0200, Thierry Reding wrote:
>> On Sat, May 19, 2018 at 12:42:22AM +0300, Dmitry Osipenko wrote:
>>> On 18.05.2018 23:33, Thierry Reding wrote:
>>>> From: Thierry Reding <treding@nvidia.com>
>>>>
>>>> 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@nvidia.com>
>>>> ---
>>>>  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.
>>
>> I wanted to have the references to those fields in the text so that it
>> becomes obvious that num_syncpts defines the number of entries in this
>> syncpts array.
>>
>> Perhaps a better formulation would be:
>>
>> 	A pointer to an array of @num_syncpts &struct drm_tegra_syncpt
>> 	structure that...
>>
>> ?

That variant is good to me.

> 
> Another alternative may be:
> 
> 	/**
> 	 * @syncpts:
> 	 *
> 	 * A pointer to an array of &struct drm_tegra_syncpt structure that
> 	 * specify the syncpoint operations performed as part of this job.
> 	 * The number of elements in the array must be equal to the value
> 	 * given by @num_syncpts.
> 	 */
> 
> That's slightly easier to read but also very explicit in relating both
> fields to one another. Perhaps a two-way link can be established by
> adding something like this to the description of @num_syncpts:
> 
> 	/**
> 	 * @num_syncpts:
> 	 *
> 	 * The number of syncpoints operated on by this job. This defines
> 	 * the length of the array pointed to by @syncpts.
> 	 */

But this variant is even better.

I don't mind either way, choose what you prefer.
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH v2] drm/tegra: Add kerneldoc for UAPI

[Thierry Reding]

[-- Attachment #1.1: Type: text/plain, Size: 14232 bytes --]

On Sat, May 19, 2018 at 01:18:05AM +0300, Dmitry Osipenko wrote:
> On 19.05.2018 01:13, Thierry Reding wrote:
> > On Fri, May 18, 2018 at 11:58:19PM +0200, Thierry Reding wrote:
> >> On Sat, May 19, 2018 at 12:42:22AM +0300, Dmitry Osipenko wrote:
> >>> On 18.05.2018 23:33, Thierry Reding wrote:
> >>>> From: Thierry Reding <treding@nvidia.com>
> >>>>
> >>>> 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@nvidia.com>
> >>>> ---
> >>>>  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.
> >>
> >> I wanted to have the references to those fields in the text so that it
> >> becomes obvious that num_syncpts defines the number of entries in this
> >> syncpts array.
> >>
> >> Perhaps a better formulation would be:
> >>
> >> 	A pointer to an array of @num_syncpts &struct drm_tegra_syncpt
> >> 	structure that...
> >>
> >> ?
> 
> That variant is good to me.
> 
> > 
> > Another alternative may be:
> > 
> > 	/**
> > 	 * @syncpts:
> > 	 *
> > 	 * A pointer to an array of &struct drm_tegra_syncpt structure that
> > 	 * specify the syncpoint operations performed as part of this job.
> > 	 * The number of elements in the array must be equal to the value
> > 	 * given by @num_syncpts.
> > 	 */
> > 
> > That's slightly easier to read but also very explicit in relating both
> > fields to one another. Perhaps a two-way link can be established by
> > adding something like this to the description of @num_syncpts:
> > 
> > 	/**
> > 	 * @num_syncpts:
> > 	 *
> > 	 * The number of syncpoints operated on by this job. This defines
> > 	 * the length of the array pointed to by @syncpts.
> > 	 */
> 
> But this variant is even better.
> 
> I don't mind either way, choose what you prefer.

I went with the latter. I've updated all of these field descriptions and
added your Reviewed-by. Pushed everything to drm/tegra/for-next and will
send a pull request for that branch shortly.

Thierry

[-- Attachment #1.2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[-- Attachment #2: Type: text/plain, Size: 160 bytes --]

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH v2] drm/tegra: Add kerneldoc for UAPI

[Dmitry Osipenko]

On 19.05.2018 01:24, Thierry Reding wrote:
> On Sat, May 19, 2018 at 01:18:05AM +0300, Dmitry Osipenko wrote:
>> On 19.05.2018 01:13, Thierry Reding wrote:
>>> On Fri, May 18, 2018 at 11:58:19PM +0200, Thierry Reding wrote:
>>>> On Sat, May 19, 2018 at 12:42:22AM +0300, Dmitry Osipenko wrote:
>>>>> On 18.05.2018 23:33, Thierry Reding wrote:
>>>>>> From: Thierry Reding <treding@nvidia.com>
>>>>>>
>>>>>> 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@nvidia.com>
>>>>>> ---
>>>>>>  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.
>>>>
>>>> I wanted to have the references to those fields in the text so that it
>>>> becomes obvious that num_syncpts defines the number of entries in this
>>>> syncpts array.
>>>>
>>>> Perhaps a better formulation would be:
>>>>
>>>> 	A pointer to an array of @num_syncpts &struct drm_tegra_syncpt
>>>> 	structure that...
>>>>
>>>> ?
>>
>> That variant is good to me.
>>
>>>
>>> Another alternative may be:
>>>
>>> 	/**
>>> 	 * @syncpts:
>>> 	 *
>>> 	 * A pointer to an array of &struct drm_tegra_syncpt structure that
>>> 	 * specify the syncpoint operations performed as part of this job.
>>> 	 * The number of elements in the array must be equal to the value
>>> 	 * given by @num_syncpts.
>>> 	 */
>>>
>>> That's slightly easier to read but also very explicit in relating both
>>> fields to one another. Perhaps a two-way link can be established by
>>> adding something like this to the description of @num_syncpts:
>>>
>>> 	/**
>>> 	 * @num_syncpts:
>>> 	 *
>>> 	 * The number of syncpoints operated on by this job. This defines
>>> 	 * the length of the array pointed to by @syncpts.
>>> 	 */
>>
>> But this variant is even better.
>>
>> I don't mind either way, choose what you prefer.
> 
> I went with the latter. I've updated all of these field descriptions and
> added your Reviewed-by. Pushed everything to drm/tegra/for-next and will
> send a pull request for that branch shortly.

Awesome! I think Mikko was going to make a patch to the validation bug in the
submit code that he spotted recently, so maybe it would worth to postpone the
pull request a tad.
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH v2] drm/tegra: Add kerneldoc for UAPI

[Thierry Reding]

[-- Attachment #1.1: Type: text/plain, Size: 15832 bytes --]

On Sat, May 19, 2018 at 01:28:17AM +0300, Dmitry Osipenko wrote:
> On 19.05.2018 01:24, Thierry Reding wrote:
> > On Sat, May 19, 2018 at 01:18:05AM +0300, Dmitry Osipenko wrote:
> >> On 19.05.2018 01:13, Thierry Reding wrote:
> >>> On Fri, May 18, 2018 at 11:58:19PM +0200, Thierry Reding wrote:
> >>>> On Sat, May 19, 2018 at 12:42:22AM +0300, Dmitry Osipenko wrote:
> >>>>> On 18.05.2018 23:33, Thierry Reding wrote:
> >>>>>> From: Thierry Reding <treding@nvidia.com>
> >>>>>>
> >>>>>> 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@nvidia.com>
> >>>>>> ---
> >>>>>>  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.
> >>>>
> >>>> I wanted to have the references to those fields in the text so that it
> >>>> becomes obvious that num_syncpts defines the number of entries in this
> >>>> syncpts array.
> >>>>
> >>>> Perhaps a better formulation would be:
> >>>>
> >>>> 	A pointer to an array of @num_syncpts &struct drm_tegra_syncpt
> >>>> 	structure that...
> >>>>
> >>>> ?
> >>
> >> That variant is good to me.
> >>
> >>>
> >>> Another alternative may be:
> >>>
> >>> 	/**
> >>> 	 * @syncpts:
> >>> 	 *
> >>> 	 * A pointer to an array of &struct drm_tegra_syncpt structure that
> >>> 	 * specify the syncpoint operations performed as part of this job.
> >>> 	 * The number of elements in the array must be equal to the value
> >>> 	 * given by @num_syncpts.
> >>> 	 */
> >>>
> >>> That's slightly easier to read but also very explicit in relating both
> >>> fields to one another. Perhaps a two-way link can be established by
> >>> adding something like this to the description of @num_syncpts:
> >>>
> >>> 	/**
> >>> 	 * @num_syncpts:
> >>> 	 *
> >>> 	 * The number of syncpoints operated on by this job. This defines
> >>> 	 * the length of the array pointed to by @syncpts.
> >>> 	 */
> >>
> >> But this variant is even better.
> >>
> >> I don't mind either way, choose what you prefer.
> > 
> > I went with the latter. I've updated all of these field descriptions and
> > added your Reviewed-by. Pushed everything to drm/tegra/for-next and will
> > send a pull request for that branch shortly.
> 
> Awesome! I think Mikko was going to make a patch to the validation bug in the
> submit code that he spotted recently, so maybe it would worth to postpone the
> pull request a tad.

This is for the main feature pull request for v4.18-rc1, for which the
deadline is usually -rc6 of the previous version, so this is already
cutting it rather close. If Mikko has a bugfix patch that's something
that can go into a separate -fixes pull request.

Thierry

[-- Attachment #1.2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[-- Attachment #2: Type: text/plain, Size: 160 bytes --]

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH v2] drm/tegra: Add kerneldoc for UAPI

[Dmitry Osipenko]

On 19.05.2018 01:35, Thierry Reding wrote:
> On Sat, May 19, 2018 at 01:28:17AM +0300, Dmitry Osipenko wrote:
>> On 19.05.2018 01:24, Thierry Reding wrote:
>>> On Sat, May 19, 2018 at 01:18:05AM +0300, Dmitry Osipenko wrote:
>>>> On 19.05.2018 01:13, Thierry Reding wrote:
>>>>> On Fri, May 18, 2018 at 11:58:19PM +0200, Thierry Reding wrote:
>>>>>> On Sat, May 19, 2018 at 12:42:22AM +0300, Dmitry Osipenko wrote:
>>>>>>> On 18.05.2018 23:33, Thierry Reding wrote:
>>>>>>>> From: Thierry Reding <treding@nvidia.com>
>>>>>>>>
>>>>>>>> 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@nvidia.com>
>>>>>>>> ---
>>>>>>>>  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.
>>>>>>
>>>>>> I wanted to have the references to those fields in the text so that it
>>>>>> becomes obvious that num_syncpts defines the number of entries in this
>>>>>> syncpts array.
>>>>>>
>>>>>> Perhaps a better formulation would be:
>>>>>>
>>>>>> 	A pointer to an array of @num_syncpts &struct drm_tegra_syncpt
>>>>>> 	structure that...
>>>>>>
>>>>>> ?
>>>>
>>>> That variant is good to me.
>>>>
>>>>>
>>>>> Another alternative may be:
>>>>>
>>>>> 	/**
>>>>> 	 * @syncpts:
>>>>> 	 *
>>>>> 	 * A pointer to an array of &struct drm_tegra_syncpt structure that
>>>>> 	 * specify the syncpoint operations performed as part of this job.
>>>>> 	 * The number of elements in the array must be equal to the value
>>>>> 	 * given by @num_syncpts.
>>>>> 	 */
>>>>>
>>>>> That's slightly easier to read but also very explicit in relating both
>>>>> fields to one another. Perhaps a two-way link can be established by
>>>>> adding something like this to the description of @num_syncpts:
>>>>>
>>>>> 	/**
>>>>> 	 * @num_syncpts:
>>>>> 	 *
>>>>> 	 * The number of syncpoints operated on by this job. This defines
>>>>> 	 * the length of the array pointed to by @syncpts.
>>>>> 	 */
>>>>
>>>> But this variant is even better.
>>>>
>>>> I don't mind either way, choose what you prefer.
>>>
>>> I went with the latter. I've updated all of these field descriptions and
>>> added your Reviewed-by. Pushed everything to drm/tegra/for-next and will
>>> send a pull request for that branch shortly.
>>
>> Awesome! I think Mikko was going to make a patch to the validation bug in the
>> submit code that he spotted recently, so maybe it would worth to postpone the
>> pull request a tad.
> 
> This is for the main feature pull request for v4.18-rc1, for which the
> deadline is usually -rc6 of the previous version, so this is already
> cutting it rather close. If Mikko has a bugfix patch that's something
> that can go into a separate -fixes pull request.

Okay.
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH v2] drm/tegra: Add kerneldoc for UAPI

[Daniel Vetter]

On Fri, May 18, 2018 at 10:33:37PM +0200, Thierry Reding wrote:
> From: Thierry Reding <treding@nvidia.com>
> 
> 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@nvidia.com>
> ---
>  include/uapi/drm/tegra_drm.h | 480 ++++++++++++++++++++++++++++++++++-

Would be great to include that somewhere in Documentation/gpu/drivers.rst
under a tegra chapter. Otherwise 0day won't check your docs at all
unfortunately.
-Daniel

>  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
> +	 * 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;
>  };
>  
> -- 
> 2.17.0
> 
> _______________________________________________
> dri-devel mailing list
> dri-devel@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel