lib/igt_aux: Improve documentation for igt_system_suspend_autoresume()
PATCH 1/1 lib/igt_aux: Improve documentation for igt_system_suspend_autoresume()
While at it fix the order of states for consistency.
Suggested by Daniel.
Cc Daniel Vetter <[email protected]>
Signed-off-by Imre Deak <[email protected]>
--- lib/igt_aux.c | 21 ++++++++++++++++----- lib/igt_aux.h | 36 +++++++++++++++++++++++++++++++++++- 2 files changed, 51 insertions(+), 6 deletions(-)
lib/igt_aux.c +16 -5
@@ -628,8 +628,8 @@ void igt_cleanup_aperture_trashers(void)static const char *suspend_state_name[] = { [SUSPEND_STATE_FREEZE ] ="freeze" , - [SUSPEND_STATE_MEM ] ="mem" , [SUSPEND_STATE_STANDBY ] ="standby" , + [SUSPEND_STATE_MEM ] ="mem" , [SUSPEND_STATE_DISK ] ="disk" , };
@@ -744,11 +744,22 @@ static uint32_t get_supported_suspend_states(int power_dir)/** * igt_system_suspend_autoresume: +* @state: an #igt_suspend_state, the target suspend state +* @test: an #igt_suspend_test, test point at which to complete the suspend +* cycle * -* Execute a system suspend (to idle, memory, disk) cycle optionally -* completing the cycle at a given test point and automaically wake up again. -* Waking up is either achieved using the RTC wake-up alarm for a full suspend -* cycle or a kernel timer for a suspend test cycle. +* Execute a system suspend cycle targeting the given @state optionally +* completing the cycle at the given @test point and automaically wake up +* again. Waking up is either achieved using the RTC wake-up alarm for a full +* suspend cycle or a kernel timer for a suspend test cycle. The kernel timer +* delay for a test cycle can be configured by the suspend.pm_test_delay +* kernel parameter (5 sec by default). +* +* #SUSPEND_TEST_NONE specifies a full suspend cycle. +* The #SUSPEND_TEST_FREEZER..#SUSPEND_TEST_CORE test points can make it +* possible to collect error logs in case a full suspend cycle would prevent +* this by hanging the machine, or they can provide an idea of the faulty +* component by comparing fail/no-fail results at different test points. * * This is very handy for implementing any kind of suspend/resume test. */
lib/igt_aux.h +35 -1
@@ -116,15 +116,48 @@ void igt_cleanup_aperture_trashers(void);/* suspend/hibernate and auto-resume system */ +/** +* igt_suspend_state: +* @SUSPEND_STATE_FREEZE: suspend-to-idle target state, aka S0ix or freeze, +* first non-hibernation state +* @SUSPEND_STATE_STANDBY: standby target state, aka S1, second +* non-hibernation state +* @SUSPEND_STATE_MEM: suspend-to-mem target state aka S3, third +* non-hibernation state +* @SUSPEND_STATE_DISK: suspend-to-disk target state, aka S4 or hibernation +* +* Target suspend states used with igt_system_suspend_autoresume(). +* See /sys/power/state for the available states on a given machine. +*/ enum igt_suspend_state {SUSPEND_STATE_FREEZE , -SUSPEND_STATE_MEM ,SUSPEND_STATE_STANDBY , +SUSPEND_STATE_MEM ,SUSPEND_STATE_DISK , +/*< private >*/ SUSPEND_STATE_NUM , }; +/** +* igt_suspend_test: +* @SUSPEND_TEST_NONE: no testing, perform a full suspend/resume cycle +* @SUSPEND_TEST_FREEZER: complete cycle after freezing all freezable threads +* @SUSPEND_TEST_DEVICES: complete cycle after the above step and suspending +* devices (before calling the drivers' suspend late and +* no_irq hooks). Platform and system devices are not +* suspended here, see #SUSPEND_TEST_CORE. +* @SUSPEND_TEST_PLATFORM: complete cycle after all the above steps and calling +* the ACPI platform global control methods (applies +* only with /sys/power/disk set to platform) +* @SUSPEND_TEST_PROCESSORS: complete cycle after all the above steps and +* disabling non-boot CPUs +* @SUSPEND_TEST_CORE: complete cycle after all the above steps and suspending +* platform and system devices +* +* Test points used with igt_system_suspend_autoresume(). Specifies if and where +* the suspend sequence is to be terminated. +*/ enum igt_suspend_test {SUSPEND_TEST_NONE ,SUSPEND_TEST_FREEZER ,
@@ -133,6 +166,7 @@ enum igt_suspend_test {SUSPEND_TEST_PROCESSORS ,SUSPEND_TEST_CORE , +/*< private >*/ SUSPEND_TEST_NUM, };
Signature · 6 lines
2.5.0 _______________________________________________ Intel-gfx mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/intel-gfx
Quoted 6 lines · Imre Deak
While at it fix the order of states for consistency.
Suggested by Daniel.
Cc Daniel Vetter <[email protected]>Signed-off-by Imre Deak <[email protected]>
Going ocd with docs makes me really happy \o/ And I think it does help for new folks to get started in our dragon dungeon of a driver. Thanks for doing this.
Reviewed-by Daniel Vetter <[email protected]>
Quoted 111 lines
--- lib/igt_aux.c | 21 ++++++++++++++++----- lib/igt_aux.h | 36 +++++++++++++++++++++++++++++++++++- 2 files changed, 51 insertions(+), 6 deletions(-)lib/igt_aux.c +16
-5@@ -628,8 +628,8 @@ void igt_cleanup_aperture_trashers(void)static const char *suspend_state_name[] = { [SUSPEND_STATE_FREEZE ] ="freeze" , - [SUSPEND_STATE_MEM ] ="mem" , [SUSPEND_STATE_STANDBY ] ="standby" , + [SUSPEND_STATE_MEM ] ="mem" , [SUSPEND_STATE_DISK ] ="disk" , };@@ -744,11 +744,22 @@ static uint32_t get_supported_suspend_states(int power_dir)/** * igt_system_suspend_autoresume: +* @state: an #igt_suspend_state, the target suspend state +* @test: an #igt_suspend_test, test point at which to complete the suspend +* cycle * -* Execute a system suspend (to idle, memory, disk) cycle optionally -* completing the cycle at a given test point and automaically wake up again. -* Waking up is either achieved using the RTC wake-up alarm for a full suspend -* cycle or a kernel timer for a suspend test cycle. +* Execute a system suspend cycle targeting the given @state optionally +* completing the cycle at the given @test point and automaically wake up +* again. Waking up is either achieved using the RTC wake-up alarm for a full +* suspend cycle or a kernel timer for a suspend test cycle. The kernel timer +* delay for a test cycle can be configured by the suspend.pm_test_delay +* kernel parameter (5 sec by default). +* +* #SUSPEND_TEST_NONE specifies a full suspend cycle. +* The #SUSPEND_TEST_FREEZER..#SUSPEND_TEST_CORE test points can make it +* possible to collect error logs in case a full suspend cycle would prevent +* this by hanging the machine, or they can provide an idea of the faulty +* component by comparing fail/no-fail results at different test points. * * This is very handy for implementing any kind of suspend/resume test. */ lib/igt_aux.h +35
-1@@ -116,15 +116,48 @@ void igt_cleanup_aperture_trashers(void);/* suspend/hibernate and auto-resume system */ +/** +* igt_suspend_state: +* @SUSPEND_STATE_FREEZE: suspend-to-idle target state, aka S0ix or freeze, +* first non-hibernation state +* @SUSPEND_STATE_STANDBY: standby target state, aka S1, second +* non-hibernation state +* @SUSPEND_STATE_MEM: suspend-to-mem target state aka S3, third +* non-hibernation state +* @SUSPEND_STATE_DISK: suspend-to-disk target state, aka S4 or hibernation +* +* Target suspend states used with igt_system_suspend_autoresume(). +* See /sys/power/state for the available states on a given machine. +*/ enum igt_suspend_state {SUSPEND_STATE_FREEZE , -SUSPEND_STATE_MEM ,SUSPEND_STATE_STANDBY , +SUSPEND_STATE_MEM ,SUSPEND_STATE_DISK , +/*< private >*/ SUSPEND_STATE_NUM , }; +/** +* igt_suspend_test: +* @SUSPEND_TEST_NONE: no testing, perform a full suspend/resume cycle +* @SUSPEND_TEST_FREEZER: complete cycle after freezing all freezable threads +* @SUSPEND_TEST_DEVICES: complete cycle after the above step and suspending +* devices (before calling the drivers' suspend late and +* no_irq hooks). Platform and system devices are not +* suspended here, see #SUSPEND_TEST_CORE. +* @SUSPEND_TEST_PLATFORM: complete cycle after all the above steps and calling +* the ACPI platform global control methods (applies +* only with /sys/power/disk set to platform) +* @SUSPEND_TEST_PROCESSORS: complete cycle after all the above steps and +* disabling non-boot CPUs +* @SUSPEND_TEST_CORE: complete cycle after all the above steps and suspending +* platform and system devices +* +* Test points used with igt_system_suspend_autoresume(). Specifies if and where +* the suspend sequence is to be terminated. +*/ enum igt_suspend_test {SUSPEND_TEST_NONE ,SUSPEND_TEST_FREEZER ,@@ -133,6 +166,7 @@ enum igt_suspend_test {SUSPEND_TEST_PROCESSORS ,SUSPEND_TEST_CORE , +/*< private >*/ SUSPEND_TEST_NUM, };Signature · 1 line
2.5.0
Signature · 7 lines
Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch _______________________________________________ Intel-gfx mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/intel-gfx