i-g-t kms

i-g-t kms — Kernel modesetting support library

Functions

Types and Values

Includes

#include <igt_kms.h>

Description

This library provides support to enumerate and set modeset configurations.

There are two parts in this library: First the low level helper function which directly build on top of raw ioctls or the interfaces provided by libdrm. Those functions all have a kmstest_ prefix.

The second part is a high-level library to manage modeset configurations which abstracts away some of the low-level details like the difference between legacy and universal plane support for setting cursors or in the future the difference between legacy and atomic commit. These high-level functions have all igt_ prefixes. This part is still very much work in progress and so also lacks a bit documentation for the individual functions.

Note that this library's header pulls in the i-g-t framebuffer library as a dependency.

Functions

kmstest_pipe_name ()

const char *
kmstest_pipe_name (enum pipe pipe);

Parameters

pipe

display pipe

 

Returns

String represnting pipe , e.g. "A".


kmstest_plane_name ()

const char *
kmstest_plane_name (enum igt_plane plane);

Parameters

plane

display plane

 

Returns

String represnting pipe , e.g. "plane1".


kmstest_port_name()

#define kmstest_port_name(port) ((port) + 'A')

Parameters

port

display plane

 

Returns

String representing port , e.g. "A".


kmstest_encoder_type_str ()

const char *
kmstest_encoder_type_str (int type);

Parameters

type

DRM_MODE_ENCODER_* enumeration value

 

Returns

A string representing the drm encoder type .


kmstest_connector_status_str ()

const char *
kmstest_connector_status_str (int status);

Parameters

status

DRM_MODE_* connector status value

 

Returns

A string representing the drm connector status status .


kmstest_connector_type_str ()

const char *
kmstest_connector_type_str (int type);

Parameters

type

DRM_MODE_CONNECTOR_* enumeration value

 

Returns

A string representing the drm connector type .


kmstest_dump_mode ()

void
kmstest_dump_mode (drmModeModeInfo *mode);

Prints mode to stdout in a huma-readable form.

Parameters

mode

libdrm mode structure

 

kmstest_get_pipe_from_crtc_id ()

int
kmstest_get_pipe_from_crtc_id (int fd,
                               int crtc_id);

Parameters

fd

DRM fd

 

crtc_id

DRM CRTC id

 

Returns

The pipe number for the given DRM CRTC crtc_id . This maps directly to an enum pipe value used in other helper functions.


kmstest_set_vt_graphics_mode ()

void
kmstest_set_vt_graphics_mode (void);

Sets the controlling VT (if available) into graphics/raw mode and installs an igt exit handler to set the VT back to text mode on exit. Use kmstest_restore_vt_mode to restore the previous VT mode manually.

All kms tests must call this function to make sure that the fbcon doesn't interfere by e.g. blanking the screen.


kmstest_restore_vt_mode ()

void
kmstest_restore_vt_mode (void);

Restore the VT mode in use before kmstest_set_vt_graphics_mode was called.


kmstest_force_connector ()

bool
kmstest_force_connector (int fd,
                         drmModeConnector *connector,
                         enum kmstest_force_connector_state state);

Force the specified state on the specified connector.

Parameters

fd

drm file descriptor

 

connector

connector

 

state

state to force on connector

 

Returns

true on success


kmstest_edid_add_3d ()

void
kmstest_edid_add_3d (const unsigned char *edid,
                     size_t length,
                     unsigned char *new_edid_ptr[],
                     size_t *new_length);

Makes a copy of an existing edid block and adds an extension indicating stereo 3D capabilities.

Parameters

edid

an existing valid edid block

 

length

length of edid

 

new_edid_ptr

pointer to where the new edid will be placed

 

new_length

pointer to the size of the new edid

 

kmstest_force_edid ()

void
kmstest_force_edid (int drm_fd,
                    drmModeConnector *connector,
                    const unsigned char *edid,
                    size_t length);

Set the EDID data on connector to edid . See also igt_kms_get_base_edid.

If length is zero, the forced EDID will be removed.

Parameters

drm_fd

drm file descriptor

 

connector

connector to set edid on

 

edid

An EDID data block

 

length

length of the EDID data. EDID_LENGTH defines the standard EDID length

 

kmstest_get_connector_default_mode ()

bool
kmstest_get_connector_default_mode (int drm_fd,
                                    drmModeConnector *connector,
                                    drmModeModeInfo *mode);

Retrieves the default mode for connector and stores it in mode .

Parameters

drm_fd

DRM fd

 

connector

libdrm connector

 

mode

libdrm mode

 

Returns

true on success, false on failure


kmstest_get_connector_config ()

bool
kmstest_get_connector_config (int drm_fd,
                              uint32_t connector_id,
                              unsigned long  crtc_idx_mask,
                              struct kmstest_connector_config *config);

This tries to find a suitable configuration for the given connector and CRTC constraint and fills it into config .

Parameters

drm_fd

DRM fd

 

connector_id

DRM connector id

 

crtc_idx_mask

mask of allowed DRM CRTC indices

 

config

structure filled with the possible configuration

 

kmstest_free_connector_config ()

void
kmstest_free_connector_config (struct kmstest_connector_config *config);

Free any resources in config allocated in kmstest_get_connector_config().

Parameters

config

connector configuration structure

 

kmstest_set_connector_dpms ()

void
kmstest_set_connector_dpms (int fd,
                            drmModeConnector *connector,
                            int mode);

This function sets the DPMS setting of connector to mode .

Parameters

fd

DRM fd

 

connector

libdrm connector

 

mode

DRM DPMS value

 

kmstest_get_property ()

bool
kmstest_get_property (int drm_fd,
                      uint32_t object_id,
                      uint32_t object_type,
                      const char *name,
                      uint32_t *prop_id,
                      uint64_t *value,
                      drmModePropertyPtr *prop);

Finds a property with the given name on the given object.

Parameters

drm_fd

drm file descriptor

 

object_id

object whose properties we're going to get

 

object_type

type of obj_id (DRM_MODE_OBJECT_*)

 

name

name of the property we're going to get

 

prop_id

if not NULL, returns the property id

 

value

if not NULL, returns the property value

 

prop

if not NULL, returns the property, and the caller will have to free it manually.

 

Returns

true in case we found something.


kmstest_unset_all_crtcs ()

void
kmstest_unset_all_crtcs (int drm_fd,
                         drmModeResPtr resources);

Disables all the screens.

Parameters

drm_fd

the DRM fd

 

resources

libdrm resources pointer

 

igt_display_init ()

void
igt_display_init (igt_display_t *display,
                  int drm_fd);

igt_display_fini ()

void
igt_display_fini (igt_display_t *display);

igt_display_commit2 ()

int
igt_display_commit2 (igt_display_t *display,
                     enum igt_commit_style s);

Commits framebuffer and positioning changes to all planes of each display pipe, using a specific API to perform the programming. This function should be used to exercise a specific driver programming API; igt_display_commit should be used instead if the API used is unimportant to the test being run.

This function should only be used to commit changes that are expected to succeed, since any failure during the commit process will cause the IGT subtest to fail. To commit changes that are expected to fail, use igt_try_display_commit2 instead.

Parameters

display

DRM device handle

 

s

Commit style

 

Returns

0 upon success. This function will never return upon failure since igt_fail() at lower levels will longjmp out of it.


igt_display_commit ()

int
igt_display_commit (igt_display_t *display);

Commits framebuffer and positioning changes to all planes of each display pipe.

Parameters

display

DRM device handle

 

Returns

0 upon success. This function will never return upon failure since igt_fail() at lower levels will longjmp out of it.


igt_display_try_commit2 ()

int
igt_display_try_commit2 (igt_display_t *display,
                         enum igt_commit_style s);

Attempts to commit framebuffer and positioning changes to all planes of each display pipe. This function should be used to commit changes that are expected to fail, so that the error code can be checked for correctness. For changes that are expected to succeed, use igt_display_commit instead.

Note that in non-atomic commit styles, no display programming will be performed after the first failure is encountered, so only some of the operations requested by a test may have been completed. Tests that catch errors returned by this function should take care to restore the display to a sane state after a failure is detected.

Parameters

display

DRM device handle

 

s

Commit style

 

Returns

0 upon success, otherwise the error code of the first error encountered.


igt_display_get_n_pipes ()

int
igt_display_get_n_pipes (igt_display_t *display);

igt_output_name ()

const char *
igt_output_name (igt_output_t *output);

igt_output_get_mode ()

drmModeModeInfo *
igt_output_get_mode (igt_output_t *output);

igt_output_set_pipe ()

void
igt_output_set_pipe (igt_output_t *output,
                     enum pipe pipe);

igt_output_get_plane ()

igt_plane_t *
igt_output_get_plane (igt_output_t *output,
                      enum igt_plane plane);

igt_plane_set_fb ()

void
igt_plane_set_fb (igt_plane_t *plane,
                  struct igt_fb *fb);

igt_plane_set_position ()

void
igt_plane_set_position (igt_plane_t *plane,
                        int x,
                        int y);

igt_plane_set_size ()

void
igt_plane_set_size (igt_plane_t *plane,
                    int w,
                    int h);

igt_plane_set_panning ()

void
igt_plane_set_panning (igt_plane_t *plane,
                       int x,
                       int y);

igt_plane_set_rotation ()

void
igt_plane_set_rotation (igt_plane_t *plane,
                        igt_rotation_t rotation);

igt_wait_for_vblank ()

void
igt_wait_for_vblank (int drm_fd,
                     enum pipe pipe);

for_each_connected_output()

#define             for_each_connected_output(display, output)

for_each_pipe()

#define             for_each_pipe(display, pipe)

IGT_FIXED()

#define IGT_FIXED(i,f) ((i) << 16 | (f))

igt_enable_connectors ()

void
igt_enable_connectors (void);

Force connectors to be enabled where this is known to work well. Use igt_reset_connectors to revert the changes.

An exit handler is installed to ensure connectors are reset when the test exits.


igt_reset_connectors ()

void
igt_reset_connectors (void);

Remove any forced state from the connectors.


igt_kms_get_base_edid ()

const unsigned char *
igt_kms_get_base_edid (void);

Get the base edid block, which includes the following modes:

  • 1920x1080 60Hz

  • 1280x720 60Hz

  • 1024x768 60Hz

  • 800x600 60Hz

  • 640x480 60Hz

This can be extended with further features using functions such as kmstest_edid_add_3d.

Returns

a basic edid block

Types and Values

enum pipe

Members

PIPE_A

   

PIPE_B

   

PIPE_C

   

I915_MAX_PIPES

   

enum igt_plane

Members

IGT_PLANE_1

   

IGT_PLANE_PRIMARY

   

IGT_PLANE_2

   

IGT_PLANE_3

   

IGT_PLANE_CURSOR

   

enum port

Members

PORT_A

   

PORT_B

   

PORT_C

   

PORT_D

   

PORT_E

   

I915_MAX_PORTS

   

struct kmstest_connector_config

struct kmstest_connector_config {
	drmModeCrtc *crtc;
	drmModeConnector *connector;
	drmModeEncoder *encoder;
	drmModeModeInfo default_mode;
	int crtc_idx;
	int pipe;
};

enum kmstest_force_connector_state

Members

FORCE_CONNECTOR_UNSPECIFIED

Unspecified

 

FORCE_CONNECTOR_ON

On

 

FORCE_CONNECTOR_DIGITAL

Digital

 

FORCE_CONNECTOR_OFF

Off

 

enum igt_commit_style

Members

COMMIT_LEGACY

   

COMMIT_UNIVERSAL

   

igt_display_t

typedef struct igt_display igt_display_t;

igt_pipe_t

typedef struct igt_pipe igt_pipe_t;

igt_fixed_t

typedef uint32_t igt_fixed_t;			/* 16.16 fixed point */

enum igt_rotation_t

Members

IGT_ROTATION_0

   

IGT_ROTATION_90

   

IGT_ROTATION_180

   

IGT_ROTATION_270

   

igt_plane_t

typedef struct {
} igt_plane_t;

struct igt_pipe

struct igt_pipe {
	igt_display_t *display;
	enum pipe pipe;
	bool enabled;
#define IGT_MAX_PLANES 4
	int n_planes;
	igt_plane_t planes[IGT_MAX_PLANES];
};

igt_output_t

typedef struct {
} igt_output_t;

struct igt_display

struct igt_display {
	int drm_fd;
	int log_shift;
	int n_pipes;
	int n_outputs;
	unsigned long pipes_in_use;
	igt_output_t *outputs;
	igt_pipe_t pipes[I915_MAX_PIPES];
	bool has_universal_planes;
};

PIPE_ANY

#define PIPE_ANY (-1)

EDID_LENGTH

#define EDID_LENGTH 128