Device selection: igt-gpu-tools Reference Manual

## Device selection Device selection — Device scanning and selection |

## Functions

void | igt_devices_scan ()
void | igt_devices_print ()
void | igt_devices_print_vendors ()
void | igt_device_print_filter_types ()
void | igt_devices_free ()
int | igt_device_filter_count ()
int | igt_device_filter_add ()
void | igt_device_filter_free_all ()
const char * | igt_device_filter_get ()
bool | igt_device_card_match ()
bool | igt_device_card_match_pci ()
bool | igt_device_find_first_i915_discrete_card ()
bool | igt_device_find_integrated_card ()
char * | igt_device_get_pretty_name ()
int | igt_open_card ()
int | igt_open_render ()

## Types and Values

enum | igt_devices_print_type
enum | igt_devices_print_option
struct | igt_devices_print_format
#define | INTEGRATED_I915_GPU_PCI_ID
#define | PCI_SLOT_NAME_SIZE
struct | igt_device_card

## 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/codename][,card=%d] | [slot=%04x:%02x:%02x.%x]

  Filter allows device selection using vendor (hex or name), device id (hex or codename) 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.

      pci:vendor=8086,device=1234,card=all
      pci:vendor=8086,device=1234,card=*

  This will add 0..N card selectors, where 0 <= N <= 63. At least one filter will be added with card=0 and all incrementally matched ones up to max numbered 63 (max total 64).

  We may use device codename or pseudo-codename (integrated/discrete) instead of pci device id:

      pci:vendor=8086,device=skylake

  or

      pci:vendor=8086,device=integrated

  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.

- sriov: select pf or vf

      sriov:[vendor=%04x/name][,device=%04x/codename][,card=%d][,pf=%d][,vf=%d]

  Filter extends pci selector to allow pf/vf selection:

      sriov:vendor=Intel,device=1234,card=0,vf=2

  When vf is not defined, pf will be selected:

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

  In case a device has more than one pf, you can also select a specific pf or a vf associated with a specific pf:

      sriov:vendor=Intel,device=1234,card=0,pf=1

      sriov:vendor=Intel,device=1234,card=0,pf=1,vf=0

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