lib: update docs for igt_pm

- Move all the pm helpers into igt_pm.c. No idea why that wasn't done
  in the original commit that created igt_pm.c.
- Add missing docs where needed.

Cc: David Weinehall <david.weinehall@intel.com>
Cc: Paulo Zanoni <paulo.r.zanoni@intel.com>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>

4 files changed, 140 insertions, 128 deletions

diff --git a/lib/igt_aux.c b/lib/igt_aux.c
index 1cb93984..5eaf35ec 100644
--- a/lib/igt_aux.c
+++ b/lib/igt_aux.c
@@ -62,7 +62,6 @@
 #include "intel_reg.h"
 #include "ioctl_wrappers.h"
 #include "igt_kms.h"
-#include "igt_pm.h"
 #include "igt_stats.h"
 
 /**
@@ -791,111 +790,6 @@ void igt_debug_manual_check(const char *var, const char *expected)
 	igt_assert(key != 'n' && key != 'N');
 }
 
-#define POWER_DIR "/sys/devices/pci0000:00/0000:00:02.0/power"
-/* We just leak this on exit ... */
-int pm_status_fd = -1;
-
-/**
- * igt_setup_runtime_pm:
- *
- * Sets up the runtime PM helper functions and enables runtime PM. To speed up
- * tests the autosuspend delay is set to 0.
- *
- * Returns:
- * True if runtime pm is available, false otherwise.
- */
-bool igt_setup_runtime_pm(void)
-{
-	int fd;
-	ssize_t size;
-	char buf[6];
-
-	if (pm_status_fd >= 0)
-		return true;
-
-	igt_pm_enable_audio_runtime_pm();
-
-	/* Our implementation uses autosuspend. Try to set it to 0ms so the test
-	 * suite goes faster and we have a higher probability of triggering race
-	 * conditions. */
-	fd = open(POWER_DIR "/autosuspend_delay_ms", O_WRONLY);
-	igt_assert_f(fd >= 0,
-		     "Can't open " POWER_DIR "/autosuspend_delay_ms\n");
-
-	/* If we fail to write to the file, it means this system doesn't support
-	 * runtime PM. */
-	size = write(fd, "0\n", 2);
-
-	close(fd);
-
-	if (size != 2)
-		return false;
-
-	/* We know we support runtime PM, let's try to enable it now. */
-	fd = open(POWER_DIR "/control", O_RDWR);
-	igt_assert_f(fd >= 0, "Can't open " POWER_DIR "/control\n");
-
-	size = write(fd, "auto\n", 5);
-	igt_assert(size == 5);
-
-	lseek(fd, 0, SEEK_SET);
-	size = read(fd, buf, ARRAY_SIZE(buf));
-	igt_assert(size == 5);
-	igt_assert(strncmp(buf, "auto\n", 5) == 0);
-
-	close(fd);
-
-	pm_status_fd = open(POWER_DIR "/runtime_status", O_RDONLY);
-	igt_assert_f(pm_status_fd >= 0,
-		     "Can't open " POWER_DIR "/runtime_status\n");
-
-	return true;
-}
-
-/**
- * igt_get_runtime_pm_status:
- *
- * Returns: The current runtime PM status.
- */
-enum igt_runtime_pm_status igt_get_runtime_pm_status(void)
-{
-	ssize_t n_read;
-	char buf[32];
-
-	lseek(pm_status_fd, 0, SEEK_SET);
-	n_read = read(pm_status_fd, buf, ARRAY_SIZE(buf));
-	igt_assert(n_read >= 0);
-	buf[n_read] = '\0';
-
-	if (strncmp(buf, "suspended\n", n_read) == 0)
-		return IGT_RUNTIME_PM_STATUS_SUSPENDED;
-	else if (strncmp(buf, "active\n", n_read) == 0)
-		return IGT_RUNTIME_PM_STATUS_ACTIVE;
-	else if (strncmp(buf, "suspending\n", n_read) == 0)
-		return IGT_RUNTIME_PM_STATUS_SUSPENDING;
-	else if (strncmp(buf, "resuming\n", n_read) == 0)
-		return IGT_RUNTIME_PM_STATUS_RESUMING;
-
-	igt_assert_f(false, "Unknown status %s\n", buf);
-	return IGT_RUNTIME_PM_STATUS_UNKNOWN;
-}
-
-/**
- * igt_wait_for_pm_status:
- * @status: desired runtime PM status
- *
- * Waits until for the driver to switch to into the desired runtime PM status,
- * with a 10 second timeout.
- *
- * Returns:
- * True if the desired runtime PM status was attained, false if the operation
- * timed out.
- */
-bool igt_wait_for_pm_status(enum igt_runtime_pm_status status)
-{
-	return igt_wait(igt_get_runtime_pm_status() == status, 10000, 100);
-}
-
 /* Functions with prefix kmstest_ independent of cairo library are pulled out
  * from file igt_kms.c since this file is skipped in lib/Android.mk when flag
  * ANDROID_HAS_CAIRO is 0. This ensures the usability of these functions even
diff --git a/lib/igt_aux.h b/lib/igt_aux.h
index be0d2d69..5627cb04 100644
--- a/lib/igt_aux.h
+++ b/lib/igt_aux.h
@@ -111,17 +111,6 @@ void igt_drop_root(void);
 void igt_debug_wait_for_keypress(const char *var);
 void igt_debug_manual_check(const char *var, const char *expected);
 
-enum igt_runtime_pm_status {
-	IGT_RUNTIME_PM_STATUS_ACTIVE,
-	IGT_RUNTIME_PM_STATUS_SUSPENDED,
-	IGT_RUNTIME_PM_STATUS_SUSPENDING,
-	IGT_RUNTIME_PM_STATUS_RESUMING,
-	IGT_RUNTIME_PM_STATUS_UNKNOWN,
-};
-bool igt_setup_runtime_pm(void);
-enum igt_runtime_pm_status igt_get_runtime_pm_status(void);
-bool igt_wait_for_pm_status(enum igt_runtime_pm_status status);
-
 /* sysinfo cross-arch wrappers from intel_os.c */
 
 /* These are separate to allow easier testing when porting, see the comment at
diff --git a/lib/igt_pm.c b/lib/igt_pm.c
index b1b5503c..5bf5b2e2 100644
--- a/lib/igt_pm.c
+++ b/lib/igt_pm.c
@@ -36,6 +36,19 @@
 
 #include "drmtest.h"
 #include "igt_pm.h"
+#include "igt_aux.h"
+
+/**
+ * SECTION:igt_pm
+ * @short_description: Power Management related helpers
+ * @title: Power Management
+ * @include: igt.h
+ *
+ * This library provides various helpers to enable power management for,
+ * and in some cases subsequently allow restoring the old behaviour of,
+ * various external components that by default are set up in a way
+ * that interferes with the testing of our power management functionality.
+ */
 
 enum {
 	POLICY_UNKNOWN = -1,
@@ -51,17 +64,6 @@ enum {
 #define MAX_POLICY_STRLEN	strlen(MAX_PERFORMANCE_STR)
 
 /**
- * SECTION:igt_pm
- * @short_description: Power Management related helpers
- * @title: Power Management
- * @include: igt.h
- *
- * This library provides various helpers to enable power management for,
- * and in some cases subsequently allow restoring the old behaviour of,
- * various external components that by default are set up in a way
- * that interferes with the testing of our power management functionality.
- */
-/**
  * igt_pm_enable_audio_runtime_pm:
  *
  * We know that if we don't enable audio runtime PM, snd_hda_intel will never
@@ -182,6 +184,7 @@ int8_t *igt_pm_enable_sata_link_power_management(void)
  *         we might restore the settings to the wrong hosts.
  */
 void igt_pm_restore_sata_link_power_management(int8_t *pm_data)
+
 {
 	int fd, i;
 	char *file_name;
@@ -231,3 +234,107 @@ void igt_pm_restore_sata_link_power_management(int8_t *pm_data)
 	}
 	free(file_name);
 }
+#define POWER_DIR "/sys/devices/pci0000:00/0000:00:02.0/power"
+/* We just leak this on exit ... */
+int pm_status_fd = -1;
+
+/**
+ * igt_setup_runtime_pm:
+ *
+ * Sets up the runtime PM helper functions and enables runtime PM. To speed up
+ * tests the autosuspend delay is set to 0.
+ *
+ * Returns:
+ * True if runtime pm is available, false otherwise.
+ */
+bool igt_setup_runtime_pm(void)
+{
+	int fd;
+	ssize_t size;
+	char buf[6];
+
+	if (pm_status_fd >= 0)
+		return true;
+
+	igt_pm_enable_audio_runtime_pm();
+
+	/* Our implementation uses autosuspend. Try to set it to 0ms so the test
+	 * suite goes faster and we have a higher probability of triggering race
+	 * conditions. */
+	fd = open(POWER_DIR "/autosuspend_delay_ms", O_WRONLY);
+	igt_assert_f(fd >= 0,
+		     "Can't open " POWER_DIR "/autosuspend_delay_ms\n");
+
+	/* If we fail to write to the file, it means this system doesn't support
+	 * runtime PM. */
+	size = write(fd, "0\n", 2);
+
+	close(fd);
+
+	if (size != 2)
+		return false;
+
+	/* We know we support runtime PM, let's try to enable it now. */
+	fd = open(POWER_DIR "/control", O_RDWR);
+	igt_assert_f(fd >= 0, "Can't open " POWER_DIR "/control\n");
+
+	size = write(fd, "auto\n", 5);
+	igt_assert(size == 5);
+
+	lseek(fd, 0, SEEK_SET);
+	size = read(fd, buf, ARRAY_SIZE(buf));
+	igt_assert(size == 5);
+	igt_assert(strncmp(buf, "auto\n", 5) == 0);
+
+	close(fd);
+
+	pm_status_fd = open(POWER_DIR "/runtime_status", O_RDONLY);
+	igt_assert_f(pm_status_fd >= 0,
+		     "Can't open " POWER_DIR "/runtime_status\n");
+
+	return true;
+}
+
+/**
+ * igt_get_runtime_pm_status:
+ *
+ * Returns: The current runtime PM status.
+ */
+enum igt_runtime_pm_status igt_get_runtime_pm_status(void)
+{
+	ssize_t n_read;
+	char buf[32];
+
+	lseek(pm_status_fd, 0, SEEK_SET);
+	n_read = read(pm_status_fd, buf, ARRAY_SIZE(buf));
+	igt_assert(n_read >= 0);
+	buf[n_read] = '\0';
+
+	if (strncmp(buf, "suspended\n", n_read) == 0)
+		return IGT_RUNTIME_PM_STATUS_SUSPENDED;
+	else if (strncmp(buf, "active\n", n_read) == 0)
+		return IGT_RUNTIME_PM_STATUS_ACTIVE;
+	else if (strncmp(buf, "suspending\n", n_read) == 0)
+		return IGT_RUNTIME_PM_STATUS_SUSPENDING;
+	else if (strncmp(buf, "resuming\n", n_read) == 0)
+		return IGT_RUNTIME_PM_STATUS_RESUMING;
+
+	igt_assert_f(false, "Unknown status %s\n", buf);
+	return IGT_RUNTIME_PM_STATUS_UNKNOWN;
+}
+
+/**
+ * igt_wait_for_pm_status:
+ * @status: desired runtime PM status
+ *
+ * Waits until for the driver to switch to into the desired runtime PM status,
+ * with a 10 second timeout.
+ *
+ * Returns:
+ * True if the desired runtime PM status was attained, false if the operation
+ * timed out.
+ */
+bool igt_wait_for_pm_status(enum igt_runtime_pm_status status)
+{
+	return igt_wait(igt_get_runtime_pm_status() == status, 10000, 100);
+}
diff --git a/lib/igt_pm.h b/lib/igt_pm.h
index c14ff1f7..eced39f8 100644
--- a/lib/igt_pm.h
+++ b/lib/igt_pm.h
@@ -28,4 +28,26 @@ void igt_pm_enable_audio_runtime_pm(void);
 int8_t *igt_pm_enable_sata_link_power_management(void);
 void igt_pm_restore_sata_link_power_management(int8_t *pm_data);
 
+/**
+ * igt_runtime_pm_status:
+ * @IGT_RUNTIME_PM_STATUS_ACTIVE: device is active
+ * @IGT_RUNTIME_PM_STATUS_SUSPENDED: device is suspended
+ * @IGT_RUNTIME_PM_STATUS_SUSPENDING: device is in the process of suspending
+ * @IGT_RUNTIME_PM_STATUS_RESUMING: device is in the process of resuming
+ * @IGT_RUNTIME_PM_STATUS_UNKNOWN: unknown runtime PM status
+ *
+ * Symbolic values for runtime PM device status.
+ */
+enum igt_runtime_pm_status {
+	IGT_RUNTIME_PM_STATUS_ACTIVE,
+	IGT_RUNTIME_PM_STATUS_SUSPENDED,
+	IGT_RUNTIME_PM_STATUS_SUSPENDING,
+	IGT_RUNTIME_PM_STATUS_RESUMING,
+	IGT_RUNTIME_PM_STATUS_UNKNOWN,
+};
+
+bool igt_setup_runtime_pm(void);
+enum igt_runtime_pm_status igt_get_runtime_pm_status(void);
+bool igt_wait_for_pm_status(enum igt_runtime_pm_status status);
+
 #endif /* IGT_PM_H */