From patchwork Fri Jan 15 09:06:41 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Marius Vlad X-Patchwork-Id: 8039291 Return-Path: X-Original-To: patchwork-intel-gfx@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork1.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork1.web.kernel.org (Postfix) with ESMTP id 98D9C9F6FA for ; Fri, 15 Jan 2016 09:05:35 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id E713C2044C for ; Fri, 15 Jan 2016 09:05:33 +0000 (UTC) Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) by mail.kernel.org (Postfix) with ESMTP id 36E13203E1 for ; Fri, 15 Jan 2016 09:05:32 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id A5A16A56E; Fri, 15 Jan 2016 01:05:31 -0800 (PST) X-Original-To: intel-gfx@lists.freedesktop.org Delivered-To: intel-gfx@lists.freedesktop.org Received: from mga04.intel.com (mga04.intel.com [192.55.52.120]) by gabe.freedesktop.org (Postfix) with ESMTP id E7D42A56E for ; Fri, 15 Jan 2016 01:05:30 -0800 (PST) Received: from orsmga002.jf.intel.com ([10.7.209.21]) by fmsmga104.fm.intel.com with ESMTP; 15 Jan 2016 01:05:30 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.22,298,1449561600"; d="scan'208";a="891012986" Received: from mcvlad-wk.rb.intel.com ([10.237.105.57]) by orsmga002.jf.intel.com with ESMTP; 15 Jan 2016 01:05:29 -0800 From: Marius Vlad To: intel-gfx@lists.freedesktop.org Date: Fri, 15 Jan 2016 11:06:41 +0200 Message-Id: <1452848802-8041-1-git-send-email-marius.c.vlad@intel.com> X-Mailer: git-send-email 2.6.4 Subject: [Intel-gfx] [PATCH i-g-t 1/2 v2] lib/igt_kms: Various fixes and add remaining documentation X-BeenThere: intel-gfx@lists.freedesktop.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: Intel graphics driver community testing & development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: intel-gfx-bounces@lists.freedesktop.org Sender: "Intel-gfx" X-Spam-Status: No, score=-4.2 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_MED, RP_MATCHES_RCVD, UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP lib/igt_kms: Fix minor spelling/gtk-doc links. Style changes -- trimmed several calls to asprintf(). Placed SECTION header at the beginning of the file. Add documentation for remaining functions and macros. v2: Initially, I wanted to aggregate the documentation in header file(s). This version keeps the initial format of the documentation. Signed-off-by: Marius Vlad --- lib/igt_kms.c | 160 +++++++++++++++++++++++++++++++++++++++++++--------------- lib/igt_kms.h | 123 ++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 236 insertions(+), 47 deletions(-) diff --git a/lib/igt_kms.c b/lib/igt_kms.c index 5d5a95c..c7a0b77 100644 --- a/lib/igt_kms.c +++ b/lib/igt_kms.c @@ -49,6 +49,30 @@ #include "intel_chipset.h" #include "igt_debugfs.h" +/** + * SECTION:igt_kms + * @short_description: Kernel modesetting support library + * @title: KMS + * @include: igt.h + * + * 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](intel-gpu-tools-Framebuffer.html) library as a + * dependency. + */ + /* list of connectors that need resetting on exit */ #define MAX_CONNECTORS 32 static char *forced_connectors[MAX_CONNECTORS + 1]; @@ -104,7 +128,7 @@ static void update_edid_csum(unsigned char *edid) * * Returns: a basic edid block */ -const unsigned char* igt_kms_get_base_edid(void) +const unsigned char *igt_kms_get_base_edid(void) { update_edid_csum(base_edid); @@ -145,7 +169,7 @@ const unsigned char* igt_kms_get_base_edid(void) * * Returns: an alternate edid block */ -const unsigned char* igt_kms_get_alt_edid(void) +const unsigned char *igt_kms_get_alt_edid(void) { update_edid_csum(alt_edid); @@ -153,33 +177,10 @@ const unsigned char* igt_kms_get_alt_edid(void) } /** - * SECTION:igt_kms - * @short_description: Kernel modesetting support library - * @title: KMS - * @include: igt.h - * - * 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](intel-gpu-tools-i-g-t-framebuffer.html) - * library as a dependency. - */ - -/** * kmstest_pipe_name: * @pipe: display pipe * - * Returns: String represnting @pipe, e.g. "A". + * Returns: String representing @pipe, e.g. "A". */ const char *kmstest_pipe_name(enum pipe pipe) { @@ -195,7 +196,7 @@ const char *kmstest_pipe_name(enum pipe pipe) * kmstest_plane_name: * @plane: display plane * - * Returns: String represnting @pipe, e.g. "plane1". + * Returns: String representing @pipe, e.g. "plane1". */ const char *kmstest_plane_name(enum igt_plane plane) { @@ -239,7 +240,7 @@ static const char *mode_stereo_name(const drmModeModeInfo *mode) * kmstest_dump_mode: * @mode: libdrm mode structure * - * Prints @mode to stdout in a huma-readable form. + * Prints @mode to stdout in a human-readable form. */ void kmstest_dump_mode(drmModeModeInfo *mode) { @@ -413,8 +414,9 @@ bool kmstest_force_connector(int drm_fd, drmModeConnector *connector, break; } - igt_assert_neq(asprintf(&path, "%s-%d/force", kmstest_connector_type_str(connector->connector_type), connector->connector_type_id), - -1); + igt_assert_neq(asprintf(&path, "%s-%d/force", + kmstest_connector_type_str(connector->connector_type), + connector->connector_type_id), -1); debugfs_fd = igt_debugfs_open(path, O_WRONLY | O_TRUNC); if (debugfs_fd == -1) { @@ -478,8 +480,9 @@ void kmstest_force_edid(int drm_fd, drmModeConnector *connector, int debugfs_fd, ret; drmModeConnector *temp; - igt_assert_neq(asprintf(&path, "%s-%d/edid_override", kmstest_connector_type_str(connector->connector_type), connector->connector_type_id), - -1); + igt_assert_neq(asprintf(&path, "%s-%d/edid_override", + kmstest_connector_type_str(connector->connector_type), + connector->connector_type_id), -1); debugfs_fd = igt_debugfs_open(path, O_WRONLY | O_TRUNC); free(path); @@ -491,8 +494,8 @@ void kmstest_force_edid(int drm_fd, drmModeConnector *connector, ret = write(debugfs_fd, edid, length); close(debugfs_fd); - /* To allow callers to always use GetConnectorCurrent we need to force a - * redetection here. */ + /* To allow callers to always use GetConnectorCurrent we need to force + * a redetection here. */ temp = drmModeGetConnector(drm_fd, connector->connector_id); drmModeFreeConnector(temp); @@ -901,8 +904,9 @@ static void igt_output_refresh(igt_output_t *output) if (!output->name) { drmModeConnector *c = output->config.connector; - igt_assert_neq(asprintf(&output->name, "%s-%d", kmstest_connector_type_str(c->connector_type), c->connector_type_id), - -1); + igt_assert_neq(asprintf(&output->name, "%s-%d", + kmstest_connector_type_str(c->connector_type), + c->connector_type_id), -1); } LOG(display, "%s: Selecting pipe %s\n", output->name, @@ -926,8 +930,9 @@ igt_plane_set_property(igt_plane_t *plane, uint32_t prop_id, uint64_t value) igt_pipe_t *pipe = plane->pipe; igt_display_t *display = pipe->display; - return drmModeObjectSetProperty(display->drm_fd, plane->drm_plane->plane_id, - DRM_MODE_OBJECT_PLANE, prop_id, value); + return drmModeObjectSetProperty(display->drm_fd, + plane->drm_plane->plane_id, + DRM_MODE_OBJECT_PLANE, prop_id, value); } static bool @@ -1145,6 +1150,12 @@ void igt_display_init(igt_display_t *display, int drm_fd) LOG_UNINDENT(display); } +/** + * igt_display_get_n_pipes: + * @display: the display on which to retrieve the number of pipes + * + * Returns: An integer with total number of pipes for that @display. + */ int igt_display_get_n_pipes(igt_display_t *display) { return display->n_pipes; @@ -1655,16 +1666,16 @@ static int do_display_commit(igt_display_t *display, * * 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 + * 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. + * #igt_try_display_commit2 instead. * * Returns: 0 upon success. This function will never return upon failure - * since igt_fail() at lower levels will longjmp out of it. + * since #igt_fail() at lower levels will longjmp out of it. */ int igt_display_commit2(igt_display_t *display, enum igt_commit_style s) @@ -1713,11 +1724,26 @@ int igt_display_commit(igt_display_t *display) return igt_display_commit2(display, COMMIT_LEGACY); } +/** + * igt_output_name: + * @output: Output of which we retrieve the name + * + * Returns: A string representing the name of @output. + */ const char *igt_output_name(igt_output_t *output) { return output->name; } +/** + * igt_output_get_mode: + * @output: Output as pointer to #igt_output_t + * + * Retrieves the default mode of @output + * + * Returns: a pointer to drmModeModeInfo + * + */ drmModeModeInfo *igt_output_get_mode(igt_output_t *output) { return &output->config.default_mode; @@ -1738,6 +1764,12 @@ void igt_output_override_mode(igt_output_t *output, drmModeModeInfo *mode) output->use_override_mode = true; } +/** + * igt_output_set_pipe: + * @output: Output of which the pipe will be overriden + * @pipe: one of #pipe + * + */ void igt_output_set_pipe(igt_output_t *output, enum pipe pipe) { igt_display_t *display = output->display; @@ -1752,6 +1784,14 @@ void igt_output_set_pipe(igt_output_t *output, enum pipe pipe) } } +/** + * igt_output_get_plane: + * @output: a pointer to #igt_output_t + * @plane: a #igt_plane plane + * + * Returns: a pointer to #igt_plane_t matching @plane + * + */ igt_plane_t *igt_output_get_plane(igt_output_t *output, enum igt_plane plane) { igt_pipe_t *pipe; @@ -1760,6 +1800,14 @@ igt_plane_t *igt_output_get_plane(igt_output_t *output, enum igt_plane plane) return igt_pipe_get_plane(pipe, plane); } +/** + * igt_plane_set_fb: + * @plane: plane pointer + * @fb: pointer to a #igt_fb + * + * Note: Sets the default plane size and position as framebuffers size. + * + */ void igt_plane_set_fb(igt_plane_t *plane, struct igt_fb *fb) { igt_pipe_t *pipe = plane->pipe; @@ -1789,6 +1837,13 @@ void igt_plane_set_fb(igt_plane_t *plane, struct igt_fb *fb) plane->size_changed = true; } +/** + * igt_plane_set_position: + * @plane: plane pointer for which the position should be set + * @x: the x-axis + * @y: the y-axis + * + */ void igt_plane_set_position(igt_plane_t *plane, int x, int y) { igt_pipe_t *pipe = plane->pipe; @@ -1878,6 +1933,13 @@ void igt_fb_set_size(struct igt_fb *fb, igt_plane_t *plane, plane->fb_changed = true; } +/** + * igt_plane_set_panning: + * @plane: plane pointer for which pannig should be set + * @x: specifies the x-axis + * @y: specifies the y-axis + * + */ void igt_plane_set_panning(igt_plane_t *plane, int x, int y) { igt_pipe_t *pipe = plane->pipe; @@ -1909,6 +1971,12 @@ static const char *rotation_name(igt_rotation_t rotation) } } +/** + * igt_plane_set_rotation: + * @plane: plane pointer for which rotation should be set + * @rotation: one of #igt_rotation_t + * + */ void igt_plane_set_rotation(igt_plane_t *plane, igt_rotation_t rotation) { igt_pipe_t *pipe = plane->pipe; @@ -1946,7 +2014,15 @@ void igt_crtc_set_background(igt_pipe_t *pipe, uint64_t background) pipe->background_changed = true; } - +/** + * igt_wait_for_vblank: + * @drm_fd: DRM fd + * @pipe: the pipe on which to wait for a vertical blank + * + * This functions can used to wait until the end of the frame and start of the + * next frame on @pipe, called a vblank. + * + */ void igt_wait_for_vblank(int drm_fd, enum pipe pipe) { drmVBlank wait_vbl; diff --git a/lib/igt_kms.h b/lib/igt_kms.h index 94f315f..a06964f 100644 --- a/lib/igt_kms.h +++ b/lib/igt_kms.h @@ -39,6 +39,12 @@ /* Low-level helpers with kmstest_ prefix */ +/** + * pipe: + * + * The front end of the display contains the pipes. There are three instances + * which are referred to as Pipe A, Pipe B, and Pipe C. + */ enum pipe { PIPE_ANY = -1, PIPE_A = 0, @@ -46,9 +52,20 @@ enum pipe { PIPE_C, I915_MAX_PIPES }; + const char *kmstest_pipe_name(enum pipe pipe); -/* We namespace this enum to not conflict with the Android i915_drm.h */ +/** + * igt_plane: + * + * Prior to GEN9, each display pipe had a primary plane, a overlay/sprite + * plane, and a cursor plane. From SKL/BXT each plane can be a primary plane, + * a sprite plane or an overlay plane. + * + * See #igt_display and #igt_display_init that retrieves this information. + * + * We namespace this enum to not conflict with the Android i915_drm.h. + */ enum igt_plane { IGT_PLANE_1 = 0, IGT_PLANE_PRIMARY = IGT_PLANE_1, @@ -57,7 +74,6 @@ enum igt_plane { IGT_PLANE_CURSOR, }; -const char *kmstest_plane_name(enum igt_plane plane); enum port { PORT_A = 0, @@ -68,6 +84,8 @@ enum port { I915_MAX_PORTS }; +const char *kmstest_plane_name(enum igt_plane plane); + /** * kmstest_port_name: * @port: display plane @@ -80,7 +98,11 @@ enum port { * kmstest_encoder_type_str: * @type: DRM_MODE_ENCODER_* enumeration value * + * Helper macro that defines this function + * can be found in [aux](intel-gpu-tools-aux.html). + * * Returns: A string representing the drm encoder @type. + * */ const char *kmstest_encoder_type_str(int type); @@ -88,6 +110,9 @@ const char *kmstest_encoder_type_str(int type); * kmstest_connector_status_str: * @status: DRM_MODE_* connector status value * + * Helper macro that defines this function + * can be found in [aux](intel-gpu-tools-aux.html). + * * Returns: A string representing the drm connector status @status. */ const char *kmstest_connector_status_str(int status); @@ -96,6 +121,9 @@ const char *kmstest_connector_status_str(int status); * kmstest_connector_type_str: * @type: DRM_MODE_CONNECTOR_* enumeration value * + * Helper macro that defines this function + * can be found in [aux](intel-gpu-tools-aux.html). + * * Returns: A string representing the drm connector @type. */ const char *kmstest_connector_type_str(int type); @@ -106,6 +134,19 @@ int kmstest_get_pipe_from_crtc_id(int fd, int crtc_id); void kmstest_set_vt_graphics_mode(void); void kmstest_restore_vt_mode(void); +/** + * kmstest_connector_config: + * @crtc: DRM pipe, pointer to #drmModeCrtc + * @connector: end-point connector; pointer to #drmModeConnector + * @encoder: pointer to #drmModeEncoder + * @default_mode: default mode found + * @crtc_idx: pipe found when searching for available connectors + * @pipe: this translates directly to #pipe + * + * Structure used to retrieve encoders, connectors and pipes + * with the help of #kmstest_get_connector_config(). + * + */ struct kmstest_connector_config { drmModeCrtc *crtc; drmModeConnector *connector; @@ -131,7 +172,9 @@ enum kmstest_force_connector_state { bool kmstest_force_connector(int fd, drmModeConnector *connector, enum kmstest_force_connector_state state); -void kmstest_edid_add_3d(const unsigned char *edid, size_t length, unsigned char *new_edid_ptr[], size_t *new_length); +void kmstest_edid_add_3d(const unsigned char *edid, size_t length, + unsigned char *new_edid_ptr[], size_t *new_length); + void kmstest_force_edid(int drm_fd, drmModeConnector *connector, const unsigned char *edid, size_t length); @@ -159,12 +202,33 @@ enum igt_commit_style { /* We'll add atomic here eventually. */ }; +/** + * igt_display_t: + * + * see #igt_display + */ typedef struct igt_display igt_display_t; + +/** + * igt_pipe_t: + * + * see #igt_pipe + */ typedef struct igt_pipe igt_pipe_t; -typedef uint32_t igt_fixed_t; /* 16.16 fixed point */ +/** + * igt_fixed_t: + * + * 16.16 fixed point + */ +typedef uint32_t igt_fixed_t; + +/** + * igt_rotation_t: + * + * this maps to the kernel API + */ typedef enum { - /* this maps to the kernel API */ IGT_ROTATION_0 = 1 << 0, IGT_ROTATION_90 = 1 << 1, IGT_ROTATION_180 = 1 << 2, @@ -202,6 +266,21 @@ typedef struct { igt_rotation_t rotation; } igt_plane_t; +/** + * igt_pipe: + * @display: a pointer to #igt_display_t + * @pipe: which pipe see #pipe + * @enabled: if this pipe is enabled + * @n_planes: number of planes for this pipe + * @planes: array of #igt_planes_t + * @background: Background color MSB BGR 16bpc LSB + * @background_changed: if the background has changed + * @background_property: background property + * + * Representation of a pipe, that connects to #igt_plane_t and + * #igt_display_t. + * + */ struct igt_pipe { igt_display_t *display; enum pipe pipe; @@ -226,6 +305,18 @@ typedef struct { drmModeModeInfo override_mode; } igt_output_t; +/** + * igt_display: + * @drm_fd: DRM fd + * @log_shift: useful for logging; see #LOG_INDENT + * @n_pipes: number of pipes + * @n_outputs: number of outputs + * @pipes_in_use: how many pipes are in use + * @outputs: a pointer to #igt_output_t; see #igt_display_init + * @pipes: array of #igt_pipe_t + * @has_universal_planes: if the hardware supports universal planes + * + */ struct igt_display { int drm_fd; int log_shift; @@ -268,13 +359,35 @@ void igt_fb_set_size(struct igt_fb *fb, igt_plane_t *plane, void igt_wait_for_vblank(int drm_fd, enum pipe pipe); +/** + * for_each_connected_output: + * @display: a pointer to #igt_display_t which contains the display + * @output: a pointer to #igt_output_t to determine if the output is valid + * + * Iterate over all connectors of a display. + */ #define for_each_connected_output(display, output) \ for (int i__ = 0; i__ < (display)->n_outputs; i__++) \ if ((output = &(display)->outputs[i__]), output->valid) +/** + * for_each_pipe: + * @display: a pointerto #igt_display_t + * @pipe: a #pipe type as a loop cursor + * + * Iterate over the pipes of a display. + */ #define for_each_pipe(display, pipe) \ for (pipe = 0; pipe < igt_display_get_n_pipes(display); pipe++) \ +/** + * for_each_plane_on_pipe: + * @display: a pointer to #igt_display_t + * @pipe: a #pipe type as a indexer into #igt_display:pipes + * @plane: a pointer to #igt_plane_t as a loop cursor + * + * Iterate over the planes of a pipe. + */ #define for_each_plane_on_pipe(display, pipe, plane) \ for (int i__ = 0; (plane) = &(display)->pipes[(pipe)].planes[i__], \ i__ < (display)->pipes[(pipe)].n_planes; i__++)