[Qemu-devel] [PATCH] aio / timers: De-document -clock

[Qemu-devel] [PATCH] aio / timers: De-document -clock

[Markus Armbruster]

Commit 6d32717 "aio / timers: Remove alarm timers" has issues:

1. It silently ignores -clock for backward compatibility.
Incompatible change: -clock help no longer terminates the program.
Tolerable.

2. Failed to update option documentation.  In particular, -help still
advises users to try -clock help for available timers.  Drop all
documentation on -clock.

3. The 'query-alarm-clock' example in docs/writing-commands.txt no
longer works, and needs to be redone.  Can't do that right now, so I
just stick in a FIXME.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 docs/writing-qmp-commands.txt |  2 ++
 qemu-options.hx               | 12 ++----------
 2 files changed, 4 insertions(+), 10 deletions(-)

diff --git a/docs/writing-qmp-commands.txt b/docs/writing-qmp-commands.txt
index 4d86c24..f3df206 100644
--- a/docs/writing-qmp-commands.txt
+++ b/docs/writing-qmp-commands.txt
@@ -365,6 +365,8 @@ documentation for information about the other types.
 
 === User Defined Types ===
 
+FIXME This example needs to be redone after commit 6d32717
+
 For this example we will write the query-alarm-clock command, which returns
 information about QEMU's timer alarm. For more information about it, please
 check the "-clock" command-line option.
diff --git a/qemu-options.hx b/qemu-options.hx
index 365b56c..778d0de 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -2983,16 +2983,8 @@ Load the contents of @var{file} as an option ROM.
 This option is useful to load things like EtherBoot.
 ETEXI
 
-DEF("clock", HAS_ARG, QEMU_OPTION_clock, \
-    "-clock          force the use of the given methods for timer alarm.\n" \
-    "                To see what timers are available use '-clock help'\n",
-    QEMU_ARCH_ALL)
-STEXI
-@item -clock @var{method}
-@findex -clock
-Force the use of the given methods for timer alarm. To see what timers
-are available use @code{-clock help}.
-ETEXI
+HXCOMM Silently ignored for compatibility
+DEF("clock", HAS_ARG, QEMU_OPTION_clock, "", QEMU_ARCH_ALL)
 
 HXCOMM Options deprecated by -rtc
 DEF("localtime", 0, QEMU_OPTION_localtime, "", QEMU_ARCH_ALL)
-- 
1.9.3

Re: [Qemu-devel] [PATCH] aio / timers: De-document -clock

[Alex Bligh]

OK by me - sorry about that.

Alex

On 6 Oct 2014, at 15:19, Markus Armbruster <armbru@redhat.com> wrote:

> Commit 6d32717 "aio / timers: Remove alarm timers" has issues:
> 
> 1. It silently ignores -clock for backward compatibility.
> Incompatible change: -clock help no longer terminates the program.
> Tolerable.
> 
> 2. Failed to update option documentation.  In particular, -help still
> advises users to try -clock help for available timers.  Drop all
> documentation on -clock.
> 
> 3. The 'query-alarm-clock' example in docs/writing-commands.txt no
> longer works, and needs to be redone.  Can't do that right now, so I
> just stick in a FIXME.
> 
> Signed-off-by: Markus Armbruster <armbru@redhat.com>

Reviewed-by: Alex Bligh <alex@alex.org.uk>

> ---
> docs/writing-qmp-commands.txt |  2 ++
> qemu-options.hx               | 12 ++----------
> 2 files changed, 4 insertions(+), 10 deletions(-)
> 
> diff --git a/docs/writing-qmp-commands.txt b/docs/writing-qmp-commands.txt
> index 4d86c24..f3df206 100644
> --- a/docs/writing-qmp-commands.txt
> +++ b/docs/writing-qmp-commands.txt
> @@ -365,6 +365,8 @@ documentation for information about the other types.
> 
> === User Defined Types ===
> 
> +FIXME This example needs to be redone after commit 6d32717
> +
> For this example we will write the query-alarm-clock command, which returns
> information about QEMU's timer alarm. For more information about it, please
> check the "-clock" command-line option.
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 365b56c..778d0de 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -2983,16 +2983,8 @@ Load the contents of @var{file} as an option ROM.
> This option is useful to load things like EtherBoot.
> ETEXI
> 
> -DEF("clock", HAS_ARG, QEMU_OPTION_clock, \
> -    "-clock          force the use of the given methods for timer alarm.\n" \
> -    "                To see what timers are available use '-clock help'\n",
> -    QEMU_ARCH_ALL)
> -STEXI
> -@item -clock @var{method}
> -@findex -clock
> -Force the use of the given methods for timer alarm. To see what timers
> -are available use @code{-clock help}.
> -ETEXI
> +HXCOMM Silently ignored for compatibility
> +DEF("clock", HAS_ARG, QEMU_OPTION_clock, "", QEMU_ARCH_ALL)
> 
> HXCOMM Options deprecated by -rtc
> DEF("localtime", 0, QEMU_OPTION_localtime, "", QEMU_ARCH_ALL)
> -- 
> 1.9.3
> 
> 
> 

-- 
Alex Bligh

Re: [Qemu-devel] [PATCH] aio / timers: De-document -clock

[Markus Armbruster]

Ping?

Markus Armbruster <armbru@redhat.com> writes:

> Commit 6d32717 "aio / timers: Remove alarm timers" has issues:
>
> 1. It silently ignores -clock for backward compatibility.
> Incompatible change: -clock help no longer terminates the program.
> Tolerable.
>
> 2. Failed to update option documentation.  In particular, -help still
> advises users to try -clock help for available timers.  Drop all
> documentation on -clock.
>
> 3. The 'query-alarm-clock' example in docs/writing-commands.txt no
> longer works, and needs to be redone.  Can't do that right now, so I
> just stick in a FIXME.
>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  docs/writing-qmp-commands.txt |  2 ++
>  qemu-options.hx               | 12 ++----------
>  2 files changed, 4 insertions(+), 10 deletions(-)
>
> diff --git a/docs/writing-qmp-commands.txt b/docs/writing-qmp-commands.txt
> index 4d86c24..f3df206 100644
> --- a/docs/writing-qmp-commands.txt
> +++ b/docs/writing-qmp-commands.txt
> @@ -365,6 +365,8 @@ documentation for information about the other types.
>  
>  === User Defined Types ===
>  
> +FIXME This example needs to be redone after commit 6d32717
> +
>  For this example we will write the query-alarm-clock command, which returns
>  information about QEMU's timer alarm. For more information about it, please
>  check the "-clock" command-line option.
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 365b56c..778d0de 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -2983,16 +2983,8 @@ Load the contents of @var{file} as an option ROM.
>  This option is useful to load things like EtherBoot.
>  ETEXI
>  
> -DEF("clock", HAS_ARG, QEMU_OPTION_clock, \
> -    "-clock          force the use of the given methods for timer alarm.\n" \
> -    "                To see what timers are available use '-clock help'\n",
> -    QEMU_ARCH_ALL)
> -STEXI
> -@item -clock @var{method}
> -@findex -clock
> -Force the use of the given methods for timer alarm. To see what timers
> -are available use @code{-clock help}.
> -ETEXI
> +HXCOMM Silently ignored for compatibility
> +DEF("clock", HAS_ARG, QEMU_OPTION_clock, "", QEMU_ARCH_ALL)
>  
>  HXCOMM Options deprecated by -rtc
>  DEF("localtime", 0, QEMU_OPTION_localtime, "", QEMU_ARCH_ALL)

Re: [Qemu-devel] [PATCH] aio / timers: De-document -clock

[Paolo Bonzini]

On 10/06/2014 04:19 PM, Markus Armbruster wrote:
> Commit 6d32717 "aio / timers: Remove alarm timers" has issues:
> 
> 1. It silently ignores -clock for backward compatibility.
> Incompatible change: -clock help no longer terminates the program.
> Tolerable.
> 
> 2. Failed to update option documentation.  In particular, -help still
> advises users to try -clock help for available timers.  Drop all
> documentation on -clock.
> 
> 3. The 'query-alarm-clock' example in docs/writing-commands.txt no
> longer works, and needs to be redone.  Can't do that right now, so I
> just stick in a FIXME.
> 
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  docs/writing-qmp-commands.txt |  2 ++
>  qemu-options.hx               | 12 ++----------
>  2 files changed, 4 insertions(+), 10 deletions(-)
> 
> diff --git a/docs/writing-qmp-commands.txt b/docs/writing-qmp-commands.txt
> index 4d86c24..f3df206 100644
> --- a/docs/writing-qmp-commands.txt
> +++ b/docs/writing-qmp-commands.txt
> @@ -365,6 +365,8 @@ documentation for information about the other types.
>  
>  === User Defined Types ===
>  
> +FIXME This example needs to be redone after commit 6d32717
> +
>  For this example we will write the query-alarm-clock command, which returns
>  information about QEMU's timer alarm. For more information about it, please
>  check the "-clock" command-line option.
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 365b56c..778d0de 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -2983,16 +2983,8 @@ Load the contents of @var{file} as an option ROM.
>  This option is useful to load things like EtherBoot.
>  ETEXI
>  
> -DEF("clock", HAS_ARG, QEMU_OPTION_clock, \
> -    "-clock          force the use of the given methods for timer alarm.\n" \
> -    "                To see what timers are available use '-clock help'\n",
> -    QEMU_ARCH_ALL)
> -STEXI
> -@item -clock @var{method}
> -@findex -clock
> -Force the use of the given methods for timer alarm. To see what timers
> -are available use @code{-clock help}.
> -ETEXI
> +HXCOMM Silently ignored for compatibility
> +DEF("clock", HAS_ARG, QEMU_OPTION_clock, "", QEMU_ARCH_ALL)
>  
>  HXCOMM Options deprecated by -rtc
>  DEF("localtime", 0, QEMU_OPTION_localtime, "", QEMU_ARCH_ALL)
> 

I picked this up.

Paolo