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@xxxxxxxxx>
---
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@xxxxxxxxxxxxxxxxxxxxx
http://lists.freedesktop.org/mailman/listinfo/intel-gfx
