sysfs: igt-gpu-tools Reference Manual

## sysfs sysfs — Support code for sysfs features |

## Functions

#define | for_each_sysfs_gt_path()
#define | for_each_sysfs_gt_dirfd()
#define | igt_sysfs_rps_write()
#define | igt_sysfs_rps_read()
#define | igt_sysfs_rps_set()
#define | igt_sysfs_rps_get()
#define | igt_sysfs_rps_scanf()
#define | igt_sysfs_rps_vprintf()
#define | igt_sysfs_rps_printf()
#define | igt_sysfs_rps_get_u32()
#define | igt_sysfs_rps_set_u32()
#define | igt_sysfs_rps_get_boolean()
#define | igt_sysfs_rps_set_boolean()
char * | igt_sysfs_path ()
int | igt_sysfs_open ()
char * | igt_sysfs_gt_path ()
int | igt_sysfs_gt_open ()
int | igt_sysfs_get_num_gt ()
bool | igt_sysfs_has_attr ()
const char * | igt_sysfs_dir_id_to_name ()
const char * | igt_sysfs_path_id_to_name ()
int | igt_sysfs_read ()
int | igt_sysfs_write ()
bool | igt_sysfs_set ()
char * | igt_sysfs_get ()
int | igt_sysfs_scanf ()
int | igt_sysfs_vprintf ()
int | igt_sysfs_printf ()
uint32_t | igt_sysfs_get_u32 ()
bool | igt_sysfs_set_u32 ()
uint64_t | igt_sysfs_get_u64 ()
bool | igt_sysfs_set_u64 ()
bool | igt_sysfs_get_boolean ()
bool | igt_sysfs_set_boolean ()
void | bind_fbcon ()
void | kick_snd_hda_intel ()
void | fbcon_blink_enable ()
void | igt_sysfs_rw_attr_verify ()

## Types and Values

enum | i915_attr_id
| igt_sysfs_rw_attr_t

## Includes

    #include <igt.h>

## Description

This library provides helpers to access sysfs features. Right now it only provides basic support for like `igt_sysfs_open()`.

## Functions

### for_each_sysfs_gt_path()

    #define             for_each_sysfs_gt_path(i915__, path__, pathlen__)

### for_each_sysfs_gt_dirfd()

    #define             for_each_sysfs_gt_dirfd(i915__, dirfd__, gt__)

### igt_sysfs_rps_write()

    #define             igt_sysfs_rps_write(dir, id, data, len)

### igt_sysfs_rps_read()

    #define             igt_sysfs_rps_read(dir, id, data, len)

### igt_sysfs_rps_set()

    #define             igt_sysfs_rps_set(dir, id, value)

### igt_sysfs_rps_get()

    #define             igt_sysfs_rps_get(dir, id)

### igt_sysfs_rps_scanf()

    #define             igt_sysfs_rps_scanf(dir, id, fmt, ...)

### igt_sysfs_rps_vprintf()

    #define             igt_sysfs_rps_vprintf(dir, id, fmt, ap)

### igt_sysfs_rps_printf()

    #define             igt_sysfs_rps_printf(dir, id, fmt, ...)

### igt_sysfs_rps_get_u32()

    #define             igt_sysfs_rps_get_u32(dir, id)

### igt_sysfs_rps_set_u32()

    #define             igt_sysfs_rps_set_u32(dir, id, value)

### igt_sysfs_rps_get_boolean()

    #define             igt_sysfs_rps_get_boolean(dir, id)

### igt_sysfs_rps_set_boolean()

    #define             igt_sysfs_rps_set_boolean(dir, id, value)

### igt_sysfs_path ()

    char *
    igt_sysfs_path (int device,
                    char *path,
                    int pathlen);

This finds the sysfs directory corresponding to `device` .

#### Parameters

device | fd of the device |
path | buffer to fill with the sysfs path to the device |
pathlen | length of `path` buffer |

#### Returns

The directory path, or NULL on failure.

### igt_sysfs_open ()

    int
    igt_sysfs_open (int device);

This opens the sysfs directory corresponding to device for use with `igt_sysfs_set()` and `igt_sysfs_get()`.

#### Parameters

device | fd of the device |

#### Returns

The directory fd, or -1 on failure.

### igt_sysfs_gt_path ()

    char *
    igt_sysfs_gt_path (int device,
                       int gt,
                       char *path,
                       int pathlen);

This finds the sysfs directory corresponding to `device` and `gt` . If the gt specific directory is not available and gt is 0, path is filled with sysfs base directory.

#### Parameters

device | fd of the device |
gt | gt number |
path | buffer to fill with the sysfs gt path to the device |
pathlen | length of `path` buffer |

#### Returns

The directory path, or NULL on failure.

### igt_sysfs_gt_open ()

    int
    igt_sysfs_gt_open (int device,
                       int gt);

This opens the sysfs gt directory corresponding to device and gt for use with `igt_sysfs_set()` and `igt_sysfs_get()`.

#### Parameters

device | fd of the device |
gt | gt number |

#### Returns

The directory fd, or -1 on failure.

### igt_sysfs_get_num_gt ()

    int
    igt_sysfs_get_num_gt (int device);

Reads number of GT sysfs entries. Asserts for atleast one GT entry. (see igt_sysfs_gt_path).

#### Parameters

device | fd of the device |

#### Returns

Number of GTs.

### igt_sysfs_has_attr ()

    bool
    igt_sysfs_has_attr (int dir,
                        const char *attr);

This checks if specified attr exists in device sysfs directory.

#### Parameters

dir | sysfs directory fd |
attr | attr inside sysfs dir that needs to be checked for existence |

#### Returns

true if attr exists in sysfs, false otherwise.

### igt_sysfs_dir_id_to_name ()

    const char *
    igt_sysfs_dir_id_to_name (int dir,
                              enum i915_attr_id id);

Returns attribute name corresponding to attribute id in either the per-gt or legacy per-device sysfs

#### Parameters

dir | sysfs directory fd |
id | sysfs attribute id |

#### Returns

Attribute name in sysfs

### igt_sysfs_path_id_to_name ()

    const char *
    igt_sysfs_path_id_to_name (const char *path,
                               enum i915_attr_id id);

Returns attribute name corresponding to attribute id in either the per-gt or legacy per-device sysfs

#### Parameters

path | sysfs directory path |
id | sysfs attribute id |

#### Returns

Attribute name in sysfs

### igt_sysfs_read ()

    int
    igt_sysfs_read (int dir,
                    const char *attr,
                    void *data,
                    int len);

This reads `len` bytes from the sysfs file to `data`

#### Parameters

dir | directory for the device from `igt_sysfs_open()` |
attr | name of the sysfs node to open |
data | the block to read into |
len | the maximum length to read |

#### Returns

The length read, -errno on failure.

### igt_sysfs_write ()

    int
    igt_sysfs_write (int dir,
                     const char *attr,
                     const void *data,
                     int len);

This writes `len` bytes from `data` to the sysfs file.

#### Parameters

dir | directory for the device from `igt_sysfs_open()` |
attr | name of the sysfs node to open |
data | the block to write from |
len | the length to write |

#### Returns

The number of bytes written, or -errno on error.

### igt_sysfs_set ()

    bool
    igt_sysfs_set (int dir,
                   const char *attr,
                   const char *value);

This writes the value to the sysfs file.

#### Parameters

dir | directory for the device from `igt_sysfs_open()` |
attr | name of the sysfs node to open |
value | the string to write |

#### Returns

True on success, false on failure.

### igt_sysfs_get ()

    char *
    igt_sysfs_get (int dir,
                   const char *attr);

This reads the value from the sysfs file.

#### Parameters

dir | directory for the device from `igt_sysfs_open()` |
attr | name of the sysfs node to open |

#### Returns

A nul-terminated string, must be freed by caller after use, or NULL on failure.

### igt_sysfs_scanf ()

    int
    igt_sysfs_scanf (int dir,
                     const char *attr,
                     const char *fmt,
                     ...);

scanf() wrapper for sysfs.

#### Parameters

dir | directory for the device from `igt_sysfs_open()` |
attr | name of the sysfs node to open |
fmt | scanf format string |
... | Additional paramaters to store the scaned input values |

#### Returns

Number of values successfully scanned (which can be 0), EOF on errors or premature end of file.

### igt_sysfs_vprintf ()

    int
    igt_sysfs_vprintf (int dir,
                       const char *attr,
                       const char *fmt,
                       va_list ap);

### igt_sysfs_printf ()

    int
    igt_sysfs_printf (int dir,
                      const char *attr,
                      const char *fmt,
                      ...);

printf() wrapper for sysfs.

#### Parameters

dir | directory for the device from `igt_sysfs_open()` |
attr | name of the sysfs node to open |
fmt | printf format string |
... | Additional paramaters to store the scaned input values |

#### Returns

Number of characters written, negative value on error.

### igt_sysfs_get_u32 ()

    uint32_t
    igt_sysfs_get_u32 (int dir,
                       const char *attr);

Convenience wrapper to read a unsigned 32bit integer from a sysfs file.

#### Parameters

dir | directory for the device from `igt_sysfs_open()` |
attr | name of the sysfs node to open |

#### Returns

The value read.

### igt_sysfs_set_u32 ()

    bool
    igt_sysfs_set_u32 (int dir,
                       const char *attr,
                       uint32_t value);

Convenience wrapper to write a unsigned 32bit integer to a sysfs file.

#### Parameters

dir | directory for the device from `igt_sysfs_open()` |
attr | name of the sysfs node to open |
value | value to set |

#### Returns

True if successfully written

### igt_sysfs_get_u64 ()

    uint64_t
    igt_sysfs_get_u64 (int dir,
                       const char *attr);

Convenience wrapper to read a unsigned 64bit integer from a sysfs file.

#### Parameters

dir | directory for the device from `igt_sysfs_open()` |
attr | name of the sysfs node to open |

#### Returns

The value read.

### igt_sysfs_set_u64 ()

    bool
    igt_sysfs_set_u64 (int dir,
                       const char *attr,
                       uint64_t value);

Convenience wrapper to write a unsigned 64bit integer to a sysfs file.

#### Parameters

dir | directory for the device from `igt_sysfs_open()` |
attr | name of the sysfs node to open |
value | value to set |

#### Returns

True if successfully written

### igt_sysfs_get_boolean ()

    bool
    igt_sysfs_get_boolean (int dir,
                           const char *attr);

Convenience wrapper to read a boolean sysfs file.

#### Parameters

dir | directory for the device from `igt_sysfs_open()` |
attr | name of the sysfs node to open |

#### Returns

The value read.

### igt_sysfs_set_boolean ()

    bool
    igt_sysfs_set_boolean (int dir,
                           const char *attr,
                           bool value);

Convenience wrapper to write a boolean sysfs file.

#### Parameters

dir | directory for the device from `igt_sysfs_open()` |
attr | name of the sysfs node to open |
value | value to set |

#### Returns

The value read.

### bind_fbcon ()

    void
    bind_fbcon (bool enable);

This functions enables/disables the text console running on top of the framebuffer device.

#### Parameters

enable | boolean value |

### kick_snd_hda_intel ()

    void
    kick_snd_hda_intel (void);

This functions unbinds the snd_hda_intel driver so the module cand be unloaded.

### fbcon_blink_enable ()

    void
    fbcon_blink_enable (bool enable);

Enables or disables the cursor blinking in fbcon, it also restores the previous blinking state when exiting test.

#### Parameters

enable | if true enables the fbcon cursor blinking otherwise disables it |

### igt_sysfs_rw_attr_verify ()

    void
    igt_sysfs_rw_attr_verify (igt_sysfs_rw_attr_t *rw);

This function attempts to verify writable sysfs attributes, that is the attribute is first written to and then read back and it is verified that the read value matches the written value to a tolerance. However, when we try to do this we run into the issue that a sysfs attribute might have a behavior where the read value is different from the written value for any reason. For example, attributes such as power, voltage, frequency and time typically have a linear region outside which they are clamped (the values saturate). Therefore for such attributes read values match the written value only in the linear region and when writing we don't know if we are writing to the linear or to the clamped region.

Therefore the verification implemented here takes the approach of sweeping across the range of possible values of the attribute (this is done using 'doubling' rather than linearly) and seeing where there are matches. There should be at least one match (to a tolerance) for the verification to have succeeded.

#### Parameters

rw | 'struct igt_sysfs_rw_attr' describing a rw sysfs attr |

## Types and Values

### enum i915_attr_id

#### Members

RPS_ACT_FREQ_MHZ |  |
RPS_CUR_FREQ_MHZ |  |
RPS_MIN_FREQ_MHZ |  |
RPS_MAX_FREQ_MHZ |  |
RPS_RP0_FREQ_MHZ |  |
RPS_RP1_FREQ_MHZ |  |
RPS_RPn_FREQ_MHZ |  |
RPS_IDLE_FREQ_MHZ |  |
RPS_BOOST_FREQ_MHZ |  |
RC6_ENABLE |  |
RC6_RESIDENCY_MS |  |
RC6P_RESIDENCY_MS |  |
RC6PP_RESIDENCY_MS |  |
MEDIA_RC6_RESIDENCY_MS |  |
SYSFS_NUM_ATTR |  |

### igt_sysfs_rw_attr_t

    typedef struct {
    	int dir;
    	char *attr;
    	uint64_t start;
    	double tol;
    } igt_sysfs_rw_attr_t;