ioctl wrappers

ioctl wrappers — ioctl wrappers and related functions

Functions

drm_intel_bo * gem_handle_to_libdrm_bo ()
void gem_get_tiling ()
void gem_set_tiling ()
void gem_set_caching ()
uint32_t gem_get_caching ()
uint32_t gem_flink ()
uint32_t gem_open ()
void gem_close ()
void gem_write ()
void gem_read ()
void gem_set_domain ()
void gem_sync ()
uint32_t gem_create ()
void gem_execbuf ()
void * gem_mmap__gtt ()
void * gem_mmap__cpu ()
int gem_madvise ()
uint32_t gem_context_create ()
void gem_sw_finish ()
bool gem_bo_busy ()
bool gem_has_llc ()
int gem_get_num_rings ()
bool gem_has_enable_ring ()
bool gem_has_bsd ()
bool gem_has_blt ()
bool gem_has_vebox ()
bool gem_uses_aliasing_ppgtt ()
int gem_available_fences ()
uint64_t gem_available_aperture_size ()
uint64_t gem_aperture_size ()
uint64_t gem_mappable_aperture_size ()
void gem_require_caching ()
void gem_require_ring ()
int prime_handle_to_fd ()
uint32_t prime_fd_to_handle ()
off_t prime_get_size ()

Types and Values

#define gem_mmap

Includes

#include <ioctl_wrappers.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

gem_handle_to_libdrm_bo ()

drm_intel_bo *
gem_handle_to_libdrm_bo (drm_intel_bufmgr *bufmgr,
                         int fd,
                         const char *name,
                         uint32_t handle);

This helper function imports a raw gem buffer handle into the libdrm buffer manager.

Parameters

bufmgr

libdrm buffer manager instance

 

fd

open i915 drm file descriptor

 

name

buffer name in libdrm

 

handle

gem buffer object handle

 

Returns

The imported libdrm buffer manager object.


gem_get_tiling ()

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

This wraps the GET_TILING ioctl.

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,
           uint32_t offset,
           const void *buf,
           uint32_t length);

This wraps the PWRITE ioctl, which is to upload a 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,
          uint32_t offset,
          void *buf,
          uint32_t length);

This wraps the PREAD ioctl, which is to download a 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 read into

 

length

size of the subrange

 

gem_set_domain ()

void
gem_set_domain (int fd,
                uint32_t handle,
                uint32_t read_domains,
                uint32_t write_domain);

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_domains

gem domain bits for read access

 

write_domain

gem domain bit for write access

 

gem_sync ()

void
gem_sync (int fd,
          uint32_t handle);

This is a wrapper around gem_set_domain() which simply blocks for any outstanding rendering to complete.

Parameters

fd

open i915 drm file descriptor

 

handle

gem buffer object handle

 

gem_create ()

uint32_t
gem_create (int fd,
            int size);

This wraps the GEM_CREATE ioctl, which allocates a new gem buffer object of size .

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

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

void *
gem_mmap__gtt (int fd,
               uint32_t handle,
               int size,
               int prot);

This functions wraps up procedure to establish a memory mapping through the GTT.

Parameters

fd

open i915 drm file descriptor

 

handle

gem buffer object handle

 

size

size of the gem buffer

 

prot

memory protection bits as used by mmap()

 

Returns

A pointer to the created memory mapping.


gem_mmap__cpu ()

void *
gem_mmap__cpu (int fd,
               uint32_t handle,
               int offset,
               int size,
               int prot);

This functions wraps up procedure to establish a memory mapping through direct cpu access, bypassing the gpu completely.

Parameters

fd

open i915 drm file descriptor

 

handle

gem buffer object handle

 

offset

offset in the gem buffer of te mmap arena

 

size

size of the mmap arena

 

prot

memory protection bits as used by mmap()

 

Returns

A pointer to the created memory mapping.


gem_madvise ()

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

This is a 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_context_create ()

uint32_t
gem_context_create (int fd);

This is a wraps the CONTEXT_CREATE ioctl, which is used to allocate a new hardware context. Not that similarly to gem_set_caching() this wrapper calls igt_require() internally to correctly skip on kernels and platforms where hw context support is not available.

Parameters

fd

open i915 drm file descriptor

 

Returns

The id of the allocated hw context.


gem_sw_finish ()

void
gem_sw_finish (int fd,
               uint32_t handle);

This is a 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 is a 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_get_num_rings ()

int
gem_get_num_rings (int fd);

Feature test macro to query the number of available rings. This is useful in test loops which need to step through all rings and similar logic.

For more explicit tests of ring availability see gem_has_enable_ring() and the ring specific versions like gem_has_bsd().

Parameters

fd

open i915 drm file descriptor

 

Returns

The number of available rings.


gem_has_enable_ring ()

bool
gem_has_enable_ring (int fd,
                     int param);

Feature test macro to query whether a specific ring is available.

Parameters

fd

open i915 drm file descriptor

 

param

ring flag bit as used in gem_execbuf()

 

Returns

Whether the ring is available or not.


gem_has_bsd ()

bool
gem_has_bsd (int fd);

Feature test macro to query whether the BSD ring is available. This is simply a specific version of gem_has_enable_ring() for the BSD ring.

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. This is simply a specific version of gem_has_enable_ring() for the blitter ring.

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. This is simply a specific version of gem_has_enable_ring() for the vebox ring.

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

bool
gem_uses_aliasing_ppgtt (int fd);

Feature test macro to check whether the kernel internally uses ppgtt to execute batches. The /aliasing/ in the function name is a bit a misnomer, this driver parameter is also true when full ppgtt address spaces are available since for batchbuffer construction only ppgtt or global gtt is relevant.

Parameters

fd

open i915 drm file descriptor

 

Returns

Whether batches are run through ppgtt.


gem_available_fences ()

int
gem_available_fences (int fd);

Feature test macro to query the kernel for the number of available fences usable in a batchbuffer. Only relevant for pre-gen4.

Parameters

fd

open i915 drm file descriptor

 

Returns

The number of available fences.


gem_available_aperture_size ()

uint64_t
gem_available_aperture_size (int fd);

Feature test macro to query the kernel for the available gpu aperture size usable in a batchbuffer.

Parameters

fd

open i915 drm file descriptor

 

Returns

The available gtt address space size.


gem_aperture_size ()

uint64_t
gem_aperture_size (int fd);

Feature test macro to query the kernel for the total gpu aperture size.

Parameters

fd

open i915 drm file descriptor

 

Returns

The total gtt address space size.


gem_mappable_aperture_size ()

uint64_t
gem_mappable_aperture_size (void);

Feature test macro to query the kernel for the mappable gpu aperture size. This is the area available for GTT memory mappings.

Returns

The mappable gtt address space size.


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,
                  int ring_id);

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

Parameters

fd

open i915 drm file descriptor

 

ring_id

ring flag bit as used in gem_execbuf()

 

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

Types and Values

gem_mmap

#define gem_mmap gem_mmap__gtt

This is a simple convenience alias to gem_mmap__gtt()