Top |
enum | pipe |
enum | port |
enum | igt_atomic_crtc_properties |
enum | igt_atomic_connector_properties |
struct | kmstest_connector_config |
struct | kmstest_plane |
struct | kmstest_crtc |
enum | kmstest_force_connector_state |
enum | intel_broadcast_rgb_mode |
enum | igt_commit_style |
enum | igt_atomic_plane_properties |
typedef | igt_display_t |
typedef | igt_pipe_t |
typedef | igt_fixed_t |
enum | igt_rotation_t |
#define | IGT_ROTATION_MASK |
igt_plane_t | |
struct | igt_pipe |
igt_output_t | |
struct | igt_display |
#define | EDID_LENGTH |
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.
void
kmstest_dump_mode (drmModeModeInfo *mode
);
Prints mode
to stdout in a human-readable form.
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.
void
kmstest_restore_vt_mode (void
);
Restore the VT mode in use before kmstest_set_vt_graphics_mode was called.
bool kmstest_force_connector (int fd
,drmModeConnector *connector
,enum kmstest_force_connector_state state
);
Force the specified state on the specified connector.
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.
void kmstest_edid_add_4k (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 a HDMI 4K mode in vsdb.
void kmstest_edid_add_audio (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 basic audio support and speaker data block.
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.
drm_fd |
drm file descriptor |
|
connector |
connector to set |
|
edid |
An EDID data block |
|
length |
length of the EDID data. EDID_LENGTH defines the standard EDID length |
bool kmstest_get_connector_default_mode (int drm_fd
,drmModeConnector *connector
,drmModeModeInfo *mode
);
Retrieves the default mode for connector
and stores it in mode
.
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
.
bool kmstest_probe_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
, fully probing the connector in the
process.
void
kmstest_free_connector_config (struct kmstest_connector_config *config
);
Free any resources in config
allocated in kmstest_get_connector_config()
.
void kmstest_set_connector_dpms (int fd
,drmModeConnector *connector
,int mode
);
This function sets the DPMS setting of connector
to mode
.
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.
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. |
void kmstest_unset_all_crtcs (int drm_fd
,drmModeResPtr resources
);
Disables all the screens.
int kmstest_get_crtc_idx (drmModeRes *res
,uint32_t crtc_id
);
Get the CRTC index based on its ID. This is useful since a few places of libdrm deal with CRTC masks.
uint32_t kmstest_find_crtc_for_connector (int fd
,drmModeRes *res
,drmModeConnector *connector
,uint32_t crtc_blacklist_idx_mask
);
uint32_t kmstest_dumb_create (int fd
,int width
,int height
,int bpp
,unsigned *stride
,uint64_t *size
);
This wraps the CREATE_DUMB ioctl, which allocates a new dumb buffer object for the specified dimensions.
void * kmstest_dumb_map_buffer (int fd
,uint32_t handle
,uint64_t size
,unsigned prot
);
void
kmstest_wait_for_pageflip (int fd
);
Blocks until pageflip is completed
unsigned int kmstest_get_vblank (int fd
,int pipe
,unsigned int flags
);
Blocks or request a signal when a specified vblank event occurs
Returns 0 on success or non-zero unsigned integer otherwise
void igt_assert_plane_visible (int fd
,enum pipe pipe
,bool visibility
);
Asserts only if the plane's visibility state matches the status being passed by visibility
void igt_display_require (igt_display_t *display
,int drm_fd
);
Initialize display
and allocate the various resources required. Use
igt_display_fini to release the resources when they are no longer required.
This function automatically skips if the kernel driver doesn't support any CRTC or outputs.
void
igt_display_fini (igt_display_t *display
);
Release any resources associated with display
. This does not free display
itself.
void
igt_display_reset (igt_display_t *display
);
Reset basic pipes, connectors and planes on display
back to default values.
In particular, the following properties will be reset:
For outputs:
IGT_CONNECTOR_BROADCAST_RGB
(if applicable)
igt_output_override_mode() to default.
For pipes:
For planes:
IGT_PLANE_SRC_
*
IGT_PLANE_CRTC_
*
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.
0 upon success. This function will never return upon failure
since igt_fail()
at lower levels will longjmp out of it.
int
igt_display_commit (igt_display_t *display
);
Commits framebuffer and positioning changes to all planes of each display pipe.
0 upon success. This function will never return upon failure
since igt_fail()
at lower levels will longjmp out of it.
int igt_display_try_commit_atomic (igt_display_t *display
,uint32_t flags
,void *user_data
);
This function is similar to igt_display_try_commit2, but is used when you want to pass different flags to the actual commit.
Useful flags can be DRM_MODE_ATOMIC_ALLOW_MODESET, DRM_MODE_ATOMIC_NONBLOCK, DRM_MODE_PAGE_FLIP_EVENT, or DRM_MODE_ATOMIC_TEST_ONLY.
user_data
is returned in the event if you pass
DRM_MODE_PAGE_FLIP_EVENT to flags
.
This function will return an error if commit fails, instead of aborting the test.
display |
igt_display_t to commit. |
|
flags |
Flags passed to drmModeAtomicCommit. |
|
user_data |
User defined pointer passed to drmModeAtomicCommit. |
void igt_display_commit_atomic (igt_display_t *display
,uint32_t flags
,void *user_data
);
This function is similar to igt_display_commit2, but is used when you want to pass different flags to the actual commit.
Useful flags can be DRM_MODE_ATOMIC_ALLOW_MODESET, DRM_MODE_ATOMIC_NONBLOCK, DRM_MODE_PAGE_FLIP_EVENT, or DRM_MODE_ATOMIC_TEST_ONLY.
user_data
is returned in the event if you pass
DRM_MODE_PAGE_FLIP_EVENT to flags
.
This function will abort the test if commit fails.
display |
igt_display_t to commit. |
|
flags |
Flags passed to drmModeAtomicCommit. |
|
user_data |
User defined pointer passed to drmModeAtomicCommit. |
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.
int
igt_display_drop_events (igt_display_t *display
);
Nonblockingly reads all current events and drops them, for highest
reliablility, call igt_display_commit2()
first to flush all outstanding
events.
This will be called on the first commit after igt_display_reset()
too,
to make sure any stale events are flushed.
int
igt_display_get_n_pipes (igt_display_t *display
);
Returns total number of pipes for the given display
void
igt_display_require_output (igt_display_t *display
);
Checks whether there's a valid pipe
/output
combination for the given display
Skips test if a valid combination of pipe
and output
is not found
void igt_display_require_output_on_pipe (igt_display_t *display
,enum pipe pipe
);
Checks whether there's a valid pipe
/output
combination for the given display
and pipe
Skips test if a valid pipe
is not found
drmModeModeInfo *
igt_output_get_mode (igt_output_t *output
);
Get the current mode of the given connector
void igt_output_override_mode (igt_output_t *output
,drmModeModeInfo *mode
);
Overrides the output's mode with mode
, so that it is used instead of the
mode obtained with get connectors. Note that the mode is used without
checking if the output supports it, so this might lead to unexpected results.
igt_plane_t * igt_output_get_plane_type (igt_output_t *output
,int plane_type
);
Finds a valid plane type for the given output
otherwise
the test is skipped if the right combination of output
/plane_type
is not found
igt_output_t * igt_output_from_connector (igt_display_t *display
,drmModeConnector *connector
);
Finds the output corresponding to the given connector
display |
a pointer to an igt_display_t structure |
|
connector |
a pointer to a drmModeConnector |
igt_plane_t * igt_pipe_get_plane_type (igt_pipe_t *pipe
,int plane_type
);
Finds a valid plane type for the given pipe
otherwise
it skips the test if the right combination of pipe
/plane_type
is not found
igt_output_t * igt_get_single_output_for_pipe (igt_display_t *display
,enum pipe pipe
);
Get a compatible output for a pipe.
display |
a pointer to an igt_display_t structure |
|
pipe |
The pipe for which an igt_output_t must be returned. |
void
igt_pipe_request_out_fence (igt_pipe_t *pipe
);
Marks this pipe for requesting an out fence at the next atomic commit will contain the fd number of the out fence created by KMS.
void igt_plane_set_fb (igt_plane_t *plane
,struct igt_fb *fb
);
Pairs a given framebuffer
to a plane
This function also sets a default size and position for the framebuffer to avoid crashes on applications that ignore to set these.
void igt_plane_set_fence_fd (igt_plane_t *plane
,int fence_fd
);
This function sets a fence fd to enable a commit to wait for some event to occur before completing.
void igt_plane_set_position (igt_plane_t *plane
,int x
,int y
);
This function sets a new (x,y) position for the given plane.
New position will be committed at plane commit time via drmModeSetPlane()
.
void igt_plane_set_size (igt_plane_t *plane
,int w
,int h
);
This function sets width and height for requested plane.
New size will be committed at plane commit time via
drmModeSetPlane()
.
void igt_plane_set_rotation (igt_plane_t *plane
,igt_rotation_t rotation
);
This function sets a new rotation for the requested plane
.
New rotation
will be committed at plane commit time via
drmModeSetPlane()
.
void igt_fb_set_position (struct igt_fb *fb
,igt_plane_t *plane
,uint32_t x
,uint32_t y
);
This function sets position for requested framebuffer as src to plane.
New position will be committed at plane commit time via drmModeSetPlane()
.
void igt_fb_set_size (struct igt_fb *fb
,igt_plane_t *plane
,uint32_t w
,uint32_t h
);
This function sets fetch rect size from requested framebuffer as src
to plane. New size will be committed at plane commit time via
drmModeSetPlane()
.
void igt_wait_for_vblank (int drm_fd
,enum pipe pipe
);
Waits for 1 vertical blank intervals
void igt_wait_for_vblank_count (int drm_fd
,enum pipe pipe
,int count
);
Waits for a given number of vertical blank intervals
#define igt_pipe_connector_valid(pipe, output)
Checks whether the given pipe and output can be used together.
#define for_each_connected_output(display, output)
This for loop iterates over all outputs.
#define for_each_pipe_static(pipe)
This for loop iterates over all pipes supported by IGT libraries.
This should be used to enumerate per-pipe subtests since it has no runtime depencies.
#define for_each_pipe(display, pipe)
This for loop iterates over all pipes.
Note that this cannot be used to enumerate per-pipe subtest names since it depends upon runtime probing of the actual kms driver that is being tested. Use for_each_pipe_static instead.
#define for_each_pipe_with_valid_output(display, pipe, output)
This for loop is called over all connected outputs. This function
will try every combination of pipe
and output
.
If you only need to test a single output for each pipe, use
for_each_pipe_with_single_output()
, if you only need an
output for a single pipe, use igt_get_single_output_for_pipe()
.
display |
a pointer to an igt_display_t structure |
|
pipe |
The pipe for which this |
|
output |
The output for which this |
#define for_each_pipe_with_single_output(display, pipe, output)
This loop is called over all pipes, and will try to find a compatible output
for each pipe. Unlike for_each_pipe_with_valid_output()
, this function will
be called at most once for each pipe.
display |
a pointer to an igt_display_t structure |
|
pipe |
The pipe for which this |
|
output |
The output for which this |
#define for_each_valid_output_on_pipe(display, pipe, output)
This for loop is called over all connected output
that can be used
on this pipe
. If there are no valid outputs for this pipe, nothing
happens.
display |
a pointer to an igt_display_t structure |
|
pipe |
Pipe to enumerate valid outputs over |
|
output |
The enumerated output. |
bool igt_plane_has_prop (igt_plane_t *plane
,enum igt_atomic_plane_properties prop
);
Check whether plane supports a given property.
uint64_t igt_plane_get_prop (igt_plane_t *plane
,enum igt_atomic_plane_properties prop
);
Return current value on a plane for a given property.
bool igt_plane_try_prop_enum (igt_plane_t *plane
,enum igt_atomic_plane_properties prop
,const char *val
);
void igt_plane_set_prop_enum (igt_plane_t *plane
,enum igt_atomic_plane_properties prop
,const char *val
);
void igt_plane_replace_prop_blob (igt_plane_t *plane
,enum igt_atomic_plane_properties prop
,const void *ptr
,size_t length
);
This function will destroy the old property blob for the given property, and will create a new property blob with the values passed to this function.
The new property blob will be committed when you call igt_display_commit()
,
igt_display_commit2()
or igt_display_commit_atomic()
.
bool igt_output_has_prop (igt_output_t *output
,enum igt_atomic_connector_properties prop
);
Check whether output supports a given property.
uint64_t igt_output_get_prop (igt_output_t *output
,enum igt_atomic_connector_properties prop
);
Return current value on an output for a given property.
bool igt_output_try_prop_enum (igt_output_t *output
,enum igt_atomic_connector_properties prop
,const char *val
);
void igt_output_set_prop_enum (igt_output_t *output
,enum igt_atomic_connector_properties prop
,const char *val
);
void igt_output_replace_prop_blob (igt_output_t *output
,enum igt_atomic_connector_properties prop
,const void *ptr
,size_t length
);
This function will destroy the old property blob for the given property, and will create a new property blob with the values passed to this function.
The new property blob will be committed when you call igt_display_commit()
,
igt_display_commit2()
or igt_display_commit_atomic()
.
bool igt_pipe_obj_has_prop (igt_pipe_t *pipe
,enum igt_atomic_crtc_properties prop
);
Check whether pipe supports a given property.
uint64_t igt_pipe_obj_get_prop (igt_pipe_t *pipe
,enum igt_atomic_crtc_properties prop
);
Return current value on a pipe for a given property.
uint64_t igt_pipe_get_prop (igt_display_t *display
,enum pipe pipe
,enum igt_atomic_crtc_properties prop
);
Return current value on a pipe for a given property.
bool igt_pipe_has_prop (igt_display_t *display
,enum pipe pipe
,enum igt_atomic_crtc_properties prop
);
Check whether pipe supports a given property.
bool igt_pipe_obj_try_prop_enum (igt_pipe_t *pipe
,enum igt_atomic_crtc_properties prop
,const char *val
);
void igt_pipe_obj_set_prop_enum (igt_pipe_t *pipe
,enum igt_atomic_crtc_properties prop
,const char *val
);
void igt_pipe_obj_replace_prop_blob (igt_pipe_t *pipe
,enum igt_atomic_crtc_properties prop
,const void *ptr
,size_t length
);
This function will destroy the old property blob for the given property, and will create a new property blob with the values passed to this function.
The new property blob will be committed when you call igt_display_commit()
,
igt_display_commit2()
or igt_display_commit_atomic()
.
Please use igt_output_override_mode()
if you want to set IGT_CRTC_MODE_ID,
it works better with legacy commit.
void
igt_enable_connectors (int drm_fd
);
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.
void
igt_reset_connectors (void
);
Remove any forced state from the connectors.
uint32_t
kmstest_get_vbl_flag (uint32_t pipe_id
);
Convert a pipe id into the flag representation expected in DRM while processing DRM_IOCTL_WAIT_VBLANK.
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.
const unsigned char *
igt_kms_get_alt_edid (void
);
Get an alternate edid block, which includes the following modes:
1400x1050 60Hz
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.
struct udev_monitor *
igt_watch_hotplug (void
);
Begin monitoring udev for sysfs hotplug events.
bool igt_hotplug_detected (struct udev_monitor *mon
,int timeout_secs
);
Assert that a hotplug event was received since we last checked the monitor.
mon |
A udev monitor initialized with igt_watch_hotplug |
|
timeout_secs |
How long to wait for a hotplug event to occur. |
void
igt_flush_hotplugs (struct udev_monitor *mon
);
Get rid of any pending hotplug events
void
igt_cleanup_hotplug (struct udev_monitor *mon
);
Cleanup the resources allocated by igt_watch_hotplug
bool igt_display_has_format_mod (igt_display_t *display
,uint32_t format
,uint64_t modifier
);
bool igt_plane_has_format_mod (igt_plane_t *plane
,uint32_t format
,uint64_t modifier
);
struct kmstest_connector_config { drmModeCrtc *crtc; drmModeConnector *connector; drmModeEncoder *encoder; drmModeModeInfo default_mode; int pipe; unsigned valid_crtc_idx_mask; };
struct kmstest_plane { int id; int index; int type; int pos_x; int pos_y; int width; int height; };
struct kmstest_crtc { int id; int pipe; bool active; int width; int height; int n_planes; struct kmstest_plane *planes; };
struct igt_pipe { igt_display_t *display; enum pipe pipe; int n_planes; int plane_cursor; int plane_primary; igt_plane_t *planes; uint64_t changed; uint32_t props[IGT_NUM_CRTC_PROPS]; uint64_t values[IGT_NUM_CRTC_PROPS]; uint32_t crtc_id; int32_t out_fence_fd; };
struct igt_display { int drm_fd; int log_shift; int n_pipes; int n_outputs; igt_output_t *outputs; igt_pipe_t *pipes; bool has_cursor_plane; bool is_atomic; bool first_commit; uint64_t *modifiers; uint32_t *formats; int format_mod_count; };