From df09cb52fc81db003e80ba9a02556e6f117510e2 Mon Sep 17 00:00:00 2001 From: Carlos Santa Date: Mon, 12 Feb 2018 15:45:23 -0800 Subject: lib/igt_kms: Add doc for kmstest_ and igt_ functions It seems some of the documentation is still not complete, finish it for the benefit of IGT newcomers. These functions include: kmstest_dumb_map_buffer kmstest_get_vblank igt_assert_plane_visible igt_display_require_output igt_display_require_output_on_pipe igt_pipe_get_plane_type igt_output_get_mode igt_output_set_pipe igt_output_get_plane_type igt_plane_set_fb igt_plane_set_position igt_plane_set_rotation igt_wait_for_vblank_count igt_wait_for_vblank Signed-off-by: Carlos Santa CC: Daniel Vetter Reviewed-by: Maarten Lankhorst --- lib/igt_kms.c | 134 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 133 insertions(+), 1 deletion(-) (limited to 'lib/igt_kms.c') diff --git a/lib/igt_kms.c b/lib/igt_kms.c index cc4a1f72..e14ecf3b 100644 --- a/lib/igt_kms.c +++ b/lib/igt_kms.c @@ -618,6 +618,14 @@ uint32_t kmstest_dumb_create(int fd, int width, int height, int bpp, return create.handle; } +/** + * kmstest_dumb_map_buffer: + * @fd: Opened drm file descriptor + * @handle: Offset in the file referred to by fd + * @size: Length of the mapping, must be greater than 0 + * @prot: Describes the memory protection of the mapping + * Returns: A pointer representing the start of the virtual mapping + */ void *kmstest_dumb_map_buffer(int fd, uint32_t handle, uint64_t size, unsigned prot) { @@ -1425,6 +1433,16 @@ static inline uint32_t pipe_select(int pipe) return 0; } +/** + * kmstest_get_vblank: + * @fd: Opened drm file descriptor + * @pipe: Display pipe + * @flags: Flags passed to drm_ioctl_wait_vblank + * + * Blocks or request a signal when a specified vblank event occurs + * + * Returns 0 on success or non-zero unsigned integer otherwise + */ unsigned int kmstest_get_vblank(int fd, int pipe, unsigned int flags) { union drm_wait_vblank vbl; @@ -1552,6 +1570,14 @@ static void kmstest_get_crtc(int device, enum pipe pipe, struct kmstest_crtc *cr igt_assert(ncrtc == 1); } +/** + * igt_assert_plane_visible: + * @fd: Opened file descriptor + * @pipe: Display pipe + * @visibility: Boolean parameter to test against the plane's current visibility state + * + * Asserts only if the plane's visibility state matches the status being passed by @visibility + */ void igt_assert_plane_visible(int fd, enum pipe pipe, bool visibility) { struct kmstest_crtc crtc; @@ -1935,11 +1961,24 @@ void igt_display_init(igt_display_t *display, int drm_fd) LOG_UNINDENT(display); } +/** + * igt_display_get_n_pipes: + * @display: A pointer to an #igt_display_t structure + * + * Returns total number of pipes for the given @display + */ int igt_display_get_n_pipes(igt_display_t *display) { return display->n_pipes; } +/** + * igt_display_require_output: + * @display: A pointer to an #igt_display_t structure + * + * 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(igt_display_t *display) { enum pipe pipe; @@ -1951,6 +1990,14 @@ void igt_display_require_output(igt_display_t *display) igt_skip("No valid crtc/connector combinations found.\n"); } +/** + * igt_display_require_output_on_pipe: + * @display: A pointer to an #igt_display_t structure + * @pipe: Display 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 + */ void igt_display_require_output_on_pipe(igt_display_t *display, enum pipe pipe) { igt_output_t *output; @@ -2111,7 +2158,16 @@ static igt_plane_t *igt_pipe_get_plane(igt_pipe_t *pipe, int plane_idx) return &pipe->planes[plane_idx]; } - +/** + * igt_pipe_get_plane_type: + * @pipe: Target pipe + * @plane_type: Cursor, primary or an overlay plane + * + * 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 + * + * Returns: A #igt_plane_t structure that matches the requested plane type + */ igt_plane_t *igt_pipe_get_plane_type(igt_pipe_t *pipe, int plane_type) { int i, plane_idx = -1; @@ -3171,11 +3227,25 @@ int igt_display_drop_events(igt_display_t *display) return ret; } +/** + * igt_output_name: + * @output: Target output + * + * Returns: String representing a connector's name, e.g. "DP-1". + */ const char *igt_output_name(igt_output_t *output) { return output->name; } +/** + * igt_output_get_mode: + * @output: Target output + * + * Get the current mode of the given connector + * + * Returns: A #drmModeModeInfo struct representing the current mode + */ drmModeModeInfo *igt_output_get_mode(igt_output_t *output) { if (output->use_override_mode) @@ -3210,6 +3280,15 @@ void igt_output_override_mode(igt_output_t *output, drmModeModeInfo *mode) } } +/* + * igt_output_set_pipe: + * @output: Target output for which the pipe is being set to + * @pipe: Display pipe to set to + * + * This function sets a @pipe to a specific @output connector by + * setting the CRTC_ID property of the @pipe. The pipe + * is only activated for all pipes except PIPE_NONE. + */ void igt_output_set_pipe(igt_output_t *output, enum pipe pipe) { igt_display_t *display = output->display; @@ -3291,6 +3370,16 @@ igt_plane_t *igt_output_get_plane(igt_output_t *output, int plane_idx) return igt_pipe_get_plane(pipe, plane_idx); } +/** + * igt_output_get_plane_type: + * @output: Target output + * @plane_type: Cursor, primary or an overlay plane + * + * 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 + * + * Returns: A #igt_plane_t structure that matches the requested plane type + */ igt_plane_t *igt_output_get_plane_type(igt_output_t *output, int plane_type) { igt_pipe_t *pipe; @@ -3301,6 +3390,16 @@ igt_plane_t *igt_output_get_plane_type(igt_output_t *output, int plane_type) return igt_pipe_get_plane_type(pipe, plane_type); } +/** + * igt_plane_set_fb: + * @plane: Plane + * @fb: Framebuffer pointer + * + * 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_fb(igt_plane_t *plane, struct igt_fb *fb) { igt_pipe_t *pipe = plane->pipe; @@ -3359,6 +3458,15 @@ void igt_plane_set_fence_fd(igt_plane_t *plane, int fence_fd) igt_plane_set_prop_value(plane, IGT_PLANE_IN_FENCE_FD, fd); } +/** + * igt_plane_set_position: + * @plane: Plane pointer for which position is to be set + * @x: X coordinate + * @y: Y coordinate + * + * 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_position(igt_plane_t *plane, int x, int y) { igt_pipe_t *pipe = plane->pipe; @@ -3456,6 +3564,15 @@ static const char *rotation_name(igt_rotation_t rotation) } } +/** + * igt_plane_set_rotation: + * @plane: Plane pointer for which rotation is to be set + * @rotation: Plane rotation value (0, 90, 180, 270) + * + * This function sets a new rotation for the requested @plane. + * New @rotation will be committed at plane commit time via + * drmModeSetPlane(). + */ void igt_plane_set_rotation(igt_plane_t *plane, igt_rotation_t rotation) { igt_pipe_t *pipe = plane->pipe; @@ -3480,6 +3597,14 @@ void igt_pipe_request_out_fence(igt_pipe_t *pipe) igt_pipe_obj_set_prop_value(pipe, IGT_CRTC_OUT_FENCE_PTR, (ptrdiff_t)&pipe->out_fence_fd); } +/** + * igt_wait_for_vblank_count: + * @drm_fd: A drm file descriptor + * @pipe: Pipe to wait_for_vblank on + * @count: Number of vblanks to wait on + * + * Waits for a given number of vertical blank intervals + */ void igt_wait_for_vblank_count(int drm_fd, enum pipe pipe, int count) { drmVBlank wait_vbl; @@ -3495,6 +3620,13 @@ void igt_wait_for_vblank_count(int drm_fd, enum pipe pipe, int count) igt_assert(drmWaitVBlank(drm_fd, &wait_vbl) == 0); } +/** + * igt_wait_for_vblank: + * @drm_fd: A drm file descriptor + * @pipe: Pipe to wait_for_vblank on + * + * Waits for 1 vertical blank intervals + */ void igt_wait_for_vblank(int drm_fd, enum pipe pipe) { igt_wait_for_vblank_count(drm_fd, pipe, 1); -- cgit v1.2.3