[Qemu-devel] [PATCH] Documentation: Add missing documentation for qdev related command line options

[Qemu-devel] [PATCH] Documentation: Add missing documentation for qdev related command line options

[Stefan Weil]

The command line options -device, -nodefaults, -readconfig,
-writeconfig had entries for command line help, but
documentation for texi and derived formats (man, html, info)
was missing.

This also required moving "@end table" to the end of
qemu-options.hx again.

Signed-off-by: Stefan Weil <weil@mail.berlios.de>
---
 qemu-options.hx |   25 +++++++++++++++++++++----
 1 files changed, 21 insertions(+), 4 deletions(-)

diff --git a/qemu-options.hx b/qemu-options.hx
index e2edd71..b2d04e2 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -404,6 +404,12 @@ ETEXI
 
 DEF("device", HAS_ARG, QEMU_OPTION_device,
     "-device driver[,options]  add device\n")
+STEXI
+@item -device @var{driver}[,@var{option}[,...]]
+Add device @var{driver}. Depending on the device type,
+@var{option} (typically @var{key}=@var{value}) may be useful.
+ETEXI
+
 DEF("name", HAS_ARG, QEMU_OPTION_name,
     "-name string1[,process=string2]\n"
     "                set the name of the guest\n"
@@ -1905,6 +1911,8 @@ ETEXI
 DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \
     "-nodefaults     don't create default devices\n")
 STEXI
+@item -nodefaults
+Don't create default devices.
 ETEXI
 
 #ifndef _WIN32
@@ -1927,10 +1935,6 @@ Immediately before starting guest execution, drop root privileges, switching
 to the specified user.
 ETEXI
 
-STEXI
-@end table
-ETEXI
-
 #if defined(TARGET_SPARC) || defined(TARGET_PPC)
 DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env,
     "-prom-env variable=value\n"
@@ -1946,6 +1950,19 @@ DEF("old-param", 0, QEMU_OPTION_old_param,
 #endif
 DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig,
     "-readconfig <file>\n")
+STEXI
+@item -readconfig @var{file}
+Read device configuration from @var{file}.
+ETEXI
 DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig,
     "-writeconfig <file>\n"
     "                read/write config file\n")
+STEXI
+@item -writeconfig @var{file}
+Write device configuration to @var{file}.
+ETEXI
+
+HXCOMM This is the last statement. Insert new options before this line!
+STEXI
+@end table
+ETEXI
-- 
1.6.5

Re: [Qemu-devel] [PATCH] Documentation: Add missing documentation for qdev related command line options

[Markus Armbruster]

Stefan Weil <weil@mail.berlios.de> writes:

> The command line options -device, -nodefaults, -readconfig,
> -writeconfig had entries for command line help, but
> documentation for texi and derived formats (man, html, info)
> was missing.
>
> This also required moving "@end table" to the end of
> qemu-options.hx again.
>
> Signed-off-by: Stefan Weil <weil@mail.berlios.de>
> ---
>  qemu-options.hx |   25 +++++++++++++++++++++----
>  1 files changed, 21 insertions(+), 4 deletions(-)
>
> diff --git a/qemu-options.hx b/qemu-options.hx
> index e2edd71..b2d04e2 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -404,6 +404,12 @@ ETEXI
>  
>  DEF("device", HAS_ARG, QEMU_OPTION_device,
>      "-device driver[,options]  add device\n")
> +STEXI
> +@item -device @var{driver}[,@var{option}[,...]]
> +Add device @var{driver}. Depending on the device type,
> +@var{option} (typically @var{key}=@var{value}) may be useful.
> +ETEXI
> +

While there, would you mind improving --help for -device a bit?  It's
too terse, and it doesn't start the help text in column 16 like the
other options do.

>  DEF("name", HAS_ARG, QEMU_OPTION_name,
[...]
> +STEXI
> +@item -writeconfig @var{file}
> +Write device configuration to @var{file}.
> +ETEXI
> +
> +HXCOMM This is the last statement. Insert new options before this line!
> +STEXI
> +@end table
> +ETEXI

Neat, thanks!

Re: [Qemu-devel] [PATCH] Documentation: Add missing documentation for qdev related command line options

[Stefan Weil]

Markus Armbruster schrieb:
> Stefan Weil <weil@mail.berlios.de> writes:
>
>> The command line options -device, -nodefaults, -readconfig,
>> -writeconfig had entries for command line help, but
>> documentation for texi and derived formats (man, html, info)
>> was missing.
>>
>> This also required moving "@end table" to the end of
>> qemu-options.hx again.
>>
>> Signed-off-by: Stefan Weil <weil@mail.berlios.de>
>> ---
>> qemu-options.hx | 25 +++++++++++++++++++++----
>> 1 files changed, 21 insertions(+), 4 deletions(-)
>>
>> diff --git a/qemu-options.hx b/qemu-options.hx
>> index e2edd71..b2d04e2 100644
>> --- a/qemu-options.hx
>> +++ b/qemu-options.hx
>> @@ -404,6 +404,12 @@ ETEXI
>>
>> DEF("device", HAS_ARG, QEMU_OPTION_device,
>> "-device driver[,options] add device\n")
>> +STEXI
>> +@item -device @var{driver}[,@var{option}[,...]]
>> +Add device @var{driver}. Depending on the device type,
>> +@var{option} (typically @var{key}=@var{value}) may be useful.
>> +ETEXI
>> +
>
> While there, would you mind improving --help for -device a bit? It's
> too terse, and it doesn't start the help text in column 16 like the
> other options do.

Hi Markus,

this needs a little more work. I just had a look on the code,
and there is no online help for the possible options (key, value).

If you (and especially those who have commit rights) agree,
I could provide these three additional patches:

* Add online help for properties (qemu -device driver,?)
* Add online help for property value (qemu -device driver,property=?)
* Update documentation for command line option -device

There is already an online help for the driver (qemu -device ?).

Regards,

Stefan

Re: [Qemu-devel] [PATCH] Documentation: Add missing documentation for qdev related command line options

[Markus Armbruster]

Stefan Weil <weil@mail.berlios.de> writes:

> Markus Armbruster schrieb:
>> Stefan Weil <weil@mail.berlios.de> writes:
>>
>>> The command line options -device, -nodefaults, -readconfig,
>>> -writeconfig had entries for command line help, but
>>> documentation for texi and derived formats (man, html, info)
>>> was missing.
>>>
>>> This also required moving "@end table" to the end of
>>> qemu-options.hx again.
>>>
>>> Signed-off-by: Stefan Weil <weil@mail.berlios.de>
>>> ---
>>> qemu-options.hx | 25 +++++++++++++++++++++----
>>> 1 files changed, 21 insertions(+), 4 deletions(-)
>>>
>>> diff --git a/qemu-options.hx b/qemu-options.hx
>>> index e2edd71..b2d04e2 100644
>>> --- a/qemu-options.hx
>>> +++ b/qemu-options.hx
>>> @@ -404,6 +404,12 @@ ETEXI
>>>
>>> DEF("device", HAS_ARG, QEMU_OPTION_device,
>>> "-device driver[,options] add device\n")
>>> +STEXI
>>> +@item -device @var{driver}[,@var{option}[,...]]
>>> +Add device @var{driver}. Depending on the device type,
>>> +@var{option} (typically @var{key}=@var{value}) may be useful.
>>> +ETEXI
>>> +
>>
>> While there, would you mind improving --help for -device a bit? It's
>> too terse, and it doesn't start the help text in column 16 like the
>> other options do.
>
> Hi Markus,
>
> this needs a little more work. I just had a look on the code,
> and there is no online help for the possible options (key, value).

What I had in mind was just to bring it up to par with your patch to the
texi, but...

> If you (and especially those who have commit rights) agree,
> I could provide these three additional patches:
>
> * Add online help for properties (qemu -device driver,?)
> * Add online help for property value (qemu -device driver,property=?)
> * Update documentation for command line option -device

... a patch to provide that is very desirable!

I figure the best way to document available properties and there values
is a self-documenting struct PropertyInfo: add a doc member, extend
DEFINE_PROP() & friends to set it, fix up users to pass NULL, and so
forth.  We can then replace the NULL by something useful at our leisure.

> There is already an online help for the driver (qemu -device ?).

[Qemu-devel] Re: [PATCH] Documentation: Add missing documentation for qdev related command line options

[Michael S. Tsirkin]

On Mon, Jan 18, 2010 at 08:32:25PM +0100, Stefan Weil wrote:
> Markus Armbruster schrieb:
> > Stefan Weil <weil@mail.berlios.de> writes:
> >
> >> The command line options -device, -nodefaults, -readconfig,
> >> -writeconfig had entries for command line help, but
> >> documentation for texi and derived formats (man, html, info)
> >> was missing.
> >>
> >> This also required moving "@end table" to the end of
> >> qemu-options.hx again.
> >>
> >> Signed-off-by: Stefan Weil <weil@mail.berlios.de>
> >> ---
> >> qemu-options.hx | 25 +++++++++++++++++++++----
> >> 1 files changed, 21 insertions(+), 4 deletions(-)
> >>
> >> diff --git a/qemu-options.hx b/qemu-options.hx
> >> index e2edd71..b2d04e2 100644
> >> --- a/qemu-options.hx
> >> +++ b/qemu-options.hx
> >> @@ -404,6 +404,12 @@ ETEXI
> >>
> >> DEF("device", HAS_ARG, QEMU_OPTION_device,
> >> "-device driver[,options] add device\n")
> >> +STEXI
> >> +@item -device @var{driver}[,@var{option}[,...]]
> >> +Add device @var{driver}. Depending on the device type,
> >> +@var{option} (typically @var{key}=@var{value}) may be useful.
> >> +ETEXI
> >> +
> >
> > While there, would you mind improving --help for -device a bit? It's
> > too terse, and it doesn't start the help text in column 16 like the
> > other options do.
> 
> Hi Markus,
> 
> this needs a little more work. I just had a look on the code,
> and there is no online help for the possible options (key, value).
> 
> If you (and especially those who have commit rights) agree,
> I could provide these three additional patches:
> 
> * Add online help for properties (qemu -device driver,?)
> * Add online help for property value (qemu -device driver,property=?)
> * Update documentation for command line option -device
> 
> There is already an online help for the driver (qemu -device ?).
> 
> Regards,
> 
> Stefan
> 

Yes, this was on list of things to be fixed for a long time now.

Some more things that need looking into:

. -device ? itself is undocumented
. - device ? currently prints system devices as well
    let's only print these that have a description
    and add ?? to list all devices
. -netdev has undocumented options as well
. we should have a flag to dump all options in one go,
  for ease of searching

-- 
MST

Re: [Qemu-devel] [PATCH] Documentation: Add missing documentation for qdev related command line options

[Anthony Liguori]

On 01/16/2010 11:19 AM, Stefan Weil wrote:
> The command line options -device, -nodefaults, -readconfig,
> -writeconfig had entries for command line help, but
> documentation for texi and derived formats (man, html, info)
> was missing.
>
> This also required moving "@end table" to the end of
> qemu-options.hx again.
>
> Signed-off-by: Stefan Weil<weil@mail.berlios.de>
>    

Applied.  Thanks.

Regards,

Anthony Liguori

> ---
>   qemu-options.hx |   25 +++++++++++++++++++++----
>   1 files changed, 21 insertions(+), 4 deletions(-)
>
> diff --git a/qemu-options.hx b/qemu-options.hx
> index e2edd71..b2d04e2 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -404,6 +404,12 @@ ETEXI
>
>   DEF("device", HAS_ARG, QEMU_OPTION_device,
>       "-device driver[,options]  add device\n")
> +STEXI
> +@item -device @var{driver}[,@var{option}[,...]]
> +Add device @var{driver}. Depending on the device type,
> +@var{option} (typically @var{key}=@var{value}) may be useful.
> +ETEXI
> +
>   DEF("name", HAS_ARG, QEMU_OPTION_name,
>       "-name string1[,process=string2]\n"
>       "                set the name of the guest\n"
> @@ -1905,6 +1911,8 @@ ETEXI
>   DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \
>       "-nodefaults     don't create default devices\n")
>   STEXI
> +@item -nodefaults
> +Don't create default devices.
>   ETEXI
>
>   #ifndef _WIN32
> @@ -1927,10 +1935,6 @@ Immediately before starting guest execution, drop root privileges, switching
>   to the specified user.
>   ETEXI
>
> -STEXI
> -@end table
> -ETEXI
> -
>   #if defined(TARGET_SPARC) || defined(TARGET_PPC)
>   DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env,
>       "-prom-env variable=value\n"
> @@ -1946,6 +1950,19 @@ DEF("old-param", 0, QEMU_OPTION_old_param,
>   #endif
>   DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig,
>       "-readconfig<file>\n")
> +STEXI
> +@item -readconfig @var{file}
> +Read device configuration from @var{file}.
> +ETEXI
>   DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig,
>       "-writeconfig<file>\n"
>       "                read/write config file\n")
> +STEXI
> +@item -writeconfig @var{file}
> +Write device configuration to @var{file}.
> +ETEXI
> +
> +HXCOMM This is the last statement. Insert new options before this line!
> +STEXI
> +@end table
> +ETEXI
>    

[Qemu-devel] [PATCH 1/3] qdev: Add help for device properties

[Stefan Weil]

When called with property "?", a list of supported
properties will be printed (instead of an error message).

This is useful for command lines like
	qemu -device e1000,?
and was already standard for other options like model=?

Signed-off-by: Stefan Weil <weil@mail.berlios.de>
---
 hw/qdev-properties.c |   15 +++++++++++++--
 1 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/hw/qdev-properties.c b/hw/qdev-properties.c
index 277ff9e..8547ad2 100644
--- a/hw/qdev-properties.c
+++ b/hw/qdev-properties.c
@@ -544,8 +544,19 @@ int qdev_prop_parse(DeviceState *dev, const char *name, const char *value)
 
     prop = qdev_prop_find(dev, name);
     if (!prop) {
-        fprintf(stderr, "property \"%s.%s\" not found\n",
-                dev->info->name, name);
+        if (strcmp(name, "?") != 0) {
+            fprintf(stderr, "property \"%s.%s\" not found\n",
+                    dev->info->name, name);
+        } else {
+            fprintf(stderr, "supported properties:\n");
+            if (dev->info->props != NULL) {
+                Property *props = dev->info->props;
+                while (props->name) {
+                    fprintf(stderr, "%s.%s\n", dev->info->name, props->name);
+                    props++;
+                }
+            }
+        }
         return -1;
     }
     if (!prop->info->parse) {
-- 
1.6.5

[Qemu-devel] [PATCH 2/3] qdev: Add help for property value

[Stefan Weil]

When called with property value "?",
a help text will be printed (instead of an error message).

This is useful for command lines like
    	qemu -device e1000,mac=?
and is already standard for other command line options.

A better help text could be provided by extending
the Property structure with a desc field.

Signed-off-by: Stefan Weil <weil@mail.berlios.de>
---
 hw/qdev-properties.c |    9 +++++++--
 1 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/hw/qdev-properties.c b/hw/qdev-properties.c
index 8547ad2..f5ca05f 100644
--- a/hw/qdev-properties.c
+++ b/hw/qdev-properties.c
@@ -565,8 +565,13 @@ int qdev_prop_parse(DeviceState *dev, const char *name, const char *value)
         return -1;
     }
     if (prop->info->parse(dev, prop, value) != 0) {
-        fprintf(stderr, "property \"%s.%s\": failed to parse \"%s\"\n",
-                dev->info->name, name, value);
+        if (strcmp(value, "?") != 0) {
+            fprintf(stderr, "property \"%s.%s\": failed to parse \"%s\"\n",
+                    dev->info->name, name, value);
+        } else {
+            fprintf(stderr, "%s.%s=%s\n",
+                    dev->info->name, name, prop->info->name);
+        }
         return -1;
     }
     return 0;
-- 
1.6.5

[Qemu-devel] [PATCH 3/3] Documentation: Improve command line help for -device option

[Stefan Weil]

* Fix column for help text.

* Give some more help, especially for the new '?' parameters.

Signed-off-by: Stefan Weil <weil@mail.berlios.de>
---
 qemu-options.hx |   15 ++++++++++++---
 1 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/qemu-options.hx b/qemu-options.hx
index ee60d8a..ef82cac 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -403,11 +403,20 @@ Network adapter that supports CDC ethernet and RNDIS protocols.
 ETEXI
 
 DEF("device", HAS_ARG, QEMU_OPTION_device,
-    "-device driver[,options]  add device\n")
-STEXI
-@item -device @var{driver}[,@var{option}[,...]]
+    "-device driver[,option[=value][,...]]\n"
+    "                add device (based on driver) with default or\n"
+    "                user defined options\n"
+    "                use -device ? to print all possible drivers\n"
+    "                use -device driver,? to print all possible options\n"
+    "                use -device driver,option=? to print a help for value\n")
+STEXI
+@item -device @var{driver}[,@var{option}[=@var{value}][,...]]
 Add device @var{driver}. Depending on the device type,
-@var{option} (typically @var{key}=@var{value}) may be useful.
+@var{option} (with default or given @var{value}) may be useful.
+To get a help on possible @var{driver}s, @var{option}s or @var{value}s, use
+@code{-device ?},
+@code{-device @var{driver},?} or
+@code{-device @var{driver},@var{option}=?}. 
 ETEXI
 
 DEF("name", HAS_ARG, QEMU_OPTION_name,
-- 
1.6.5

Re: [Qemu-devel] [PATCH] Documentation: Add missing documentation for qdev related command line options

[Stefan Weil]

Markus Armbruster schrieb:
> Stefan Weil <weil@mail.berlios.de> writes:
>
>> Markus Armbruster schrieb:
>>> Stefan Weil <weil@mail.berlios.de> writes:
>>>
>>>> The command line options -device, -nodefaults, -readconfig,
>>>> -writeconfig had entries for command line help, but
>>>> documentation for texi and derived formats (man, html, info)
>>>> was missing.
>>>>
>>>> This also required moving "@end table" to the end of
>>>> qemu-options.hx again.
>>>>
>>>> Signed-off-by: Stefan Weil <weil@mail.berlios.de>
>>>> ---
>>>> qemu-options.hx | 25 +++++++++++++++++++++----
>>>> 1 files changed, 21 insertions(+), 4 deletions(-)
>>>>
>>>> diff --git a/qemu-options.hx b/qemu-options.hx
>>>> index e2edd71..b2d04e2 100644
>>>> --- a/qemu-options.hx
>>>> +++ b/qemu-options.hx
>>>> @@ -404,6 +404,12 @@ ETEXI
>>>>
>>>> DEF("device", HAS_ARG, QEMU_OPTION_device,
>>>> "-device driver[,options] add device\n")
>>>> +STEXI
>>>> +@item -device @var{driver}[,@var{option}[,...]]
>>>> +Add device @var{driver}. Depending on the device type,
>>>> +@var{option} (typically @var{key}=@var{value}) may be useful.
>>>> +ETEXI
>>>> +
>>> While there, would you mind improving --help for -device a bit? It's
>>> too terse, and it doesn't start the help text in column 16 like the
>>> other options do.
>> Hi Markus,
>>
>> this needs a little more work. I just had a look on the code,
>> and there is no online help for the possible options (key, value).
>
> What I had in mind was just to bring it up to par with your patch to the
> texi, but...
>
>> If you (and especially those who have commit rights) agree,
>> I could provide these three additional patches:
>>
>> * Add online help for properties (qemu -device driver,?)
>> * Add online help for property value (qemu -device driver,property=?)
>> * Update documentation for command line option -device
>
> ... a patch to provide that is very desirable!
>
> I figure the best way to document available properties and there values
> is a self-documenting struct PropertyInfo: add a doc member, extend
> DEFINE_PROP() & friends to set it, fix up users to pass NULL, and so
> forth. We can then replace the NULL by something useful at our leisure.
>
>> There is already an online help for the driver (qemu -device ?).

I cannot spend too much time on this, but a very basic help
for "?" is implemented by the patch series I just sent to the list.

The new feature was already very helpful for me, but it still
can be improved, of course: the driver list contains shows
too many drivers and is not nicely formatted, the help text
for the values could be more user friendly, ...

Re: [Qemu-devel] [PATCH 1/3] qdev: Add help for device properties

[Markus Armbruster]

Stefan Weil <weil@mail.berlios.de> writes:

> When called with property "?", a list of supported
> properties will be printed (instead of an error message).
>
> This is useful for command lines like
> 	qemu -device e1000,?
> and was already standard for other options like model=?
>
> Signed-off-by: Stefan Weil <weil@mail.berlios.de>
> ---
>  hw/qdev-properties.c |   15 +++++++++++++--
>  1 files changed, 13 insertions(+), 2 deletions(-)
>
> diff --git a/hw/qdev-properties.c b/hw/qdev-properties.c
> index 277ff9e..8547ad2 100644
> --- a/hw/qdev-properties.c
> +++ b/hw/qdev-properties.c
> @@ -544,8 +544,19 @@ int qdev_prop_parse(DeviceState *dev, const char *name, const char *value)
>  
>      prop = qdev_prop_find(dev, name);
>      if (!prop) {
> -        fprintf(stderr, "property \"%s.%s\" not found\n",
> -                dev->info->name, name);
> +        if (strcmp(name, "?") != 0) {
> +            fprintf(stderr, "property \"%s.%s\" not found\n",
> +                    dev->info->name, name);
> +        } else {
> +            fprintf(stderr, "supported properties:\n");
> +            if (dev->info->props != NULL) {
> +                Property *props = dev->info->props;
> +                while (props->name) {
> +                    fprintf(stderr, "%s.%s\n", dev->info->name, props->name);
> +                    props++;
> +                }
> +            }
> +        }
>          return -1;
>      }
>      if (!prop->info->parse) {

I like it.

Re: [Qemu-devel] [PATCH 2/3] qdev: Add help for property value

[Markus Armbruster]

Stefan Weil <weil@mail.berlios.de> writes:

> When called with property value "?",
> a help text will be printed (instead of an error message).
>
> This is useful for command lines like
>     	qemu -device e1000,mac=?
> and is already standard for other command line options.
>
> A better help text could be provided by extending
> the Property structure with a desc field.
>
> Signed-off-by: Stefan Weil <weil@mail.berlios.de>
> ---
>  hw/qdev-properties.c |    9 +++++++--
>  1 files changed, 7 insertions(+), 2 deletions(-)
>
> diff --git a/hw/qdev-properties.c b/hw/qdev-properties.c
> index 8547ad2..f5ca05f 100644
> --- a/hw/qdev-properties.c
> +++ b/hw/qdev-properties.c
> @@ -565,8 +565,13 @@ int qdev_prop_parse(DeviceState *dev, const char *name, const char *value)
>          return -1;
>      }
>      if (prop->info->parse(dev, prop, value) != 0) {
> -        fprintf(stderr, "property \"%s.%s\": failed to parse \"%s\"\n",
> -                dev->info->name, name, value);
> +        if (strcmp(value, "?") != 0) {
> +            fprintf(stderr, "property \"%s.%s\": failed to parse \"%s\"\n",
> +                    dev->info->name, name, value);
> +        } else {
> +            fprintf(stderr, "%s.%s=%s\n",
> +                    dev->info->name, name, prop->info->name);
> +        }
>          return -1;
>      }
>      return 0;

This one is problematic.  If prop->info->parse() accepts "?", help is
inaccessible.  PATCH 1/3 is immune to that problem, because we won't
name a property "?".

PATCH 1/3 already makes -device FOO,? print all property names.  I
figure it could just as well print all help along with names.

Re: [Qemu-devel] [PATCH 1/3] qdev: Add help for device properties

[Markus Armbruster]

Markus Armbruster <armbru@redhat.com> writes:

> Stefan Weil <weil@mail.berlios.de> writes:
>
>> When called with property "?", a list of supported
>> properties will be printed (instead of an error message).
>>
>> This is useful for command lines like
>> 	qemu -device e1000,?
>> and was already standard for other options like model=?
>>
>> Signed-off-by: Stefan Weil <weil@mail.berlios.de>
>> ---
>>  hw/qdev-properties.c |   15 +++++++++++++--
>>  1 files changed, 13 insertions(+), 2 deletions(-)
>>
>> diff --git a/hw/qdev-properties.c b/hw/qdev-properties.c
>> index 277ff9e..8547ad2 100644
>> --- a/hw/qdev-properties.c
>> +++ b/hw/qdev-properties.c
>> @@ -544,8 +544,19 @@ int qdev_prop_parse(DeviceState *dev, const char *name, const char *value)
>>  
>>      prop = qdev_prop_find(dev, name);
>>      if (!prop) {
>> -        fprintf(stderr, "property \"%s.%s\" not found\n",
>> -                dev->info->name, name);
>> +        if (strcmp(name, "?") != 0) {
>> +            fprintf(stderr, "property \"%s.%s\" not found\n",
>> +                    dev->info->name, name);
>> +        } else {
>> +            fprintf(stderr, "supported properties:\n");
>> +            if (dev->info->props != NULL) {
>> +                Property *props = dev->info->props;
>> +                while (props->name) {
>> +                    fprintf(stderr, "%s.%s\n", dev->info->name, props->name);
>> +                    props++;
>> +                }
>> +            }
>> +        }
>>          return -1;
>>      }
>>      if (!prop->info->parse) {
>
> I like it.

One question, though: why print DRIVER.PROPNAME instead of just
PROPNAME?  You could still put DRIVER into the heading, say "Properties
of DRIVER:".

Re: [Qemu-devel] [PATCH] Documentation: Add missing documentation for qdev related command line options

[Markus Armbruster]

Stefan Weil <weil@mail.berlios.de> writes:

> Markus Armbruster schrieb:
>> Stefan Weil <weil@mail.berlios.de> writes:
>>
>>> Markus Armbruster schrieb:
[...]
>>>> While there, would you mind improving --help for -device a bit? It's
>>>> too terse, and it doesn't start the help text in column 16 like the
>>>> other options do.
>>> Hi Markus,
>>>
>>> this needs a little more work. I just had a look on the code,
>>> and there is no online help for the possible options (key, value).
>>
>> What I had in mind was just to bring it up to par with your patch to the
>> texi, but...
>>
>>> If you (and especially those who have commit rights) agree,
>>> I could provide these three additional patches:
>>>
>>> * Add online help for properties (qemu -device driver,?)
>>> * Add online help for property value (qemu -device driver,property=?)
>>> * Update documentation for command line option -device
>>
>> ... a patch to provide that is very desirable!
>>
>> I figure the best way to document available properties and there values
>> is a self-documenting struct PropertyInfo: add a doc member, extend
>> DEFINE_PROP() & friends to set it, fix up users to pass NULL, and so
>> forth. We can then replace the NULL by something useful at our leisure.
>>
>>> There is already an online help for the driver (qemu -device ?).
>
> I cannot spend too much time on this, but a very basic help
> for "?" is implemented by the patch series I just sent to the list.
>
> The new feature was already very helpful for me, but it still
> can be improved, of course: the driver list contains shows
> too many drivers and is not nicely formatted, the help text
> for the values could be more user friendly, ...

It's a start.  Many thanks!

Re: [Qemu-devel] [PATCH 1/3] qdev: Add help for device properties

[Gerd Hoffmann]

On 01/21/10 17:44, Markus Armbruster wrote:
> Markus Armbruster<armbru@redhat.com>  writes:
>
>>> -        fprintf(stderr, "property \"%s.%s\" not found\n",
>>> -                dev->info->name, name);

>>> +                    fprintf(stderr, "%s.%s\n", dev->info->name, props->name);
>>> +                    props++;

> One question, though: why print DRIVER.PROPNAME instead of just
> PROPNAME?  You could still put DRIVER into the heading, say "Properties
> of DRIVER:".

Probably for consistency with the error messages.

cheers,
   Gerd