debugfs: igt-gpu-tools Reference Manual

## debugfs debugfs — Support code for debugfs features |

## Functions

const char * | igt_debugfs_mount ()
char * | igt_debugfs_path ()
int | igt_debugfs_dir ()
int | igt_debugfs_connector_dir ()
int | igt_debugfs_pipe_dir ()
int | igt_debugfs_open ()
bool | igt_debugfs_exists ()
int | igt_debugfs_simple_read ()
bool | igt_debugfs_search ()
#define | igt_debugfs_read()
#define | igt_debugfs_write()
void | igt_hpd_storm_set_threshold ()
void | igt_hpd_storm_reset ()
bool | igt_hpd_storm_detected ()
void | igt_require_hpd_storm_ctl ()
void | igt_reset_fifo_underrun_reporting ()
bool | igt_drop_caches_has ()
void | igt_drop_caches_set ()
void | rcu_barrier ()
int | igt_get_stable_obj_count ()
#define | igt_debugfs_dump()

## Types and Values

#define | DROP_UNBOUND
#define | DROP_BOUND
#define | DROP_RETIRE
#define | DROP_ACTIVE
#define | DROP_FREED
#define | DROP_SHRINK_ALL
#define | DROP_IDLE
#define | DROP_RESET_ACTIVE
#define | DROP_RESET_SEQNO
#define | DROP_RCU
#define | DROP_ALL

## Includes

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

### Other debugfs interface wrappers

This covers the miscellaneous debugfs interface wrappers:

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

## Functions

### igt_debugfs_mount ()

    const char *
    igt_debugfs_mount (void);

This attempts to locate where debugfs is mounted on the filesystem, and if not found, will then try to mount debugfs at /sys/kernel/debug.

#### Returns

The path to the debugfs mount point (e.g. /sys/kernel/debug)

### igt_debugfs_path ()

    char *
    igt_debugfs_path (int device,
                      char *path,
                      int pathlen);

This finds the debugfs directory corresponding to `device` .

#### Parameters

device | fd of the device |
path | buffer to store path |
pathlen | len of `path` buffer. |

#### Returns

The directory path, or NULL on failure.

### igt_debugfs_dir ()

    int
    igt_debugfs_dir (int device);

This opens the debugfs directory corresponding to device for use with `igt_sysfs_get()` and related functions.

#### Parameters

device | fd of the device |

#### Returns

The directory fd, or -1 on failure.

### igt_debugfs_connector_dir ()

    int
    igt_debugfs_connector_dir (int device,
                               char *conn_name,
                               int mode);

This opens the debugfs directory corresponding to connector on the device for use with `igt_sysfs_get()` and related functions.

#### Parameters

device | fd of the device |
conn_name | conenctor name |
mode | mode bits as used by `open()` |

#### Returns

The directory fd, or -1 on failure.

### igt_debugfs_pipe_dir ()

    int
    igt_debugfs_pipe_dir (int device,
                          int pipe,
                          int mode);

This opens the debugfs directory corresponding to the pipe index on the device for use with `igt_sysfs_get()` and related functions. This is just syntax sugar for `igt_debugfs_open()`.

#### Parameters

device | fd of the device |
pipe | index of pipe |
mode | mode bits as used by `open()` |

#### Returns

The directory fd, or -1 on failure.

### igt_debugfs_open ()

    int
    igt_debugfs_open (int fd,
                      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_exists ()

    bool
    igt_debugfs_exists (int fd,
                        const char *filename,
                        int mode);

Test that the specified debugfs file exists and can be opened with the requested mode.

#### Parameters

device | the drm device file fd |
filename | file name |
mode | mode bits as used by `open()` |

### igt_debugfs_simple_read ()

    int
    igt_debugfs_simple_read (int dir,
                             const char *filename,
                             char *buf,
                             int size);

This function is similar to __igt_debugfs_read, the difference is that it expects the debugfs directory to be open and it's descriptor passed as the first argument.

#### Parameters

filename | file name |
buf | buffer where the contents will be stored, allocated by the caller |
size | size of the buffer |

#### Returns

-errorno on failure or bytes read on success

### igt_debugfs_search ()

    bool
    igt_debugfs_search (int fd,
                        const char *filename,
                        const char *substring);

Searches each line in `filename` for the substring specified in `substring` .

#### Parameters

filename | file name |
substring | string to search for in `filename` |

#### Returns

True if the `substring` is found to occur in `filename`

### igt_debugfs_read()

    #define             igt_debugfs_read(fd, filename, buf)

This is just a convenience wrapper for __igt_debugfs_read. See its documentation.

#### Parameters

filename | name of the debugfs file |
buf | buffer where the contents will be stored, allocated by the caller. |

### igt_debugfs_write()

    #define             igt_debugfs_write(fd, filename, buf)

This is just a convenience wrapper for __igt_debugfs_write. See its documentation.

#### Parameters

fd | the drm device file fd |
filename | name of the debugfs file |
buf | buffer to be written to the debugfs file |

### igt_hpd_storm_set_threshold ()

    void
    igt_hpd_storm_set_threshold (int fd,
                                 unsigned int threshold);

Convienence helper to configure the HPD storm detection threshold for i915 through debugfs. Useful for hotplugging tests where HPD storm detection might get in the way and slow things down.

If the system does not support HPD storm detection, this function does nothing.

See: https://01.org/linuxgraphics/gfx-docs/drm/gpu/i915.htmlhotplug

#### Parameters

threshold | How many hotplugs per second required to trigger an HPD storm, or 0 to disable storm detection. |

### igt_hpd_storm_reset ()

    void
    igt_hpd_storm_reset (int fd);

Convienence helper to reset HPD storm detection to it's default settings. If hotplug detection was disabled on any ports due to an HPD storm, it will be immediately re-enabled. Always called on exit if the HPD storm detection threshold was modified during any tests.

If the system does not support HPD storm detection, this function does nothing.

See: https://01.org/linuxgraphics/gfx-docs/drm/gpu/i915.htmlhotplug

### igt_hpd_storm_detected ()

    bool
    igt_hpd_storm_detected (int fd);

Checks whether or not i915 has detected an HPD interrupt storm on any of the system's ports.

This function always returns false on systems that do not support HPD storm detection.

See: https://01.org/linuxgraphics/gfx-docs/drm/gpu/i915.htmlhotplug

#### Returns

Whether or not an HPD storm has been detected.

### igt_require_hpd_storm_ctl ()

    void
    igt_require_hpd_storm_ctl (int fd);

Skips the current test if the system does not have HPD storm detection.

See: https://01.org/linuxgraphics/gfx-docs/drm/gpu/i915.htmlhotplug

### igt_reset_fifo_underrun_reporting ()

    void
    igt_reset_fifo_underrun_reporting (int drm_fd);

Resets fifo underrun reporting, if supported by the device. Useful since fifo underrun reporting tends to be one-shot, so good to reset it before the actual functional test again in case there's been a separate issue happening while preparing the test setup.

#### Parameters

drm_fd | drm device file descriptor |

### igt_drop_caches_has ()

    bool
    igt_drop_caches_has (int fd,
                         uint64_t val);

This queries the debugfs to see if it supports the full set of desired operations.

#### Parameters

val | bitmask for DROP_* values |

### igt_drop_caches_set ()

    void
    igt_drop_caches_set (int fd,
                         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 |

### rcu_barrier ()

    void
    rcu_barrier (int fd);

### igt_get_stable_obj_count ()

    int
    igt_get_stable_obj_count (int driver);

This puts the driver into a stable (quiescent) state and then returns the current number of gem buffer objects as reported in the i915_gem_objects debugFS interface.

#### Parameters

driver | fd to drm/i915 GEM driver |

### igt_debugfs_dump()

    #define igt_debugfs_dump(d, f) __igt_debugfs_dump(d, f, IGT_LOG_DEBUG)

## Types and Values

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

### DROP_FREED

    #define DROP_FREED 0x10

Also drop freed objects.

### DROP_SHRINK_ALL

    #define DROP_SHRINK_ALL 0x20

Force all unpinned buffers to be evicted from their GTT and returned to the system.

### DROP_IDLE

    #define DROP_IDLE 0x40

Flush the driver's idle_worker, releasing internal caches and wakerefs.

### DROP_RESET_ACTIVE

    #define DROP_RESET_ACTIVE 0x80

Cancel all outstanding requests by forcing a gpu reset

### DROP_RESET_SEQNO

    #define DROP_RESET_SEQNO 0x100

Reset the global request seqno counter back to 0

### DROP_RCU

    #define DROP_RCU 0x200

Performs `rcu_barrier()` and waits for an RCU grace period to complete, which will flush any RCU callbacks and deferred tasks.

### DROP_ALL

    #define             DROP_ALL

All of the above DROP_ flags combined.