Patchwork Documentation: Add missing documentation for qdev related command line options

login
register
mail settings
Submitter Stefan Weil
Date Jan. 16, 2010, 5:19 p.m.
Message ID <1263662384-1459-1-git-send-email-weil@mail.berlios.de>
Download mbox | patch
Permalink /patch/43013/
State New
Headers show

Comments

Stefan Weil - Jan. 16, 2010, 5:19 p.m.
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(-)
Markus Armbruster - Jan. 18, 2010, 10:09 a.m.
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!
Stefan Weil - Jan. 18, 2010, 7:32 p.m.
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
Markus Armbruster - Jan. 19, 2010, 9:38 a.m.
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 ?).
Michael S. Tsirkin - Jan. 19, 2010, 1:32 p.m.
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
Anthony Liguori - Jan. 20, 2010, 2:55 p.m.
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
>
Stefan Weil - Jan. 20, 2010, 10:05 p.m.
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, ...
Markus Armbruster - Jan. 21, 2010, 4:45 p.m.
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!

Patch

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