[PATCH i-g-t 1/2 v2] lib/igt_kms: Various fixes and add remaining documentation

[Marius Vlad <marius.c.vlad@intel.com>]

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 <marius.c.vlad@intel.com>
---
 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__++)
-- 
2.6.2

_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx