Re: [PATCH 0/5] {ioctl_}userfaultfd.2: initial updates for 4.11

[Michael Kerrisk (man-pages)]

Hello Mike,

On 04/26/2017 09:43 AM, Mike Rapoport wrote:
> On Wed, Apr 26, 2017 at 09:23:45AM +0200, Michael Kerrisk (man-pages) wrote:
>> Hello Mike,
>>
>> On 04/25/2017 06:29 PM, Mike Rapoport wrote:
>>> Hello Michael,
>>>
>>> These patches are some kind of brief highlights of the changes to the
>>> userfaultfd pages.
>>
>> Thanks for the patches. All merged. A few tweaks made,
>> and pushed to Git.
>>
>>> The changes to userfaultfd functionality are also described at update to
>>> Documentation/vm/userfaultfd.txt [1].
>>>
>>> In general, there were three major additions:
>>> * hugetlbfs support
>>> * shmem support
>>> * non-page fault events
>>>
>>> I think we should add some details about using userfaultfd with different
>>> memory types, describe meaning of each feature bits and add some text about
>>> the new events.
>>
>> Agreed.
>>
>>> I haven't updated 'struct uffd_msg' yet, and I hesitate whether it's
>>> description belongs to userfaultfd.2 or ioctl_userfaultfd.2
>>
>> My guess is userfaultfd.2. But, maybe I missed something.
>> What suggests to you that it could be ioctl_userfaultfd.2 instead?
> 
> I've started to add relatively elaborate descriptions of UFFD_EVENT_* to
> ioctl_userfaultfd.2 and I've found that I write a lot about struct uffd_msg
> fields, but the structure itself is described at userfaultfd.2.
> Now, when I'm thinking about it, maybe it would be better to put the
> detailed descriptions of the events in userfaultfd.2 and only brief notes
> in ioctl_userfaultfd.2.

Okay -- we can tune as we go along.

>>> As for the userfaultfd.7 we've discussed earlier, I believe it would
>>> repeat Documentation/vm/userfaultfd.txt in way, so I'm not really sure it
>>> is required.
>>
>> The thing about kernel Doc files is they are a lot less visible.
>> It would be best I think to have the user-space visible
>> API fully described in man pages...
> 
> I agree with the point about the visibility, I just don't know if
> userfaultfd.7 would be required or we'll have all the necessary bits in
> {ioctl_}userfaultfd.2. I'm going to add more content to the man2 pages and
> then we'll see if we need man7 as well.

Okay.

Cheers,

Michael


>> Cheers,
>>
>> Michael
>>
>>
>>> [1] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=5a02026d390ea1bb0c16a0e214e45613a3e3d885
>>>
>>> Mike Rapoport (5):
>>>   userfaultfd.2: describe memory types that can be used from 4.11
>>>   ioctl_userfaultfd.2: describe memory types that can be used from 4.11
>>>   ioctl_userfaultfd.2: update UFFDIO_API description
>>>   userfaultfd.2: add Linux container migration use-case to NOTES
>>>   usefaultfd.2: add brief description of "non-cooperative" mode
>>>
>>>  man2/ioctl_userfaultfd.2 | 46 ++++++++++++++++++++++++++++++++++++++--------
>>>  man2/userfaultfd.2       | 25 ++++++++++++++++++++++---
>>>  2 files changed, 60 insertions(+), 11 deletions(-)
>>>
>>
>>
>> -- 
>> Michael Kerrisk
>> Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
>> Linux/UNIX System Programming Training: http://man7.org/training/
>>
> 
> --
> To unsubscribe from this list: send the line "unsubscribe linux-man" in
> the body of a message to majordomo@xxxxxxxxxxxxxxx
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/