lib/igt_kms: Add some more documentation to some common kms functions.

Signed-off-by: Maarten Lankhorst <maarten.lankhorst@linux.intel.com>

2 files changed, 100 insertions, 8 deletions

diff --git a/lib/igt_kms.c b/lib/igt_kms.c
index 8b507b21..7d7a53c9 100644
--- a/lib/igt_kms.c
+++ b/lib/igt_kms.c
@@ -468,6 +468,8 @@ uint32_t kmstest_find_crtc_for_connector(int fd, drmModeRes *res,
  * @width: width of the buffer in pixels
  * @height: height of the buffer in pixels
  * @bpp: bytes per pixel of the buffer
+ * @stride: Pointer which receives the dumb bo's stride, can be NULL.
+ * @size: Pointer which receives the dumb bo's size, can be NULL.
  *
  * This wraps the CREATE_DUMB ioctl, which allocates a new dumb buffer object
  * for the specified dimensions.
@@ -2269,6 +2271,25 @@ static int do_display_commit(igt_display_t *display,
 	return 0;
 }
 
+/**
+ * igt_display_try_commit_atomic:
+ * @display: #igt_display_t to commit.
+ * @flags: Flags passed to drmModeAtomicCommit.
+ * @user_data: User defined pointer passed to drmModeAtomicCommit.
+ *
+ * This function is similar to #igt_display_try_commit2, but is
+ * used when you want to pass different flags to the actual commit.
+ *
+ * Useful flags can be DRM_MODE_ATOMIC_ALLOW_MODESET,
+ * DRM_MODE_ATOMIC_NONBLOCK, DRM_MODE_PAGE_FLIP_EVENT,
+ * or DRM_MODE_ATOMIC_TEST_ONLY.
+ *
+ * @user_data is returned in the event if you pass
+ * DRM_MODE_PAGE_FLIP_EVENT to @flags.
+ *
+ * This function will return an error if commit fails, instead of
+ * aborting the test.
+ */
 int igt_display_try_commit_atomic(igt_display_t *display, uint32_t flags, void *user_data)
 {
 	int ret;
@@ -2291,6 +2312,24 @@ int igt_display_try_commit_atomic(igt_display_t *display, uint32_t flags, void *
 	return 0;
 }
 
+/**
+ * igt_display_commit_atomic:
+ * @display: #igt_display_t to commit.
+ * @flags: Flags passed to drmModeAtomicCommit.
+ * @user_data: User defined pointer passed to drmModeAtomicCommit.
+ *
+ * This function is similar to #igt_display_commit2, but is
+ * used when you want to pass different flags to the actual commit.
+ *
+ * Useful flags can be DRM_MODE_ATOMIC_ALLOW_MODESET,
+ * DRM_MODE_ATOMIC_NONBLOCK, DRM_MODE_PAGE_FLIP_EVENT,
+ * or DRM_MODE_ATOMIC_TEST_ONLY.
+ *
+ * @user_data is returned in the event if you pass
+ * DRM_MODE_PAGE_FLIP_EVENT to @flags.
+ *
+ * This function will abort the test if commit fails.
+ */
 void igt_display_commit_atomic(igt_display_t *display, uint32_t flags, void *user_data)
 {
 	int ret = igt_display_try_commit_atomic(display, flags, user_data);
@@ -2715,6 +2754,7 @@ void igt_reset_connectors(void)
 
 /**
  * kmstest_get_vbl_flag:
+ * @pipe_id: Pipe to convert to flag representation.
  *
  * Convert a pipe id into the flag representation
  * expected in DRM while processing DRM_IOCTL_WAIT_VBLANK.
diff --git a/lib/igt_kms.h b/lib/igt_kms.h
index bc7825a3..005d7e8c 100644
--- a/lib/igt_kms.h
+++ b/lib/igt_kms.h
@@ -39,6 +39,15 @@
 
 /* Low-level helpers with kmstest_ prefix */
 
+/**
+ * pipe:
+ * @PIPE_NONE: Invalid pipe, used for disconnecting a output from a pipe.
+ * @PIPE_ANY: Deprecated alias for @PIPE_NONE.
+ * @PIPE_A: First crtc.
+ * @PIPE_B: Second crtc.
+ * @PIPE_C: Third crtc.
+ * @I915_MAX_PIPES: Max number of pipes allowed.
+ */
 enum pipe {
         PIPE_NONE = -1,
         PIPE_ANY = PIPE_NONE,
@@ -174,6 +183,13 @@ void *kmstest_dumb_map_buffer(int fd, uint32_t handle, uint64_t size,
  */
 
 /* High-level kms api with igt_ prefix */
+
+/**
+ * igt_commit_style:
+ * @COMMIT_LEGACY: Changes will be committed using the legacy API.
+ * @COMMIT_UNIVERSAL: Changes will be committed with the universal plane API, no modesets are allowed.
+ * @COMMIT_ATOMIC: Changes will be committed using the atomic API.
+ */
 enum igt_commit_style {
 	COMMIT_LEGACY = 0,
 	COMMIT_UNIVERSAL,
@@ -351,24 +367,50 @@ static inline bool igt_output_is_connected(igt_output_t *output)
 	return false;
 }
 
-static inline bool igt_pipe_connector_valid(enum pipe pipe,
-					    igt_output_t *output)
-{
-	return igt_output_is_connected(output) &&
-	       (output->config.valid_crtc_idx_mask & (1 << pipe));
-}
+/**
+ * igt_pipe_connector_valid:
+ * @pipe: pipe to check.
+ * @output: #igt_output_t to check.
+ *
+ * Checks whether the given pipe and output can be used together.
+ */
+#define igt_pipe_connector_valid(pipe, output) \
+	(igt_output_is_connected((output)) && \
+	       (output->config.valid_crtc_idx_mask & (1 << (pipe))))
 
 #define for_each_if(condition) if (!(condition)) {} else
 
+/**
+ * for_each_connected_output:
+ * @display: a pointer to an #igt_display_t structure
+ * @output: The output to iterate.
+ *
+ * This for loop iterates over all outputs.
+ */
 #define for_each_connected_output(display, output)		\
 	for (int i__ = 0;  i__ < (display)->n_outputs; i__++)	\
 		for_each_if (((output = &(display)->outputs[i__]), \
 			      igt_output_is_connected(output)))
 
+/**
+ * for_each_pipe:
+ * @display: a pointer to an #igt_display_t structure
+ * @pipe: The pipe to iterate.
+ *
+ * This for loop iterates over all pipes.
+ */
 #define for_each_pipe(display, pipe)					\
-	for (pipe = 0; pipe < igt_display_get_n_pipes(display); pipe++)	\
+	for (pipe = 0; pipe < igt_display_get_n_pipes(display); pipe++)
 
-/* Big complex macro to make 'break' work as expected. */
+/**
+ * for_each_pipe_with_valid_output:
+ * @display: a pointer to an #igt_display_t structure
+ * @pipe: The pipe for which this @pipe / @output combination is valid.
+ * @output: The output for which this @pipe / @output combination is valid.
+ *
+ * This for loop is called over all connected outputs. This function
+ * will try every combination of @pipe and @output.
+ */
 #define for_each_pipe_with_valid_output(display, pipe, output) \
 	for (int con__ = pipe = 0; \
 	     pipe < igt_display_get_n_pipes((display)) && con__ < (display)->n_outputs; \
@@ -376,6 +418,16 @@ static inline bool igt_pipe_connector_valid(enum pipe pipe,
 		for_each_if (((output = &(display)->outputs[con__]), \
 			     igt_pipe_connector_valid(pipe, output)))
 
+/**
+ * for_each_valid_output_on_pipe:
+ * @display: a pointer to an #igt_display_t structure
+ * @pipe: Pipe to enumerate valid outputs over
+ * @output: The enumerated output.
+ *
+ * This for loop is called over all connected @output that can be used
+ * on this @pipe . If there are no valid outputs for this pipe, nothing
+ * happens.
+ */
 #define for_each_valid_output_on_pipe(display, pipe, output) \
 	for_each_connected_output(display, output) \
 		for_each_if (igt_pipe_connector_valid(pipe, output))