Blitter library: igt-gpu-tools Reference Manual

## Blitter library Blitter library — i915 blitter library |

## Functions

bool | blt_supports_compression ()
bool | blt_supports_tiling ()
const char * | blt_tiling_name ()
uint64_t | emit_blt_block_copy ()
int | blt_block_copy ()
uint64_t | emit_blt_ctrl_surf_copy ()
int | blt_ctrl_surf_copy ()
uint64_t | emit_blt_fast_copy ()
int | blt_fast_copy ()
void | blt_surface_info ()
void | blt_surface_fill_rect ()
void | blt_surface_to_png ()

## Types and Values

#define | CCS_RATIO
enum | blt_color_depth
enum | blt_tiling
enum | blt_compression
enum | blt_compression_type
struct | blt_copy_object
struct | blt_copy_batch
struct | blt_copy_data
enum | blt_surface_type
struct | blt_block_copy_object_ext
struct | blt_block_copy_data_ext
enum | blt_access_type
struct | blt_ctrl_surf_copy_object
struct | blt_ctrl_surf_copy_data

## Includes

    #include <i915_blt.h>

## Description

### Introduction

Gen12+ blitter commands like XY_BLOCK_COPY_BLT are quite long and if we would like to provide all arguments to function, list would be long, unreadable and error prone to invalid argument placement. Providing objects (structs) seems more reasonable and opens some more opportunities to share some object data across different blitter commands.

Blitter library supports no-reloc (softpin) mode only (apart of TGL there's no relocations enabled) thus ahnd is mandatory. Providing NULL ctx means we use default context with I915_EXEC_BLT as an execution engine.

Library introduces tiling enum which distinguishes tiling formats regardless legacy I915_TILING_... definitions. This allows to control fully what tilings are handled by command and skip/assert ones which are not supported.

### Supported commands

- XY_BLOCK_COPY_BLT - (block-copy) TGL/DG1 + DG2+ (ext version)

- XY_FAST_COPY_BLT - (fast-copy)

- XY_CTRL_SURF_COPY_BLT - (ctrl-surf-copy) DG2+

### Usage details

For block-copy and fast-copy `blt_copy_object` struct is used to collect data about source and destination objects. It contains handle, region, size, etc... which are using for blits. Some fields are not used for fast-copy copy (like compression) and command which use this exclusively is annotated in the comment.

## Functions

### blt_supports_compression ()

    bool
    blt_supports_compression (int i915);

Function checks if HW supports flatccs compression in blitter commands on `i915` device.

#### Parameters

i915 | drm fd |

#### Returns

true if it does, false otherwise.

### blt_supports_tiling ()

    bool
    blt_supports_tiling (int i915,
                         enum blt_tiling tiling);

Function checks if blitter supports `tiling` on `i915` device.

#### Parameters

i915 | drm fd |
tiling | tiling id |

#### Returns

true if it does, false otherwise.

### blt_tiling_name ()

    const char *
    blt_tiling_name (enum blt_tiling tiling);

#### Parameters

tiling | tiling id |

#### Returns

name of `tiling` passed. Useful to build test names.

### emit_blt_block_copy ()

    uint64_t
    emit_blt_block_copy (int i915,
                         uint64_t ahnd,
                         const struct blt_copy_data *blt,
                         const struct blt_block_copy_data_ext *ext,
                         uint64_t bb_pos,
                         bool emit_bbe);

Function inserts block-copy blit into batch at `bb_pos` . Allows concatenating with other commands to achieve pipelining.

#### Parameters

i915 | drm fd |
ahnd | allocator handle |
blt | basic blitter data (for TGL/DG1 which doesn't support ext version) |
ext | extended blitter data (for DG2+, supports flatccs compression) |
bb_pos | position at which insert block copy commands |
emit_bbe | emit MI_BATCH_BUFFER_END after block-copy or not |

#### Returns

Next write position in batch.

### blt_block_copy ()

    int
    blt_block_copy (int i915,
                    const intel_ctx_t *ctx,
                    const struct intel_execution_engine2 *e,
                    uint64_t ahnd,
                    const struct blt_copy_data *blt,
                    const struct blt_block_copy_data_ext *ext);

Function does blit between `src` and `dst` described in `blt` object.

#### Parameters

i915 | drm fd |
ctx | intel_ctx_t context |
e | blitter engine for `ctx` |
ahnd | allocator handle |
blt | basic blitter data (for TGL/DG1 which doesn't support ext version) |
ext | extended blitter data (for DG2+, supports flatccs compression) |

#### Returns

execbuffer status.

### emit_blt_ctrl_surf_copy ()

    uint64_t
    emit_blt_ctrl_surf_copy (int i915,
                             uint64_t ahnd,
                             const struct blt_ctrl_surf_copy_data *surf,
                             uint64_t bb_pos,
                             bool emit_bbe);

Function emits ctrl-surf-copy blit between `src` and `dst` described in `blt` object at `bb_pos` . Allows concatenating with other commands to achieve pipelining.

#### Parameters

i915 | drm fd |
ahnd | allocator handle |
surf | blitter data for ctrl-surf-copy |
bb_pos | position at which insert block copy commands |
emit_bbe | emit MI_BATCH_BUFFER_END after ctrl-surf-copy or not |

#### Returns

Next write position in batch.

### blt_ctrl_surf_copy ()

    int
    blt_ctrl_surf_copy (int i915,
                        const intel_ctx_t *ctx,
                        const struct intel_execution_engine2 *e,
                        uint64_t ahnd,
                        const struct blt_ctrl_surf_copy_data *surf);

Function does ctrl-surf-copy blit between `src` and `dst` described in `blt` object.

#### Parameters

i915 | drm fd |
ctx | intel_ctx_t context |
e | blitter engine for `ctx` |
ahnd | allocator handle |
surf | blitter data for ctrl-surf-copy |

#### Returns

execbuffer status.

### emit_blt_fast_copy ()

    uint64_t
    emit_blt_fast_copy (int i915,
                        uint64_t ahnd,
                        const struct blt_copy_data *blt,
                        uint64_t bb_pos,
                        bool emit_bbe);

Function emits fast-copy blit between `src` and `dst` described in `blt` object at `bb_pos` . Allows concatenating with other commands to achieve pipelining.

#### Parameters

i915 | drm fd |
ahnd | allocator handle |
blt | blitter data for fast-copy (same as for block-copy but doesn't use compression fields). |
bb_pos | position at which insert block copy commands |
emit_bbe | emit MI_BATCH_BUFFER_END after fast-copy or not |

#### Returns

Next write position in batch.

### blt_fast_copy ()

    int
    blt_fast_copy (int i915,
                   const intel_ctx_t *ctx,
                   const struct intel_execution_engine2 *e,
                   uint64_t ahnd,
                   const struct blt_copy_data *blt);

Function does fast blit between `src` and `dst` described in `blt` object.

#### Parameters

i915 | drm fd |
ctx | intel_ctx_t context |
e | blitter engine for `ctx` |
ahnd | allocator handle |
blt | blitter data for fast-copy (same as for block-copy but doesn't use compression fields). |

#### Returns

execbuffer status.

### blt_surface_info ()

    void
    blt_surface_info (const char *info,
                      const struct blt_copy_object *obj);

#### Parameters

info | information header |
obj | blitter copy object (`blt_copy_object` ) to print surface info |

### blt_surface_fill_rect ()

    void
    blt_surface_fill_rect (int i915,
                           const struct blt_copy_object *obj,
                           uint32_t width,
                           uint32_t height);

Function fills surface `width` x `height` * 24bpp with color gradient (internally uses ARGB where A == 0xff, see Cairo docs).

#### Parameters

i915 | drm fd |
obj | blitter copy object (`blt_copy_object` ) to fill with gradient pattern |
width | width |
height | height |

### blt_surface_to_png ()

    void
    blt_surface_to_png (int i915,
                        uint32_t run_id,
                        const char *fileid,
                        const struct blt_copy_object *obj,
                        uint32_t width,
                        uint32_t height);

Function save surface to png file. Assumes ARGB format where A == 0xff.

#### Parameters

i915 | drm fd |
run_id | prefix id to allow grouping files stored from single run |
fileid | file identifier |
obj | blitter copy object (`blt_copy_object` ) to save to png |
width | width |
height | height |

## Types and Values

### CCS_RATIO

    #define CCS_RATIO 256

### enum blt_color_depth

#### Members

CD_8bit |  |
CD_16bit |  |
CD_32bit |  |
CD_64bit |  |
CD_96bit |  |
CD_128bit |  |

### enum blt_tiling

#### Members

T_LINEAR |  |
T_XMAJOR |  |
T_YMAJOR |  |
T_TILE4 |  |
T_TILE64 |  |

### enum blt_compression

#### Members

COMPRESSION_DISABLED |  |
COMPRESSION_ENABLED |  |

### enum blt_compression_type

#### Members

COMPRESSION_TYPE_3D |  |
COMPRESSION_TYPE_MEDIA |  |

### struct blt_copy_object

    struct blt_copy_object {
    	uint32_t handle;
    	uint32_t region;
    	uint64_t size;
    	uint8_t mocs;
    	enum blt_tiling tiling;
    	enum blt_compression compression;  /* BC only */
    	enum blt_compression_type compression_type; /* BC only */
    	uint32_t pitch;
    	uint16_t x_offset, y_offset;
    	int16_t x1, y1, x2, y2;

    	/* mapping or null */
    	uint32_t *ptr;
    };

### struct blt_copy_batch

    struct blt_copy_batch {
    	uint32_t handle;
    	uint32_t region;
    	uint64_t size;
    };

### struct blt_copy_data

    struct blt_copy_data {
    	int i915;
    	struct blt_copy_object src;
    	struct blt_copy_object dst;
    	struct blt_copy_batch bb;
    	enum blt_color_depth color_depth;

    	/* debug stuff */
    	bool print_bb;
    };

### enum blt_surface_type

#### Members

SURFACE_TYPE_1D |  |
SURFACE_TYPE_2D |  |
SURFACE_TYPE_3D |  |
SURFACE_TYPE_CUBE |  |

### struct blt_block_copy_object_ext

    struct blt_block_copy_object_ext {
    	uint8_t compression_format;
    	bool clear_value_enable;
    	uint64_t clear_address;
    	uint16_t surface_width;
    	uint16_t surface_height;
    	enum blt_surface_type surface_type;
    	uint16_t surface_qpitch;
    	uint16_t surface_depth;
    	uint8_t lod;
    	uint8_t horizontal_align;
    	uint8_t vertical_align;
    	uint8_t mip_tail_start_lod;
    	bool depth_stencil_resource;
    	uint16_t array_index;
    };

### struct blt_block_copy_data_ext

    struct blt_block_copy_data_ext {
    	struct blt_block_copy_object_ext src;
    	struct blt_block_copy_object_ext dst;
    };

### enum blt_access_type

#### Members

INDIRECT_ACCESS |  |
DIRECT_ACCESS |  |

### struct blt_ctrl_surf_copy_object

    struct blt_ctrl_surf_copy_object {
    	uint32_t handle;
    	uint32_t region;
    	uint64_t size;
    	uint8_t mocs;
    	enum blt_access_type access_type;
    };

### struct blt_ctrl_surf_copy_data

    struct blt_ctrl_surf_copy_data {
    	int i915;
    	struct blt_ctrl_surf_copy_object src;
    	struct blt_ctrl_surf_copy_object dst;
    	struct blt_copy_batch bb;

    	/* debug stuff */
    	bool print_bb;
    };