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 slot or vendor and device properties

    pci:[vendor=%04x/name][,device=%04x][,card=%d] | [slot=%04x:%02x:%02x.%x]
    

    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.

    Another possibility is to select device using a PCI slot:

    pci:slot=0000:01:00.0
    

    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 (const struct igt_devices_print_format *fmt);

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

fmt

Print format as specified by struct igt_devices_print_format

 

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_devices_free ()

void
igt_devices_free (void);

igt_device_filter_count ()

int
igt_device_filter_count (void);

Returns number of filters collected in the filter list.


igt_device_filter_add ()

int
igt_device_filter_add (const char *filter);

Function allows passing single or more filters within one string. This is for CI when it can extract filter from environment variable (and it must be single string). So if filter contains semicolon ';' it treats each part as separate filter and adds to the filter array.

Returns number of filters added to filter array. Can be greater than 1 if filters contains more than one filter separated by semicolon.

Parameters

filters

filter(s) to be stored in filter array

 

igt_device_filter_free_all ()

void
igt_device_filter_free_all (void);

Free all filters within array.


igt_device_filter_get ()

const char *
igt_device_filter_get (int num);

Returns filter string or NULL if num is out of range of filter array.

Parameters

num

Number of filter from filter array

 

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_device_card_match_pci ()

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

Function applies filter to match device from device array. Populate associated pci subsystem data if available.

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_device_find_first_i915_discrete_card ()

bool
igt_device_find_first_i915_discrete_card
                               (struct igt_device_card *card);

igt_device_find_integrated_card ()

bool
igt_device_find_integrated_card (struct igt_device_card *card);

igt_device_get_pretty_name ()

char *
igt_device_get_pretty_name (struct igt_device_card *card,
                            bool numeric);

For card function returns allocated string having pretty name or vendor:device as hex if no backend pretty-resolver is implemented.

Parameters

card

pointer to igt_device_card struct

 

Returns

newly allocated string.


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

   

IGT_PRINT_USER

   

enum igt_devices_print_option

Members

IGT_PRINT_DRM

   

IGT_PRINT_SYSFS

   

IGT_PRINT_PCI

   

struct igt_devices_print_format

struct igt_devices_print_format {
	enum igt_devices_print_type   type;
	enum igt_devices_print_option option;
	bool numeric;
};

INTEGRATED_I915_GPU_PCI_ID

#define INTEGRATED_I915_GPU_PCI_ID "0000:00:02.0"

PCI_SLOT_NAME_SIZE

#define PCI_SLOT_NAME_SIZE 12

struct igt_device_card

struct igt_device_card {
	char subsystem[NAME_MAX];
	char card[NAME_MAX];
	char render[NAME_MAX];
	char pci_slot_name[PCI_SLOT_NAME_SIZE+1];
	uint16_t pci_vendor, pci_device;
};