Re: [Qemu-devel] [PATCH 6/6] virtfs: Fix documentation of -fsdev and -virtfs

[Thomas Huth]

On 13/05/2019 11.34, Greg Kurz wrote:
> On Mon, 13 May 2019 10:39:17 +0200
> Thomas Huth <address@hidden> wrote:
> 
>> On 09/05/2019 15.18, Greg Kurz wrote:
>>> On Wed, 8 May 2019 17:54:42 +0200
>>> Thomas Huth <address@hidden> wrote:
>>>   
>>>> On 07/05/2019 10.45, Greg Kurz wrote:  
>>>>> This fixes several things:
>>>>> - add "id" description to -virtfs documentation
>>>>> - split the description into several lines in both usage and documentation
>>>>>   for accurateness and clarity
>>>>> - add documentation and usage of the synth fsdriver
>>>>> - add "throttling.*" description to -fsdev local
>>>>> - add some missing periods
>>>>>
>>>>> Buglink: https://bugs.launchpad.net/qemu/+bug/1581976
>>>>> Signed-off-by: Greg Kurz <address@hidden>
>>>>> ---
>>>>>  qemu-options.hx |   84 
>>>>> +++++++++++++++++++++++++++++++++++++++----------------
>>>>>  1 file changed, 60 insertions(+), 24 deletions(-)
>>>>>
>>>>> diff --git a/qemu-options.hx b/qemu-options.hx
>>>>> index 9c5cc2e6bf70..975342dfbd66 100644
>>>>> --- a/qemu-options.hx
>>>>> +++ b/qemu-options.hx
>>>>> @@ -1232,26 +1232,35 @@ the write back by pressing @key{C-a s} 
>>>>> (@pxref{disk_images}).
>>>>>  ETEXI
>>>>>  
>>>>>  DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev,
>>>>> -    "-fsdev 
>>>>> fsdriver,id=id[,path=path,][security_model={mapped-xattr|mapped-file|passthrough|none}]\n"
>>>>> -    " 
>>>>> [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd][,fmode=fmode][,dmode=dmode]\n"
>>>>> +    "-fsdev 
>>>>> local,id=id,path=path,security_model=mapped-xattr|mapped-file|passthrough|none\n"
>>>>> +    " [,writeout=immediate][,readonly][,fmode=fmode][,dmode=dmode]\n"
>>>>>      " 
>>>>> [[,throttling.bps-total=b]|[[,throttling.bps-read=r][,throttling.bps-write=w]]]\n"
>>>>>      " 
>>>>> [[,throttling.iops-total=i]|[[,throttling.iops-read=r][,throttling.iops-write=w]]]\n"
>>>>>      " 
>>>>> [[,throttling.bps-total-max=bm]|[[,throttling.bps-read-max=rm][,throttling.bps-write-max=wm]]]\n"
>>>>>      " 
>>>>> [[,throttling.iops-total-max=im]|[[,throttling.iops-read-max=irm][,throttling.iops-write-max=iwm]]]\n"
>>>>> -    " [[,throttling.iops-size=is]]\n",
>>>>> +    " [[,throttling.iops-size=is]]\n"
>>>>> +    "-fsdev proxy,id=id,socket=socket[,writeout=immediate][,readonly]\n"
>>>>> +    "-fsdev 
>>>>> proxy,id=id,sock_fd=sock_fd[,writeout=immediate][,readonly]\n"
>>>>> +    "-fsdev synth,id=id\n",
>>>>>      QEMU_ARCH_ALL)
>>>>>  
>>>>>  STEXI
>>>>>  
>>>>> address@hidden -fsdev 
>>>>> @var{fsdriver},address@hidden,address@hidden,address@hidden,address@hidden,readonly][,address@hidden|address@hidden,address@hidden,address@hidden
>>>>> address@hidden -fsdev local,address@hidden,address@hidden,address@hidden 
>>>>> [,address@hidden,readonly][,address@hidden,address@hidden 
>>>>> [,address@hidden@var{value}[,address@hidden@var{value}[,...]]]
>>>>> address@hidden -fsdev 
>>>>> proxy,address@hidden,address@hidden,address@hidden,readonly]
>>>>> address@hidden -fsdev 
>>>>> proxy,address@hidden,address@hidden,address@hidden,readonly]
>>>>> address@hidden -fsdev synth,address@hidden,readonly]
>>>>>  @findex -fsdev
>>>>>  Define a new file system device. Valid options are:
>>>>>  @table @option
>>>>> address@hidden @var{fsdriver}
>>>>> -This option specifies the fs driver backend to use.
>>>>> -Currently "local" and "proxy" file system drivers are supported.
>>>>> address@hidden local
>>>>> +Accesses to the filesystem are done by QEMU.
>>>>> address@hidden proxy
>>>>> +Accesses to the filesystem are done by virtfs-proxy-helper(1).
>>>>> address@hidden synth
>>>>> +Synthetic filesystem, only used by QTests.
>>>>>  @item address@hidden
>>>>> -Specifies identifier for this device
>>>>> +Specifies identifier for this device.
>>>>>  @item address@hidden
>>>>>  Specifies the export path for the file system device. Files under
>>>>>  this path will be available to the 9p client on the guest.
>>>>> @@ -1279,17 +1288,33 @@ Enables exporting 9p share as a readonly mount 
>>>>> for guests. By default
>>>>>  read-write access is given.
>>>>>  @item address@hidden
>>>>>  Enables proxy filesystem driver to use passed socket file for 
>>>>> communicating
>>>>> -with virtfs-proxy-helper
>>>>> +with virtfs-proxy-helper(1).    
>>>>
>>>> Why did you add a "(1)" after each virtfs-proxy-helper?
>>>>  
>>>
>>> Oops forgot to mention that in the changelog... We have a manual page for 
>>> the
>>> virtfs-proxy-helper command, and IIUC this is the way for a manual page to
>>> reference another one. Makes sense ?  
>>
>> Makes sense for the man page ... but it might look a little bit strange
>> in the qemu-doc.html file? I've got no strong opinion, but I think I'd
>> rather not include the "(1)" here.
>>
> 
> FWIW, we already have some similar references to manual pages:
> 
> $ grep '([1-9])' qemu-doc.html
> <p>Note that, by default, GUS shares IRQ(7) with parallel ports and so
> QEMU mmap(2) <samp>mem-path</samp>, and accepts common suffixes, eg
> <dd><p>is a QEMU user creatable object definition. See the 
> <code>qemu(1)</code> manual
> <p>The size syntax is similar to dd(1)&rsquo;s size syntax.
> See the <code>qemu(1)</code> manual page for full details of the properties

Ok, you convinced me.

 Thomas