Blitter library

Blitter library — i915/xe blitter library

Functions

Types and Values

Includes

#include <intel_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_command ()

bool
blt_supports_command (const struct intel_cmds_info *cmds_info,
                      enum blt_cmd_type cmd);

Checks if cmds_info has an entry of supported tiling formats for cmd command.

Parameters

cmds_info

Copy commands description struct

 

cmd

Blitter command enum

 

Returns

true if it does, false otherwise


blt_cmd_supports_tiling ()

bool
blt_cmd_supports_tiling (const struct intel_cmds_info *cmds_info,
                         enum blt_cmd_type cmd,
                         enum blt_tiling_type tiling);

Checks if a cmd entry of cmds_info lists tiling . It also returns false if no information about the command is stored.

Parameters

cmds_info

Copy commands description struct

 

cmd

Blitter command enum

 

tiling

tiling format enum

 

Returns

true if it does, false otherwise


blt_cmd_has_property ()

bool
blt_cmd_has_property (const struct intel_cmds_info *cmds_info,
                      enum blt_cmd_type cmd,
                      uint32_t prop);

Checks if a cmd entry of cmds_info has prop property. The properties can be freely combined, but the function will return true for platforms for which all properties defined in the bit flag are present. The function returns false if no information about the command is stored.

Parameters

cmds_info

Copy commands description struct

 

cmd

Blitter command enum

 

prop

property flag

 

Returns

true if it does, false otherwise


blt_has_block_copy ()

bool
blt_has_block_copy (int fd);

Check if block copy is supported by fd device

Parameters

fd

drm fd

 

Returns

true if it does, false otherwise.


blt_has_fast_copy ()

bool
blt_has_fast_copy (int fd);

Check if fast copy is supported by fd device

Parameters

fd

drm fd

 

Returns

true if it does, false otherwise.


blt_has_xy_src_copy ()

bool
blt_has_xy_src_copy (int fd);

Check if XY src copy is supported by fd device

Parameters

fd

drm fd

 

Returns

true if it does, false otherwise.


blt_has_xy_color ()

bool
blt_has_xy_color (int fd);

Check if XY_COLOR_BLT is supported by fd device

Parameters

fd

drm fd

 

Returns

true if it does, false otherwise.


blt_fast_copy_supports_tiling ()

bool
blt_fast_copy_supports_tiling (int fd,
                               enum blt_tiling_type tiling);

Check if fast copy provided by fd device supports tiling format

Parameters

fd

drm fd

 

tiling

tiling format

 

Returns

true if it does, false otherwise.


blt_block_copy_supports_tiling ()

bool
blt_block_copy_supports_tiling (int fd,
                                enum blt_tiling_type tiling);

Check if block copy provided by fd device supports tiling format

Parameters

fd

drm fd

 

tiling

tiling format

 

Returns

true if it does, false otherwise.


blt_xy_src_copy_supports_tiling ()

bool
blt_xy_src_copy_supports_tiling (int fd,
                                 enum blt_tiling_type tiling);

Check if XY src copy provided by fd device supports tiling format

Parameters

fd

drm fd

 

tiling

tiling format

 

Returns

true if it does, false otherwise.


blt_block_copy_supports_compression ()

bool
blt_block_copy_supports_compression (int fd);

Check if block copy provided by fd device supports compression.

Parameters

fd

drm fd

 

Returns

true if it does, false otherwise.


blt_uses_extended_block_copy ()

bool
blt_uses_extended_block_copy (int fd);

Check if block copy provided by fd device uses an extended version of the command.

Parameters

fd

drm fd

 

Returns

true if it does, false otherwise.


blt_tiling_name ()

const char *
blt_tiling_name (enum blt_tiling_type tiling);

Parameters

tiling

tiling id

 

Returns

name of tiling passed. Useful to build test names.


blt_copy_init ()

void
blt_copy_init (int fd,
               struct blt_copy_data *blt);

Function is zeroing blt and sets fd and driver fields (INTEL_DRIVER_I915 or INTEL_DRIVER_XE).

Parameters

fd

drm fd

 

blt

structure for initialization

 

emit_blt_block_copy ()

uint64_t
emit_blt_block_copy (int fd,
                     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

fd

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 fd,
                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

fd

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 fd,
                         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

fd

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

void
blt_ctrl_surf_copy_init (int fd,
                         struct blt_ctrl_surf_copy_data *surf);

Function is zeroing surf and sets fd and driver fields (INTEL_DRIVER_I915 or INTEL_DRIVER_XE).

Parameters

fd

drm fd

 

surf

structure for initialization

 

blt_ctrl_surf_copy ()

int
blt_ctrl_surf_copy (int fd,
                    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

fd

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 fd,
                    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

fd

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 fd,
               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

fd

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

void
blt_set_geom (struct blt_copy_object *obj,
              uint32_t pitch,
              int16_t x1,
              int16_t y1,
              int16_t x2,
              int16_t y2,
              uint16_t x_offset,
              uint16_t y_offset);

blt_set_batch ()

void
blt_set_batch (struct blt_copy_batch *batch,
               uint32_t handle,
               uint64_t size,
               uint32_t region);

blt_create_object ()

struct blt_copy_object *
blt_create_object (const struct blt_copy_data *blt,
                   uint32_t region,
                   uint32_t width,
                   uint32_t height,
                   uint32_t bpp,
                   uint8_t mocs,
                   enum blt_tiling_type tiling,
                   enum blt_compression compression,
                   enum blt_compression_type compression_type,
                   bool create_mapping);

blt_destroy_object ()

void
blt_destroy_object (int fd,
                    struct blt_copy_object *obj);

blt_set_object ()

void
blt_set_object (struct blt_copy_object *obj,
                uint32_t handle,
                uint64_t size,
                uint32_t region,
                uint8_t mocs,
                enum blt_tiling_type tiling,
                enum blt_compression compression,
                enum blt_compression_type compression_type);

blt_set_object_ext ()

void
blt_set_object_ext (struct blt_block_copy_object_ext *obj,
                    uint8_t compression_format,
                    uint16_t surface_width,
                    uint16_t surface_height,
                    enum blt_surface_type surface_type);

blt_set_copy_object ()

void
blt_set_copy_object (struct blt_copy_object *obj,
                     const struct blt_copy_object *orig);

blt_set_ctrl_surf_object ()

void
blt_set_ctrl_surf_object (struct blt_ctrl_surf_copy_object *obj,
                          uint32_t handle,
                          uint32_t region,
                          uint64_t size,
                          uint8_t mocs,
                          enum blt_access_type access_type);

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 fd,
                       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

fd

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 fd,
                    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

fd

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

 

blt_dump_corruption_info_32b ()

void
blt_dump_corruption_info_32b (const struct blt_copy_object *surf1,
                              const struct blt_copy_object *surf2);

Function dumps ascii representation of the surfaces corruption. Comparison is performed on 8x8 32bpp color pixel blocks. Number of differences on such block varies from 0 (no corruption) to 64 (pixels on those surfaces differs). It is added then to '0' ascii character to point the corruption occurred, for non affected block '.' is printed out.

Idea of this function is to determine character of the differences between two surfaces without generating difference image.

Currently function assumes both surf1 and surf2 are 32-bit color surfaces.

Parameters

surf1

first surface

 

surf2

second surface

 

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_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_type 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;

	/* enable to use multiplane framebuffers */
	uint32_t plane_offset;
};

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 fd;
	enum intel_driver driver;
	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

BLT_INDIRECT_ACCESS

   

BLT_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 fd;
	enum intel_driver driver;
	struct blt_ctrl_surf_copy_object src;
	struct blt_ctrl_surf_copy_object dst;
	struct blt_copy_batch bb;

	/* debug stuff */
	bool print_bb;
};