intel-gpu-tools Reference Manual: intel batchbuffer

## intel batchbuffer intel batchbuffer — Batchbuffer and blitter support |

## Functions

struct intel_batchbuffer * | intel_batchbuffer_alloc ()
void | intel_batchbuffer_set_context ()
void | intel_batchbuffer_free ()
void | intel_batchbuffer_flush ()
void | intel_batchbuffer_flush_on_ring ()
void | intel_batchbuffer_flush_with_context ()
void | intel_batchbuffer_reset ()
void | intel_batchbuffer_data ()
void | intel_batchbuffer_emit_reloc ()
unsigned int | intel_batchbuffer_space ()
void | intel_batchbuffer_emit_dword ()
void | intel_batchbuffer_require_space ()
#define | BEGIN_BATCH()
#define | OUT_BATCH()
#define | OUT_RELOC_FENCED()
#define | OUT_RELOC()
#define | ADVANCE_BATCH
#define | BLIT_COPY_BATCH_START()
#define | COLOR_BLIT_COPY_BATCH_START()
void | intel_blt_copy ()
void | intel_copy_bo ()
unsigned | igt_buf_width ()
unsigned | igt_buf_height ()
void | (*igt_render_copyfunc_t) ()
igt_render_copyfunc_t | igt_get_render_copyfunc ()
void | (*igt_fillfunc_t) ()
igt_fillfunc_t | igt_get_media_fillfunc ()
igt_fillfunc_t | igt_get_gpgpu_fillfunc ()

## Types and Values

#define | BATCH_SZ
#define | BATCH_RESERVED
struct | intel_batchbuffer
struct | igt_buf

## Includes

    #include <intel_batchbuffer.h>

## Description

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.

Note that this library's header pulls in the i-g-t core library as a dependency.

## Functions

### intel_batchbuffer_alloc ()

    struct intel_batchbuffer *
    intel_batchbuffer_alloc (drm_intel_bufmgr *bufmgr,
                             uint32_t devid);

Allocates a new batchbuffer object. `devid` must be supplied since libdrm doesn't expose it directly.

#### Parameters

bufmgr | libdrm buffer manager |
devid | pci device id of the drm device |

#### Returns

The allocated and initialized batchbuffer object.

### intel_batchbuffer_set_context ()

    void
    intel_batchbuffer_set_context (struct intel_batchbuffer *batch,
                                   drm_intel_context *ctx);

### intel_batchbuffer_free ()

    void
    intel_batchbuffer_free (struct intel_batchbuffer *batch);

Releases all resource of the batchbuffer object `batch` .

#### Parameters

batch | batchbuffer object |

### intel_batchbuffer_flush ()

    void
    intel_batchbuffer_flush (struct intel_batchbuffer *batch);

Submits the batch for execution on the blitter engine, selecting the right ring depending upon the hardware platform.

#### Parameters

batch | batchbuffer object |

### intel_batchbuffer_flush_on_ring ()

    void
    intel_batchbuffer_flush_on_ring (struct intel_batchbuffer *batch,
                                     int ring);

Submits the batch for execution on `ring` .

#### Parameters

batch | batchbuffer object |
ring | execbuf ring flag |

### intel_batchbuffer_flush_with_context ()

    void
    intel_batchbuffer_flush_with_context (struct intel_batchbuffer *batch,
                                          drm_intel_context *context);

Submits the batch for execution on the render engine with the supplied hardware context.

#### Parameters

batch | batchbuffer object |
context | libdrm hardware context object |

### intel_batchbuffer_reset ()

    void
    intel_batchbuffer_reset (struct intel_batchbuffer *batch);

Resets `batch` by allocating a new gem buffer object as backing storage.

#### Parameters

batch | batchbuffer object |

### intel_batchbuffer_data ()

    void
    intel_batchbuffer_data (struct intel_batchbuffer *batch,
                            const void *data,
                            unsigned int bytes);

This transfers the given `data` into the batchbuffer. Note that the length must be DWORD aligned, i.e. multiples of 32bits.

#### Parameters

batch | batchbuffer object |
data | pointer to the data to write into the batchbuffer |
bytes | number of bytes to write into the batchbuffer |

### intel_batchbuffer_emit_reloc ()

    void
    intel_batchbuffer_emit_reloc (struct intel_batchbuffer *batch,
                                  drm_intel_bo *buffer,
                                  uint64_t delta,
                                  uint32_t read_domains,
                                  uint32_t write_domain,
                                  int fenced);

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.

#### Parameters

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 |

### intel_batchbuffer_space ()

    unsigned int
    intel_batchbuffer_space (struct intel_batchbuffer *batch);

### intel_batchbuffer_emit_dword ()

    void
    intel_batchbuffer_emit_dword (struct intel_batchbuffer *batch,
                                  uint32_t dword);

### intel_batchbuffer_require_space ()

    void
    intel_batchbuffer_require_space (struct intel_batchbuffer *batch,
                                     unsigned int sz);

### BEGIN_BATCH()

    #define             BEGIN_BATCH(n, r)

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.

#### Parameters

n | number of DWORDS to emit |
r | number of RELOCS to emit |

### OUT_BATCH()

    #define OUT_BATCH(d) intel_batchbuffer_emit_dword(batch, d)

Emits `d` into a batch.

This macro needs a pointer to an intel_batchbuffer structure called batch in scope.

#### Parameters

d | DWORD to emit |

### OUT_RELOC_FENCED()

    #define             OUT_RELOC_FENCED(buf, read_domains, write_domain, delta)

Emits a fenced relocation into a batch.

This macro needs a pointer to an intel_batchbuffer structure called batch in scope.

#### Parameters

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 |

### OUT_RELOC()

    #define             OUT_RELOC(buf, read_domains, write_domain, delta)

Emits a normal, unfenced relocation into a batch.

This macro needs a pointer to an intel_batchbuffer structure called batch in scope.

#### Parameters

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 |

### ADVANCE_BATCH

    #define             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.

### BLIT_COPY_BATCH_START()

    #define             BLIT_COPY_BATCH_START(flags)

### COLOR_BLIT_COPY_BATCH_START()

    #define             COLOR_BLIT_COPY_BATCH_START(flags)

### intel_blt_copy ()

    void
    intel_blt_copy (struct intel_batchbuffer *batch,
                    drm_intel_bo *src_bo,
                    int src_x1,
                    int src_y1,
                    int src_pitch,
                    drm_intel_bo *dst_bo,
                    int dst_x1,
                    int dst_y1,
                    int dst_pitch,
                    int width,
                    int height,
                    int bpp);

This emits a 2D copy operation using blitter commands into the supplied batch buffer object.

#### Parameters

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 | 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 |
bpp | bits per pixel |

### intel_copy_bo ()

    void
    intel_copy_bo (struct intel_batchbuffer *batch,
                   drm_intel_bo *dst_bo,
                   drm_intel_bo *src_bo,
                   long int size);

This emits a copy operation using blitter commands into the supplied batch buffer object. A total of `size` bytes from the start of `src_bo` is copied over to `dst_bo` . Note that `size` must be page-aligned.

#### Parameters

batch | batchbuffer object |
src_bo | source libdrm buffer object |
dst_bo | destination libdrm buffer object |
size | size of the copy range in bytes |

### igt_buf_width ()

    unsigned
    igt_buf_width (struct igt_buf *buf);

Computes the widht in 32-bit pixels of the given buffer.

#### Parameters

buf | the i-g-t buffer object |

#### Returns

The width of the buffer.

### igt_buf_height ()

    unsigned
    igt_buf_height (struct igt_buf *buf);

Computes the height in 32-bit pixels of the given buffer.

#### Parameters

buf | the i-g-t buffer object |

#### Returns

The height of the buffer.

### igt_render_copyfunc_t ()

    void
    (*igt_render_copyfunc_t) (struct intel_batchbuffer *batch,
                              drm_intel_context *context,
                              struct igt_buf *src,
                              unsigned  src_x,
                              unsigned  src_y,
                              unsigned  width,
                              unsigned  height,
                              struct igt_buf *dst,
                              unsigned  dst_x,
                              unsigned  dst_y);

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.

#### Parameters

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 |

### igt_get_render_copyfunc ()

    igt_render_copyfunc_t
    igt_get_render_copyfunc (int devid);

#### Parameters

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_fillfunc_t ()

    void
    (*igt_fillfunc_t) (struct intel_batchbuffer *batch,
                       struct igt_buf *dst,
                       unsigned  x,
                       unsigned  y,
                       unsigned  width,
                       unsigned  height,
                       uint8_t color);

This is the type of the per-platform fill functions using media or gpgpu pipeline. The platform-specific implementation can be obtained by calling `igt_get_media_fillfunc()` or `igt_get_gpgpu_fillfunc()`.

A fill function will emit a batchbuffer to the kernel which executes the specified blit fill operation using the media/gpgpu engine.

#### Parameters

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 |

### igt_get_media_fillfunc ()

    igt_fillfunc_t
    igt_get_media_fillfunc (int devid);

#### Parameters

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_get_gpgpu_fillfunc ()

    igt_fillfunc_t
    igt_get_gpgpu_fillfunc (int devid);

#### Parameters

devid | pci device id |

#### Returns

The platform-specific gpgpu fill function pointer for the device specified with `devid` . Will return NULL when no gpgpu fill function is implemented.

## Types and Values

### BATCH_SZ

    #define BATCH_SZ 4096

### BATCH_RESERVED

    #define BATCH_RESERVED 16

### struct intel_batchbuffer

    struct intel_batchbuffer {
    	drm_intel_bufmgr *bufmgr;
    	uint32_t devid;
    	int gen;

    	drm_intel_context *ctx;
    	drm_intel_bo *bo;

    	uint8_t buffer[BATCH_SZ];
    	uint8_t *ptr, *end;
    	uint8_t *state;
    };

### struct igt_buf

    struct igt_buf {
        drm_intel_bo *bo;
        uint32_t stride;
        uint32_t tiling;
        uint32_t *data;
        uint32_t size;
    };

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 fill functions.

#### Members

drm_intel_bo *`bo`; | underlying libdrm buffer object |
uint32_t `stride`; | stride of the buffer |
uint32_t `tiling`; | tiling mode bits |
uint32_t *`data`; | pointer to the memory mapping of the buffer |
uint32_t `size`; | size of the buffer object |