debugfs

debugfs — Support code for debugfs features

Functions

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

bool
igt_debugfs_search (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(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 (igt_crc_t *a,
                      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_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 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 (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_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_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_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 (or -1 to default to Intel)

 

Returns

The directory fd, or -1 on failure.


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.


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

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_ALL

#define             DROP_ALL

All of the above DROP_ flags combined.