[Qemu-devel] [PATCH 1/1] Add -incoming help text

[Qemu-devel] [PATCH 1/1] Add -incoming help text

[Dr. David Alan Gilbert (git)]

From: "Dr. David Alan Gilbert" <dgilbert@redhat.com>

The help/man text for

-incoming defer

didn't make it through the merge of the code that implemented it.

Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
---
 qemu-options.hx | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/qemu-options.hx b/qemu-options.hx
index dad49cf..3085412 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -3238,7 +3238,9 @@ DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
     "-incoming fd:fd\n" \
     "-incoming exec:cmdline\n" \
     "                accept incoming migration on given file descriptor\n" \
-    "                or from given external command\n",
+    "                or from given external command\n" \
+    "-incoming defer\n" \
+    "                wait for the URI to be specified via migrate_incoming\n",
     QEMU_ARCH_ALL)
 STEXI
 @item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6]
@@ -3254,6 +3256,8 @@ Accept incoming migration from a given filedescriptor.
 
 @item -incoming exec:@var{cmdline}
 Accept incoming migration as an output from specified external command.
+@item -incoming defer
+Wait for the URI to be specified via migrate_incoming.
 ETEXI
 
 DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \
-- 
2.4.1

Re: [Qemu-devel] [PATCH 1/1] Add -incoming help text

[Michael Tokarev]

29.05.2015 21:52, Dr. David Alan Gilbert (git) wrote:
> From: "Dr. David Alan Gilbert" <dgilbert@redhat.com>
> 
> The help/man text for
> 
> -incoming defer
> 
> didn't make it through the merge of the code that implemented it.
> 
> Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
> ---
>  qemu-options.hx | 6 +++++-
>  1 file changed, 5 insertions(+), 1 deletion(-)
> 
> diff --git a/qemu-options.hx b/qemu-options.hx
> index dad49cf..3085412 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -3238,7 +3238,9 @@ DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
>      "-incoming fd:fd\n" \
>      "-incoming exec:cmdline\n" \
>      "                accept incoming migration on given file descriptor\n" \
> -    "                or from given external command\n",
> +    "                or from given external command\n" \
> +    "-incoming defer\n" \
> +    "                wait for the URI to be specified via migrate_incoming\n",
>      QEMU_ARCH_ALL)
>  STEXI
>  @item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6]
> @@ -3254,6 +3256,8 @@ Accept incoming migration from a given filedescriptor.
>  
>  @item -incoming exec:@var{cmdline}
>  Accept incoming migration as an output from specified external command.
> +@item -incoming defer
> +Wait for the URI to be specified via migrate_incoming.

I wonder what's the reason of mentioning it twice with
such a short and _identical_ text each time...  Maybe
it's a good idea to reword the second message a bit.
Because actually it is not clear what does the whole
thing mean, what qemu will do when starting? Will it
accept other commands?

Thanks,

/mjt

Re: [Qemu-devel] [PATCH 1/1] Add -incoming help text

[Markus Armbruster]

Michael Tokarev <mjt@tls.msk.ru> writes:

> 29.05.2015 21:52, Dr. David Alan Gilbert (git) wrote:
>> From: "Dr. David Alan Gilbert" <dgilbert@redhat.com>
>> 
>> The help/man text for
>> 
>> -incoming defer
>> 
>> didn't make it through the merge of the code that implemented it.
>> 
>> Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
>> ---
>>  qemu-options.hx | 6 +++++-
>>  1 file changed, 5 insertions(+), 1 deletion(-)
>> 
>> diff --git a/qemu-options.hx b/qemu-options.hx
>> index dad49cf..3085412 100644
>> --- a/qemu-options.hx
>> +++ b/qemu-options.hx
>> @@ -3238,7 +3238,9 @@ DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
>>      "-incoming fd:fd\n" \
>>      "-incoming exec:cmdline\n" \
>>      "                accept incoming migration on given file descriptor\n" \
>> -    "                or from given external command\n",
>> +    "                or from given external command\n" \
>> +    "-incoming defer\n" \
>> +    "                wait for the URI to be specified via migrate_incoming\n",
>>      QEMU_ARCH_ALL)
>>  STEXI
>>  @item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6]
>> @@ -3254,6 +3256,8 @@ Accept incoming migration from a given filedescriptor.
>>  
>>  @item -incoming exec:@var{cmdline}
>>  Accept incoming migration as an output from specified external command.
>> +@item -incoming defer
>> +Wait for the URI to be specified via migrate_incoming.
>
> I wonder what's the reason of mentioning it twice with
> such a short and _identical_ text each time...

Because that's the way our documentation works.

The first hunk patches the fourth argument of DEF(), which goes into
-help.

The second hunk patches STEXI..ETEXI, which goes via qemu-options.texi
into qemu.1 and qemu-doc.{dvi,info,html,pdf}.

>                                                 Maybe
> it's a good idea to reword the second message a bit.
> Because actually it is not clear what does the whole
> thing mean, what qemu will do when starting? Will it
> accept other commands?

You're right in that .texi allows more verbose explanations than -help.

David's text looks okay to me as is.  Perhaps your questions inspire
further improvements.

Re: [Qemu-devel] [PATCH 1/1] Add -incoming help text

[Dr. David Alan Gilbert]

* Markus Armbruster (armbru@redhat.com) wrote:
> Michael Tokarev <mjt@tls.msk.ru> writes:
> 
> > 29.05.2015 21:52, Dr. David Alan Gilbert (git) wrote:
> >> From: "Dr. David Alan Gilbert" <dgilbert@redhat.com>
> >> 
> >> The help/man text for
> >> 
> >> -incoming defer
> >> 
> >> didn't make it through the merge of the code that implemented it.
> >> 
> >> Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
> >> ---
> >>  qemu-options.hx | 6 +++++-
> >>  1 file changed, 5 insertions(+), 1 deletion(-)
> >> 
> >> diff --git a/qemu-options.hx b/qemu-options.hx
> >> index dad49cf..3085412 100644
> >> --- a/qemu-options.hx
> >> +++ b/qemu-options.hx
> >> @@ -3238,7 +3238,9 @@ DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
> >>      "-incoming fd:fd\n" \
> >>      "-incoming exec:cmdline\n" \
> >>      "                accept incoming migration on given file descriptor\n" \
> >> -    "                or from given external command\n",
> >> +    "                or from given external command\n" \
> >> +    "-incoming defer\n" \
> >> +    "                wait for the URI to be specified via migrate_incoming\n",
> >>      QEMU_ARCH_ALL)
> >>  STEXI
> >>  @item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6]
> >> @@ -3254,6 +3256,8 @@ Accept incoming migration from a given filedescriptor.
> >>  
> >>  @item -incoming exec:@var{cmdline}
> >>  Accept incoming migration as an output from specified external command.
> >> +@item -incoming defer
> >> +Wait for the URI to be specified via migrate_incoming.
> >
> > I wonder what's the reason of mentioning it twice with
> > such a short and _identical_ text each time...
> 
> Because that's the way our documentation works.
> 
> The first hunk patches the fourth argument of DEF(), which goes into
> -help.
> 
> The second hunk patches STEXI..ETEXI, which goes via qemu-options.texi
> into qemu.1 and qemu-doc.{dvi,info,html,pdf}.
> 
> >                                                 Maybe
> > it's a good idea to reword the second message a bit.
> > Because actually it is not clear what does the whole
> > thing mean, what qemu will do when starting? Will it
> > accept other commands?
> 
> You're right in that .texi allows more verbose explanations than -help.
> 
> David's text looks okay to me as is.  Perhaps your questions inspire
> further improvements.

How about changing the second part to.

+@item -incoming defer
+Wait for the URI to be specified via migrate_incoming.  The monitor can
+be used to change settings (such as migration parameters) prior to issuing
+the migrate_incoming to allow the migration to begin.

Dave

--
Dr. David Alan Gilbert / dgilbert@redhat.com / Manchester, UK

Re: [Qemu-devel] [PATCH 1/1] Add -incoming help text

[Markus Armbruster]

"Dr. David Alan Gilbert" <dgilbert@redhat.com> writes:

> * Markus Armbruster (armbru@redhat.com) wrote:
>> Michael Tokarev <mjt@tls.msk.ru> writes:
>> 
>> > 29.05.2015 21:52, Dr. David Alan Gilbert (git) wrote:
>> >> From: "Dr. David Alan Gilbert" <dgilbert@redhat.com>
>> >> 
>> >> The help/man text for
>> >> 
>> >> -incoming defer
>> >> 
>> >> didn't make it through the merge of the code that implemented it.
>> >> 
>> >> Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
>> >> ---
>> >>  qemu-options.hx | 6 +++++-
>> >>  1 file changed, 5 insertions(+), 1 deletion(-)
>> >> 
>> >> diff --git a/qemu-options.hx b/qemu-options.hx
>> >> index dad49cf..3085412 100644
>> >> --- a/qemu-options.hx
>> >> +++ b/qemu-options.hx
>> >> @@ -3238,7 +3238,9 @@ DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
>> >>      "-incoming fd:fd\n" \
>> >>      "-incoming exec:cmdline\n" \
>> >>      "                accept incoming migration on given file descriptor\n" \
>> >> -    "                or from given external command\n",
>> >> +    "                or from given external command\n" \
>> >> +    "-incoming defer\n" \
>> >> +    "                wait for the URI to be specified via migrate_incoming\n",
>> >>      QEMU_ARCH_ALL)
>> >>  STEXI
>> >>  @item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6]
>> >> @@ -3254,6 +3256,8 @@ Accept incoming migration from a given filedescriptor.
>> >>  
>> >>  @item -incoming exec:@var{cmdline}
>> >>  Accept incoming migration as an output from specified external command.
>> >> +@item -incoming defer
>> >> +Wait for the URI to be specified via migrate_incoming.
>> >
>> > I wonder what's the reason of mentioning it twice with
>> > such a short and _identical_ text each time...
>> 
>> Because that's the way our documentation works.
>> 
>> The first hunk patches the fourth argument of DEF(), which goes into
>> -help.
>> 
>> The second hunk patches STEXI..ETEXI, which goes via qemu-options.texi
>> into qemu.1 and qemu-doc.{dvi,info,html,pdf}.
>> 
>> >                                                 Maybe
>> > it's a good idea to reword the second message a bit.
>> > Because actually it is not clear what does the whole
>> > thing mean, what qemu will do when starting? Will it
>> > accept other commands?
>> 
>> You're right in that .texi allows more verbose explanations than -help.
>> 
>> David's text looks okay to me as is.  Perhaps your questions inspire
>> further improvements.
>
> How about changing the second part to.
>
> +@item -incoming defer
> +Wait for the URI to be specified via migrate_incoming.  The monitor can
> +be used to change settings (such as migration parameters) prior to issuing
> +the migrate_incoming to allow the migration to begin.

I like it.

Preferably with this improvement:
Reviewed-by: Markus Armbruster <armbru@redhat.com>

Re: [Qemu-devel] [PATCH 1/1] Add -incoming help text

[Michael Tokarev]

29.05.2015 21:52, Dr. David Alan Gilbert (git) wrote:
> From: "Dr. David Alan Gilbert" <dgilbert@redhat.com>
> 
> The help/man text for
> 
> -incoming defer
> 
> didn't make it through the merge of the code that implemented it.

Applied to -trivial, with the more verbose text for the documentation.

Thank you very much!

/mjt