This patch updates the descriptions of 'guest-suspend-ram' and
'guest-suspend-hybrid' to mention that both commands relies now
on the proper support for wake up from suspend, retrieved by the
'wakeup-suspend-support' attribute of the 'query-current-machine'
QMP command.

Reported-by: Balamuruhan S <bala24@linux.vnet.ibm.com>
Signed-off-by: Daniel Henrique Barboza <danielhb413@gmail.com>
Reviewed-by: Michael Roth <mdroth@linux.vnet.ibm.com>
---
 qga/qapi-schema.json | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
index dfbc4a5e32..7ae7e2502c 100644
--- a/qga/qapi-schema.json
+++ b/qga/qapi-schema.json
@@ -567,9 +567,9 @@
 # For the best results it's strongly recommended to have the pm-utils
 # package installed in the guest.
 #
-# IMPORTANT: guest-suspend-ram requires QEMU to support the 'system_wakeup'
-# command.  Thus, it's *required* to query QEMU for the presence of the
-# 'system_wakeup' command before issuing guest-suspend-ram.
+# IMPORTANT: guest-suspend-ram requires working wakeup support in
+# QEMU. You *must* check QMP command query-current-machine returns
+# wakeup-suspend-support: true before issuing this command.
 #
 # This command does NOT return a response on success. There are two options
 # to check for success:
@@ -594,9 +594,9 @@
 #
 # This command requires the pm-utils package to be installed in the guest.
 #
-# IMPORTANT: guest-suspend-hybrid requires QEMU to support the 'system_wakeup'
-# command.  Thus, it's *required* to query QEMU for the presence of the
-# 'system_wakeup' command before issuing guest-suspend-hybrid.
+# IMPORTANT: guest-suspend-hybrid requires working wakeup support in
+# QEMU. You *must* check QMP command query-current-machine returns
+# wakeup-suspend-support: true before issuing this command.
 #
 # This command does NOT return a response on success. There are two options
 # to check for success:
-- 
2.17.1

Daniel Henrique Barboza <danielhb413@gmail.com> writes:

> This patch updates the descriptions of 'guest-suspend-ram' and
> 'guest-suspend-hybrid' to mention that both commands relies now
> on the proper support for wake up from suspend, retrieved by the
> 'wakeup-suspend-support' attribute of the 'query-current-machine'
> QMP command.
>
> Reported-by: Balamuruhan S <bala24@linux.vnet.ibm.com>
> Signed-off-by: Daniel Henrique Barboza <danielhb413@gmail.com>
> Reviewed-by: Michael Roth <mdroth@linux.vnet.ibm.com>
> ---
>  qga/qapi-schema.json | 12 ++++++------
>  1 file changed, 6 insertions(+), 6 deletions(-)
>
> diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
> index dfbc4a5e32..7ae7e2502c 100644
> --- a/qga/qapi-schema.json
> +++ b/qga/qapi-schema.json
> @@ -567,9 +567,9 @@
>  # For the best results it's strongly recommended to have the pm-utils
>  # package installed in the guest.
>  #
> -# IMPORTANT: guest-suspend-ram requires QEMU to support the 'system_wakeup'
> -# command.  Thus, it's *required* to query QEMU for the presence of the
> -# 'system_wakeup' command before issuing guest-suspend-ram.
> +# IMPORTANT: guest-suspend-ram requires working wakeup support in
> +# QEMU. You *must* check QMP command query-current-machine returns
> +# wakeup-suspend-support: true before issuing this command.
>  #
>  # This command does NOT return a response on success. There are two options
>  # to check for success:
> @@ -594,9 +594,9 @@
>  #
>  # This command requires the pm-utils package to be installed in the guest.
>  #
> -# IMPORTANT: guest-suspend-hybrid requires QEMU to support the 'system_wakeup'
> -# command.  Thus, it's *required* to query QEMU for the presence of the
> -# 'system_wakeup' command before issuing guest-suspend-hybrid.
> +# IMPORTANT: guest-suspend-hybrid requires working wakeup support in
> +# QEMU. You *must* check QMP command query-current-machine returns
> +# wakeup-suspend-support: true before issuing this command.
>  #
>  # This command does NOT return a response on success. There are two options
>  # to check for success:

The emphasis in "You *must* check" hints at all kinds of terrible
disasters if you don't, but then you're not pointing to any.

So, what can happen if you issue this command when query-current-machine
returns wakeup-suspend-support: false?

On 10/11/18 4:40 AM, Markus Armbruster wrote:
> Daniel Henrique Barboza <danielhb413@gmail.com> writes:
>
>> This patch updates the descriptions of 'guest-suspend-ram' and
>> 'guest-suspend-hybrid' to mention that both commands relies now
>> on the proper support for wake up from suspend, retrieved by the
>> 'wakeup-suspend-support' attribute of the 'query-current-machine'
>> QMP command.
>>
>> Reported-by: Balamuruhan S <bala24@linux.vnet.ibm.com>
>> Signed-off-by: Daniel Henrique Barboza <danielhb413@gmail.com>
>> Reviewed-by: Michael Roth <mdroth@linux.vnet.ibm.com>
>> ---
>>   qga/qapi-schema.json | 12 ++++++------
>>   1 file changed, 6 insertions(+), 6 deletions(-)
>>
>> diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
>> index dfbc4a5e32..7ae7e2502c 100644
>> --- a/qga/qapi-schema.json
>> +++ b/qga/qapi-schema.json
>> @@ -567,9 +567,9 @@
>>   # For the best results it's strongly recommended to have the pm-utils
>>   # package installed in the guest.
>>   #
>> -# IMPORTANT: guest-suspend-ram requires QEMU to support the 'system_wakeup'
>> -# command.  Thus, it's *required* to query QEMU for the presence of the
>> -# 'system_wakeup' command before issuing guest-suspend-ram.
>> +# IMPORTANT: guest-suspend-ram requires working wakeup support in
>> +# QEMU. You *must* check QMP command query-current-machine returns
>> +# wakeup-suspend-support: true before issuing this command.
>>   #
>>   # This command does NOT return a response on success. There are two options
>>   # to check for success:
>> @@ -594,9 +594,9 @@
>>   #
>>   # This command requires the pm-utils package to be installed in the guest.
>>   #
>> -# IMPORTANT: guest-suspend-hybrid requires QEMU to support the 'system_wakeup'
>> -# command.  Thus, it's *required* to query QEMU for the presence of the
>> -# 'system_wakeup' command before issuing guest-suspend-hybrid.
>> +# IMPORTANT: guest-suspend-hybrid requires working wakeup support in
>> +# QEMU. You *must* check QMP command query-current-machine returns
>> +# wakeup-suspend-support: true before issuing this command.
>>   #
>>   # This command does NOT return a response on success. There are two options
>>   # to check for success:
> The emphasis in "You *must* check" hints at all kinds of terrible
> disasters if you don't, but then you're not pointing to any.
>
> So, what can happen if you issue this command when query-current-machine
> returns wakeup-suspend-support: false?

That's fair. If you don't check for flag when issuing 
guest-suspend-{ram/hybrid},
what happens is that QEMU will suspend the guest (QGA will suspend the
guest via systemctl, regardless of the guest arch) but system_wakeup 
will not
be able to wake the guest back up. You'll need to reboot the guest.

What  do you think of this new text?

+# IMPORTANT: guest-suspend-hybrid requires working wakeup support in
+# QEMU. You *must* check QMP command query-current-machine returns
+# wakeup-suspend-support: true before issuing this command. Failure in
+# doing so can result in a suspended guest that QEMU will not be able to
+# awaken, forcing the user to power cycle the guest to bring it back.