ioctl wrappers

ioctl wrappers — ioctl wrappers and related functions

Functions

Types and Values

Includes

#include <igt.h>

Description

This helper library contains simple functions to wrap the raw drm/i915 kernel ioctls. The normal versions never pass any error codes to the caller and use igt_assert() to check for error conditions instead. For some ioctls raw wrappers which do pass on error codes are available. These raw wrappers have a __ prefix.

For wrappers which check for feature bits there can also be two versions: The normal one simply returns a boolean to the caller. But when skipping the testcase entirely is the right action then it's better to use igt_skip() directly in the wrapper. Such functions have _require_ in their name to distinguish them.

Functions

int ()

__thread
int ();

gem_get_tiling ()

bool
gem_get_tiling (int fd,
                uint32_t handle,
                uint32_t *tiling,
                uint32_t *swizzle);

This wraps the GET_TILING ioctl.

Returns whether the actual physical tiling matches the reported tiling.

Parameters

fd

open i915 drm file descriptor

 

handle

gem buffer object handle

 

tiling

(out) tiling mode of the gem buffer

 

swizzle

(out) bit 6 swizzle mode

 

gem_set_tiling ()

void
gem_set_tiling (int fd,
                uint32_t handle,
                uint32_t tiling,
                uint32_t stride);

This wraps the SET_TILING ioctl.

Parameters

fd

open i915 drm file descriptor

 

handle

gem buffer object handle

 

tiling

tiling mode bits

 

stride

stride of the buffer when using a tiled mode, otherwise must be 0

 

gem_set_caching ()

void
gem_set_caching (int fd,
                 uint32_t handle,
                 uint32_t caching);

This wraps the SET_CACHING ioctl. Note that this function internally calls igt_require() when SET_CACHING isn't available, hence automatically skips the test. Therefore always extract test logic which uses this into its own subtest.

Parameters

fd

open i915 drm file descriptor

 

handle

gem buffer object handle

 

caching

caching mode bits

 

gem_get_caching ()

uint32_t
gem_get_caching (int fd,
                 uint32_t handle);

This wraps the GET_CACHING ioctl.

Parameters

fd

open i915 drm file descriptor

 

handle

gem buffer object handle

 

Returns

The current caching mode bits.


gem_flink ()

uint32_t
gem_flink (int fd,
           uint32_t handle);

This wraps the GEM_FLINK ioctl, which is used to export a gem buffer object into the device-global flink namespace. See gem_open() for opening such a buffer name on a different i915 drm file descriptor.

Parameters

fd

open i915 drm file descriptor

 

handle

file-private gem buffer object handle

 

Returns

The created flink buffer name.


gem_open ()

uint32_t
gem_open (int fd,
          uint32_t name);

This wraps the GEM_OPEN ioctl, which is used to import an flink name.

Parameters

fd

open i915 drm file descriptor

 

name

flink buffer name

 

Returns

gem file-private buffer handle of the open object.


gem_close ()

void
gem_close (int fd,
           uint32_t handle);

This wraps the GEM_CLOSE ioctl, which to release a file-private gem buffer handle.

Parameters

fd

open i915 drm file descriptor

 

handle

gem buffer object handle

 

gem_write ()

void
gem_write (int fd,
           uint32_t handle,
           uint64_t offset,
           const void *buf,
           uint64_t length);

Method to write to a gem object. Uses the PWRITE ioctl when it is available, else it uses mmap + memcpy to upload linear data to a subrange of a gem buffer object.

Parameters

fd

open i915 drm file descriptor

 

handle

gem buffer object handle

 

offset

offset within the buffer of the subrange

 

buf

pointer to the data to write into the buffer

 

length

size of the subrange

 

gem_read ()

void
gem_read (int fd,
          uint32_t handle,
          uint64_t offset,
          void *buf,
          uint64_t length);

Method to read from a gem object. Uses the PREAD ioctl when it is available, else it uses mmap + memcpy to download linear data from a subrange of a gem buffer object.

Parameters

fd

open i915 drm file descriptor

 

handle

gem buffer object handle

 

offset

offset within the buffer of the subrange

 

buf

pointer to the data to read into

 

length

size of the subrange

 

gem_has_pwrite ()

bool
gem_has_pwrite (int fd);

Feature test macro to query whether pwrite ioctl is supported

Parameters

fd

open i915 drm file descriptor

 

gem_has_pread ()

bool
gem_has_pread (int fd);

Feature test macro to query whether pread ioctl is supported

Parameters

fd

open i915 drm file descriptor

 

gem_require_pread_pwrite ()

void
gem_require_pread_pwrite (int fd);

Feature test macro to query whether pread/pwrite ioctls are supported and skip if they are not

Parameters

fd

open i915 drm file descriptor

 

gem_set_domain ()

void
gem_set_domain (int fd,
                uint32_t handle,
                uint32_t read,
                uint32_t write);

This wraps the SET_DOMAIN ioctl, which is used to control the coherency of the gem buffer object between the cpu and gtt mappings. It is also use to synchronize with outstanding rendering in general, but for that use-case please have a look at gem_sync().

Parameters

fd

open i915 drm file descriptor

 

handle

gem buffer object handle

 

read

gem domain bits for read access

 

write

gem domain bit for write access

 

gem_wait ()

int
gem_wait (int fd,
          uint32_t handle,
          int64_t *timeout_ns);

gem_sync ()

void
gem_sync (int fd,
          uint32_t handle);

This functions waits for outstanding rendering to complete.

Parameters

fd

open i915 drm file descriptor

 

handle

gem buffer object handle

 

gem_buffer_create_fb_obj ()

uint32_t
gem_buffer_create_fb_obj (int fd,
                          uint64_t size);

This wraps the GEM_CREATE ioctl, which allocates a new gem buffer object of size from file descriptor specific region

Parameters

fd

open i915 drm file descriptor

 

size

desired size of the buffer

 

Returns

The file-private handle of the created buffer object


gem_execbuf_wr ()

void
gem_execbuf_wr (int fd,
                struct drm_i915_gem_execbuffer2 *execbuf);

This wraps the EXECBUFFER2_WR ioctl, which submits a batchbuffer for the gpu to run.

Parameters

fd

open i915 drm file descriptor

 

execbuf

execbuffer data structure

 

gem_execbuf ()

void
gem_execbuf (int fd,
             struct drm_i915_gem_execbuffer2 *execbuf);

This wraps the EXECBUFFER2 ioctl, which submits a batchbuffer for the gpu to run.

Parameters

fd

open i915 drm file descriptor

 

execbuf

execbuffer data structure

 

gem_madvise ()

int
gem_madvise (int fd,
             uint32_t handle,
             int state);

This wraps the MADVISE ioctl, which is used in libdrm to implement opportunistic buffer object caching. Objects in the cache are set to DONTNEED (internally in the kernel tracked as purgeable objects). When such a cached object is in need again it must be set back to WILLNEED before first use.

Parameters

fd

open i915 drm file descriptor

 

handle

gem buffer object handle

 

state

desired madvise state

 

Returns

When setting the madvise state to WILLNEED this returns whether the backing storage was still available or not.


gem_userptr ()

void
gem_userptr (int fd,
             void *ptr,
             uint64_t size,
             int read_only,
             uint32_t flags,
             uint32_t *handle);

Returns userptr handle for the GEM object.

Parameters

fd

open i915 drm file descriptor

 

ptr

userptr pointer to be passed

 

size

desired size of the buffer

 

read_only

specify whether userptr is opened read only

 

flags

other userptr flags

 

handle

returned handle for the object

 

gem_sw_finish ()

void
gem_sw_finish (int fd,
               uint32_t handle);

This wraps the SW_FINISH ioctl, which is used to flush out frontbuffer rendering done through the direct cpu memory mappings. Shipping userspace does _not_ call this after frontbuffer rendering through gtt memory mappings.

Parameters

fd

open i915 drm file descriptor

 

handle

gem buffer object handle

 

gem_bo_busy ()

bool
gem_bo_busy (int fd,
             uint32_t handle);

This wraps the BUSY ioctl, which tells whether a buffer object is still actively used by the gpu in a execbuffer.

Parameters

fd

open i915 drm file descriptor

 

handle

gem buffer object handle

 

Returns

The busy state of the buffer object.


gem_has_llc ()

bool
gem_has_llc (int fd);

gem_has_bsd ()

bool
gem_has_bsd (int fd);

Feature test macro to query whether the BSD ring is available.

Note that recent Bspec calls this the VCS ring for Video Command Submission.

Parameters

fd

open i915 drm file descriptor

 

Returns

Whether the BSD ring is available or not.


gem_has_blt ()

bool
gem_has_blt (int fd);

Feature test macro to query whether the blitter ring is available.

Note that recent Bspec calls this the BCS ring for Blitter Command Submission.

Parameters

fd

open i915 drm file descriptor

 

Returns

Whether the blitter ring is available or not.


gem_has_vebox ()

bool
gem_has_vebox (int fd);

Feature test macro to query whether the vebox ring is available.

Note that recent Bspec calls this the VECS ring for Video Enhancement Command Submission.

Parameters

fd

open i915 drm file descriptor

 

Returns

Whether the vebox ring is available or not.


gem_has_bsd2 ()

bool
gem_has_bsd2 (int fd);

Feature test macro to query whether the BSD2 ring is available.

Note that recent Bspec calls this the VCS ring for Video Command Submission.

Parameters

fd

open i915 drm file descriptor

 

Returns

Whether the BSD ring is avaible or not.


gem_uses_ppgtt ()

bool
gem_uses_ppgtt (int fd);

Feature test macro to check whether the kernel internally uses ppgtt to execute batches. Note that this is also true when we're using full ppgtt.

Parameters

fd

open i915 drm file descriptor

 

Returns

Whether batches are run through ppgtt.


gem_uses_full_ppgtt ()

bool
gem_uses_full_ppgtt (int fd);

Feature test macro to check whether the kernel internally uses full per-process gtt to execute batches. Note that this is also true when we're using full 64b ppgtt.

Parameters

fd

open i915 drm file descriptor

 

Returns

Whether batches are run through full ppgtt.


gem_gpu_reset_type ()

int
gem_gpu_reset_type (int fd);

Query whether reset-engine (2), global-reset (1) or reset-disable (0) is available.

Parameters

fd

open i915 drm file descriptor

 

Returns

GPU reset type available


gem_gpu_reset_enabled ()

bool
gem_gpu_reset_enabled (int fd);

Feature test macro to check whether the kernel internally uses hangchecks and can reset the GPU upon hang detection. Note that this is also true when reset-engine (the lightweight, single engine reset) is available.

Parameters

fd

open i915 drm file descriptor

 

Returns

Whether the driver will detect hangs and perform a reset.


gem_engine_reset_enabled ()

bool
gem_engine_reset_enabled (int fd);

Feature test macro to check whether the kernel internally uses hangchecks and can reset individual engines upon hang detection.

Parameters

fd

open i915 drm file descriptor

 

Returns

Whether the driver will detect hangs and perform an engine reset.


gem_total_stolen_size ()

uint64_t
gem_total_stolen_size (int fd);

gem_has_softpin ()

bool
gem_has_softpin (int fd);

Feature test macro to query whether the softpinning functionality is supported.

Parameters

fd

open i915 drm file descriptor

 

Returns

Whether softpin support is available


gem_has_exec_fence ()

bool
gem_has_exec_fence (int fd);

Feature test macro to query whether in/out fence support in execbuffer is available.

Parameters

fd

open i915 drm file descriptor

 

Returns

Whether fence support is available


gem_require_caching ()

void
gem_require_caching (int fd);

Feature test macro to query whether buffer object caching control is available. Automatically skips through igt_require() if not.

Parameters

fd

open i915 drm file descriptor

 

gem_require_ring ()

void
gem_require_ring (int fd,
                  unsigned  ring);

Feature test macro to query whether a specific ring is available. This automagically skips if the ring isn't available by calling igt_require().

Parameters

fd

open i915 drm file descriptor

 

ring

ring flag bit as used in gem_execbuf()

 

gem_has_mocs_registers ()

bool
gem_has_mocs_registers (int fd);

Feature test macro to query whether the device has MOCS registers. These exist gen 9+.

Parameters

fd

open i915 drm file descriptor

 

gem_require_mocs_registers ()

void
gem_require_mocs_registers (int fd);

Feature test macro to query whether the device has MOCS registers. These exist gen 9+.

Parameters

fd

open i915 drm file descriptor

 

gem_has_ring()

#define gem_has_ring(f, r) gem_context_has_engine(f, 0, r)

prime_handle_to_fd ()

int
prime_handle_to_fd (int fd,
                    uint32_t handle);

This wraps the PRIME_HANDLE_TO_FD ioctl, which is used to export a gem buffer object into a global (i.e. potentially cross-device) dma-buf file-descriptor handle.

Parameters

fd

open i915 drm file descriptor

 

handle

file-private gem buffer object handle

 

Returns

The created dma-buf fd handle.


prime_handle_to_fd_for_mmap ()

int
prime_handle_to_fd_for_mmap (int fd,
                             uint32_t handle);

Same as prime_handle_to_fd above but with DRM_RDWR capabilities, which can be useful for writing into the mmap'ed dma-buf file-descriptor.

Parameters

fd

open i915 drm file descriptor

 

handle

file-private gem buffer object handle

 

Returns

The created dma-buf fd handle or -1 if the ioctl fails.


prime_fd_to_handle ()

uint32_t
prime_fd_to_handle (int fd,
                    int dma_buf_fd);

This wraps the PRIME_FD_TO_HANDLE ioctl, which is used to import a dma-buf file-descriptor into a gem buffer object.

Parameters

fd

open i915 drm file descriptor

 

dma_buf_fd

dma-buf fd handle

 

Returns

The created gem buffer object handle.


prime_get_size ()

off_t
prime_get_size (int dma_buf_fd);

This wraps the lseek() protocol used to query the invariant size of a dma-buf. Not all kernels support this, which is check with igt_require() and so will result in automagic test skipping.

Parameters

dma_buf_fd

dma-buf fd handle

 

Returns

The lifetime-invariant size of the dma-buf object.


prime_sync_start ()

void
prime_sync_start (int dma_buf_fd,
                  bool write);

Must be called before starting CPU mmap access to a dma-buf.

Parameters

dma_buf_fd

dma-buf fd handle

 

write

read/write or read-only access

 

prime_sync_end ()

void
prime_sync_end (int dma_buf_fd,
                bool write);

Must be called after finishing CPU mmap access to a dma-buf.

Parameters

dma_buf_fd

dma-buf fd handle

 

write

read/write or read-only access

 

igt_has_fb_modifiers ()

bool
igt_has_fb_modifiers (int fd);

igt_require_fb_modifiers ()

void
igt_require_fb_modifiers (int fd);

Requires presence of DRM_CAP_ADDFB2_MODIFIERS.

Parameters

fd

Open DRM file descriptor.

 

igt_has_drm_cap ()

bool
igt_has_drm_cap (int fd,
                 uint64_t capability);

This helper verifies if the passed capability is supported by the kernel

Parameters

fd

Open DRM file descriptor.

 

capability

DRM capability

 

Returns

Whether the capability is supported or not.


igt_has_set_caching ()

bool
igt_has_set_caching (uint32_t devid);

This helper verifies if the passed platform id has support for setting cache.

Parameters

devid

platform id.

 

Returns

Whether the cache setting is supported or not.

Types and Values

I915_GEM_DOMAIN_WC

#define I915_GEM_DOMAIN_WC 0x80

struct local_dma_buf_sync

struct local_dma_buf_sync {
	uint64_t flags;
};

LOCAL_DMA_BUF_SYNC_READ

#define LOCAL_DMA_BUF_SYNC_READ      (1 << 0)

LOCAL_DMA_BUF_SYNC_WRITE

#define LOCAL_DMA_BUF_SYNC_WRITE     (2 << 0)

LOCAL_DMA_BUF_SYNC_RW

#define LOCAL_DMA_BUF_SYNC_RW        (LOCAL_DMA_BUF_SYNC_READ | LOCAL_DMA_BUF_SYNC_WRITE)

LOCAL_DMA_BUF_SYNC_START

#define LOCAL_DMA_BUF_SYNC_START     (0 << 2)

LOCAL_DMA_BUF_SYNC_END

#define LOCAL_DMA_BUF_SYNC_END       (1 << 2)

LOCAL_DMA_BUF_SYNC_VALID_FLAGS_MASK

#define             LOCAL_DMA_BUF_SYNC_VALID_FLAGS_MASK

LOCAL_DMA_BUF_BASE

#define LOCAL_DMA_BUF_BASE 'b'

LOCAL_DMA_BUF_IOCTL_SYNC

#define LOCAL_DMA_BUF_IOCTL_SYNC _IOW(LOCAL_DMA_BUF_BASE, 0, struct local_dma_buf_sync)

DRM_RDWR

#define DRM_RDWR O_RDWR