Skip to contentSkip to conversation

lib/igt_kms: Various fixes and add remaining documentation

PATCH New Marius Vlad 3 participants 6 messages Jan 15, 2016 – Jan 19, 2016 Library code

lore
Share & tools
lore
#0 lore raw

PATCH v2 1/2 lib/igt_kms: Various fixes and add remaining documentation

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.

---
 lib/igt_kms.c | 160 +++++++++++++++++++++++++++++++++++++++++++---------------
 lib/igt_kms.h | 123 ++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 236 insertions(+), 47 deletions(-)
lib/igt_kms.c +118 -42
index 5d5a95c..c7a0b77 100644
@@ -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;
lib/igt_kms.h +118 -5

215 lines not on this page · raw message

Signature · 6 lines
2.6.2

_______________________________________________
Intel-gfx mailing list
[email protected]
http://lists.freedesktop.org/mailman/listinfo/intel-gfx
#1 lore raw

PATCH 2/2 lib/igt_kms: Short description between Intel/DRM terminology.

lib/igt_kms: Briefly describe Intel-to-DRM mapping between pipes, encoders and connectors.

---
 lib/igt_kms.c | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)
lib/igt_kms.c +82 -0
index c7a0b77..caa8837 100644
@@ -68,6 +68,88 @@
  * 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.
  *
+ * Intel/DRM terminology and display connections:
+ *
+ * Intel documentation describes the road from memory to an output connector as
+ * follows:
+ *
+ * |[!<-- language="C" -->
+ * .--------.     .-------.     .-------------.     .-----.
+ * | Memory |---->| Pipes |---->| Transcoders |---->| DDI |
+ * '--------'     '-------'     '-------------'     '-----'
+ * ]|
+ *
+ * Pipes represent the front-end of the display contain the planes, blending,
+ * and color correction, while the transcoders contain timing generators,
+ * encoders, A/V mixers and PSR (Panel-Self Refresh) controllers. Finally the
+ * DDI represent the connectors attached to the display.
+ *
+ *
+ *  In DRM we have the following:
+ *
+ * |[!<-- language="C" -->
+ * .-----------.     .-------.     .-----------.     .------------.
+ * | Framebuff |---->| Pipes |---->| Encoders  |---->| Connectors |
+ * '-----------'     '-------'     '-----------'     '------------'
+ * ]|
+ *
+ *
+ * The frame buffer ties a reference to a memory object and provides a pointer
+ * to the actual data.
+ *
+ * The pipe is used to set the display mode, timings and gamma tables. On some
+ * hardware models this is tied with the transcoder.  In DRM-parlance this is
+ * referred as a CRTC.
+ *
+ * Each pipe has multiple planes. On older hardware these planes where known as
+ * primary plane, overlay/sprite plane, and cursor plane. From GEN9 (SKL/BXT)
+ * each pipe has three planes and a cursor plane. Each plane can be used as a
+ * primary, as a sprite or as an overlay plane. The planes are the ones that
+ * retrieve the pixels from memory and pushes them to the encoder.
+ *
+ * A pipe prior to GEN9:
+ *
+ * |[!<-- language="C" -->
+ * .--------.
+ * | Memory |             .--------.
+ * |        |------------>| Cursor |------>...
+ * |        |             '--------'
+ * |        |
+ * |        |         .--------.
+ * |        |-------->| Sprite |---------->...
+ * |        |         '--------'
+ * |        |
+ * |        |      .---------.
+ * |        |----->| Primary |------------>...
+ * |        |      '---------'
+ * '--------'
+ * ]|
+ *
+ * A pipe with universal planes:
+ *
+ * |[!<-- language="C" -->
+ * .--------.
+ * | Memory |             .--------.
+ * |        |------------>| Cursor |------>...
+ * |        |             '--------'
+ * |        |
+ * |        |         .-------.
+ * |        |-------->| Plane |---------->...
+ * |        |         '-------'
+ * |        |
+ * |        |      .-------.
+ * |        |----->| Plane |------------>...
+ * |        |      '-------'
+ * '--------'
+ * ]|
+ *
+ * The encoder is used to convert, depending on the output, pixels from pipes
+ * to signals understood by the connector.
+ *
+ * The connector will connect to the output display. This contains information
+ * about the attached display such as EDID, DPMS and information about modes
+ * supported by the display.
+ *
  * Note that this library's header pulls in the [i-g-t
  * framebuffer](intel-gpu-tools-Framebuffer.html) library as a
  * dependency.
Signature · 6 lines
2.6.2

_______________________________________________
Intel-gfx mailing list
[email protected]
http://lists.freedesktop.org/mailman/listinfo/intel-gfx
#2 lore raw

Re: [PATCH i-g-t 2/2] lib/igt_kms: Short description between Intel/DRM terminology.

Quoted 29 lines · Marius Vlad

lib/igt_kms: Briefly describe Intel-to-DRM mapping between pipes, encoders and connectors.

---
 lib/igt_kms.c | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)
lib/igt_kms.c +13 -0
index c7a0b77..caa8837 100644
@@ -68,6 +68,88 @@
  * 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.
  *
+ * Intel/DRM terminology and display connections:
+ *
+ * Intel documentation describes the road from memory to an output connector as
+ * follows:
+ *
+ * |[!<-- language="C" -->
+ * .--------.     .-------.     .-------------.     .-----.
+ * | Memory |---->| Pipes |---->| Transcoders |---->| DDI |
+ * '--------'     '-------'     '-------------'     '-----'
+ * ]|
+ *
+ * Pipes represent the front-end of the display contain the planes, blending,
+ * and color correction, while the transcoders contain timing generators,

lib/igt_kms.c line 93

Quoted 10 lines
lib/igt_kms.c +10 -0
+ * encoders, A/V mixers and PSR (Panel-Self Refresh) controllers. Finally the
+ * DDI represent the connectors attached to the display.
+ *
+ *
+ *  In DRM we have the following:
+ *
+ * |[!<-- language="C" -->
+ * .-----------.     .-------.     .-----------.     .------------.
+ * | Framebuff |---->| Pipes |---->| Encoders  |---->| Connectors |
+ * '-----------'     '-------'     '-----------'     '------------'

"Framebuff"?

Also should this say crtc instead of pipe?

lib/igt_kms.c

Quoted 13 lines
lib/igt_kms.c +13 -0
+ * ]|
+ *
+ *
+ * The frame buffer ties a reference to a memory object and provides a pointer
+ * to the actual data.
+ *
+ * The pipe is used to set the display mode, timings and gamma tables. On some
+ * hardware models this is tied with the transcoder.  In DRM-parlance this is
+ * referred as a CRTC.
+ *
+ * Each pipe has multiple planes. On older hardware these planes where known as
+ * primary plane, overlay/sprite plane, and cursor plane. From GEN9 (SKL/BXT)
+ * each pipe has three planes and a cursor plane.

Not quite true.

Quoted 5 lines

Each plane can be used as a
+ * primary, as a sprite or as an overlay plane. The planes are the ones that
+ * retrieve the pixels from memory and pushes them to the encoder.
+ *
+ * A pipe prior to GEN9:

Really more like g4x-bdw. Before g4x it was totally different, and gen4 was sort of mix of both the old and the new. And vlv/chv have two sprites on each pipe.

So given all the variations in the hardware, and the fact that it keeps changing all the time, I'm not convinced there's any point in documenting this in igt. It'll get stale real quick, and there are efforts to decouple igt from i915 as much as possible, so next thing you know someone else will want to docuemnt their favorite hardware here as well.

So if we do want to document this stuff, then I think it should be somewhere in the kernel modeset code (around crtc/plane init I suppose).

Quoted 52 lines

+ *
+ * |[!<-- language="C" -->
+ * .--------.

+ * | Memory |             .--------.
+ * |        |------------>| Cursor |------>...
+ * |        |             '--------'
+ * |        |
+ * |        |         .--------.
+ * |        |-------->| Sprite |---------->...
+ * |        |         '--------'
+ * |        |
+ * |        |      .---------.
+ * |        |----->| Primary |------------>...
+ * |        |      '---------'

+ * '--------'
+ * ]|
+ *
+ * A pipe with universal planes:
+ *
+ * |[!<-- language="C" -->
+ * .--------.

+ * | Memory |             .--------.
+ * |        |------------>| Cursor |------>...
+ * |        |             '--------'
+ * |        |
+ * |        |         .-------.
+ * |        |-------->| Plane |---------->...
+ * |        |         '-------'
+ * |        |
+ * |        |      .-------.
+ * |        |----->| Plane |------------>...
+ * |        |      '-------'

+ * '--------'
+ * ]|
+ *
+ * The encoder is used to convert, depending on the output, pixels from pipes
+ * to signals understood by the connector.
+ *
+ * The connector will connect to the output display. This contains information
+ * about the attached display such as EDID, DPMS and information about modes
+ * supported by the display.
+ *
* Note that this library's header pulls in the [i-g-t
* framebuffer](intel-gpu-tools-Framebuffer.html) library as a
* dependency.

Signature · 6 lines
2.6.2

_______________________________________________
Intel-gfx mailing list
[email protected]
http://lists.freedesktop.org/mailman/listinfo/intel-gfx
Signature · 6 lines
Ville Syrjälä
Intel OTC
_______________________________________________
Intel-gfx mailing list
[email protected]
http://lists.freedesktop.org/mailman/listinfo/intel-gfx
#3 lore raw

Re: [PATCH i-g-t 2/2] lib/igt_kms: Short description between Intel/DRM terminology.

Quoted 43 lines · Ville Syrjälä
Quoted 29 lines · Marius Vlad

lib/igt_kms: Briefly describe Intel-to-DRM mapping between pipes, encoders and connectors.

---
 lib/igt_kms.c | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)
lib/igt_kms.c +13 -0
index c7a0b77..caa8837 100644
@@ -68,6 +68,88 @@
  * 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.
  *
+ * Intel/DRM terminology and display connections:
+ *
+ * Intel documentation describes the road from memory to an output connector as
+ * follows:
+ *
+ * |[!<-- language="C" -->
+ * .--------.     .-------.     .-------------.     .-----.
+ * | Memory |---->| Pipes |---->| Transcoders |---->| DDI |
+ * '--------'     '-------'     '-------------'     '-----'
+ * ]|
+ *
+ * Pipes represent the front-end of the display contain the planes, blending,
+ * and color correction, while the transcoders contain timing generators,

lib/igt_kms.c line 93

Quoted 10 lines
lib/igt_kms.c +10 -0
+ * encoders, A/V mixers and PSR (Panel-Self Refresh) controllers. Finally the
+ * DDI represent the connectors attached to the display.
+ *
+ *
+ *  In DRM we have the following:
+ *
+ * |[!<-- language="C" -->
+ * .-----------.     .-------.     .-----------.     .------------.
+ * | Framebuff |---->| Pipes |---->| Encoders  |---->| Connectors |
+ * '-----------'     '-------'     '-----------'     '------------'

"Framebuff"?

Quoted 1 line

Also should this say crtc instead of pipe?

Right, pipe indeed.

Quoted 34 lines
Quoted 4 lines
lib/igt_kms.c +3 -0
+ * ]|
+ *
+ *

lib/igt_kms.c

Quoted 10 lines
lib/igt_kms.c +10 -0
+ * The frame buffer ties a reference to a memory object and provides a pointer
+ * to the actual data.
+ *
+ * The pipe is used to set the display mode, timings and gamma tables. On some
+ * hardware models this is tied with the transcoder.  In DRM-parlance this is
+ * referred as a CRTC.
+ *
+ * Each pipe has multiple planes. On older hardware these planes where known as
+ * primary plane, overlay/sprite plane, and cursor plane. From GEN9 (SKL/BXT)
+ * each pipe has three planes and a cursor plane.

Not quite true.

Quoted 5 lines

Each plane can be used as a
+ * primary, as a sprite or as an overlay plane. The planes are the ones that
+ * retrieve the pixels from memory and pushes them to the encoder.
+ *
+ * A pipe prior to GEN9:

Really more like g4x-bdw. Before g4x it was totally different, and gen4 was sort of mix of both the old and the new. And vlv/chv have two sprites on each pipe.

So given all the variations in the hardware, and the fact that it keeps changing all the time, I'm not convinced there's any point in documenting this in igt. It'll get stale real quick, and there are efforts to decouple igt from i915 as much as possible, so next thing you know someone else will want to docuemnt their favorite hardware here as well.

Quoted 2 lines

So if we do want to document this stuff, then I think it should be somewhere in the kernel modeset code (around crtc/plane init I suppose).

Yes, it might make more sense to be in the kernel. What I wanted to achieve with this small intro was to bridge the gap between DRM terminology and the one in Intel 01.org PRM for igt. For a first timer is rather tedious to identify software/hadware abstraction when looking at the PRMs and when looking in igt -- I know for a fact that I'm still having trouble identifying those parts.

Daniel has already suggested to add some documention between DRM-to-Intel Mappings in the kernel.

Do you suggest that we should document all platforms?

Quoted 49 lines
Quoted 49 lines

+ *
+ * |[!<-- language="C" -->
+ * .--------.

+ * | Memory |             .--------.
+ * |        |------------>| Cursor |------>...
+ * |        |             '--------'
+ * |        |
+ * |        |         .--------.
+ * |        |-------->| Sprite |---------->...
+ * |        |         '--------'
+ * |        |
+ * |        |      .---------.
+ * |        |----->| Primary |------------>...
+ * |        |      '---------'

+ * '--------'
+ * ]|
+ *
+ * A pipe with universal planes:
+ *
+ * |[!<-- language="C" -->
+ * .--------.

+ * | Memory |             .--------.
+ * |        |------------>| Cursor |------>...
+ * |        |             '--------'
+ * |        |
+ * |        |         .-------.
+ * |        |-------->| Plane |---------->...
+ * |        |         '-------'
+ * |        |
+ * |        |      .-------.
+ * |        |----->| Plane |------------>...
+ * |        |      '-------'

+ * '--------'
+ * ]|
+ *
+ * The encoder is used to convert, depending on the output, pixels from pipes
+ * to signals understood by the connector.
+ *
+ * The connector will connect to the output display. This contains information
+ * about the attached display such as EDID, DPMS and information about modes
+ * supported by the display.
+ *
* Note that this library's header pulls in the [i-g-t
* framebuffer](intel-gpu-tools-Framebuffer.html) library as a
* dependency.

Signature · 1 line
2.6.2
Quoted 8 lines
Quoted 4 lines

_______________________________________________
Intel-gfx mailing list
[email protected]
http://lists.freedesktop.org/mailman/listinfo/intel-gfx

Signature · 2 lines
Ville Syrjälä
Intel OTC

_______________________________________________
Intel-gfx mailing list
[email protected]
http://lists.freedesktop.org/mailman/listinfo/intel-gfx

#4 lore raw

Re: [PATCH i-g-t 2/2] lib/igt_kms: Short description between Intel/DRM terminology.

Quoted 90 lines · Marius Vlad
Quoted 43 lines · Ville Syrjälä
Quoted 29 lines · Marius Vlad

lib/igt_kms: Briefly describe Intel-to-DRM mapping between pipes, encoders and connectors.

---
 lib/igt_kms.c | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)
lib/igt_kms.c +13 -0
index c7a0b77..caa8837 100644
@@ -68,6 +68,88 @@
  * 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.
  *
+ * Intel/DRM terminology and display connections:
+ *
+ * Intel documentation describes the road from memory to an output connector as
+ * follows:
+ *
+ * |[!<-- language="C" -->
+ * .--------.     .-------.     .-------------.     .-----.
+ * | Memory |---->| Pipes |---->| Transcoders |---->| DDI |
+ * '--------'     '-------'     '-------------'     '-----'
+ * ]|
+ *
+ * Pipes represent the front-end of the display contain the planes, blending,
+ * and color correction, while the transcoders contain timing generators,

lib/igt_kms.c line 93

Quoted 10 lines
lib/igt_kms.c +10 -0
+ * encoders, A/V mixers and PSR (Panel-Self Refresh) controllers. Finally the
+ * DDI represent the connectors attached to the display.
+ *
+ *
+ *  In DRM we have the following:
+ *
+ * |[!<-- language="C" -->
+ * .-----------.     .-------.     .-----------.     .------------.
+ * | Framebuff |---->| Pipes |---->| Encoders  |---->| Connectors |
+ * '-----------'     '-------'     '-----------'     '------------'

"Framebuff"?

Quoted 1 line

Also should this say crtc instead of pipe?

Right, pipe indeed.

Quoted 34 lines
Quoted 4 lines
lib/igt_kms.c +3 -0
+ * ]|
+ *
+ *

lib/igt_kms.c

Quoted 10 lines
lib/igt_kms.c +10 -0
+ * The frame buffer ties a reference to a memory object and provides a pointer
+ * to the actual data.
+ *
+ * The pipe is used to set the display mode, timings and gamma tables. On some
+ * hardware models this is tied with the transcoder.  In DRM-parlance this is
+ * referred as a CRTC.
+ *
+ * Each pipe has multiple planes. On older hardware these planes where known as
+ * primary plane, overlay/sprite plane, and cursor plane. From GEN9 (SKL/BXT)
+ * each pipe has three planes and a cursor plane.

Not quite true.

Quoted 5 lines

Each plane can be used as a
+ * primary, as a sprite or as an overlay plane. The planes are the ones that
+ * retrieve the pixels from memory and pushes them to the encoder.
+ *
+ * A pipe prior to GEN9:

Really more like g4x-bdw. Before g4x it was totally different, and gen4 was sort of mix of both the old and the new. And vlv/chv have two sprites on each pipe.

So given all the variations in the hardware, and the fact that it keeps changing all the time, I'm not convinced there's any point in documenting this in igt. It'll get stale real quick, and there are efforts to decouple igt from i915 as much as possible, so next thing you know someone else will want to docuemnt their favorite hardware here as well.

Quoted 2 lines

So if we do want to document this stuff, then I think it should be somewhere in the kernel modeset code (around crtc/plane init I suppose).

Yes, it might make more sense to be in the kernel. What I wanted to achieve with this small intro was to bridge the gap between DRM terminology and the one in Intel 01.org PRM for igt. For a first timer is rather tedious to identify software/hadware abstraction when looking at the PRMs and when looking in igt -- I know for a fact that I'm still having trouble identifying those parts.

Quoted 4 lines

Daniel has already suggested to add some documention between DRM-to-Intel Mappings in the kernel.

Do you suggest that we should document all platforms?

I'd either keep it fairly generic, or document all of them. What you had here seemed like something in between.

Quoted 59 lines
Quoted 59 lines
Quoted 55 lines

+ *
+ * |[!<-- language="C" -->
+ * .--------.

+ * | Memory |             .--------.
+ * |        |------------>| Cursor |------>...
+ * |        |             '--------'
+ * |        |
+ * |        |         .--------.
+ * |        |-------->| Sprite |---------->...
+ * |        |         '--------'
+ * |        |
+ * |        |      .---------.
+ * |        |----->| Primary |------------>...
+ * |        |      '---------'

+ * '--------'
+ * ]|
+ *
+ * A pipe with universal planes:
+ *
+ * |[!<-- language="C" -->
+ * .--------.

+ * | Memory |             .--------.
+ * |        |------------>| Cursor |------>...
+ * |        |             '--------'
+ * |        |
+ * |        |         .-------.
+ * |        |-------->| Plane |---------->...
+ * |        |         '-------'
+ * |        |
+ * |        |      .-------.
+ * |        |----->| Plane |------------>...
+ * |        |      '-------'

+ * '--------'
+ * ]|
+ *
+ * The encoder is used to convert, depending on the output, pixels from pipes
+ * to signals understood by the connector.
+ *
+ * The connector will connect to the output display. This contains information
+ * about the attached display such as EDID, DPMS and information about modes
+ * supported by the display.
+ *
* Note that this library's header pulls in the [i-g-t
* framebuffer](intel-gpu-tools-Framebuffer.html) library as a
* dependency.

Signature · 6 lines
2.6.2

_______________________________________________
Intel-gfx mailing list
[email protected]
http://lists.freedesktop.org/mailman/listinfo/intel-gfx
Signature · 2 lines
Ville Syrjälä
Intel OTC
Signature · 6 lines
Ville Syrjälä
Intel OTC
_______________________________________________
Intel-gfx mailing list
[email protected]
http://lists.freedesktop.org/mailman/listinfo/intel-gfx
#5 lore raw

Re: [PATCH i-g-t 2/2] lib/igt_kms: Short description between Intel/DRM terminology.

Quoted 91 lines · Ville Syrjälä
Quoted 90 lines · Marius Vlad
Quoted 43 lines · Ville Syrjälä
Quoted 29 lines · Marius Vlad

lib/igt_kms: Briefly describe Intel-to-DRM mapping between pipes, encoders and connectors.

---
 lib/igt_kms.c | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)
lib/igt_kms.c +13 -0
index c7a0b77..caa8837 100644
@@ -68,6 +68,88 @@
  * 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.
  *
+ * Intel/DRM terminology and display connections:
+ *
+ * Intel documentation describes the road from memory to an output connector as
+ * follows:
+ *
+ * |[!<-- language="C" -->
+ * .--------.     .-------.     .-------------.     .-----.
+ * | Memory |---->| Pipes |---->| Transcoders |---->| DDI |
+ * '--------'     '-------'     '-------------'     '-----'
+ * ]|
+ *
+ * Pipes represent the front-end of the display contain the planes, blending,
+ * and color correction, while the transcoders contain timing generators,

lib/igt_kms.c line 93

Quoted 10 lines
lib/igt_kms.c +10 -0
+ * encoders, A/V mixers and PSR (Panel-Self Refresh) controllers. Finally the
+ * DDI represent the connectors attached to the display.
+ *
+ *
+ *  In DRM we have the following:
+ *
+ * |[!<-- language="C" -->
+ * .-----------.     .-------.     .-----------.     .------------.
+ * | Framebuff |---->| Pipes |---->| Encoders  |---->| Connectors |
+ * '-----------'     '-------'     '-----------'     '------------'

"Framebuff"?

Quoted 1 line

Also should this say crtc instead of pipe?

Right, pipe indeed.

Quoted 34 lines
Quoted 4 lines
lib/igt_kms.c +3 -0
+ * ]|
+ *
+ *

lib/igt_kms.c

Quoted 10 lines
lib/igt_kms.c +10 -0
+ * The frame buffer ties a reference to a memory object and provides a pointer
+ * to the actual data.
+ *
+ * The pipe is used to set the display mode, timings and gamma tables. On some
+ * hardware models this is tied with the transcoder.  In DRM-parlance this is
+ * referred as a CRTC.
+ *
+ * Each pipe has multiple planes. On older hardware these planes where known as
+ * primary plane, overlay/sprite plane, and cursor plane. From GEN9 (SKL/BXT)
+ * each pipe has three planes and a cursor plane.

Not quite true.

Quoted 5 lines

Each plane can be used as a
+ * primary, as a sprite or as an overlay plane. The planes are the ones that
+ * retrieve the pixels from memory and pushes them to the encoder.
+ *
+ * A pipe prior to GEN9:

Really more like g4x-bdw. Before g4x it was totally different, and gen4 was sort of mix of both the old and the new. And vlv/chv have two sprites on each pipe.

So given all the variations in the hardware, and the fact that it keeps changing all the time, I'm not convinced there's any point in documenting this in igt. It'll get stale real quick, and there are efforts to decouple igt from i915 as much as possible, so next thing you know someone else will want to docuemnt their favorite hardware here as well.

Quoted 2 lines

So if we do want to document this stuff, then I think it should be somewhere in the kernel modeset code (around crtc/plane init I suppose).

Yes, it might make more sense to be in the kernel. What I wanted to achieve with this small intro was to bridge the gap between DRM terminology and the one in Intel 01.org PRM for igt. For a first timer is rather tedious to identify software/hadware abstraction when looking at the PRMs and when looking in igt -- I know for a fact that I'm still having trouble identifying those parts.

Quoted 7 lines
Quoted 4 lines

Daniel has already suggested to add some documention between DRM-to-Intel Mappings in the kernel.

Do you suggest that we should document all platforms?

I'd either keep it fairly generic, or document all of them. What you had here seemed like something in between.

Yeah I still think bridging the terminology gap in igt/drm would be good, but indeed a bit more high-level might work better. And I agree with Ville that the detailed docs are probably best in the kernel, next to the actual paltform support code.
-Daniel

Quoted 66 lines
Quoted 60 lines
Quoted 60 lines
Quoted 56 lines

+ *
+ * |[!<-- language="C" -->
+ * .--------.

+ * | Memory |             .--------.
+ * |        |------------>| Cursor |------>...
+ * |        |             '--------'
+ * |        |
+ * |        |         .--------.
+ * |        |-------->| Sprite |---------->...
+ * |        |         '--------'
+ * |        |
+ * |        |      .---------.
+ * |        |----->| Primary |------------>...
+ * |        |      '---------'

+ * '--------'
+ * ]|
+ *
+ * A pipe with universal planes:
+ *
+ * |[!<-- language="C" -->
+ * .--------.

+ * | Memory |             .--------.
+ * |        |------------>| Cursor |------>...
+ * |        |             '--------'
+ * |        |
+ * |        |         .-------.
+ * |        |-------->| Plane |---------->...
+ * |        |         '-------'
+ * |        |
+ * |        |      .-------.
+ * |        |----->| Plane |------------>...
+ * |        |      '-------'

+ * '--------'
+ * ]|
+ *
+ * The encoder is used to convert, depending on the output, pixels from pipes
+ * to signals understood by the connector.
+ *
+ * The connector will connect to the output display. This contains information
+ * about the attached display such as EDID, DPMS and information about modes
+ * supported by the display.
+ *
* Note that this library's header pulls in the [i-g-t
* framebuffer](intel-gpu-tools-Framebuffer.html) library as a
* dependency.

Signature · 6 lines
2.6.2

_______________________________________________
Intel-gfx mailing list
[email protected]
http://lists.freedesktop.org/mailman/listinfo/intel-gfx
Signature · 2 lines
Ville Syrjälä
Intel OTC
Signature · 2 lines
Ville Syrjälä
Intel OTC
Signature · 7 lines
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
Intel-gfx mailing list
[email protected]
http://lists.freedesktop.org/mailman/listinfo/intel-gfx