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:

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.

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.

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.

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.

igt_device_filter_pci ()

int
igt_device_filter_pci (void);

Filter devices to PCI only.

Returns PCI devices count.

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.

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.

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

bool
igt_device_find_first_xe_discrete_card
                               (struct igt_device_card *card);

Iterate over all igt_devices array and find first xe discrete card. card will be updated only if a device is found.

igt_device_find_xe_integrated_card ()

bool
igt_device_find_xe_integrated_card (struct igt_device_card *card);

Iterate over all igt_devices array and find first xe integrated card. card will be updated only if a device is found.

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.

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

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

igt_device_prepare_filtered_view ()

int
igt_device_prepare_filtered_view (const char *vendor);

Filter GPU devices for given vendor or with supplied --device option or IGT_DEVICE environment variable.

enum igt_devices_print_type

enum igt_devices_print_option

struct igt_devices_print_format

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

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;
};