Buffer operations

Buffer operations — Buffer operation on tiled surfaces

Functions

Types and Values

Includes

#include <igt.h>

Description

Buffer operations

Intel GPU devices supports different set of tiled surfaces. Checking each time what tile formats are supports is cumbersome and error prone.

Buffer operation (buf_ops) provide a wrapper to conditional code which can be used without worrying of implementation details giving:

  • copy linear to tiled buffer

  • copy tiled buffer to linear

Following code order should be used (linear is plain memory with some image data):

1
2
3
4
5
6
7
8
9
10
11
12
13
struct buf_ops *bops;
struct intel_buf ibuf;
...
bops = buf_ops_create(fd);
intel_buf_init(bops, &ibuf, 512, 512, 32, 64, I915_TILING_X, false);
...
linear_to_intel_buf(bops, &ibuf, linear);
...
intel_buf_to_linear(bops, &ibuf, linear);
...
intel_buf_close(bops, &ibuf);
...
buf_ops_destroy(bops);

Calling buf_ops_create(fd) probes hardware capabilities (supported fences, swizzling) and returns opaque pointer to buf_ops. From now on intel_buf_to_linear() and linear_to_intel_buf() will choose appropriate function to do the job.

Note: bufops doesn't support SW tiling code yet.

Functions

INVALID_ADDR()

#define INVALID_ADDR(x) ((x) == INTEL_BUF_INVALID_ADDRESS)

intel_buf_ccs_width ()

unsigned int
intel_buf_ccs_width (int gen,
                     const struct intel_buf *buf);

intel_buf_ccs_height ()

unsigned int
intel_buf_ccs_height (int gen,
                      const struct intel_buf *buf);

intel_buf_size ()

uint64_t
intel_buf_size (const struct intel_buf *buf);

intel_buf_bo_size ()

uint64_t
intel_buf_bo_size (const struct intel_buf *buf);

buf_ops_create ()

struct buf_ops *
buf_ops_create (int fd);

Create buf_ops structure depending on fd-device capabilities.

Parameters

fd

device filedescriptor

 

Returns

opaque pointer to buf_ops.


buf_ops_create_with_selftest ()

struct buf_ops *
buf_ops_create_with_selftest (int fd);

Create buf_ops structure depending on fd-device capabilities. Runs with idempotency selftest to verify software tiling gives same result like hardware tiling (gens with mappable gtt).

Parameters

fd

device filedescriptor

 

Returns

opaque pointer to buf_ops.


buf_ops_destroy ()

void
buf_ops_destroy (struct buf_ops *bops);

Function frees buf_ops structure.

Parameters

bops

pointer to buf_ops

 

buf_ops_get_fd ()

int
buf_ops_get_fd (struct buf_ops *bops);

Parameters

bops

pointer to buf_ops

 

Returns

drm fd


buf_ops_set_software_tiling ()

bool
buf_ops_set_software_tiling (struct buf_ops *bops,
                             uint32_t tiling,
                             bool use_software_tiling);

Function allows switch X / Y surfaces to software / hardware copying methods which honors tiling and swizzling.

Parameters

bops

pointer to buf_ops

 

tiling

surface tiling

 

use_software_tiling

if true use software copying methods, otherwise use hardware (via gtt)

 

Returns

false - switch wasn't possible. true - switch to software / hardware method succeed.


intel_buf_to_linear ()

void
intel_buf_to_linear (struct buf_ops *bops,
                     struct intel_buf *buf,
                     uint32_t *linear);

linear_to_intel_buf ()

void
linear_to_intel_buf (struct buf_ops *bops,
                     struct intel_buf *buf,
                     uint32_t *linear);

buf_ops_has_hw_fence ()

bool
buf_ops_has_hw_fence (struct buf_ops *bops,
                      uint32_t tiling);

Function checks if surface with tiling has HW fences which can be used to copy it via gtt.

Parameters

bops

pointer to buf_ops

 

tiling

surface tiling

 

Returns

false - fence for tiling is not supported. true - fence for tiling is supported.


buf_ops_has_tiling_support ()

bool
buf_ops_has_tiling_support (struct buf_ops *bops,
                            uint32_t tiling);

Function checks capabilities to handle surfaces with tiling in GPU.

Parameters

bops

pointer to buf_ops

 

tiling

surface tiling

 

Returns

false - GPU does not support tiling. true - GPU supports tiling.


intel_buf_init ()

void
intel_buf_init (struct buf_ops *bops,
                struct intel_buf *buf,
                int width,
                int height,
                int bpp,
                int alignment,
                uint32_t tiling,
                uint32_t compression);

Function creates new BO within intel_buf structure and fills all structure fields. Takes bo handle ownership.

Note. For X / Y if GPU supports fences HW tiling is configured.

Parameters

bops

pointer to buf_ops

 

buf

pointer to intel_buf structure to be filled

 

width

surface width

 

height

surface height

 

bpp

bits-per-pixel (8 / 16 / 32 / 64)

 

alignment

alignment of the stride for linear surfaces

 

tiling

surface tiling

 

compression

surface compression type

 

intel_buf_init_in_region ()

void
intel_buf_init_in_region (struct buf_ops *bops,
                          struct intel_buf *buf,
                          int width,
                          int height,
                          int bpp,
                          int alignment,
                          uint32_t tiling,
                          uint32_t compression,
                          uint32_t region);

Same as intel_buf_init with the additional region argument


intel_buf_close ()

void
intel_buf_close (struct buf_ops *bops,
                 struct intel_buf *buf);

Function closes gem BO inside intel_buf if bo is owned by intel_buf. For handle passed from the caller intel_buf doesn't take ownership and doesn't close it in close()/destroy() paths. When intel_buf was previously added to intel_bb (intel_bb_add_intel_buf() call) it is tracked there and must be removed from its internal structures.

Parameters

bops

pointer to buf_ops

 

buf

pointer to intel_buf structure

 

intel_buf_init_using_handle ()

void
intel_buf_init_using_handle (struct buf_ops *bops,
                             uint32_t handle,
                             struct intel_buf *buf,
                             int width,
                             int height,
                             int bpp,
                             int alignment,
                             uint32_t req_tiling,
                             uint32_t compression);

Function configures BO handle within intel_buf structure passed by the caller (with all its metadata - width, height, ...). Useful if BO was created outside.

Note: intel_buf_close() can be used because intel_buf is aware it is not buffer owner so it won't close it underneath.

Parameters

bops

pointer to buf_ops

 

handle

BO handle created by the caller

 

buf

pointer to intel_buf structure to be filled

 

width

surface width

 

height

surface height

 

bpp

bits-per-pixel (8 / 16 / 32 / 64)

 

alignment

alignment of the stride for linear surfaces

 

tiling

surface tiling

 

compression

surface compression type

 

intel_buf_create ()

struct intel_buf *
intel_buf_create (struct buf_ops *bops,
                  int width,
                  int height,
                  int bpp,
                  int alignment,
                  uint32_t req_tiling,
                  uint32_t compression);

Function creates intel_buf with created BO handle. Takes ownership of the buffer.

Parameters

bops

pointer to buf_ops

 

width

surface width

 

height

surface height

 

bpp

bits-per-pixel (8 / 16 / 32 / 64)

 

alignment

alignment of the stride for linear surfaces

 

tiling

surface tiling

 

compression

surface compression type

 

intel_buf_create_using_handle ()

struct intel_buf *
intel_buf_create_using_handle (struct buf_ops *bops,
                               uint32_t handle,
                               int width,
                               int height,
                               int bpp,
                               int alignment,
                               uint32_t req_tiling,
                               uint32_t compression);

Function creates intel_buf with passed BO handle from the caller. Doesn't take ownership of the buffer. close()/destroy() paths doesn't close passed handle unless buffer will take ownership using set_ownership().

Parameters

bops

pointer to buf_ops

 

handle

BO handle created by the caller

 

width

surface width

 

height

surface height

 

bpp

bits-per-pixel (8 / 16 / 32 / 64)

 

alignment

alignment of the stride for linear surfaces

 

tiling

surface tiling

 

compression

surface compression type

 

intel_buf_create_using_handle_and_size ()

struct intel_buf *
intel_buf_create_using_handle_and_size
                               (struct buf_ops *bops,
                                uint32_t handle,
                                int width,
                                int height,
                                int bpp,
                                int alignment,
                                uint32_t req_tiling,
                                uint32_t compression,
                                uint64_t size,
                                int stride);

intel_buf_destroy ()

void
intel_buf_destroy (struct intel_buf *buf);

Function frees intel_buf memory. It closes bo handle if intel_buf has buffer ownership.

Parameters

buf

intel_buf

 

intel_buf_cpu_map ()

void *
intel_buf_cpu_map (struct intel_buf *buf,
                   bool write);

intel_buf_device_map ()

void *
intel_buf_device_map (struct intel_buf *buf,
                      bool write);

intel_buf_unmap ()

void
intel_buf_unmap (struct intel_buf *buf);

intel_buf_flush_and_unmap ()

void
intel_buf_flush_and_unmap (struct intel_buf *buf);

intel_buf_print ()

void
intel_buf_print (const struct intel_buf *buf);

intel_buf_dump ()

void
intel_buf_dump (const struct intel_buf *buf,
                const char *filename);

intel_buf_set_name ()

const char *
intel_buf_set_name (struct intel_buf *buf,
                    const char *name);

intel_buf_write_to_png ()

void
intel_buf_write_to_png (struct intel_buf *buf,
                        const char *filename);

intel_buf_write_aux_to_png ()

void
intel_buf_write_aux_to_png (struct intel_buf *buf,
                            const char *filename);

Types and Values

INTEL_BUF_INVALID_ADDRESS

#define INTEL_BUF_INVALID_ADDRESS (-1ull)

INTEL_BUF_NAME_MAXSIZE

#define INTEL_BUF_NAME_MAXSIZE 32

struct intel_buf

struct intel_buf {
	struct buf_ops *bops;

	bool is_owner;
	uint32_t handle;
	uint64_t size;
	uint32_t tiling;
	uint32_t bpp;
	uint32_t compression;
	uint32_t swizzle_mode;
	uint32_t yuv_semiplanar_bpp;
	bool format_is_yuv;
	bool format_is_yuv_semiplanar;
	struct {
		uint32_t offset;
		uint32_t stride;
		uint64_t size;
	} surface[2];
	struct {
		uint32_t offset;
		uint32_t stride;
	} ccs[2];
	struct {
		uint32_t offset;
	} cc;
	struct {
		uint64_t offset;
		uint32_t ctx;
	} addr;

	uint64_t bo_size;

	/* Tracking */
	struct intel_bb *ibb;
	struct igt_list_head link;

	/* CPU mapping */
	uint32_t *ptr;
	bool cpu_write;

	/* Content Protection*/
	bool is_protected;

	/* For debugging purposes */
	char name[INTEL_BUF_NAME_MAXSIZE + 1];
};

struct buf_ops

struct buf_ops;