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

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.

CCS_RATIO()

#define CCS_RATIO(fd) (intel_gen(intel_get_drm_devid(fd)) >= 20 ? 512 : 256)

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.

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.

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.

blt_has_block_copy ()

bool
blt_has_block_copy (int fd);

Check if block copy is supported by fd device

blt_has_mem_copy ()

bool
blt_has_mem_copy (int fd);

Check if mem copy is supported by fd device

blt_has_mem_set ()

bool
blt_has_mem_set (int fd);

Check if mem set is supported by fd device

blt_has_fast_copy ()

bool
blt_has_fast_copy (int fd);

Check if fast copy is supported by fd device

blt_has_xy_src_copy ()

bool
blt_has_xy_src_copy (int fd);

Check if XY src copy is supported by fd device

blt_has_xy_color ()

bool
blt_has_xy_color (int fd);

Check if XY_COLOR_BLT is supported by fd device

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

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

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

blt_block_copy_supports_compression ()

bool
blt_block_copy_supports_compression (int fd);

Check if block copy provided by fd device supports compression.

blt_platform_has_flat_ccs_enabled ()

bool
blt_platform_has_flat_ccs_enabled (int fd);

Check if platform provided by fd device has flat-ccs enabled.

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.

render_supports_tiling ()

bool
render_supports_tiling (int fd,
                        enum blt_tiling_type tiling,
                        bool compression);

Check if render provided by fd device supports tiling format wrt compression

blt_tiling_name ()

const char *
blt_tiling_name (enum blt_tiling_type tiling);

blt_tile_to_i915_tile ()

int
blt_tile_to_i915_tile (enum blt_tiling_type tiling);

i915_tile_to_blt_tile ()

enum blt_tiling_type
i915_tile_to_blt_tile (uint32_t tiling);

blt_get_min_stride ()

uint32_t
blt_get_min_stride (uint32_t width,
                    uint32_t bpp,
                    enum blt_tiling_type tiling);

Function calculates minimum posibble stride in bytes for width, bpp and tiling.

blt_get_aligned_height ()

uint32_t
blt_get_aligned_height (uint32_t height,
                        uint32_t bpp,
                        enum blt_tiling_type tiling);

Function returns aligned height for specific tiling. Height returned is important from memory allocation perspective, because each tiling has specific memory constraints.

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).

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.

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.

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.

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).

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.

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.

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.

blt_mem_init ()

void
blt_mem_init (int fd,
              struct blt_mem_data *mem);

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

blt_mem_copy ()

int
blt_mem_copy (int fd,
              const intel_ctx_t *ctx,
              const struct intel_execution_engine2 *e,
              uint64_t ahnd,
              const struct blt_mem_data *mem);

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

blt_mem_set ()

int
blt_mem_set (int fd,
             const intel_ctx_t *ctx,
             const struct intel_execution_engine2 *e,
             uint64_t ahnd,
             const struct blt_mem_data *mem,
             uint8_t fill_data);

Function does mem set blit in described blt object.

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_index,
                   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_destroy_object_and_alloc_free ()

void
blt_destroy_object_and_alloc_free (int fd,
                                   uint64_t ahnd,
                                   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_index,
                uint8_t pat_index,
                enum blt_tiling_type tiling,
                enum blt_compression compression,
                enum blt_compression_type compression_type);

blt_set_mem_object ()

void
blt_set_mem_object (struct blt_mem_object *obj,
                    uint32_t handle,
                    uint64_t size,
                    uint32_t pitch,
                    uint32_t width,
                    uint32_t height,
                    uint32_t region,
                    uint8_t mocs_index,
                    uint8_t pat_index,
                    enum blt_memop_type type,
                    enum blt_compression compression);

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_index,
                          uint8_t pat_index,
                          enum blt_access_type access_type);

blt_surface_get_flatccs_data ()

void
blt_surface_get_flatccs_data (int fd,
                              intel_ctx_t *ctx,
                              const struct intel_execution_engine2 *e,
                              uint64_t ahnd,
                              const struct blt_copy_object *obj,
                              uint32_t **ccsptr,
                              uint64_t *sizeptr);

Function executes ctrl-surf-copy to extract object ccs data from flatccs area. Memory for the result ccs data are allocated in the function and must be freed by the caller.

blt_surface_is_compressed ()

bool
blt_surface_is_compressed (int fd,
                           intel_ctx_t *ctx,
                           const struct intel_execution_engine2 *e,
                           uint64_t ahnd,
                           const struct blt_copy_object *obj);

Function extracts object ccs data and check it contains any non-zero value what means surface is compressed. Returns true if it is, otherwise false.

blt_surface_info ()

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

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).

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,
                    uint32_t bpp);

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

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.

enum blt_color_depth

enum blt_compression

enum blt_compression_type

struct blt_copy_object

struct blt_copy_object {
	uint32_t handle;
	uint32_t region;
	uint64_t size;
	uint8_t mocs_index;
	uint8_t pat_index;
	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_mem_object

struct blt_mem_object {
	uint32_t handle;
	uint32_t region;
	uint64_t size;
	uint8_t mocs_index;
	uint8_t pat_index;
	enum blt_memop_type type;
	enum blt_compression compression;
	uint32_t width;
	uint32_t height;
	uint32_t pitch;
	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 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;
};

struct blt_mem_data

struct blt_mem_data {
	int fd;
	enum intel_driver driver;
	struct blt_mem_object src;
	struct blt_mem_object dst;
	struct blt_copy_batch bb;
};

enum blt_surface_type

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

struct blt_ctrl_surf_copy_object

struct blt_ctrl_surf_copy_object {
	uint32_t handle;
	uint32_t region;
	uint64_t size;
	uint8_t mocs_index;
	uint8_t pat_index;
	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;
};