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:

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.

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.

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

buf_ops_destroy ()

void
buf_ops_destroy (struct buf_ops *bops);

Function frees buf_ops structure.

buf_ops_get_fd ()

int
buf_ops_get_fd (struct buf_ops *bops);

buf_ops_get_driver ()

enum intel_driver
buf_ops_get_driver (struct buf_ops *bops);

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.

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.

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.

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.

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,
                          uint64_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.

intel_buf_init_full ()

void
intel_buf_init_full (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,
                     uint64_t size,
                     int stride,
                     uint64_t region,
                     uint8_t pat_index,
                     uint8_t mocs_index);

Function configures BO handle within intel_buf structure passed by the caller (with all its metadata - width, height, ...). Useful if BO was created outside. Allows passing real size which caller is aware of.

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

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.

intel_buf_init_using_handle_and_size ()

void
intel_buf_init_using_handle_and_size (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,
                                      uint64_t size);

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.

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

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

intel_buf_create_full ()

struct intel_buf *
intel_buf_create_full (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,
                       uint64_t region,
                       uint8_t pat_index,
                       uint8_t mocs_index);

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.

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

intel_buf_raw_write_to_png ()

void
intel_buf_raw_write_to_png (struct intel_buf *buf,
                            const char *namefmt,
                            ...);

intel_buf_draw_pattern ()

void
intel_buf_draw_pattern (struct buf_ops *bops,
                        struct intel_buf *buf,
                        int x,
                        int y,
                        int w,
                        int h,
                        int cx,
                        int cy,
                        int cw,
                        int ch,
                        bool use_alternate_colors);

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 width;
	uint32_t height;
	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;
	uint64_t region;

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

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

	/* Content Protection*/
	bool is_protected;

	/* pat_index to use for mapping this buf. Only used in Xe. */
	uint8_t pat_index;

	/* mocs_index to use for operations using this intel_buf, like render_copy  */
	uint8_t mocs_index;

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

struct buf_ops

struct buf_ops;