Использование

Механизм userfaultfd разработан для того, чтобы позволить нити в многонитевой программе выполнять деление на страницы пользовательского пространства других нитей процесса. При возникновении страничной ошибки в одной из зарегистрированных в объекте userfaultfd областей нить с ошибкой засыпает и генерируется событие, которое можно прочитать через файловый дескриптор userfaultfd. Нить обработки страничных ошибок читает сообщения из этого файлового дескриптора и обслуживает из с помощью операций, описанных в ioctl_userfaultfd(2). В время этого нить обработки страничных ошибок может привести в действие механизм пробуждения спящей нити.

Нити с ошибкой и нити обработки страничных ошибок могут быть запущены в контексте различных процессов. В этом случае данные нити могут принадлежать разным программам, а программам, выполняющим нити с ошибкой, не обязательно взаимодействовать с программой, обрабатывающей страничные ошибки. В таком разобщённом режиме процессу, следящему за userfaultfd и обрабатывающему страничные ошибки, необходимо знать об изменениях в раскладке виртуальной памяти процесса с ошибкой, чтобы не допустить повреждение памяти.

Начиная с Linux 4.11, userfaultfd также уведомляет нити обработки страничных ошибок об изменениях в раскладке виртуальной памяти процесса с ошибкой. Также, если процесс с ошибкой вызывает fork(2), то для объекта userfaultfd, связанного с родителем, в дочернем процессе может быть создать дубликат, и отслеживающий userfaultfd также будет уведомлён (смотрите описание UFFD_EVENT_FORK ниже) о файловом дескрипторе, связанном с объектом userfault, который был создан для дочернего процесса, что позволяет отслеживающему userfaultfd выполнять деление на страницы пользовательское пространство дочернего процесса. В отличие от страничных ошибок, которые происходят синхронно и требуют явного или неявного пробуждения, все остальные события доставляются асинхронно и не взаимодействующий процесс возобновляет выполнение сразу же после того как отслеживающий userfaultfd выполняет read(2). Отслеживающий userfaultfd должен корректно синхронизировать вызовы UFFDIO_COPY при обработке событий.

Имеющаяся асинхронная модель доставки событий оптимальна для реализации однонитевой не взаимодействующей отслеживающей userfaultfd программы.

Работа с userfaultfd

После создания объекта userfaultfd с помощью userfaultfd() приложение должно включить его с помощью операции UFFDIO_API вызова ioctl(2). Данная операция позволяет согласовать между ядром и пользовательским пространством версию программного интерфейса поддерживаемых свойств. Эта операция должна быть выполнено самой первой среди других операций ioctl(2), описываемых ниже (в противном случае эти операции завершаются ошибкой EINVAL).

После успешного выполнения UFFDIO_API приложение должно зарегистрировать диапазоны адресов памяти с помощью операции UFFDIO_REGISTER вызова ioctl(2). После успешного выполнения UFFDIO_REGISTER страничная ошибка, возникающая в запрошенном диапазоне и удовлетворяющая режиму, определённому в момент регистрации, будет переслана ядром приложению в пользовательском пространстве. Для решения страничной ошибки приложение может использовать операцию UFFDIO_COPY или UFFDIO_ZEROPAGE вызова ioctl(2).

Начиная с Linux 4.14, если приложение устанавливает бит свойства UFFD_FEATURE_SIGBUS с помощью UFFDIO_API ioctl(2), то уведомления о страничных ошибках не пересылаются в пользовательское пространство. Вместо этого в ошибшийся процесс посылается сигнал SIGBUS. С данным свойством userfaultfd можно использовать в целях надёжности, просто ловя все попытки доступа к областях внутри зарегистрированного адресного диапазона, в котором нет выделенных страниц, не слушая при этом события userfaultfd. При таком доступе к памяти не потребуется процесс слежения за userfaultfd. Например, данное свойство может оказаться полезным приложениям, которые хотят не давать ядру выполнять автоматическое выделение страниц и заполнение дыр в разреженных файлах при обращении к дыре через отображение в памяти.

Свойство UFFD_FEATURE_SIGBUS неявно наследуется при fork(2), если используется вместе с UFFD_FEATURE_FORK.

Подробности о различных операциях ioctl(2) можно найти в ioctl_userfaultfd(2).

Начиная с Linux 4.11 при операции UFFDIO_API можно включить не только события страничной ошибки.

До Linux 4.11 объект userfaultfd мог быть использован только с анонимными частными отображениями памяти. Начиная с Linux 4.11 объект userfaultfd может также использоваться с отображениями общей памяти и hugetlbfs.

Чтение из структуры userfaultfd

Каждый вызов read(2) из файлового дескриптора userfaultfd возвращает одну или более структур uffd_msg, каждая из которых описывает событие страничной ошибки или событие, требуемое для использования userfaultfd в разобщённом режиме:

struct uffd_msg {

    __u8  event;            /* тип события */

    ...

    union {

        struct {

            __u64 flags;    /* флаги, описывающие ошибку */

            __u64 address;  /* ошибочный адрес */

        } pagefault;

        struct {            /* начиная с Linux 4.11 */

            __u32 ufd;      /* файловый дескриптор userfault

                               дочернего процесса */

        } fork;

        struct {            /* начиная с Linux 4.11 */

            __u64 from;     /* старый адрес переотображаемой области */

            __u64 to;       /* новый адрес переотображаемой области */

            __u64 len;      /* начальный размер отображения */

        } remap;

        struct {            /* начиная с Linux 4.11 */

            __u64 start;    /* начальный адрес удаляемой области */

            __u64 end;      /* конечный адрес удаляемой области */

        } remove;

        ...

    } arg;

    /* поля-заполнители не показаны */
} __packed;

Если доступно несколько событий и переданный буфер достаточного размера, то read(2) возвращает столько событий сколько влезает в буфер. Если буфер, указанный read(2), меньше размера структуры uffd_msg, то read(2) завершается ошибкой EINVAL.

Поля структуры uffd_msg:

event

Тип события. Тип события влияет на заполняемые поля объединения arg, представляющего детали, требуемые для обработки события. События, не относящиеся к страничным ошибкам, генерируются только когда включено соответствующее свойство при согласовании программного интерфейса с помощью операции UFFDIO_API вызова ioctl(2).

В поле event могут появляться следующие значения:

pagefault.address

Адрес, из-за которого возникла страничная ошибка.

pagefault.flags

Битовая маска флагов, описывающих событие. Для UFFD_EVENT_PAGEFAULT может появляться следующий флаг:

fork.ufd

С помощью fork(2) был создан потомок, для которого был создан файловый дескриптор, связанный с объектом userfault.

remap.from

Первоначальный адрес диапазона памяти, который был переотображён с помощью mremap(2).

remap.to

Новый адрес диапазона памяти, который был переотображён с помощью mremap(2).

remap.len

Первоначальный размер диапазона памяти, который был переотображён с помощью mremap(2).

remove.start

Начальный адрес диапазона памяти, который был освобождён с помощью madvise(2) или было отменено проецирование.

remove.end

Конечный адрес диапазона памяти, который был освобождён с помощью madvise(2) или было отменено проецирование.

Вызов read(2) с файловым дескриптором userfaultfd может завершиться следующими ошибками:

EINVAL

Объект userfaultfd не был включён с помощью операции UFFDIO_API вызова ioctl(2).

Если в связанном открытом файловом описании указан флаг O_NONBLOCK, то файловый дескриптор userfaultfd можно отслеживать с помощью poll(2), select(2) и epoll(7). При возникновении событий, файловый дескриптор помечается как доступный на чтение. Если флаг O_NONBLOCK не задан, то poll(2) (всегда) показывает, что файл находится в состоянии POLLERR, а select(2) показывает, что файловый дескриптор доступен на чтение и запись.

Исходный код программы

/* userfaultfd_demo.c

   распространяется по лицензии GNU General Public License version 2 и новее.
*/
#define _GNU_SOURCE
#include <sys/types.h>
#include <stdio.h>
#include <linux/userfaultfd.h>
#include <pthread.h>
#include <errno.h>
#include <unistd.h>
#include <stdlib.h>
#include <fcntl.h>
#include <signal.h>
#include <poll.h>
#include <string.h>
#include <sys/mman.h>
#include <sys/syscall.h>
#include <sys/ioctl.h>
#include <poll.h>
#define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \

                        } while (0)
static int page_size;
static void *
fault_handler_thread(void *arg)
{

    static struct uffd_msg msg;   /* данные, прочитанные из userfaultfd */

    static int fault_cnt = 0;     /* количество обработанных ошибок */

    long uffd;                    /* файловый дескриптор userfaultfd */

    static char *page = NULL;

    struct uffdio_copy uffdio_copy;

    ssize_t nread;

    uffd = (long) arg;

    /* создаём страницу, которая будет копироваться в ошибочную область */

    if (page == NULL) {

        page = mmap(NULL, page_size, PROT_READ | PROT_WRITE,

                    MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);

        if (page == MAP_FAILED)

            errExit("mmap");

    }

    /* циклически обрабатываем входные сообщения в

       файловом дескрипторе userfaultfd */

    for (;;) {

        /* С помощью poll() проверяем userfaultfd */

        struct pollfd pollfd;

        int nready;

        pollfd.fd = uffd;

        pollfd.events = POLLIN;

        nready = poll(&pollfd, 1, -1);

        if (nready == -1)

            errExit("poll");

        printf("\nfault_handler_thread():\n");

        printf("    poll() вернул: nready = %d; "

                "POLLIN = %d; POLLERR = %d\n", nready,

                (pollfd.revents & POLLIN) != 0,

                (pollfd.revents & POLLERR) != 0);

        /* читаем событие из userfaultfd */

        nread = read(uffd, &msg, sizeof(msg));

        if (nread == 0) {

            printf("EOF в userfaultfd!\n");

            exit(EXIT_FAILURE);

        }

        if (nread == -1)

            errExit("read");

        /* ожидаем только один тип событий; проверяем, что это так */

        if (msg.event != UFFD_EVENT_PAGEFAULT) {

            fprintf(stderr, "Неожидаемый тип события в userfaultfd\n");

            exit(EXIT_FAILURE);

        }

        /* показываем информацию о событии страничной ошибки */

        printf("    событие UFFD_EVENT_PAGEFAULT: ");

        printf("флаги = %llx; ", msg.arg.pagefault.flags);

        printf("адрес = %llx\n", msg.arg.pagefault.address);

        /* копируем страницу, на которую указывает 'page', в ошибочную

           область. Меняем содержимое, которое копируем для того, чтобы

           было более очевидно, что каждая ошибка обрабатывается отдельно. */

        memset(page, 'A' + fault_cnt % 20, page_size);

        fault_cnt++;

        uffdio_copy.src = (unsigned long) page;

        /* мы должны обрабатывать страничные ошибки в единицах страниц(!).

           поэтому округляем адрес ошибки по нижней границы страницы */

        uffdio_copy.dst = (unsigned long) msg.arg.pagefault.address &

                                           ~(page_size - 1);

        uffdio_copy.len = page_size;

        uffdio_copy.mode = 0;

        uffdio_copy.copy = 0;

        if (ioctl(uffd, UFFDIO_COPY, &uffdio_copy) == -1)

            errExit("ioctl-UFFDIO_COPY");

        printf("        (uffdio_copy.copy равно %lld)\n",

                uffdio_copy.copy);

    }
}
int
main(int argc, char *argv[])
{

    long uffd;          /* файловый дескриптор userfaultfd */

    char *addr;         /* Начало области, обрабатываемое userfaultfd */

    unsigned long len;  /* Размер области, обрабатываемой userfaultfd */

    pthread_t thr;      /* ID нити, обрабатывающей страничные ошибки */

    struct uffdio_api uffdio_api;

    struct uffdio_register uffdio_register;

    int s;

    if (argc != 2) {

        fprintf(stderr, "Использование: %s количество-страниц\n", argv[0]);

        exit(EXIT_FAILURE);

    }

    page_size = sysconf(_SC_PAGE_SIZE);

    len = strtoul(argv[1], NULL, 0) * page_size;

    /* создаём и включаем объект userfaultfd */

    uffd = syscall(__NR_userfaultfd, O_CLOEXEC | O_NONBLOCK);

    if (uffd == -1)

        errExit("userfaultfd");

    uffdio_api.api = UFFD_API;

    uffdio_api.features = 0;

    if (ioctl(uffd, UFFDIO_API, &uffdio_api) == -1)

        errExit("ioctl-UFFDIO_API");

    /* Копируем частное анонимное отображение. Память будет

       выделена по требованию, то есть реально не выделяется. Когда мы

       обратимся к памяти, она будет выделена с помощью

       userfaultfd. */

    addr = mmap(NULL, len, PROT_READ | PROT_WRITE,

                MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);

    if (addr == MAP_FAILED)

        errExit("mmap");

    printf("Адрес, возвращённый mmap() = %p\n", addr);

    /* Регистрируем в объекте userfaultfd область памяти отображения

       которое мы только что создали. Запрашиваем режим слежения

       за отсутствующими страницами (т. е., которые пока не

       были заполнены). */

    uffdio_register.range.start = (unsigned long) addr;

    uffdio_register.range.len = len;

    uffdio_register.mode = UFFDIO_REGISTER_MODE_MISSING;

    if (ioctl(uffd, UFFDIO_REGISTER, &uffdio_register) == -1)

        errExit("ioctl-UFFDIO_REGISTER");

    /* Создаём нить, которая будет обрабатывать события  userfaultfd */

    s = pthread_create(&thr, NULL, fault_handler_thread, (void *) uffd);

    if (s != 0) {

        errno = s;

        errExit("pthread_create");

    }

    /* Теперь главная нить обращается к памяти в отображении c

       интервалом в 1024 байта. Это создаст события в userfaultfd

       для всех страниц в области. */

    int l;

    l = 0xf;    /* Гарантируем, что ошибочный адрес не на границе

                   страницы, чтобы протестировать что, мы правильно

                   обрабатываем этот случай в fault_handling_thread() */

    while (l < len) {

        char c = addr[l];

        printf("Чтение по адресу %p в main(): ", addr + l);

        printf("%c\n", c);

        l += 1024;

        usleep(100000);         /* замедлим программу */

    }

    exit(EXIT_SUCCESS);
}