Buffer operations: igt-gpu-tools Reference Manual

## Buffer operations Buffer operations — Buffer operation on tiled surfaces |

## Functions

#define | INVALID_ADDR()
bool | intel_buf_compressed ()
unsigned int | intel_buf_width ()
unsigned int | intel_buf_height ()
unsigned int | intel_buf_ccs_width ()
unsigned int | intel_buf_ccs_height ()
uint64_t | intel_buf_size ()
uint64_t | intel_buf_bo_size ()
struct buf_ops * | buf_ops_create ()
struct buf_ops * | buf_ops_create_with_selftest ()
void | buf_ops_destroy ()
int | buf_ops_get_fd ()
bool | buf_ops_set_software_tiling ()
void | intel_buf_to_linear ()
void | linear_to_intel_buf ()
bool | buf_ops_has_hw_fence ()
bool | buf_ops_has_tiling_support ()
void | intel_buf_set_ownership ()
void | intel_buf_init ()
void | intel_buf_init_in_region ()
void | intel_buf_close ()
void | intel_buf_init_using_handle ()
struct intel_buf * | intel_buf_create ()
struct intel_buf * | intel_buf_create_using_handle ()
struct intel_buf * | intel_buf_create_using_handle_and_size ()
void | intel_buf_destroy ()
void | intel_buf_set_pxp ()
bool | intel_buf_pxp ()
void * | intel_buf_cpu_map ()
void * | intel_buf_device_map ()
void | intel_buf_unmap ()
void | intel_buf_flush_and_unmap ()
void | intel_buf_print ()
void | intel_buf_dump ()
const char * | intel_buf_set_name ()
void | intel_buf_write_to_png ()
void | intel_buf_write_aux_to_png ()

## Types and Values

#define | INTEL_BUF_INVALID_ADDRESS
#define | INTEL_BUF_NAME_MAXSIZE
struct | intel_buf
struct | buf_ops

## 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_compressed ()

    bool
    intel_buf_compressed (const struct intel_buf *buf);

### intel_buf_width ()

    unsigned int
    intel_buf_width (const struct intel_buf *buf);

### intel_buf_height ()

    unsigned int
    intel_buf_height (const struct intel_buf *buf);

### 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_set_ownership ()

    void
    intel_buf_set_ownership (struct intel_buf *buf,
                             bool is_owner);

### 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_set_pxp ()

    void
    intel_buf_set_pxp (struct intel_buf *buf,
                       bool new_pxp_state);

### intel_buf_pxp ()

    bool
    intel_buf_pxp (const struct intel_buf *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;