* Re: [Qemu-devel] [PATCH v2] Man page: Add -global description
2012-03-14 8:53 ` [Qemu-devel] [PATCH v2] " Miroslav Rezanina
@ 2012-03-14 18:09 ` Markus Armbruster
2012-03-14 18:21 ` Peter Maydell
2012-03-15 15:57 ` [Qemu-devel] [PATCH v3] " Miroslav Rezanina
2 siblings, 0 replies; 16+ messages in thread
From: Markus Armbruster @ 2012-03-14 18:09 UTC (permalink / raw)
To: Miroslav Rezanina; +Cc: qemu-trivial, qemu-devel
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?
^ permalink raw reply [flat|nested] 16+ messages in thread* Re: [Qemu-devel] [PATCH v2] Man page: Add -global description
2012-03-14 8:53 ` [Qemu-devel] [PATCH v2] " Miroslav Rezanina
2012-03-14 18:09 ` Markus Armbruster
@ 2012-03-14 18:21 ` Peter Maydell
2012-03-14 19:23 ` Anthony Liguori
2012-03-15 8:35 ` Miroslav Rezanina
2012-03-15 15:57 ` [Qemu-devel] [PATCH v3] " Miroslav Rezanina
2 siblings, 2 replies; 16+ messages in thread
From: Peter Maydell @ 2012-03-14 18:21 UTC (permalink / raw)
To: Miroslav Rezanina; +Cc: qemu-devel
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
^ permalink raw reply [flat|nested] 16+ messages in thread* Re: [Qemu-devel] [PATCH v2] Man page: Add -global description
2012-03-14 18:21 ` Peter Maydell
@ 2012-03-14 19:23 ` Anthony Liguori
2012-03-15 7:50 ` Markus Armbruster
2012-03-16 9:24 ` Gerd Hoffmann
2012-03-15 8:35 ` Miroslav Rezanina
1 sibling, 2 replies; 16+ messages in thread
From: Anthony Liguori @ 2012-03-14 19:23 UTC (permalink / raw)
To: Peter Maydell; +Cc: Miroslav Rezanina, qemu-devel
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
>
^ permalink raw reply [flat|nested] 16+ messages in thread* Re: [Qemu-devel] [PATCH v2] Man page: Add -global description
2012-03-14 19:23 ` Anthony Liguori
@ 2012-03-15 7:50 ` Markus Armbruster
2012-03-16 9:24 ` Gerd Hoffmann
1 sibling, 0 replies; 16+ messages in thread
From: Markus Armbruster @ 2012-03-15 7:50 UTC (permalink / raw)
To: Anthony Liguori; +Cc: Peter Maydell, Miroslav Rezanina, qemu-devel
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.
^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: [Qemu-devel] [PATCH v2] Man page: Add -global description
2012-03-14 19:23 ` Anthony Liguori
2012-03-15 7:50 ` Markus Armbruster
@ 2012-03-16 9:24 ` Gerd Hoffmann
2012-03-19 17:13 ` Paolo Bonzini
1 sibling, 1 reply; 16+ messages in thread
From: Gerd Hoffmann @ 2012-03-16 9:24 UTC (permalink / raw)
To: Anthony Liguori; +Cc: Peter Maydell, Miroslav Rezanina, qemu-devel
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
^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: [Qemu-devel] [PATCH v2] Man page: Add -global description
2012-03-16 9:24 ` Gerd Hoffmann
@ 2012-03-19 17:13 ` Paolo Bonzini
0 siblings, 0 replies; 16+ messages in thread
From: Paolo Bonzini @ 2012-03-19 17:13 UTC (permalink / raw)
To: Gerd Hoffmann
Cc: Peter Maydell, Miroslav Rezanina, qemu-devel, Anthony Liguori
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
^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: [Qemu-devel] [PATCH v2] Man page: Add -global description
2012-03-14 18:21 ` Peter Maydell
2012-03-14 19:23 ` Anthony Liguori
@ 2012-03-15 8:35 ` Miroslav Rezanina
1 sibling, 0 replies; 16+ messages in thread
From: Miroslav Rezanina @ 2012-03-15 8:35 UTC (permalink / raw)
To: Peter Maydell; +Cc: qemu-devel
----- 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
^ permalink raw reply [flat|nested] 16+ messages in thread
* [Qemu-devel] [PATCH v3] Man page: Add -global description
2012-03-14 8:53 ` [Qemu-devel] [PATCH v2] " Miroslav Rezanina
2012-03-14 18:09 ` Markus Armbruster
2012-03-14 18:21 ` Peter Maydell
@ 2012-03-15 15:57 ` Miroslav Rezanina
2012-03-21 12:25 ` Markus Armbruster
2012-03-21 12:46 ` [Qemu-devel] [PATCH v4] " Miroslav Rezanina
2 siblings, 2 replies; 16+ messages in thread
From: Miroslav Rezanina @ 2012-03-15 15:57 UTC (permalink / raw)
To: qemu-devel
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,
^ permalink raw reply related [flat|nested] 16+ messages in thread* Re: [Qemu-devel] [PATCH v3] Man page: Add -global description
2012-03-15 15:57 ` [Qemu-devel] [PATCH v3] " Miroslav Rezanina
@ 2012-03-21 12:25 ` Markus Armbruster
2012-03-21 12:46 ` [Qemu-devel] [PATCH v4] " Miroslav Rezanina
1 sibling, 0 replies; 16+ messages in thread
From: Markus Armbruster @ 2012-03-21 12:25 UTC (permalink / raw)
To: Miroslav Rezanina; +Cc: qemu-devel, Anthony Liguori
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,
^ permalink raw reply [flat|nested] 16+ messages in thread* [Qemu-devel] [PATCH v4] Man page: Add -global description
2012-03-15 15:57 ` [Qemu-devel] [PATCH v3] " Miroslav Rezanina
2012-03-21 12:25 ` Markus Armbruster
@ 2012-03-21 12:46 ` Miroslav Rezanina
2012-03-21 17:05 ` Markus Armbruster
2012-03-26 20:07 ` Anthony Liguori
1 sibling, 2 replies; 16+ messages in thread
From: Miroslav Rezanina @ 2012-03-21 12:46 UTC (permalink / raw)
To: qemu-devel
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,
^ permalink raw reply related [flat|nested] 16+ messages in thread* Re: [Qemu-devel] [PATCH v4] Man page: Add -global description
2012-03-21 12:46 ` [Qemu-devel] [PATCH v4] " Miroslav Rezanina
@ 2012-03-21 17:05 ` Markus Armbruster
2012-03-26 20:07 ` Anthony Liguori
1 sibling, 0 replies; 16+ messages in thread
From: Markus Armbruster @ 2012-03-21 17:05 UTC (permalink / raw)
To: Miroslav Rezanina; +Cc: qemu-devel, Anthony Liguori
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 ;)
^ permalink raw reply [flat|nested] 16+ messages in thread* Re: [Qemu-devel] [PATCH v4] Man page: Add -global description
2012-03-21 12:46 ` [Qemu-devel] [PATCH v4] " Miroslav Rezanina
2012-03-21 17:05 ` Markus Armbruster
@ 2012-03-26 20:07 ` Anthony Liguori
1 sibling, 0 replies; 16+ messages in thread
From: Anthony Liguori @ 2012-03-26 20:07 UTC (permalink / raw)
To: Miroslav Rezanina; +Cc: qemu-devel
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,
>
>
^ permalink raw reply [flat|nested] 16+ messages in thread