[Qemu-devel] Man page: Add -global description

[Qemu-devel] Man page: Add -global description

[Miroslav Rezanina]

There's only TODO information in qemu man page for -global option. This is a basic description of this option with simple example.

Signed-off-by: Miroslav Rezanina <mrezanin@redhat.com>

Patch:
--
diff --git a/qemu-options.hx b/qemu-options.hx
index daefce3..56d8c78 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -292,9 +292,13 @@ DEF("global", HAS_ARG, QEMU_OPTION_global,
     "                set a global default for a driver property\n",
     QEMU_ARCH_ALL)
 STEXI
-@item -global
+@item -global @var{driver}.@var{property}=@var{value}
 @findex -global
-TODO
+Set a default value of the @var{driver}'s @var{property} to the @var{value}, e.g.:
+
+@example
+qemu -global ide-drive.physical_block_size=524 -drive file=file,if=ide,index=0,media=disk
+@end example
 ETEXI
 
 DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,

Re: [Qemu-devel] Man page: Add -global description

[Paolo Bonzini]

Il 13/03/2012 19:09, Miroslav Rezanina ha scritto:
> +@example
> +qemu -global ide-drive.physical_block_size=524 -drive file=file,if=ide,index=0,media=disk
> +@end example

Let's use something that works, such as 4096 instead of 524. :)

Paolo

Re: [Qemu-devel] Man page: Add -global description

[Miroslav Rezanina]

----- Original Message -----
> From: "Paolo Bonzini" <pbonzini@redhat.com>
> To: "Miroslav Rezanina" <mrezanin@redhat.com>
> Cc: qemu-devel@nongnu.org
> Sent: Wednesday, March 14, 2012 8:42:00 AM
> Subject: Re: Man page: Add -global description
> 
> Il 13/03/2012 19:09, Miroslav Rezanina ha scritto:
> > +@example
> > +qemu -global ide-drive.physical_block_size=524 -drive
> > file=file,if=ide,index=0,media=disk
> > +@end example
> 
> Let's use something that works, such as 4096 instead of 524. :)
> 
> Paolo
> 

Yeah, I was thinking what value to use - 524 was choosed as non-standard
but used value. However, you're right - something more standard would be
probably better and 4096 is the best candidate.

Mirek

[Qemu-devel] [PATCH v2] Man page: Add -global description

[Miroslav Rezanina]

There's only TODO information in qemu man page for -global option. This is a basic description of this option with simple example.

Signed-off-by: Miroslav Rezanina <mrezanin@redhat.com>

Patch:
--
diff --git a/qemu-options.hx b/qemu-options.hx
index daefce3..876f929 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -292,9 +292,13 @@ DEF("global", HAS_ARG, QEMU_OPTION_global,
     "                set a global default for a driver property\n",
     QEMU_ARCH_ALL)
 STEXI
-@item -global
+@item -global @var{driver}.@var{property}=@var{value}
 @findex -global
-TODO
+Set default value of @var{driver}'s @var{property} to @var{value}, e.g.:
+
+@example
+qemu -global ide-drive.physical_block_size=4096 -drive file=file,if=ide,index=0
+@end example
 ETEXI
 
 DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,

Re: [Qemu-devel] [PATCH v2] Man page: Add -global description

[Markus Armbruster]

Miroslav Rezanina <mrezanin@redhat.com> writes:

> There's only TODO information in qemu man page for -global option. This is a basic description of this option with simple example.
>
> Signed-off-by: Miroslav Rezanina <mrezanin@redhat.com>
>
> Patch:
> --
> diff --git a/qemu-options.hx b/qemu-options.hx
> index daefce3..876f929 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -292,9 +292,13 @@ DEF("global", HAS_ARG, QEMU_OPTION_global,
>      "                set a global default for a driver property\n",
>      QEMU_ARCH_ALL)
>  STEXI
> -@item -global
> +@item -global @var{driver}.@var{property}=@var{value}
>  @findex -global
> -TODO
> +Set default value of @var{driver}'s @var{property} to @var{value}, e.g.:
> +
> +@example
> +qemu -global ide-drive.physical_block_size=4096 -drive file=file,if=ide,index=0
> +@end example
>  ETEXI
>  
>  DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,

Much better than nothing.  Stefan, would you like to take this through
your trivial queue?

Re: [Qemu-devel] [PATCH v2] Man page: Add -global description

[Peter Maydell]

On 14 March 2012 08:53, Miroslav Rezanina <mrezanin@redhat.com> wrote:
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -292,9 +292,13 @@ DEF("global", HAS_ARG, QEMU_OPTION_global,
>     "                set a global default for a driver property\n",
>     QEMU_ARCH_ALL)
>  STEXI
> -@item -global
> +@item -global @var{driver}.@var{property}=@var{value}

We seem to use @var{prop}, not @var{property}, elsewhere in the docs.

>  @findex -global
> -TODO
> +Set default value of @var{driver}'s @var{property} to @var{value}, e.g.:
> +
> +@example
> +qemu -global ide-drive.physical_block_size=4096 -drive file=file,if=ide,index=0
> +@end example
>  ETEXI

This is missing any motivation for why you would want to actually
use this option. How about:

"In particular, you can use this to set driver properties for devices which
are created automatically by the machine model. (To create a device which is
not created automatically and set properties on it, use -device.)"

?

That's still not great, but I think it helps a little.

(ideally if -device/-global are the new standard interface we should have a
section explaining the general concepts and syntax and then documentation of
how to do specific things like networking via -device, and relegate all the
'legacy' options to a section clearly marked as 'legacy' with pointers back
to the new ways of doing the same thing. That would be a much bigger job,
though.)

-- PMM

Re: [Qemu-devel] [PATCH v2] Man page: Add -global description

[Anthony Liguori]

On 03/14/2012 01:21 PM, Peter Maydell wrote:
> On 14 March 2012 08:53, Miroslav Rezanina<mrezanin@redhat.com>  wrote:
>> --- a/qemu-options.hx
>> +++ b/qemu-options.hx
>> @@ -292,9 +292,13 @@ DEF("global", HAS_ARG, QEMU_OPTION_global,
>>      "                set a global default for a driver property\n",
>>      QEMU_ARCH_ALL)
>>   STEXI
>> -@item -global
>> +@item -global @var{driver}.@var{property}=@var{value}
>
> We seem to use @var{prop}, not @var{property}, elsewhere in the docs.
>
>>   @findex -global
>> -TODO
>> +Set default value of @var{driver}'s @var{property} to @var{value}, e.g.:
>> +
>> +@example
>> +qemu -global ide-drive.physical_block_size=4096 -drive file=file,if=ide,index=0
>> +@end example
>>   ETEXI
>
> This is missing any motivation for why you would want to actually
> use this option. How about:
>
> "In particular, you can use this to set driver properties for devices which
> are created automatically by the machine model. (To create a device which is
> not created automatically and set properties on it, use -device.)"
>
> ?
>
> That's still not great, but I think it helps a little.
>
> (ideally if -device/-global are the new standard interface we should have a
> section explaining the general concepts and syntax and then documentation of
> how to do specific things like networking via -device, and relegate all the
> 'legacy' options to a section clearly marked as 'legacy' with pointers back
> to the new ways of doing the same thing. That would be a much bigger job,
> though.)

Just while we're here, I'll be posting the following shortly:

commit 82aff428155d469ab705294486cc26cb34947999
Author: Anthony Liguori <aliguori@us.ibm.com>
Date:   Fri Dec 23 11:30:45 2011 -0600

qdev: don't allow globals to be set by bus name

This is technically a compatibility breaker.  However:

1) libvirt does not rely on this (it always uses the driver name)

2) This behavior isn't actually documented anywhere (the docs just say driver).

3) I suspect there are less than three people on earth that even know this is
    possible (minus the people reading this message).

So I think we can safely break it :-)

Signed-off-by: Anthony Liguori <aliguori@us.ibm.com>

Regards,

Anthony Liguori

>
> -- PMM
>

Re: [Qemu-devel] [PATCH v2] Man page: Add -global description

[Markus Armbruster]

Anthony Liguori <anthony@codemonkey.ws> writes:

> Just while we're here, I'll be posting the following shortly:
>
> commit 82aff428155d469ab705294486cc26cb34947999
> Author: Anthony Liguori <aliguori@us.ibm.com>
> Date:   Fri Dec 23 11:30:45 2011 -0600
>
> qdev: don't allow globals to be set by bus name
>
> This is technically a compatibility breaker.  However:
>
> 1) libvirt does not rely on this (it always uses the driver name)
>
> 2) This behavior isn't actually documented anywhere (the docs just say driver).
>
> 3) I suspect there are less than three people on earth that even know this is
>    possible (minus the people reading this message).
>
> So I think we can safely break it :-)

Go right ahead.  We shouldn't tie ourselves up in knots over
undocumented behavior, unless there's clear evidence of use.

Re: [Qemu-devel] [PATCH v2] Man page: Add -global description

[Miroslav Rezanina]

----- Original Message -----
> From: "Peter Maydell" <peter.maydell@linaro.org>
> To: "Miroslav Rezanina" <mrezanin@redhat.com>
> Cc: qemu-devel@nongnu.org
> Sent: Wednesday, March 14, 2012 7:21:30 PM
> Subject: Re: [Qemu-devel] [PATCH v2] Man page: Add -global description
>
> On 14 March 2012 08:53, Miroslav Rezanina <mrezanin@redhat.com>
> wrote:
> > --- a/qemu-options.hx
> > +++ b/qemu-options.hx
> > @@ -292,9 +292,13 @@ DEF("global", HAS_ARG, QEMU_OPTION_global,
> >     "                set a global default for a driver property\n",
> >     QEMU_ARCH_ALL)
> >  STEXI
> > -@item -global
> > +@item -global @var{driver}.@var{property}=@var{value}
>
> We seem to use @var{prop}, not @var{property}, elsewhere in the docs.
>
You're right, I reused naming from DEF part...both has to be updated.

> >  @findex -global
> > -TODO
> > +Set default value of @var{driver}'s @var{property} to @var{value},
> > e.g.:
> > +
> > +@example
> > +qemu -global ide-drive.physical_block_size=4096 -drive
> > file=file,if=ide,index=0
> > +@end example
> >  ETEXI
>
> This is missing any motivation for why you would want to actually
> use this option. How about:
>
> "In particular, you can use this to set driver properties for devices
> which
> are created automatically by the machine model. (To create a device
> which is
> not created automatically and set properties on it, use -device.)"
>
> ?
>
> That's still not great, but I think it helps a little.
>

Yeah, more use case should be stated but I do not think man page is good
place for extensive user motivation.

> (ideally if -device/-global are the new standard interface we should
> have a
> section explaining the general concepts and syntax and then
> documentation of
> how to do specific things like networking via -device, and relegate
> all the
> 'legacy' options to a section clearly marked as 'legacy' with
> pointers back
> to the new ways of doing the same thing. That would be a much bigger
> job,
> though.)
>

Agree, man page is really behind the code. However, I think documenting new
interfaces should be done first to agree on them and their usage. After new
way is known extracting old interface as legacy stuff would be easier.

> -- PMM
>


Anyway, I will resend this patch with updates you recommended.

Mirek

[Qemu-devel] [PATCH v3] Man page: Add -global description

[Miroslav Rezanina]

There's only TODO information in qemu man page for -global option. This is a basic description of this option with simple example.

Signed-off-by: Miroslav Rezanina <mrezanin@redhat.com>

Patch:
--
diff --git a/qemu-options.hx b/qemu-options.hx
index daefce3..db8be37 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -288,13 +288,19 @@ TODO
 ETEXI
 
 DEF("global", HAS_ARG, QEMU_OPTION_global,
-    "-global driver.property=value\n"
+    "-global driver.prop=value\n"
     "                set a global default for a driver property\n",
     QEMU_ARCH_ALL)
 STEXI
-@item -global
+@item -global @var{driver}.@var{prop}=@var{value}
 @findex -global
-TODO
+Set default value of @var{driver}'s property @var{prop} to @var{value}, e.g.:
+
+@example
+qemu -global ide-drive.physical_block_size=4096 -drive file=file,if=ide,index=0,media=disk
+@end example
+
+In particular, you can use this to set driver properties for devices which are created automatically by the machine model. To create a device which is not created automatically and set properties on it, use -@option{device}.
 ETEXI
 
 DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,

Re: [Qemu-devel] [PATCH v2] Man page: Add -global description

[Gerd Hoffmann]

  Hi,

> commit 82aff428155d469ab705294486cc26cb34947999
> Author: Anthony Liguori <aliguori@us.ibm.com>
> Date:   Fri Dec 23 11:30:45 2011 -0600
> 
> qdev: don't allow globals to be set by bus name

> So I think we can safely break it :-)

There are compat properties using that (turn off new pci features on old
releases for all pci devices).

cheers,
  Gerd

Re: [Qemu-devel] [PATCH v2] Man page: Add -global description

[Paolo Bonzini]

Il 16/03/2012 10:24, Gerd Hoffmann ha scritto:
>> > commit 82aff428155d469ab705294486cc26cb34947999
>> > Author: Anthony Liguori <aliguori@us.ibm.com>
>> > Date:   Fri Dec 23 11:30:45 2011 -0600
>> > 
>> > qdev: don't allow globals to be set by bus name
>> > So I think we can safely break it :-)
> There are compat properties using that (turn off new pci features on old
> releases for all pci devices).

It could be changed to a compat property on the abstract PCI device
class (with changes to look up global properties on the whole hierarchy
of course).

Paolo

Re: [Qemu-devel] [PATCH v3] Man page: Add -global description

[Markus Armbruster]

Miroslav Rezanina <mrezanin@redhat.com> writes:

> There's only TODO information in qemu man page for -global option. This is a basic description of this option with simple example.
>
> Signed-off-by: Miroslav Rezanina <mrezanin@redhat.com>
>
> Patch:
> --
> diff --git a/qemu-options.hx b/qemu-options.hx
> index daefce3..db8be37 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -288,13 +288,19 @@ TODO
>  ETEXI
>  
>  DEF("global", HAS_ARG, QEMU_OPTION_global,
> -    "-global driver.property=value\n"
> +    "-global driver.prop=value\n"
>      "                set a global default for a driver property\n",
>      QEMU_ARCH_ALL)
>  STEXI
> -@item -global
> +@item -global @var{driver}.@var{prop}=@var{value}
>  @findex -global
> -TODO
> +Set default value of @var{driver}'s property @var{prop} to @var{value}, e.g.:
> +
> +@example
> +qemu -global ide-drive.physical_block_size=4096 -drive file=file,if=ide,index=0,media=disk
> +@end example
> +
> +In particular, you can use this to set driver properties for devices which are created automatically by the machine model. To create a device which is not created automatically and set properties on it, use -@option{device}.

Long line, please wrap.

>  ETEXI
>  
>  DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,

[Qemu-devel] [PATCH v4] Man page: Add -global description

[Miroslav Rezanina]

There's only TODO information in qemu man page for -global option. This is a basic description of this option with simple example.

Signed-off-by: Miroslav Rezanina <mrezanin@redhat.com>

v4:
 - break long line 

v3:
 - add use case description
 - use prop instead of property

v2:
 - Use better value in example 
Patch:
--
diff --git a/qemu-options.hx b/qemu-options.hx
index daefce3..662f571 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -288,13 +288,21 @@ TODO
 ETEXI
 
 DEF("global", HAS_ARG, QEMU_OPTION_global,
-    "-global driver.property=value\n"
+    "-global driver.prop=value\n"
     "                set a global default for a driver property\n",
     QEMU_ARCH_ALL)
 STEXI
-@item -global
+@item -global @var{driver}.@var{prop}=@var{value}
 @findex -global
-TODO
+Set default value of @var{driver}'s property @var{prop} to @var{value}, e.g.:
+
+@example
+qemu -global ide-drive.physical_block_size=4096 -drive file=file,if=ide,index=0,media=disk
+@end example
+
+In particular, you can use this to set driver properties for devices which are 
+created automatically by the machine model. To create a device which is not 
+created automatically and set properties on it, use -@option{device}.
 ETEXI
 
 DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,

Re: [Qemu-devel] [PATCH v4] Man page: Add -global description

[Markus Armbruster]

Miroslav Rezanina <mrezanin@redhat.com> writes:

> There's only TODO information in qemu man page for -global option. This is a basic description of this option with simple example.
>
> Signed-off-by: Miroslav Rezanina <mrezanin@redhat.com>
>
> v4:
>  - break long line 
>
> v3:
>  - add use case description
>  - use prop instead of property
>
> v2:
>  - Use better value in example 
> Patch:
> --
> diff --git a/qemu-options.hx b/qemu-options.hx
> index daefce3..662f571 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -288,13 +288,21 @@ TODO
>  ETEXI
>  
>  DEF("global", HAS_ARG, QEMU_OPTION_global,
> -    "-global driver.property=value\n"
> +    "-global driver.prop=value\n"
>      "                set a global default for a driver property\n",
>      QEMU_ARCH_ALL)
>  STEXI
> -@item -global
> +@item -global @var{driver}.@var{prop}=@var{value}
>  @findex -global
> -TODO
> +Set default value of @var{driver}'s property @var{prop} to @var{value}, e.g.:
> +
> +@example
> +qemu -global ide-drive.physical_block_size=4096 -drive file=file,if=ide,index=0,media=disk
> +@end example
> +
> +In particular, you can use this to set driver properties for devices which are 
> +created automatically by the machine model. To create a device which is not 
> +created automatically and set properties on it, use -@option{device}.
>  ETEXI
>  
>  DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,

This is a clear improvement.  Cc'ing Anthony, the qdev maintainer in all
but name ;)

Re: [Qemu-devel] [PATCH v4] Man page: Add -global description

[Anthony Liguori]

On 03/21/2012 07:46 AM, Miroslav Rezanina wrote:
> There's only TODO information in qemu man page for -global option. This is a basic description of this option with simple example.
>
> Signed-off-by: Miroslav Rezanina<mrezanin@redhat.com>

Applied.  Thanks.

Regards,

Anthony Liguori

>
> v4:
>   - break long line
>
> v3:
>   - add use case description
>   - use prop instead of property
>
> v2:
>   - Use better value in example
> Patch:
> --
> diff --git a/qemu-options.hx b/qemu-options.hx
> index daefce3..662f571 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -288,13 +288,21 @@ TODO
>   ETEXI
>
>   DEF("global", HAS_ARG, QEMU_OPTION_global,
> -    "-global driver.property=value\n"
> +    "-global driver.prop=value\n"
>       "                set a global default for a driver property\n",
>       QEMU_ARCH_ALL)
>   STEXI
> -@item -global
> +@item -global @var{driver}.@var{prop}=@var{value}
>   @findex -global
> -TODO
> +Set default value of @var{driver}'s property @var{prop} to @var{value}, e.g.:
> +
> +@example
> +qemu -global ide-drive.physical_block_size=4096 -drive file=file,if=ide,index=0,media=disk
> +@end example
> +
> +In particular, you can use this to set driver properties for devices which are
> +created automatically by the machine model. To create a device which is not
> +created automatically and set properties on it, use -@option{device}.
>   ETEXI
>
>   DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,
>
>