[Intel-gfx] [PATCH 11/28] lib/intel_batchbuffer: api documentation for render copy/media fill

[Daniel Vetter]

Also fix a fumble in the documentation for intel_blt_copy. One thing
we might want to do is unify the parameter ordering here a bit ...

Again gtkdoc fails to pick up the documentation for struct igt_buf :(

Signed-off-by: Daniel Vetter <daniel.vetter at ffwll.ch>
---
 lib/intel_batchbuffer.c | 41 +++++++++++++++++++++++++++++++++++--
 lib/intel_batchbuffer.h | 54 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 93 insertions(+), 2 deletions(-)

diff --git a/lib/intel_batchbuffer.c b/lib/intel_batchbuffer.c
index 6a585c7df967..3a38f13326ec 100644
--- a/lib/intel_batchbuffer.c
+++ b/lib/intel_batchbuffer.c
@@ -286,8 +286,8 @@ intel_batchbuffer_data(struct intel_batchbuffer *batch,
  * @src_y1: source pixel y-coordination
  * @src_pitch: @src_bo's pitch in bytes
  * @dst_bo: destination libdrm buffer object
- * @dst_x1: source pixel x-coordination
- * @dst_y1: source pixel y-coordination
+ * @dst_x1: destination pixel x-coordination
+ * @dst_y1: destination pixel y-coordination
  * @dst_pitch: @dst_bo's pitch in bytes
  * @width: width of the copied rectangle
  * @height: height of the copied rectangle
@@ -387,16 +387,44 @@ intel_copy_bo(struct intel_batchbuffer *batch,
 		       4096/4, size/4096, 32);
 }
 
+/**
+ * igt_buf_width:
+ * @buf: the i-g-t buffer object
+ *
+ * Computes the widht in 32-bit pixels of the given buffer.
+ *
+ * Returns:
+ * The width of the buffer.
+ */
 unsigned igt_buf_width(struct igt_buf *buf)
 {
 	return buf->stride/sizeof(uint32_t);
 }
 
+/**
+ * igt_buf_height:
+ * @buf: the i-g-t buffer object
+ *
+ * Computes the height in 32-bit pixels of the given buffer.
+ *
+ * Returns:
+ * The height of the buffer.
+ */
 unsigned igt_buf_height(struct igt_buf *buf)
 {
 	return buf->size/buf->stride;
 }
 
+/**
+ * igt_get_render_copyfunc:
+ * @devid: pci device id
+ *
+ * Returns:
+ *
+ * The platform-specific render copy function pointer for the device
+ * specified with @devid. Will return NULL when no render copy function is
+ * implemented.
+ */
 igt_render_copyfunc_t igt_get_render_copyfunc(int devid)
 {
 	igt_render_copyfunc_t copy = NULL;
@@ -415,6 +443,15 @@ igt_render_copyfunc_t igt_get_render_copyfunc(int devid)
 	return copy;
 }
 
+/**
+ * igt_get_media_fillfunc:
+ * @devid: pci device id
+ *
+ * Returns:
+ *
+ * The platform-specific media fill function pointer for the device specified
+ * with @devid. Will return NULL when no media fill function is implemented.
+ */
 igt_media_fillfunc_t igt_get_media_fillfunc(int devid)
 {
 	igt_media_fillfunc_t fill = NULL;
diff --git a/lib/intel_batchbuffer.h b/lib/intel_batchbuffer.h
index 6a65f6f7b36f..b3e4b8ffd4e5 100644
--- a/lib/intel_batchbuffer.h
+++ b/lib/intel_batchbuffer.h
@@ -196,6 +196,22 @@ void intel_copy_bo(struct intel_batchbuffer *batch,
 		   drm_intel_bo *dst_bo, drm_intel_bo *src_bo,
 		   long int size);
 
+/**
+ * igt_buf:
+ * @bo: underlying libdrm buffer object
+ * @stride: stride of the buffer
+ * @tiling: tiling mode bits
+ * @data: pointer to the memory mapping of the buffer
+ * @size: size of the buffer object
+ * @num_tiles: number of tiles of the buffer object
+ *
+ * This is a i-g-t buffer object wrapper structure which augments the baseline
+ * libdrm buffer object with suitable data needed by the render copy and the
+ * media fill functions.
+ *
+ * Note that @num_tiles is only used by gem_stress.c internally and can be
+ * ignored.
+ */
 struct igt_buf {
     drm_intel_bo *bo;
     uint32_t stride;
@@ -208,6 +224,27 @@ struct igt_buf {
 unsigned igt_buf_width(struct igt_buf *buf);
 unsigned igt_buf_height(struct igt_buf *buf);
 
+/**
+ * igt_render_copyfunc_t:
+ * @batch: batchbuffer object
+ * @context: libdrm hardware context to use
+ * @src: source i-g-t buffer object
+ * @src_x: source pixel x-coordination
+ * @src_y: source pixel y-coordination
+ * @width: width of the copied rectangle
+ * @height: height of the copied rectangle
+ * @dst: destination i-g-t buffer object
+ * @dst_x: destination pixel x-coordination
+ * @dst_y: destination pixel y-coordination
+ *
+ * This is the type of the per-platform render copy functions. The
+ * platform-specific implementation can be obtained by calling
+ * igt_get_render_copyfunc().
+ *
+ * A render copy function will emit a batchbuffer to the kernel which executes
+ * the specified blit copy operation using the render engine. @context is
+ * optional and can be NULL.
+ */
 typedef void (*igt_render_copyfunc_t)(struct intel_batchbuffer *batch,
 				      drm_intel_context *context,
 				      struct igt_buf *src, unsigned src_x, unsigned src_y,
@@ -216,6 +253,23 @@ typedef void (*igt_render_copyfunc_t)(struct intel_batchbuffer *batch,
 
 igt_render_copyfunc_t igt_get_render_copyfunc(int devid);
 
+/**
+ * igt_media_fillfunc_t:
+ * @batch: batchbuffer object
+ * @dst: destination i-g-t buffer object
+ * @x: destination pixel x-coordination
+ * @y: destination pixel y-coordination
+ * @width: width of the filled rectangle
+ * @height: height of the filled rectangle
+ * @color: fill color to use
+ *
+ * This is the type of the per-platform media fill functions. The
+ * platform-specific implementation can be obtained by calling
+ * igt_get_media_fillfunc().
+ *
+ * A media fill function will emit a batchbuffer to the kernel which executes
+ * the specified blit fill operation using the media engine.
+ */
 typedef void (*igt_media_fillfunc_t)(struct intel_batchbuffer *batch,
 				     struct igt_buf *dst,
 				     unsigned x, unsigned y,
-- 
1.8.5.2