intel-gpu-tools Reference Manual: i-g-t debugfs

## i-g-t debugfs i-g-t debugfs — Support code for debugfs features |

## Functions

int | igt_debugfs_open ()
FILE * | igt_debugfs_fopen ()
bool | igt_crc_is_null ()
bool | igt_crc_equal ()
char * | igt_crc_to_string ()
void | igt_require_pipe_crc ()
igt_pipe_crc_t * | igt_pipe_crc_new ()
void | igt_pipe_crc_free ()
void | igt_pipe_crc_start ()
void | igt_pipe_crc_stop ()
void | igt_pipe_crc_get_crcs ()
void | igt_pipe_crc_collect_crc ()
#define | DROP_ALL
void | igt_drop_caches_set ()
void | igt_disable_prefault ()
void | igt_enable_prefault ()
int | igt_open_forcewake_handle ()
enum stop_ring_flags | igt_to_stop_ring_flag ()
void | igt_set_stop_rings ()
enum stop_ring_flags | igt_get_stop_rings ()

## Types and Values

typedef | igt_pipe_crc_t
| igt_crc_t
enum | intel_pipe_crc_source
#define | DROP_UNBOUND
#define | DROP_BOUND
#define | DROP_RETIRE
#define | DROP_ACTIVE
enum | stop_ring_flags

## Includes

    #include <igt_debugfs.h>

## Description

This library provides helpers to access debugfs features. On top of some basic functions to access debugfs files with e.g. `igt_debugfs_open()` it also provides higher-level wrappers for some debugfs features

### Pipe CRC Support

This library wraps up the kernel's support for capturing pipe CRCs into a neat and tidy package. For the detailed usage see all the functions which work on igt_pipe_crc_t. This is supported on all platforms and outputs.

Actually using pipe CRCs to write modeset tests is a bit tricky though, so there is no way to directly check a CRC: Both the details of the plane blending, color correction and other hardware and how exactly the CRC is computed at each tap point vary by hardware generation and are not disclosed.

The only way to use igt_crc_t CRCs therefore is to compare CRCs among each another either for equality or difference. Otherwise CRCs must be treated as completely opaque values. Note that not even CRCs from different pipes or tap points on the same platform can be compared. Hence only use `igt_crc_is_null()` and `igt_crc_equal()` to inspect CRC values captured by the same igt_pipe_crc_t object.

### Other debugfs interface wrappers

This covers the miscellaneous debugfs interface wrappers:

- drm/i915 supports interfaces to evict certain clases of gem buffer objects, see `igt_drop_caches_set()`.

- drm/i915 supports an interface to disable prefaulting, useful to test slowpaths in ioctls. See `igt_disable_prefault()`.

## Functions

### igt_debugfs_open ()

    int
    igt_debugfs_open (const char *filename,
                      int mode);

This opens a debugfs file as a Unix file descriptor. The filename should be relative to the drm device's root, i.e without "drm/<minor>".

#### Parameters

filename | name of the debugfs node to open |
mode | mode bits as used by `open()` |

#### Returns

The Unix file descriptor for the debugfs file or -1 if that didn't work out.

### igt_debugfs_fopen ()

    FILE *
    igt_debugfs_fopen (const char *filename,
                       const char *mode);

This opens a debugfs file as a libc FILE. The filename should be relative to the drm device's root, i.e without "drm/<minor>".

#### Parameters

filename | name of the debugfs node to open |
mode | mode string as used by `fopen()` |

#### Returns

The libc FILE pointer for the debugfs file or NULL if that didn't work out.

### igt_crc_is_null ()

    bool
    igt_crc_is_null (igt_crc_t *crc);

#### Parameters

crc | pipe CRC value to check |

#### Returns

True if the CRC is null/invalid, false if it represents a captured valid CRC.

### igt_crc_equal ()

    bool
    igt_crc_equal (igt_crc_t *a,
                   igt_crc_t *b);

Compares two CRC values.

#### Parameters

a | first pipe CRC value |
b | second pipe CRC value |

#### Returns

true if the two CRCs match, false otherwise.

### igt_crc_to_string ()

    char *
    igt_crc_to_string (igt_crc_t *crc);

This formats `crc` into a string buffer which is owned by `igt_crc_to_string()`. The next call will override the buffer again, which makes this multithreading unsafe.

This should only ever be used for diagnostic debug output.

#### Parameters

crc | pipe CRC value to print |

### igt_require_pipe_crc ()

    void
    igt_require_pipe_crc (void);

Convenience helper to check whether pipe CRC capturing is supported by the kernel. Uses igt_skip to automatically skip the test/subtest if this isn't the case.

### igt_pipe_crc_new ()

    igt_pipe_crc_t *
    igt_pipe_crc_new (enum pipe pipe,
                      enum intel_pipe_crc_source source);

This sets up a new pipe CRC capture object for the given `pipe` and `source` .

#### Parameters

pipe | display pipe to use as source |
source | CRC tap point to use as source |

#### Returns

A pipe CRC object if the given `pipe` and `source` . The library assumes that the source is always available since recent kernels support at least INTEL_PIPE_CRC_SOURCE_AUTO everywhere.

### igt_pipe_crc_free ()

    void
    igt_pipe_crc_free (igt_pipe_crc_t *pipe_crc);

Frees all resources associated with `pipe_crc` .

#### Parameters

pipe_crc | pipe CRC object |

### igt_pipe_crc_start ()

    void
    igt_pipe_crc_start (igt_pipe_crc_t *pipe_crc);

Starts the CRC capture process on `pipe_crc` .

#### Parameters

pipe_crc | pipe CRC object |

### igt_pipe_crc_stop ()

    void
    igt_pipe_crc_stop (igt_pipe_crc_t *pipe_crc);

Stops the CRC capture process on `pipe_crc` .

#### Parameters

pipe_crc | pipe CRC object |

### igt_pipe_crc_get_crcs ()

    void
    igt_pipe_crc_get_crcs (igt_pipe_crc_t *pipe_crc,
                           int n_crcs,
                           igt_crc_t **out_crcs);

Read `n_crcs` from `pipe_crc` . This function blocks until `n_crcs` are retrieved. `out_crcs` is alloced by this function and must be released with `free()` by the caller.

Callers must start and stop the capturing themselves by calling `igt_pipe_crc_start()` and `igt_pipe_crc_stop()`.

#### Parameters

pipe_crc | pipe CRC object |
n_crcs | number of CRCs to capture |
out_crcs | buffer pointer for the captured CRC values |

### igt_pipe_crc_collect_crc ()

    void
    igt_pipe_crc_collect_crc (igt_pipe_crc_t *pipe_crc,
                              igt_crc_t *out_crc);

Read a single CRC from `pipe_crc` . This function blocks until the CRC is retrieved. `out_crc` must be allocated by the caller.

This function takes care of the pipe_crc book-keeping, it will start/stop the collection of the CRC.

#### Parameters

pipe_crc | pipe CRC object |
out_crc | buffer for the captured CRC values |

### DROP_ALL

    #define             DROP_ALL

### igt_drop_caches_set ()

    void
    igt_drop_caches_set (uint64_t val);

This calls the debugfs interface the drm/i915 GEM driver exposes to drop or evict certain classes of gem buffer objects.

#### Parameters

val | bitmask for DROP_* values |

### igt_disable_prefault ()

    void
    igt_disable_prefault (void);

Disable prefaulting in certain gem ioctls through the debugfs interface. As usual this installs an exit handler to clean up and re-enable prefaulting even when the test exited abnormally.

igt_enable_prefault() will enable normale operation again.

### igt_enable_prefault ()

    void
    igt_enable_prefault (void);

Enable prefault (again) through the debugfs interface.

### igt_open_forcewake_handle ()

    int
    igt_open_forcewake_handle (void);

This functions opens the debugfs forcewake file and so prevents the GT from suspending. The reference is automatically dropped when the is closed.

#### Returns

The file descriptor of the forcewake handle or -1 if that didn't work out.

### igt_to_stop_ring_flag ()

    enum stop_ring_flags
    igt_to_stop_ring_flag (int ring);

This converts the specified ring to a ring flag to be used with `igt_get_stop_rings()` and `igt_set_stop_rings()`.

#### Parameters

ring | the specified ring flag from execbuf ioctl (I915_EXEC_*) |

#### Returns

Ring flag for the given ring.

### igt_set_stop_rings ()

    void
    igt_set_stop_rings (enum stop_ring_flags flags);

This writes `flags` to 'i915_ring_stop' debugfs entry. Driver will prevent the CPU from writing tail pointer for the ring that `flags` specify. Note that the ring is not stopped right away. Instead any further command emissions won't be executed after the flag is set.

This is the least invasive way to make the GPU stuck. Hence you must set this after a batch submission with it's own invalid or endless looping instructions. In this case it is merely for giving notification for the driver that this was simulated hang, as the batch would have caused hang in any case. On the other hand if you use a valid or noop batch and want to hang the ring (GPU), you must set corresponding flag before submitting the batch.

Driver checks periodically if a ring is making any progress, and if it is not, it will declare the ring to be hung and will reset the GPU. After reset, the driver will clear flags in 'i915_ring_stop'

Note: Always when hanging the GPU, use `igt_set_stop_rings()` to notify the driver. Driver controls hang log messaging based on these flags and thus prevents false positives on logs.

#### Parameters

flags | Ring flags to write |

### igt_get_stop_rings ()

    enum stop_ring_flags
    igt_get_stop_rings (void);

Read current ring flags from 'i915_ring_stop' debugfs entry.

#### Returns

Current ring flags.

## Types and Values

### igt_pipe_crc_t

    typedef struct _igt_pipe_crc igt_pipe_crc_t;

Pipe CRC support structure. Needs to be allocated and set up with `igt_pipe_crc_new()` for a specific pipe and pipe CRC source value.

### igt_crc_t

    typedef struct {
    	uint32_t frame;
    	int n_words;
    	uint32_t crc[5];
    } igt_crc_t;

Pipe CRC value. All other members than `frame` are private and should not be inspected by testcases.

#### Members

uint32_t `frame`; | frame number of the capture CRC |
int `n_words`; | internal field, don't access |
uint32_t `crc`[5]; | internal field, don't access |

### enum intel_pipe_crc_source

Enumeration of all supported pipe CRC sources. Not all platforms and all outputs support all of them. Generic tests should just use INTEL_PIPE_CRC_SOURCE_AUTO. It should always map to an end-of-pipe CRC suitable for checking planes, cursor, color correction and any other output-agnostic features.

#### Members

INTEL_PIPE_CRC_SOURCE_NONE |  |
INTEL_PIPE_CRC_SOURCE_PLANE1 |  |
INTEL_PIPE_CRC_SOURCE_PLANE2 |  |
INTEL_PIPE_CRC_SOURCE_PF |  |
INTEL_PIPE_CRC_SOURCE_PIPE |  |
INTEL_PIPE_CRC_SOURCE_TV |  |
INTEL_PIPE_CRC_SOURCE_DP_B |  |
INTEL_PIPE_CRC_SOURCE_DP_C |  |
INTEL_PIPE_CRC_SOURCE_DP_D |  |
INTEL_PIPE_CRC_SOURCE_AUTO |  |
INTEL_PIPE_CRC_SOURCE_MAX |  |

### DROP_UNBOUND

    #define DROP_UNBOUND 0x1

Drop all currently unbound gem buffer objects from the cache.

### DROP_BOUND

    #define DROP_BOUND 0x2

Drop all inactive objects which are bound into some gpu address space.

### DROP_RETIRE

    #define DROP_RETIRE 0x4

Wait for all outstanding gpu commands to complete, but do not take any further actions.

### DROP_ACTIVE

    #define DROP_ACTIVE 0x8

Also drop active objects once retired.

### enum stop_ring_flags

Enumeration of all supported flags for `igt_set_stop_rings()`.

#### Members

STOP_RING_NONE | Can be used to clear the pending stop (warning: hang might be declared already). Returned by `igt_get_stop_rings()` if there is no currently stopped rings. |
STOP_RING_RENDER | Render ring |
STOP_RING_BSD | Video encoding/decoding ring |
STOP_RING_BLT | Blitter ring |
STOP_RING_VEBOX | Video enhancement ring |
STOP_RING_ALL | All rings |
STOP_RING_ALLOW_ERRORS | Driver will not omit expected DRM_ERRORS |
STOP_RING_ALLOW_BAN | Driver will use context ban policy |
STOP_RING_DEFAULTS | STOP_RING_ALL | STOP_RING_ALLOW_ERRORS |