Re: Document EVFILT_FS and VQ_*

2010/9/21 John Baldwin <jhb_at_freebsd.org>:
> On Tuesday, September 21, 2010 8:22:24 am Baptiste Daroussin wrote:
>> Hi,
>>
>> For a projects I needed to use EVFILT_FS and saw that it hasn't been documented
>> so here is a patch to document it http://planet.etoilebsd.net/kqueue.2.diff
>>
>> It is based on the commit message for the implementation of EVFILT_FS, sorry I
>> don't know how to better document it
>> (http://lists.freebsd.org/pipermail/cvs-src/2005-September/052288.html)
>
> Hmm, the code for this seems quite broken.  For example, when an NFS mount is
> marked up, it posts an event saying it is down.  Right now when the user gets
> an EVFILT_FS event, the info in the event contains a mask of states that have
> changed, but the code would still need to issue a VFS_CTL_QUERY sysctl to get
> the actual state.  It would be more useful if the kevent could return two
> values: 1) would be a bitmask of changed flags, and 2) would be the current
> state of the vfs query flags.  Perhaps 2) could be implemented in kn_data,
> but we would need to change the kernel to keep the current state of the
> vfs query flags in 'struct mount' (this could be done in vfs_event_signal()).
> Doing so would also allow VFS_CTL_QUERY to be implemented generically.
>
>> While using it I also discover that VQ_MOUNT, VQ_UMOUNT, VQ_NOTRESP and
>> VQ_NOTRESPLOCK are not documented either but I don't know where to document
>> them.
>
> VFS_CTL_QUERY is not really documented either.  For now I think you could
> document all of this in kevent(2).  At the very least, you should note that
> for EVFILT_FS, the 'flags' field is a bitmask of changed flags that can be
> queried via VFS_CTL_QUERY.  If the code is changed to provide the current
> flags in 'data', then you could just document the flags explicitly and not
> bother mentioning VFS_CTL_QUERY.
>

*Ouch* I'm far from understanding everything, I think I won't be able
to document all that without a real comprehension of it.

At the begining I just wanted to point out that some parts wasn't
documented, and try to document what I could :)

regards,
Bapt