Dummyload: igt-gpu-tools Reference Manual

## Dummyload Dummyload — Library for submitting GPU workloads |

## Functions

igt_spin_t * | igt_spin_factory ()
#define | igt_spin_new()
void | igt_spin_set_timeout ()
void | igt_spin_reset ()
void | igt_spin_end ()
void | igt_spin_free ()
bool | igt_spin_has_poll ()
bool | igt_spin_has_started ()
void | igt_spin_busywait_until_started ()
void | igt_terminate_spins ()
void | igt_unshare_spins ()
void | igt_free_spins ()
#define | IGT_CORK()
#define | IGT_CORK_HANDLE()
#define | IGT_CORK_FENCE()
uint32_t | igt_cork_plug ()
void | igt_cork_unplug ()

## Types and Values

| igt_spin_factory_t
| igt_spin_t
#define | IGT_SPIN_FENCE_IN
#define | IGT_SPIN_FENCE_SUBMIT
#define | IGT_SPIN_FENCE_OUT
#define | IGT_SPIN_POLL_RUN
#define | IGT_SPIN_FAST
#define | IGT_SPIN_NO_PREEMPTION
#define | IGT_SPIN_INVALID_CS
#define | IGT_SPIN_USERPTR
#define | IGT_SPIN_SOFTDEP
enum | igt_cork_type
struct | igt_cork_vgem
struct | igt_cork_sw_sync
struct | igt_cork

## Includes

    #include <igt.h>

## Description

A lot of igt testcases need some GPU workload to make sure a race window is big enough. Unfortunately having a fixed amount of workload leads to spurious test failures or overly long runtimes on some fast/slow platforms. This library contains functionality to submit GPU workloads that should consume exactly a specific amount of time.

## Functions

### igt_spin_factory ()

    igt_spin_t *
    igt_spin_factory (int fd,
                      const igt_spin_factory_t *opts);

Start a recursive batch on a ring. Immediately returns a igt_spin_t that contains the batch's handle that can be waited upon. The returned structure must be passed to `igt_spin_free()` for post-processing.

#### Parameters

fd | open i915 drm file descriptor |
opts | controlling options such as context, engine, dependencies etc |

#### Returns

Structure with helper internal state for `igt_spin_free()`.

### igt_spin_new()

    #define             igt_spin_new(fd, ...)

### igt_spin_set_timeout ()

    void
    igt_spin_set_timeout (igt_spin_t *spin,
                          int64_t ns);

Specify a timeout. This ends the recursive batch associated with `spin` after the timeout has elapsed.

#### Parameters

spin | spin state from `igt_spin_new()` |
ns | amount of time in nanoseconds the batch continues to execute before finishing. |

### igt_spin_reset ()

    void
    igt_spin_reset (igt_spin_t *spin);

Reset the state of spin, allowing its reuse.

#### Parameters

spin | spin state from `igt_spin_new()` |

### igt_spin_end ()

    void
    igt_spin_end (igt_spin_t *spin);

End the spinner associated with `spin` manually.

#### Parameters

spin | spin state from `igt_spin_new()` |

### igt_spin_free ()

    void
    igt_spin_free (int fd,
                   igt_spin_t *spin);

This function does the necessary post-processing after starting a spin with `igt_spin_new()` and then frees it.

#### Parameters

fd | open i915 drm file descriptor |
spin | spin state from `igt_spin_new()` |

### igt_spin_has_poll ()

    bool
    igt_spin_has_poll (const igt_spin_t *spin);

### igt_spin_has_started ()

    bool
    igt_spin_has_started (igt_spin_t *spin);

### igt_spin_busywait_until_started ()

    void
    igt_spin_busywait_until_started (igt_spin_t *spin);

### igt_terminate_spins ()

    void
    igt_terminate_spins (void);

### igt_unshare_spins ()

    void
    igt_unshare_spins (void);

### igt_free_spins ()

    void
    igt_free_spins (int i915);

### IGT_CORK()

    #define IGT_CORK(name, cork_type) struct igt_cork name = { .type = cork_type, .fd = -1}

### IGT_CORK_HANDLE()

    #define IGT_CORK_HANDLE(name) IGT_CORK(name, CORK_VGEM_HANDLE)

### IGT_CORK_FENCE()

    #define IGT_CORK_FENCE(name) IGT_CORK(name, CORK_SYNC_FD)

### igt_cork_plug ()

    uint32_t
    igt_cork_plug (struct igt_cork *cork,
                   int fd);

This function provides a mechanism to stall submission. It provides two blocking methods:

VGEM_BO. Imports a vgem bo with a fence attached to it. This bo can be used as a dependency during submission to stall execution until the fence is signaled.

SW_SYNC: Creates a timeline and then a fence on that timeline. The fence can be used as an input fence to a request, the request will be stalled until the fence is signaled.

The parameters required to unblock the execution and to cleanup are stored in the provided cork structure.

#### Parameters

fd | open drm file descriptor |
method | method to utilize for corking. |
cork | structure that will be filled with the state of the cork bo. Note: this has to match the corking method. |

#### Returns

Handle of the imported BO / Sw sync fence FD.

### igt_cork_unplug ()

    void
    igt_cork_unplug (struct igt_cork *cork);

This function unblocks the execution by signaling the fence attached to the imported bo and does the necessary post-processing.

NOTE: the handle returned by igt_cork_plug is not closed during this phase.

#### Parameters

method | method to utilize for corking. |
cork | cork state from `igt_cork_plug()` |

## Types and Values

### igt_spin_factory_t

    typedef struct {
    	uint32_t ctx_id;
    	const intel_ctx_t *ctx;
    	uint32_t dependency;
    	uint64_t dependency_size;
    	unsigned int engine;
    	unsigned int flags;
    	int fence;
    	uint64_t ahnd;
    } igt_spin_factory_t;

A factory struct which contains creation parameters for an igt_spin_t.

#### Members

uint32_t `ctx_id`; | GEM context handle |
const intel_ctx_t *`ctx`; | intel_ctx_t context wrapper |
uint32_t `dependency`; | GEM object to depend on |
uint64_t `dependency_size`; |  |
unsigned int `engine`; | Flags describing the engine to execute on |
unsigned int `flags`; | Set of IGT_SPIN_* flags |
int `fence`; | In-fence to wait on |
uint64_t `ahnd`; |  |

### igt_spin_t

    typedef struct {
    	struct igt_list_head link;

    	uint32_t handle;
    	uint32_t poll_handle;

    	uint32_t *batch;

    	uint32_t *condition;
    	uint32_t cmd_precondition;

    	uint32_t *poll;
    #define SPIN_POLL_START_IDX 0

    	struct timespec last_signal;
    	pthread_t timer_thread;
    	int timerfd;

    	int out_fence;
    	struct drm_i915_gem_exec_object2 obj[2];
    #define IGT_SPIN_BATCH   1
    	struct drm_i915_gem_execbuffer2 execbuf;

    	unsigned int flags;
    #define SPIN_CLFLUSH (1 << 0)

    	struct igt_spin_factory opts;
    } igt_spin_t;

### IGT_SPIN_FENCE_IN

    #define IGT_SPIN_FENCE_IN      (1 << 0)

### IGT_SPIN_FENCE_SUBMIT

    #define IGT_SPIN_FENCE_SUBMIT  (1 << 1)

### IGT_SPIN_FENCE_OUT

    #define IGT_SPIN_FENCE_OUT     (1 << 2)

### IGT_SPIN_POLL_RUN

    #define IGT_SPIN_POLL_RUN      (1 << 3)

### IGT_SPIN_FAST

    #define IGT_SPIN_FAST          (1 << 4)

### IGT_SPIN_NO_PREEMPTION

    #define IGT_SPIN_NO_PREEMPTION (1 << 5)

### IGT_SPIN_INVALID_CS

    #define IGT_SPIN_INVALID_CS    (1 << 6)

### IGT_SPIN_USERPTR

    #define IGT_SPIN_USERPTR       (1 << 7)

### IGT_SPIN_SOFTDEP

    #define IGT_SPIN_SOFTDEP       (1 << 8)

### enum igt_cork_type

#### Members

CORK_SYNC_FD |  |
CORK_VGEM_HANDLE |  |

### struct igt_cork_vgem

    struct igt_cork_vgem {
    	int device;
    	uint32_t fence;
    };

### struct igt_cork_sw_sync

    struct igt_cork_sw_sync {
    	int timeline;
    };

### struct igt_cork

    struct igt_cork {
    	enum igt_cork_type type;

    	union {
    		int fd;

    		struct igt_cork_vgem vgem;
    		struct igt_cork_sw_sync sw_sync;
    	};
    };