Device selection

Device selection — Device scanning and selection

Functions

Types and Values

Includes

#include <igt.h>

Description

Device scanning

Device scanning iterates over DRM subsystem using udev library to acquire DRM devices. For each DRM device we also get and store its parent to allow device selection happen in a more contextual way.

Parent devices are bus devices (like PCI, platform, etc.) and contain a lot of extra data on top of the DRM device itself.


Filters

Device selection can be done using filters that are using the data collected udev + some syntactic sugar.

Direct device selection filter uses sysfs path to find the device:

sys:/sys/path/to/device/or/parent

Examples:

- sys:/sys/devices/pci0000:00/0000:00:02.0/drm/card0
- sys:/sys/devices/pci0000:00/0000:00:02.0
- sys:/sys/devices/platform/vgem

The alternative is to use other implemented filters:

  • drm: get drm /dev/dri/... device directly

    drm:/dev/dri/...
    

    Loading drivers in different order can cause different ordering of /dev/dri/card nodes which be problematic for reliable and reproducible device selection, e.g. in automated execution setting. In such scenarios please consider using sys, pci or platform filters instead.

  • pci: select device using PCI vendor and device properties

    pci:[vendor=%04x/name][,device=%04x][,card=%d]
    

    Filter allows device selection using vendor (hex or name), device id (hex) and nth-card from all matches. For example if there are 4 PCI cards installed (let two cards have 1234 and other two 1235 device id, all of them of vendor Intel) you can select one using:

    pci:vendor=Intel,device=1234,card=0
    

    or

    pci:vendor=8086,device=1234,card=0
    

    This takes first device with 1234 id for Intel vendor (8086).

    pci:vendor=Intel,device=1234,card=1
    

    or

    pci:vendor=8086,device=1234,card=1
    

    It selects the second one.

    As order the on PCI bus doesn't change (unless you'll add new device or reorder existing one) device selection using this filter will always return you same device regardless the order of enumeration.

    Simple syntactic sugar over using the sysfs paths.

Functions

igt_devices_scan ()

void
igt_devices_scan (bool force);

Function scans udev in search of gpu devices. For first run it can be called with force = false. If something changes during the the test or test does some module loading (new drm devices occurs during execution) function must be called again with force = true to refresh device array.

Parameters

force

enforce scanning devices

 

igt_devices_print ()

void
igt_devices_print (enum igt_devices_print_type printtype);

Function can be used by external tool to print device array in simple or detailed form. This function is added here to avoid exposing internal implementation data structures.

Parameters

printtype

IGT_PRINT_SIMPLE or IGT_PRINT_DETAIL

 

igt_devices_print_vendors ()

void
igt_devices_print_vendors (void);

Print pci id -> vendor mappings. Vendor names printed by this function can be used for filters like pci which allows passing vendor - like vendor id (8086) or as a string (Intel).


igt_device_print_filter_types ()

void
igt_device_print_filter_types (void);

igt_device_is_filter_set ()

bool
igt_device_is_filter_set (void);

Returns whether we have a filter set.


igt_device_filter_set ()

void
igt_device_filter_set (const char *filter);

Parameters

filter

filter that should be set globally

 

igt_device_filter_free ()

void
igt_device_filter_free (void);

Free the filter that we store internally, effectively unsetting it.


igt_device_filter_get ()

const char *
igt_device_filter_get (void);

Returns filter string or NULL if not set


igt_device_card_match ()

bool
igt_device_card_match (const char *filter,
                       struct igt_device_card *card);

Function applies filter to match device from device array.

Parameters

filter

filter string

 

card

pointer to igt_device_card struct

 

Returns

false - no card pointer was passed or card wasn't matched, true - card matched and returned.


igt_open_card ()

int
igt_open_card (struct igt_device_card *card);

Open /dev/dri/cardX device represented by igt_device_card structure. Requires filled card argument (see igt_device_card_match() function).

An open DRM fd or -1 on error

Parameters

card

pointer to igt_device_card structure

 

igt_open_render ()

int
igt_open_render (struct igt_device_card *card);

Open /dev/dri/renderDX device represented by igt_device_card structure. Requires filled card argument (see igt_device_card_match() function).

An open DRM fd or -1 on error

Parameters

card

pointer to igt_device_card structure

 

Types and Values

enum igt_devices_print_type

Members

IGT_PRINT_SIMPLE

   

IGT_PRINT_DETAIL

   

struct igt_device_card

struct igt_device_card {
	char subsystem[NAME_MAX];
	char card[NAME_MAX];
	char render[NAME_MAX];
};