[Intel-gfx] [PATCH 4/6] lib: api docs for intel_batchbuffer
Daniel Vetter
daniel.vetter at ffwll.ch
Thu Mar 13 19:02:49 CET 2014
- I didn't bother to document the BLIT batch header macros - I'm not
too happy with them and they're fairly obscure.
- intel_copy_bo could use some interface love, added a FIXME comment
for now.
Signed-off-by: Daniel Vetter <daniel.vetter at ffwll.ch>
---
lib/intel_batchbuffer.c | 119 +++++++++++++++++++++++++++++++++++++++++++++++-
lib/intel_batchbuffer.h | 57 +++++++++++++++++++++++
2 files changed, 175 insertions(+), 1 deletion(-)
diff --git a/lib/intel_batchbuffer.c b/lib/intel_batchbuffer.c
index 9ce7424fceb1..931cfca809de 100644
--- a/lib/intel_batchbuffer.c
+++ b/lib/intel_batchbuffer.c
@@ -39,6 +39,28 @@
#include "intel_reg.h"
#include <i915_drm.h>
+/**
+ * SECTION:intel_batchbuffer
+ * @short_description: Batchbuffer and blitter support
+ * @title: intel batchbuffer
+ *
+ * This library provides some basic support for batchbuffers and using the
+ * blitter engine based upon libdrm. A new batchbuffer is allocated with
+ * intel_batchbuffer_alloc() and for simple blitter commands submitted with
+ * intel_batchbuffer_flush().
+ *
+ * It also provides some convenient macros to easily emit commands into
+ * batchbuffers. All those macros presume that a pointer to a #intel_batchbuffer
+ * structure called batch is in scope. The basic macros are #BEGIN_BATCH,
+ * #OUT_BATCH, #OUT_RELOC and #ADVANCE_BATCH.
+ */
+
+/**
+ * intel_batchbuffer_reset:
+ * @batch: batchbuffer object
+ *
+ * Resets @batch by allocating a new gem buffer object as backing storage.
+ */
void
intel_batchbuffer_reset(struct intel_batchbuffer *batch)
{
@@ -55,6 +77,16 @@ intel_batchbuffer_reset(struct intel_batchbuffer *batch)
batch->ptr = batch->buffer;
}
+/**
+ * intel_batchbuffer_reset:
+ * @bufmgr: libdrm buffer manager
+ * @devid: pci device id of the drm device
+ *
+ * Allocates a new batchbuffer object. @devid must be supplied since libdrm
+ * doesn't expose it directly.
+ *
+ * Returns: The allocated and initialized batchbuffer object.
+ */
struct intel_batchbuffer *
intel_batchbuffer_alloc(drm_intel_bufmgr *bufmgr, uint32_t devid)
{
@@ -67,6 +99,12 @@ intel_batchbuffer_alloc(drm_intel_bufmgr *bufmgr, uint32_t devid)
return batch;
}
+/**
+ * intel_batchbuffer_reset:
+ * @batch: batchbuffer object
+ *
+ * Releases all resource of the batchbuffer object @batch.
+ */
void
intel_batchbuffer_free(struct intel_batchbuffer *batch)
{
@@ -106,6 +144,13 @@ flush_on_ring_common(struct intel_batchbuffer *batch, int ring)
return batch->ptr - batch->buffer;
}
+/**
+ * intel_batchbuffer_flush_on_ring:
+ * @batch: batchbuffer object
+ * @ring: execbuf ring flag
+ *
+ * Submits the batch for execution on @ring.
+ */
void
intel_batchbuffer_flush_on_ring(struct intel_batchbuffer *batch, int ring)
{
@@ -123,6 +168,14 @@ intel_batchbuffer_flush_on_ring(struct intel_batchbuffer *batch, int ring)
intel_batchbuffer_reset(batch);
}
+/**
+ * intel_batchbuffer_flush_with_context:
+ * @batch: batchbuffer object
+ * @context: libdrm hardware context object
+ *
+ * Submits the batch for execution on the render engine with the supplied
+ * hardware context.
+ */
void
intel_batchbuffer_flush_with_context(struct intel_batchbuffer *batch,
drm_intel_context *context)
@@ -145,6 +198,13 @@ intel_batchbuffer_flush_with_context(struct intel_batchbuffer *batch,
intel_batchbuffer_reset(batch);
}
+/**
+ * intel_batchbuffer_flush:
+ * @batch: batchbuffer object
+ *
+ * Submits the batch for execution on the blitter engine, selecting the right
+ * ring depending upon the hardware platform.
+ */
void
intel_batchbuffer_flush(struct intel_batchbuffer *batch)
{
@@ -155,7 +215,21 @@ intel_batchbuffer_flush(struct intel_batchbuffer *batch)
}
-/* This is the only way buffers get added to the validate list.
+/**
+ * intel_batchbuffer_emit_reloc:
+ * @batch: batchbuffer object
+ * @buffer: relocation target libdrm buffer object
+ * @delta: delta value to add to @buffer's gpu address
+ * @read_domains: gem domain bits for the relocation
+ * @write_domain: gem domain bit for the relocation
+ * @fenced: whether this gpu access requires fences
+ *
+ * Emits both a libdrm relocation entry pointing at @buffer and the pre-computed
+ * DWORD of @batch's presumed gpu address plus the supplied @delta into @batch.
+ *
+ * Note that @fenced is only relevant if @buffer is actually tiled.
+ *
+ * This is the only way buffers get added to the validate list.
*/
void
intel_batchbuffer_emit_reloc(struct intel_batchbuffer *batch,
@@ -183,6 +257,15 @@ intel_batchbuffer_emit_reloc(struct intel_batchbuffer *batch,
assert(ret == 0);
}
+/**
+ * intel_batchbuffer_data:
+ * @batch: batchbuffer object
+ * @data: pointer to the data to write into the batchbuffer
+ * @bytes: number of bytes to write into the batchbuffer
+ *
+ * This transfers the given @data into the batchbuffer. Note that the length
+ * must be DWORD aligned, i.e. multiples of 32bits.
+ */
void
intel_batchbuffer_data(struct intel_batchbuffer *batch,
const void *data, unsigned int bytes)
@@ -193,6 +276,24 @@ intel_batchbuffer_data(struct intel_batchbuffer *batch,
batch->ptr += bytes;
}
+/**
+ * intel_blt_copy:
+ * @batch: batchbuffer object
+ * @src_bo: source libdrm buffer object
+ * @src_x1: source pixel x-coordination
+ * @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_pitch: @dst_bo's pitch in bytes
+ * @width: width of the copied rectangle
+ * @height: height of the copied rectangle
+ * @bpp: bits per pixel
+ *
+ * This emits a 2D copy operation using blitter commands into the supplied batch
+ * buffer object.
+ */
void
intel_blt_copy(struct intel_batchbuffer *batch,
drm_intel_bo *src_bo, int src_x1, int src_y1, int src_pitch,
@@ -260,6 +361,22 @@ intel_blt_copy(struct intel_batchbuffer *batch,
intel_batchbuffer_flush(batch);
}
+/**
+ * intel_copy_bo:
+ * @batch: batchbuffer object
+ * @src_bo: source libdrm buffer object
+ * @dst_bo: destination libdrm buffer object
+ * @width: width of the copied area in 4-byte pixels
+ * @height: height of the copied area in lines
+ *
+ * This emits a copy operation using blitter commands into the supplied batch
+ * buffer object. A total of @width times @height bytes from the start of
+ * @src_bo is copied over to @dst_bo.
+ *
+ * FIXME: We need @width and @height to avoid hitting into platform specific
+ * of the blitter. It would be easier to just accept a size and do the math
+ * ourselves.
+ */
void
intel_copy_bo(struct intel_batchbuffer *batch,
drm_intel_bo *dst_bo, drm_intel_bo *src_bo,
diff --git a/lib/intel_batchbuffer.h b/lib/intel_batchbuffer.h
index fe000e7d1af3..65a21d781000 100644
--- a/lib/intel_batchbuffer.h
+++ b/lib/intel_batchbuffer.h
@@ -71,24 +71,75 @@ intel_batchbuffer_require_space(struct intel_batchbuffer *batch,
intel_batchbuffer_flush(batch);
}
+/**
+ * BEGIN_BATCH:
+ * @n: number of DWORDS to emit
+ *
+ * Prepares a batch to emit @n DWORDS, flushing it if there's not enough space
+ * available.
+ *
+ * This macro needs a pointer to an #intel_batchbuffer structure called batch in
+ * scope.
+ */
#define BEGIN_BATCH(n) do { \
intel_batchbuffer_require_space(batch, (n)*4); \
} while (0)
+/**
+ * OUT_BATCH:
+ * @d: DWORD to emit
+ *
+ * Emits @d into a batch.
+ *
+ * This macro needs a pointer to an #intel_batchbuffer structure called batch in
+ * scope.
+ */
#define OUT_BATCH(d) intel_batchbuffer_emit_dword(batch, d)
+/**
+ * OUT_RELOC_FENCED:
+ * @buf: relocation target libdrm buffer object
+ * @read_domains: gem domain bits for the relocation
+ * @write_domain: gem domain bit for the relocation
+ * @delta: delta value to add to @buffer's gpu address
+ *
+ * Emits a fenced relocation into a batch.
+ *
+ * This macro needs a pointer to an #intel_batchbuffer structure called batch in
+ * scope.
+ */
#define OUT_RELOC_FENCED(buf, read_domains, write_domain, delta) do { \
assert((delta) >= 0); \
intel_batchbuffer_emit_reloc(batch, buf, delta, \
read_domains, write_domain, 1); \
} while (0)
+/**
+ * OUT_RELOC_FENCED:
+ * @buf: relocation target libdrm buffer object
+ * @read_domains: gem domain bits for the relocation
+ * @write_domain: gem domain bit for the relocation
+ * @delta: delta value to add to @buffer's gpu address
+ *
+ * Emits a normal, unfenced relocation into a batch.
+ *
+ * This macro needs a pointer to an #intel_batchbuffer structure called batch in
+ * scope.
+ */
#define OUT_RELOC(buf, read_domains, write_domain, delta) do { \
assert((delta) >= 0); \
intel_batchbuffer_emit_reloc(batch, buf, delta, \
read_domains, write_domain, 0); \
} while (0)
+/**
+ * ADVANCE_BATCH:
+ *
+ * Completes the batch command emission sequence started with #BEGIN_BATCH.
+ *
+ * This macro needs a pointer to an #intel_batchbuffer structure called batch in
+ * scope.
+ */
#define ADVANCE_BATCH() do { \
} while(0)
@@ -123,6 +174,12 @@ intel_batchbuffer_require_space(struct intel_batchbuffer *batch,
} \
} while(0)
+/**
+ * BLIT_RELOC_UDW:
+ * @devid: pci device id of the drm device
+ *
+ * Emits the upper relocation DWORD on gen8+ and nothing on earlier generations.
+ */
#define BLIT_RELOC_UDW(devid) do { \
if (intel_gen(devid) >= 8) { \
OUT_BATCH(0); \
--
1.8.5.2
More information about the Intel-gfx
mailing list