## debugfs debugfs — Support code for debugfs features |

## Functions

const char * | igt_debugfs_mount ()
char * | igt_debugfs_path ()
int | igt_debugfs_dir ()
int | igt_debugfs_open ()
bool | igt_debugfs_search ()
#define | igt_debugfs_read()
void | igt_assert_crc_equal ()
bool | igt_check_crc_equal ()
char * | igt_crc_to_string_extended ()
char * | igt_crc_to_string ()
void | igt_require_pipe_crc ()
igt_pipe_crc_t * | igt_pipe_crc_new ()
igt_pipe_crc_t * | igt_pipe_crc_new_nonblock ()
void | igt_pipe_crc_free ()
void | igt_pipe_crc_start ()
void | igt_pipe_crc_stop ()
int | igt_pipe_crc_get_crcs ()
void | igt_pipe_crc_collect_crc ()
void | igt_hpd_storm_set_threshold ()
void | igt_hpd_storm_reset ()
bool | igt_hpd_storm_detected ()
void | igt_require_hpd_storm_ctl ()
bool | igt_drop_caches_has ()
void | igt_drop_caches_set ()
void | igt_disable_prefault ()
void | igt_enable_prefault ()
int | igt_get_stable_obj_count ()
void | igt_debugfs_dump ()

## Types and Values

typedef | igt_pipe_crc_t
#define | DRM_MAX_CRC_NR
| igt_crc_t
enum | intel_pipe_crc_source
#define | DROP_UNBOUND
#define | DROP_BOUND
#define | DROP_RETIRE
#define | DROP_ACTIVE
#define | DROP_FREED
#define | DROP_SHRINK_ALL
#define | DROP_IDLE
#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.

### 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_assert_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 classes of gem buffer objects, see `igt_drop_caches_set()`.

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

## 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_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_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_assert_crc_equal ()

    void
    igt_assert_crc_equal (const igt_crc_t *a,
                          const igt_crc_t *b);

Compares two CRC values and fails the testcase if they don't match with `igt_fail()`. Note that due to CRC collisions CRC based testcase can only assert that CRCs match, never that they are different. Otherwise there might be random testcase failures when different screen contents end up with the same CRC by chance.

#### Parameters

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

### igt_check_crc_equal ()

    bool
    igt_check_crc_equal (const igt_crc_t *a,
                         const igt_crc_t *b);

Compares two CRC values and return whether they match.

#### Parameters

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

#### Returns

A boolean indicating whether the CRC values match

### igt_crc_to_string_extended ()

    char *
    igt_crc_to_string_extended (igt_crc_t *crc,
                                char delimiter,
                                int crc_size);

This function allocates a string and formats `crc` into it, depending on `delimiter` and `crc_size` . The caller is responsible for freeing the string.

This should only ever be used for diagnostic debug output.

#### Parameters

crc | pipe CRC value to print |
delimiter | The delimiter to use between crc words |
crc_size | the number of bytes to print per crc word (between 1 and 4) |

### igt_crc_to_string ()

    char *
    igt_crc_to_string (igt_crc_t *crc);

This function allocates a string and formats `crc` into it. The caller is responsible for freeing the string.

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 (int fd);

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 (int fd,
                      enum pipe pipe,
                      enum intel_pipe_crc_source source);

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

#### Parameters

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

#### Returns

A pipe CRC object for 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_new_nonblock ()

    igt_pipe_crc_t *
    igt_pipe_crc_new_nonblock (int fd,
                               enum pipe pipe,
                               enum intel_pipe_crc_source source);

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

#### Parameters

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

#### Returns

A pipe CRC object for 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 ()

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

Read up to `n_crcs` from `pipe_crc` . This function does not block, and will return early if not enough CRCs can be captured, if `pipe_crc` has been opened using `igt_pipe_crc_new_nonblock()`. It will block until `n_crcs` are retrieved if `pipe_crc` has been opened using `igt_pipe_crc_new()`. `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()`. For one-shot CRC collecting look at `igt_pipe_crc_collect_crc()`.

#### Parameters

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

#### Returns

The number of CRCs captured. Should be equal to `n_crcs` in blocking mode, but can be less (even zero) in non-blocking mode.

### 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, irrespective of whether `pipe_crc` has been opened with `igt_pipe_crc_new()` or `igt_pipe_crc_new_nonblock()`. `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.

This function also calls the interactive debug with the "crc" domain, so you can make use of this feature to actually see the screen that is being CRC'd.

For continuous CRC collection look at `igt_pipe_crc_start()`, `igt_pipe_crc_get_crcs()` and `igt_pipe_crc_stop()`.

#### Parameters

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

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

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

    void
    igt_debugfs_dump (int device,
                      const char *filename);

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

### DRM_MAX_CRC_NR

    #define DRM_MAX_CRC_NR 10

### igt_crc_t

    typedef struct {
    	uint32_t frame;
    	bool has_valid_frame;
    	int n_words;
    	uint32_t crc[DRM_MAX_CRC_NR];
    } 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 |
bool `has_valid_frame`; |  |
int `n_words`; | internal field, don't access |
uint32_t `crc`[DRM_MAX_CRC_NR]; | 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 | No source |
INTEL_PIPE_CRC_SOURCE_PLANE1 | Plane 1 |
INTEL_PIPE_CRC_SOURCE_PLANE2 | Plane 2 |
INTEL_PIPE_CRC_SOURCE_PF | Panel Filter |
INTEL_PIPE_CRC_SOURCE_PIPE | Pipe |
INTEL_PIPE_CRC_SOURCE_TV | TV |
INTEL_PIPE_CRC_SOURCE_DP_B | DisplayPort B |
INTEL_PIPE_CRC_SOURCE_DP_C | DisplayPort C |
INTEL_PIPE_CRC_SOURCE_DP_D | DisplayPort D |
INTEL_PIPE_CRC_SOURCE_AUTO | Automatic source selection |
INTEL_PIPE_CRC_SOURCE_MAX | Number of available sources |

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

    #define             DROP_ALL

All of the above DROP_ flags combined.