| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-ID: <4c05c2bb-af77-d706-9455-8ceaa5510580@gmail.com>
Date: Fri, 21 Apr 2017 13:41:18 +0200
From: "Michael Kerrisk (man-pages)" <mtk.manpages@...il.com>
To: Mike Rapoport <rppt@...ux.vnet.ibm.com>
Cc: mtk.manpages@...il.com, Andrea Arcangeli <aarcange@...hat.com>,
lkml <linux-kernel@...r.kernel.org>,
"linux-mm@...ck.org" <linux-mm@...ck.org>,
linux-man <linux-man@...r.kernel.org>
Subject: Re: Review request: draft ioctl_userfaultfd(2) manual page
Hi Mike,
On 04/21/2017 01:07 PM, Mike Rapoport wrote:
> Hello Michael,
>
> On Fri, Apr 21, 2017 at 11:11:18AM +0200, Michael Kerrisk (man-pages) wrote:
>> Hello Mike,
>> Hello Andrea (we need your help!),
>>
>> On 03/22/2017 02:54 PM, Mike Rapoport wrote:
>>> Hello Michael,
>>>
>>> On Mon, Mar 20, 2017 at 09:11:07PM +0100, Michael Kerrisk (man-pages) wrote:
>>>> Hello Andrea, Mike, and all,
>>>>
>>>> Mike: here's the split out page that describes the
>>>> userfaultfd ioctl() operations.
>>>>
>>>> I'd like to get review input, especially from you and
>>>> Andrea, but also anyone else, for the current version
>>>> of this page, which includes quite a few FIXMEs to be
>>>> sorted.
>>>>
>>>> I've shown the rendered version of the page below.
>>>> The groff source is attached, and can also be found
>>>> at the branch here:
>>>>
>>>> https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/log/?h=draft_userfaultfd
>>>>
>>>> The new ioctl_userfaultfd(2) page follows this mail.
>>>>
>>>> Cheers,
>>>>
>>>> Michael
>>>>
>>>> NAME
>>>> userfaultfd - create a file descriptor for handling page faults in user
>>>> space
>>>>
>>>> SYNOPSIS
>>>> #include <sys/ioctl.h>
>>>>
>>>> int ioctl(int fd, int cmd, ...);
>>>>
>>>> DESCRIPTION
>>>> Various ioctl(2) operations can be performed on a userfaultfd object
>>>> (created by a call to userfaultfd(2)) using calls of the form:
>>>>
>>>> ioctl(fd, cmd, argp);
>>>>
>>>> In the above, fd is a file descriptor referring to a userfaultfd
>>>> object, cmd is one of the commands listed below, and argp is a pointer
>>>> to a data structure that is specific to cmd.
>>>>
>>>> The various ioctl(2) operations are described below. The UFFDIO_API,
>>>> UFFDIO_REGISTER, and UFFDIO_UNREGISTER operations are used to configure
>>>> userfaultfd behavior. These operations allow the caller to choose what
>>>> features will be enabled and what kinds of events will be delivered to
>>>> the application. The remaining operations are range operations. These
>>>> operations enable the calling application to resolve page-fault events
>>>> in a consistent way.
>>>>
>>>>
>>>> ┌─────────────────────────────────────────────────────┐
>>>> │FIXME │
>>>> ├─────────────────────────────────────────────────────┤
>>>> │Above: What does "consistent" mean? │
>>>> │ │
>>>> └─────────────────────────────────────────────────────┘
>>>
>>> Andrea, can you please help with this one?
>>
>> Let's see what Andrea has to say.
>
> Actually, I though I've copied this text from Andrea's docs, but now I've
> found out it was my wording and I really don't remember now what was my
> intention for "consistent" :)
> My guess is that I was thinking about atomicity of UFFDIO_COPY, or the fact
> that from the faulting thread perspective the page fault handling is the
> same whether it's done in kernel or via userfaultfd...
> That said, maybe it'd be better just to drop "in a consistent way".
Okay. Dropped.
>>>> UFFDIO_API
>>>> (Since Linux 4.3.) Enable operation of the userfaultfd and perform API
>>>> handshake. The argp argument is a pointer to a uffdio_api structure,
>>>> defined as:
>>>>
>>>> struct uffdio_api {
>>>> __u64 api; /* Requested API version (input) */
>>>> __u64 features; /* Must be zero */
>>>> __u64 ioctls; /* Available ioctl() operations (output) */
>>>> };
>>>>
>>>> The api field denotes the API version requested by the application.
>>>> Before the call, the features field must be initialized to zero.
>>>>
>>>>
>>>> ┌─────────────────────────────────────────────────────┐
>>>> │FIXME │
>>>> ├─────────────────────────────────────────────────────┤
>>>> │Above: Why must the 'features' field be initialized │
>>>> │to zero? │
>>>> └─────────────────────────────────────────────────────┘
>>>
>>> Until 4.11 the only supported feature is delegation of missing page fault
>>> and the UFFDIO_FEATURES bitmask is 0.
>>
>> So, the thing that was not clear, but now I think I understand:
>> 'features' is an input field where one can ask about supported features
>> (but none are supported, before Linux 4.11). Is that correct?
>
> Yes.
Thanks.
>> I've changed the text here to read:
>>
>> Before the call, the features field must be initialized
>> to zero. In the future, it is intended that this field can be
>> used to ask whether particular features are supported.
>>
>> Seem okay?
>
> Yes.
> Just the future is only a week or two from today as we are at 4.11-rc7 :)
Yes, I understand :-). So of course there's a *lot* more
new stuff to document, right?
[...]
>>>> UFFDIO_REGISTER
[...]
>>>> EINVAL There as an incompatible mapping in the specified address range.
>>>>
>>>>
>>>> ┌─────────────────────────────────────────────────────┐
>>>> │FIXME │
>>>> ├─────────────────────────────────────────────────────┤
>>>> │Above: What does "incompatible" mean? │
>>>> │ │
>>>> └─────────────────────────────────────────────────────┘
>>>
>>> Up to 4.10 userfault context may be registered only for MAP_ANONYMOUS |
>>> MAP_PRIVATE mappings.
>>
>> Hmmm -- this restriction is not actually mentioned in the description
>> of UFFDIO_REGISTER. So, at the start of the description of that operation,
>> I've made the text as follows:
>>
>> [[
>> .SS UFFDIO_REGISTER
>> (Since Linux 4.3.)
>> Register a memory address range with the userfaultfd object.
>> The pages in the range must be "compatible".
>> In the current implementation,
>> .\" According to Mike Rapoport, this will change in Linux 4.11.
>> only private anonymous ranges are compatible for registering with
>> .BR UFFDIO_REGISTER .
>> ]]
>>
>> Okay?
>
> Yes.
Thanks for checking it.
>>>> UFFDIO_UNREGISTER
[...]
>>>> EINVAL There as an incompatible mapping in the specified address range.
>>>>
>>>>
>>>> ┌─────────────────────────────────────────────────────┐
>>>> │FIXME │
>>>> ├─────────────────────────────────────────────────────┤
>>>> │Above: What does "incompatible" mean? │
>>>> └─────────────────────────────────────────────────────┘
>>>
>>> The same comments as for UFFDIO_REGISTER apply here as well.
>>
>> Okay. I changed the introductory text on UFFDIO_UNREGISTER to say:
>>
>> [[
>> .SS UFFDIO_UNREGISTER
>> (Since Linux 4.3.)
>> Unregister a memory address range from userfaultfd.
>> The pages in the range must be "compatible" (see the description of
>> .BR UFFDIO_REGISTER .)
>> ]]
>>
>> Okay?
>
> Yes.
Thanks.
[...]
The current version of the two pages has been pushed to
https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/log/?h=draft_userfaultfd
Cheers,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
Powered by blists - more mailing lists