Provided by: manpages-fr-dev_4.21.0-2_all 
NOM
userfaultfd - Créer un descripteur de fichier pour gérer les erreurs de page en espace
utilisateur
BIBLIOTHÈQUE
Bibliothèque C standard (libc, -lc)
SYNOPSIS
#include <fcntl.h> /* Définition des constantes O_* */
#include <sys/syscall.h> /* Définition des constantes SYS_* */
#include <linux/userfaultfd.h> /* Définition des constantes UFFD_* */
#include <unistd.h>
int syscall(SYS_userfaultfd, int flags);
Note : la glibc ne fournit pas d'enveloppe pour userfaultfd(), imposant l'utilisation de
syscall(2).
DESCRIPTION
userfaultfd() crée un nouvel objet userfaultfd qui peut être utilisé pour la délégation de
la gestion des erreurs de page à une application de l'espace utilisateur et renvoie un
descripteur de fichier qui fait référence au nouvel objet. Le nouvel objet userfaultfd est
configuré en utilisant ioctl(2).
Une fois l'objet userfaultfd configuré, l'application peut utiliser read(2) pour recevoir
des notification d'userfaultfd. Les lectures à partir d'userfaultfd peuvent être
bloquantes ou non bloquantes en fonction de la valeur des attributs (flags) utilisés pour
la création de l'userfaultfd ou des appels suivants à fcntl(2).
Les valeurs suivantes peuvent être combinées dans flags par un OU binaire pour modifier le
comportement d'userfaultfd() :
O_CLOEXEC
Activer l'attribut close-on-exec pour le nouveau descripteur de fichier
userfaultfd. Consultez la description de l'attribut O_CLOEXEC dans open(2).
O_NONBLOCK
Permettre une opération non bloquante pour l'objet userfaultfd. Voir la description
de l'attribut O_NONBLOCK dans open(2).
UFFD_USER_MODE_ONLY
C'est un attribut spécifique à userfaultfd qui a été introduit dans Linux 5.11.
Quand il est défini, l'objet userfaultfd ne pourra gérer que les erreurs de page
provenant de l'espace utilisateur dans les régions enregistrées. Quand une erreur
provenant du noyau est déclenchée dans l'intervalle enregistré avec cet
userfaultfd, un signal SIGBUS sera envoyé.
Quand le dernier descripteur de fichier faisant référence à un objet userfaultfd est
fermé, tous les intervalles de mémoire qui ont été enregistrés avec l'objet sont
désenregistrés et les événements non lus sont vidés.
Userfaultfd gère trois modes d'enregistrement :
UFFDIO_REGISTER_MODE_MISSING (depuis Linux 4.10)
Quand il est enregistré avec le mode UFFDIO_REGISTER_MODE_MISSING, l'espace
utilisateur recevra une notification d'erreur de page lors de l'accès à une page
manquante. L'exécution du thread fautif sera arrêtée jusqu'à ce que l'erreur de
page soit résolue à partir de l'espace utilisateur par un ioctl UFFDIO_COPY ou
UFFDIO_ZEROPAGE.
UFFDIO_REGISTER_MODE_MINOR (depuis Linux 5.13)
Quand il est enregistré avec le mode UFFDIO_REGISTER_MODE_MINOR, l'espace
utilisateur recevra une notification d'erreur de page lorsqu'une erreur de page
mineure survient. C'est-à-dire quand une page de sauvegarde est dans le cache de
page, mais les entrées dans la table de pages n'existent pas encore. L'exécution du
thread fautif sera arrêtée jusqu'à ce que l'erreur de page soit résolue à partir de
l'espace utilisateur par un ioctl UFFDIO_CONTINUE.
UFFDIO_REGISTER_MODE_WP (depuis Linux 5.7)
Quand il est enregistré avec le mode UFFDIO_REGISTER_MODE_WP, l'espace utilisateur
recevra une notification d'erreur de page lors d'une écriture sur une page protégée
en écriture. L'exécution du thread fautif sera arrêtée jusqu'à ce que l'espace
utilisateur supprime la protection de la page en utilisant un ioctl
UFFDIO_WRITEPROTECT.
Plusieurs modes peuvent être activés en même temps pour le même intervalle de mémoire.
Depuis Linux 4.14, une notification d'erreur de page d'userfaultfd peut incorporer de
façon sélective des informations d'identifiant des threads en erreur dans une
notification. Il est nécessaire d'activer cette fonctionnalité explicitement en utilisant
le bit de fonction UFFD_FEATURE_THREAD_ID lors de l'initialisation du contexte
d'userfaultfd. Par défaut, la déclaration de l'identifiant du thread est désactivée.
Utilisation
Le mécanisme d'userfaultfd est conçu pour permettre à un thread dans un programme
multi-thread de réaliser la pagination en espace utilisateur pour d'autres threads dans le
processus. Lorsqu'un erreur de page survient pour une des régions enregistrées dans
l'objet userfaultfd, le thread en erreur est mis en sommeil et un événement est généré qui
peut être lu au moyen du descripteur de fichier userfaultfd. Le thread de gestion d'erreur
lit les événements à partir de ce descripteur de fichier et les corrige en utilisant les
opérations décrites dans ioctl_userfaultfd(2). Lors de l'intervention sur les événements
d'erreur de page, le thread de gestion d'erreur peut déclencher le réveil d'un thread
endormi.
Il est possible que les threads en erreur et les threads traitant les erreurs soient
exécutés dans le contexte de processus différents. Dans ce cas, ces threads peuvent
appartenir à différents programmes, et le programme qui exécute les threads en erreur ne
collaborera pas nécessairement avec le programme qui gère les erreurs de page. Dans ce
mode non coopératif, le processus qui contrôle userfaultfd et gère les erreurs de page a
besoin d'avoir connaissance des modifications dans la disposition de la mémoire virtuelle
du processus en erreur pour éviter une corruption de mémoire.'
Depuis Linux 4.11, userfaultfd peut aussi informer les threads gérant les erreurs des
modifications dans la disposition de la mémoire virtuelle du processus en erreur. De plus,
si le processus en erreur invoque fork(2), les objets userfaultfd associés au parent
peuvent être dupliqués dans le processus enfant et le contrôleur d'userfaultfd sera
informé (au moyen de UFFD_EVENT_FORK décrit plus bas) sur le descripteur de fichier
associé aux objets userfault créés pour le processus enfant, ce qui permet au contrôleur
d'userfaultfd de réaliser la pagination de l'espace utilisateur pour le processus enfant.
À la différence des erreurs de page qui doivent être synchrones et réclament un réveil
explicite ou explicite, tous les autres événements sont envoyés de façon asynchrone et le
processus non coopératif reprend son exécution dès que le gestionnaire d'userfaultfd
exécute read(2). Le gestionnaire d'userfaultfd doit soigneusement synchroniser les appels
à UFFDIO_COPY avec le traitement des événements.
Le modèle asynchrone actuel d'envoi d'événement est optimal pour des implémentations de
gestionnaire userfaultfd non coopératif à thread unique.
Depuis Linux 5.7, userfaultfd peut effectuer le suivi synchrone de page sale en utilisant
le nouveau mode d'enregistrement de page protégée en écriture. Il faut vérifier le bit de
fonction UFFD_FEATURE_PAGEFAULT_FLAG_WP avant d'utiliser cette fonctionnalité. Le mode
protection en écriture, similaire au mode d'origine page manquante d'userfaultfd, génère
une notification d'userfaultfd quand la page protégée en écriture est écrite.
L'utilisateur doit résoudre l'erreur de page en déprotégeant la page fautive et en forçant
le thread fautif à continuer. Pour plus d'informations, consultez la section « Mode
protection d'écriture d'userfaultfd »
Fonctionnement d'userfaultfd
Après la création de l'objet userfaultfd avec userfaultfd(), l'application doit l'activer
en utilisant l'opération UFFDIO_API de ioctl(2). Cette opération permet une connexion
entre le noyau et l'espace utilisateur pour déterminer la version de l'API et les
fonctions prises en charge. Cette opération doit être réalisée avant toutes les autres
opérations ioctl(2) décrites plus bas (ou ces opérations échouent avec l'erreur EINVAL.)
Après le succès d'une opération UFFDIO_API, l'application enregistre alors les intervalles
d'adresses mémoire en utilisant l'opération d'ioctl(2) UFFDIO_REGISTER. Quand l'opération
UFFDIO_REGISTER s'est achevée avec succès, une erreur de page, se produisant dans
l'intervalle de mémoire requis et satisfaisant au mode défini au moment de
l'enregistrement, sera transmis par le noyau à l'application de l'espace utilisateur.
L'application peut alors utiliser les opérations d'ioctl(2) UFFDIO_COPY, UFFDIO_ZEROPAGE
ou UFFDIO_CONTINUE pour résoudre l'erreur de page.
Depuis Linux 4.4, si l'application définit le bit de la fonction UFFD_FEATURE_SIGBUS en
utilisant l'ioctl(2) UFFDIO_API, aucune notification d'erreur d page ne sera transmise à
l'espace utilisateur. Un signal est envoyé à la place au processus en erreur. Avec cette
fonction, userfaultfd peut être utilisé à des fins de robustesse pour capturer simplement
tout accès aux zones dans l'intervalle d'adresses enregistré qui n'ont pas de pages
allouées sans avoir à écouter les événements d'userfaultfd. Aucun contrôleur d'userfaultfd
ne sera requis pour traiter ce type d'accès mémoire. Par exemple, cette fonction peut être
utile à des applications qui désirent empêcher le noyau d'allouer des pages
automatiquement et de remplir des trous dans des fichiers creux quand c'est un mappage
mémoire qui permet l'accès aux trous.
La fonction UFFD_FEATURE_SIGBUS est héritée de façon implicite avec fork(2) si elle est
utilisée en combinaison avec UFFD_FEATURE_FORK.
Des détails sur les différentes opérations d'ioctl(2) sont disponibles dans
ioctl_userfaultfd(2).
Depuis Linux 4.11, les événements autres que les erreurs de page peuvent être activés
pendant l'opération UFFDIO_API.
Jusqu'à Linux 4.11, userfaultfd ne peut être utilisé qu'avec des mappages de mémoire
privée anonyme. Depuis Linux 4.11, userfaultfd peut aussi être utilisé avec des mappages
de mémoire hugelbfs et partagée.
Mode protection d'écriture d'userfaultfd (depuis Linux 5.7)
Depuis Linux 5.7, userfaultfd prend en charge le mode protection d'écriture pour la
mémoire anonyme. L'utilisateur doit d'abord vérifier la disponibilité de cette
fonctionnalité en utilisant l'ioctl UFFDIO_API sur le bit de fonction
UFFD_FEATURE_PAGEFAULT_FLAG_WP avant d'utiliser cette fonctionnalité.
Depuis Linux 5.19, le mode protection d'écriture est aussi pris en charge sur la mémoire
de type shmem ou hugetlbfs. Il peut être détecté avec le bit de fonction
UFFD_FEATURE_WP_HUGETLBFS_SHMEM.
Pour enregistrer avec le mode page protégée en écriture de userfaultfd, l'utilisateur doit
initier l'ioctl UFFDIO_REGISTER avec le mode UFFDIO_REGISTER_MODE_WP défini. Notez qu'il
est permis de surveiller le même intervalle de mémoire avec plusieurs modes. Par exemple,
un utilisateur peut effectuer UFFDIO_REGISTER avec le mode défini à
UFFDIO_REGISTER_MODE_MISSING | UFFDIO_REGISTER_MODE_WP. Quand seul le mode
UFFDIO_REGISTER_MODE_WP est enregistré, l'espace utilisateur ne recevra aucune
notification quand une page manquante est écrite. À la place, l'espace utilisateur ne
recevra une notification d'erreur de page protégée en écriture que quand une page
existante et protégée en écriture est écrite.
Après que l'ioctl UFFDIO_REGISTER s'est terminé avec le mode UFFDIO_REGISTER_MODE_WP
défini, l'utilisateur peut protéger en écriture toute mémoire dans l'intervalle en
utilisant l'ioctl UFFDIO_WRITEPROTECT où uffdio_writeprotect.mode devrait être défini à
UFFDIO_WRITEPROTECT_MODE_WP.
Quand un événement de protection en écriture survient, l'espace utilisateur recevra une
notification d'erreur de page dont l'uffd_msg.pagefault.flags aura l'attribut
UFFD_PAGEFAULT_FLAG_WP défini. Notez : dans la mesure où seulement les écritures peuvent
déclencher ce genre d'erreur, les notifications de protection en écriture auront toujours
le bit UFFD_PAGEFAULT_FLAG_WRITE défini en même temps que le bit UFFD_PAGEFAULT_FLAG_WP.
Pour résoudre une erreur de page de protection d'écriture, l'utilisateur doit initier un
autre ioctl UFFDIO_WRITEPROTECT dont l'uffd_msg.pagefault.flags doit avoir l'attribut
UFFDIO_WRITEPROTECT_MODE_WP effacé après la page ou l'intervalle fautif.
Mode erreur mineure d'userfaultfd (depuis Linux 5.13)
Depuis Linux 5.13, userfaultfd prend en charge le mode erreur mineure. Dans ce mode, les
messages d’erreur ne sont pas produits pour des erreurs majeures (où les pages étaient
absentes), mais plutôt pour des erreurs mineures où une page existe dans le cache de page,
mais où les entrées de la table de pages ne sont pas encore présentes. L'utilisateur doit
d'abord vérifier la disponibilité de cette fonctionnalité en utilisant l'ioctl UFFDIO_API
avec les bits de fonction appropriés avant d'utiliser cette fonctionnalité :
UFFD_FEATURE_MINOR_HUGETLBFS depuis Linux 5.13 ou UFFD_FEATURE_MINOR_SHMEM depuis
Linux 5.14.
Pour enregistrer avec le mode erreur mineure d'userfaultfd, l'utilisateur doit initier
l'ioctl UFFDIO_REGISTER avec le mode UFFD_REGISTER_MODE_MINOR défini.
Quand une erreur mineure survient, l'espace utilisateur recevra une notification d'erreur
de page dont l'uffd_msg.pagefault.flags aura l'attribut UFFD_PAGEFAULT_FLAG_MINOR défini.
Pour résoudre une erreur de page mineure, le gestionnaire doit décider si le contenu de la
page existante doit être modifiée d'abord, ou non. Si c'est le cas, cela doit être fait à
son emplacement au moyen d'un second mappage non enregistré par userfaultfd vers la même
page de sauvegarde (par exemple en mappant deux fois le fichier shmem ou hugetlbfs). Une
fois que la page est considérée « à jour », l'erreur peut être résolue en initiant un
ioctl UFFDIO_CONTINUE qui installe les entrées de la table de pages et (par défaut)
réveille le ou les threads en erreur.
Le mode erreur mineure ne prend en charge que la mémoire s'appuyant sur hugetlbfs (depuis
Linux 5.13) et sur shmem (depuis Linux 5.14).
Lire à partir de la structure userfaultfd
Chaque read(2) à partir du descripteur de fichier userfaultfd renvoie une ou plusieurs
structures uffd_msg, chacune d'elles décrit un événement d'erreur de page ou un événement
requis pour l'utilisation non coopérative d'userfaultfd :
struct uffd_msg {
__u8 event; /* Type d'événement */
...
union {
struct {
__u64 flags; /* Attributs décrivant l'erreur */
__u64 address; /* Adresse fautive */
union {
__u32 ptid; /* ID du thread de l'erreur */
} feat;
} pagefault;
struct { /* Depuis Linux 4.11 */
__u32 ufd; /* Descripteur de ficher d'userfault
du processus enfant */
} fork;
struct { /* Depuis Linux 4.11 */
__u64 from; /* Ancienne adresse de la zone remappée */
__u64 to; /* Nouvelle adresse de la zone remappée */
__u64 len; /* Taille originale du mappage */
} remap;
struct { /* Depuis Linux 4.11 */
__u64 start; /* Adresse de début de la zone supprimée */
__u64 end; /* Adresse de fin de la zone supprimée */
} remove;
...
} arg;
/* Remplissage des champs omis */
} __packed;
Si plusieurs événements sont disponibles et si le tampon fourni est suffisamment grand,
read(2) renvoie autant d'événements qu'il en tient dans le tampon fourni. Si le tampon
fourni à read(2) est plus petit que la taille de la structure uffd_msg, read(2) échoue
avec l'erreur EINVAL.
Les champs définis dans la structure uffd_msg sont les suivants :
event Le type d'événement. Selon le type d'événement, différents champs de l'union arg
représentent les détails nécessaires au traitement de l'événement. Les événements
qui ne sont pas des erreurs de page ne sont générés que quand la fonctionnalité
appropriée est activée durant la connexion de l'API à l'ioctl(2) UFFDIO_API.
Les valeurs suivantes peuvent apparaître dans le champ event :
UFFD_EVENT_PAGEFAULT (depuis Linux 4.3)
Un événement d'erreur de page. Les détails de l'erreur de page sont
disponibles dans le champ pagefault.
UFFD_EVENT_FORK (depuis Linux 4.11)
Généré lorsque le processus en erreur invoque fork(2) (ou clone(2) sans
l'attribut CLONE_VM). Les détails de l'événement sont disponibles dans le
champ fork.
UFFD_EVENT_REMAP (depuis Linux 4.11)
Généré lorsque le processus en erreur invoque mremap(2). Les détails de
l'événement sont disponibles dans le champ remap.
UFFD_EVENT_REMOVE (depuis Linux 4.11)
Généré lorsque le processus en erreur invoque madvise(2) avec les conseils
MADV_DONTNEED ou MADV_REMOVE. Les détails de l'événement sont disponibles
dans le champ remove.
UFFD_EVENT_UNMAP (depuis Linux 4.11)
Généré lorsque le processus en erreur supprime le mappage d'un intervalle de
mémoire soit explicitement avec munmap(2), soit implicitement durant
l'exécution de mmap(2) ou mremap(2). Les détails de l'événement sont
disponibles dans le champ remove.
pagefault.address
L'adresse qui a déclenché l'erreur de page.
pagefault.flags
Un masque de bits qui décrit l'événement. Pour UFFD_EVENT_PAGEFAULT, les attributs
suivants peuvent apparaître :
UFFD_PAGEFAULT_FLAG_WP
Si cet attribut est défini, alors l'erreur était une erreur de protection en
écriture.
UFFD_PAGEFAULT_FLAG_MINOR
Si cet attribut est défini, alors l'erreur était une erreur mineure.
UFFD_PAGEFAULT_FLAG_WRITE
Si cet attribut est défini, alors l'erreur était une erreur d'écriture.
Si ni UFFD_PAGEFAULT_FLAG_WP ni UFFD_PAGEFAULT_FLAG_MINOR ne sont définis, l'erreur
était une erreur d'absence.
pagefault.feat.pid
L'identifiant du thread qui a déclenché l'erreur de page.
fork.ufd
Le descripteur de fichier associé à l'objet userfault créé pour l'enfant créé par
fork(2).
remap.from
L'adresse d'origine de la plage de mémoire dont le mappage a été modifié en
utilisant madvise(2).
remap.to
La nouvelle adresse de la plage de mémoire dont le mappage a été modifié en
utilisant madvise(2).
remap.len
La taille d'origine de la plage de mémoire dont le mappage a été modifié en
utilisant madvise(2).
remove.start
L'adresse de début de la plage de mémoire qui a été libérée en utilisant madvise(2)
ou dont le mappage a été supprimé.
remove.end
L'adresse terminale de la plage de mémoire qui a été libérée en utilisant
madvise(2) ou dont le mappage a été supprimé.
read(2) sur un descripteur de fichier userfaultfd peut échouer pour les raisons
suivantes :
EINVAL L'objet userfaultfd n'a pas encore été activé avec l'opération d'ioctl(2)
UFFDIO_API.
Si l'attribut O_NONBLOCK est activé dans la description de fichier ouvert associée, le
descripteur de fichier userfaultfd peut être surveillé avec poll(2), select(2) et
epoll(7). Quand les événements sont disponibles, le descripteur de fichier l'indique comme
lisible. Si l'attribut O_NONBLOCK n'est pas activé, alors poll(2) indique (toujours) que
le fichier comme ayant une condition POLLERR et select(2) indique que le descripteur de
fichier est à la fois accessible en lecture et en écriture.
VALEUR RENVOYÉE
En cas de succès, userfaultfd() renvoie un nouveau descripteur de fichier qui fait
référence à l'objet userfaultfd. En cas d'erreur, la fonction renvoie -1 et errno est
défini pour indiquer l'erreur.
ERREURS
EINVAL Une valeur non prise en compte a été spécifiée dans flags.
EMFILE La limite par processus du nombre de descripteurs de fichier ouverts a été
atteinte.
ENFILE La limite du nombre total de fichiers ouverts pour le système entier a été
atteinte.
ENOMEM La mémoire disponible du noyau n'était pas suffisante.
EPERM (depuis Linux 5.2)
L'appelant n'est pas privilégié (il n'a pas la capacité CAP_SYS_PTRACE dans
l'espace de noms initial) et /proc/sys/vm/unprivileged_userfaultfd a la valeur 0.
VERSIONS
L'appel système userfaultfd() est apparu pour la première fois dans Linux 4.3.
La prise en charge des zones de mémoire hugetlbfs et partagée et des événements qui ne
sont pas des erreurs de page a été ajoutée dans Linux 4.11
STANDARDS
userfaultfd() est spécifique à Linux et ne devrait pas être employé dans des programmes
destinés à être portables.
NOTES
Le mécanisme d'userfaultfd peut être utilisé comme une alternative aux techniques
traditionnelles de pagination de l'espace utilisateur basées sur l'utilisation du signal
SIGSEGV et de mmap(2). Il peut aussi être utilisé pour implémenter la restauration en mode
paresseux (« lazy restore ») pour les mécanismes de la fonctionnalité de gel des
applications (checkpoint/restore), aussi bien que la migration après copie pour permettre
une exécution (presque) ininterrompue lors du transfert de machines virtuelles et de
conteneurs Linux d'un hôte à un autre.
BOGUES
Si UFFD_FEATURE_EVENT_FORK est activé et si un appel système issu de la famille de fork(2)
est interrompu par un signal ou échoue, un descripteur périmé d'userfaultfd peut être
créé. Dans ce cas, un faux UFFD_EVENT_FORK sera fourni au surveillant d'userfaultfd.
EXEMPLES
Le programme ci-dessous démontre l'utilisation du mécanisme userfaultfd. Le programme crée
deux threads, un qui agit comme gestionnaire d'erreur de page pour le processus, pour les
pages dans une région sans demande de page en utilisant mmap(2).
Le programme prend un argument en ligne de commande, qui est le nombre de pages qui seront
créées dans un mappage dont les erreurs de pages seront gérées au moyen d'userfaultfd.
Après la création d'un objet userfaultfd, le programme crée alors un mappage privé anonyme
de la taille spécifiée et enregistre l'intervalle d'adresses de ce mappage en utilisant
l'opération d'ioctl(2) UFFDIO_REGISTER. Le programme crée alors un second thread qui
exécutera la tâche de gestion des erreurs de page.
Le thread principal parcourt les pages du mappage à la recherche des octets des pages
successives. Comme il n'y a pas eu encore d'accès aux pages, le premier accès à un octet
de chaque page déclenchera un événement d'erreur de page sur le descripteur de fichier
userfaultfd.
Chaque événement d'erreur de page est géré par le second thread qui s'installe dans une
boucle traitant l'entrée du descripteur de fichier userfaultfd. À chaque itération de la
boucle, le second thread appelle poll(2) pour vérifier l'état du descripteur de fichier
puis lit un événement à partir de ce descripteur de fichier. Tout ce type d'événements
doit être un événement UFFD_EVENT_PAGEFAULT que le thread traite en copiant un page de
données dans la région en erreur en utilisant l'opération d'ioctl(2) UFFDIO_COPY.
La suite est un exemple de ce qui est observé lors de l'exécution du programme :
$ ./userfaultfd_demo 3
Address returned by mmap() = 0x7fd30106c000
fault_handler_thread():
poll() returns: nready = 1; POLLIN = 1; POLLERR = 0
UFFD_EVENT_PAGEFAULT event: flags = 0; address = 7fd30106c00f
(uffdio_copy.copy returned 4096)
Read address 0x7fd30106c00f in main(): A
Read address 0x7fd30106c40f in main(): A
Read address 0x7fd30106c80f in main(): A
Read address 0x7fd30106cc0f in main(): A
fault_handler_thread():
poll() returns: nready = 1; POLLIN = 1; POLLERR = 0
UFFD_EVENT_PAGEFAULT event: flags = 0; address = 7fd30106d00f
(uffdio_copy.copy returned 4096)
Read address 0x7fd30106d00f in main(): B
Read address 0x7fd30106d40f in main(): B
Read address 0x7fd30106d80f in main(): B
Read address 0x7fd30106dc0f in main(): B
fault_handler_thread():
poll() returns: nready = 1; POLLIN = 1; POLLERR = 0
UFFD_EVENT_PAGEFAULT event: flags = 0; address = 7fd30106e00f
(uffdio_copy.copy returned 4096)
Read address 0x7fd30106e00f in main(): C
Read address 0x7fd30106e40f in main(): C
Read address 0x7fd30106e80f in main(): C
Read address 0x7fd30106ec0f in main(): C
Source du programme
/* userfaultfd_demo.c
Licensed under the GNU General Public License version 2 or later.
*/
#define _GNU_SOURCE
#include <err.h>
#include <errno.h>
#include <fcntl.h>
#include <inttypes.h>
#include <linux/userfaultfd.h>
#include <poll.h>
#include <pthread.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/ioctl.h>
#include <sys/mman.h>
#include <sys/syscall.h>
#include <unistd.h>
static int page_size;
static void *
fault_handler_thread(void *arg)
{
int nready;
long uffd; /* descripteur du fichier userfaultfd */
ssize_t nread;
struct pollfd pollfd;
struct uffdio_copy uffdio_copy;
static int fault_cnt = 0; /* Nombres d'erreurs déjà gérées */
static char *page = NULL;
static struct uffd_msg msg; /* Données lues à partir de userfaultfd */
uffd = (long) arg;
/* Créer une page qui sera copiée dans la région en erreur. */
if (page == NULL) {
page = mmap(NULL, page_size, PROT_READ | PROT_WRITE,
MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);
if (page == MAP_FAILED)
err(EXIT_FAILURE, "mmap");
/* Boucle gérant les événements entrants sur le descripteur
de fichier userfaultfd. */
for (;;) {
/* Voir ce que poll() nous dit sur l'userfaultfd. */
pollfd.fd = uffd;
pollfd.events = POLLIN;
nready = poll(&pollfd, 1, -1);
if (nready == -1)
err(EXIT_FAILURE, "poll");
printf("\nfault_handler_thread():\n");
printf(" poll() returns: nready = %d; "
"POLLIN = %d; POLLERR = %d\n", nready,
(pollfd.revents & POLLIN) != 0,
(pollfd.revents & POLLERR) != 0);
/* Lire un événement à partir de l'userfaultfd. */
nread = read(uffd, &msg, sizeof(msg));
if (nread == 0) {
printf("EOF on userfaultfd!\n");
exit(EXIT_FAILURE);
}
if (nread == -1)
err(EXIT_FAILURE, "read");
/* Un seul type d'événement est attendu ; il faut vérifier
cette supposition. */
if (msg.event != UFFD_EVENT_PAGEFAULT) {
fprintf(stderr, "Unexpected event on userfaultfd\n");
exit(EXIT_FAILURE);
}
/* Afficher une information sur l'événement erreur de page. */
printf(" UFFD_EVENT_PAGEFAULT event: ");
printf("flags = %"PRIx64"; ", msg.arg.pagefault.flags);
printf("address = %"PRIx64"\n", msg.arg.pagefault.address);
/* Copier la page sur laquelle pointe la « page » dans la région
fautive. Varier le contenu copié, afin qu'il soit plus
évident que chaque erreur soit gérée séparément. */
memset(page, 'A' + fault_cnt % 20, page_size);
fault_cnt++;
uffdio_copy.src = (unsigned long) page;
/* Il est nécessaire de gérer les erreurs de page en
unités de pages(!). Aussi, il faut arrondir les
adresses fautives à la limite de 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)
err(EXIT_FAILURE, "ioctl-UFFDIO_COPY");
printf(" (uffdio_copy.copy returned %"PRId64")\n",
uffdio_copy.copy);
}
}
int
main(int argc, char *argv[])
{
int s;
char c;
char *addr; /* Début de la région gérée par userfaultfd */
long uffd; /* Descripteur de fichier userfaultfd */
size_t len, l; /* Taille de la région gérée par userfaultfd */
pthread_t thr; /* ID du thread qui gère les erreurs de page */
struct uffdio_api uffdio_api;
struct uffdio_register uffdio_register;
if (argc != 2) {
fprintf(stderr, "Usage : %s num-pages\n", argv[0]);
exit(EXIT_FAILURE);
}
page_size = sysconf(_SC_PAGE_SIZE);
len = strtoull(argv[1], NULL, 0) * page_size;
/* Créer et activer un objet userfaultfd. */
uffd = syscall(SYS_userfaultfd, O_CLOEXEC | O_NONBLOCK);
if (uffd == -1)
err(EXIT_FAILURE, "userfaultfd");
uffdio_api.api = UFFD_API;
uffdio_api.features = 0;
if (ioctl(uffd, UFFDIO_API, &uffdio_api) == -1)
err(EXIT_FAILURE, "ioctl-UFFDIO_API");
/* Créer un mappage anonyme privé. La mémoire sera paginée
avec aucune demande — c'est-à-dire, sans être encore
allouée. Quand la mémoire sera réellement utilisée,
elle sera allouée au moyen de l'userfaultfd. */
addr = mmap(NULL, len, PROT_READ | PROT_WRITE,
MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);
if (addr == MAP_FAILED)
err(EXIT_FAILURE, "mmap");
printf("Address returned by mmap() = %p\n", addr);
/* Enregistrer l'intervalle de mémoire du mappage qui vient d'être
créé pour le traitement par l'objet userfaultfd. Dans mode,
suivre les pages manquantes (c'est-à-dire, les pages qui ne sont
pas encore fautives). */
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)
err(EXIT_FAILURE, "ioctl-UFFDIO_REGISTER");
/* Créer un thread qui traitera les événements userfaultfd. */
s = pthread_create(&thr, NULL, fault_handler_thread, (void *) uffd);
if (s != 0) {
errc(EXIT_FAILURE, s, "pthread_create");
}
/* Le thread principal utilise la mémoire dans le mappage,
utilisant des emplacements séparés de 1024 octets. Cela va
déclencher des événements userfaultfd pour toutes les pages
dans la région. */
l = 0xf; /* Assurer que l'adresse fautive n'est pas sur une
limite de page afin de vérifier que ce cas est
correctement géré dans le fault_handling_thread(). */
while (l < len) {
c = addr[l];
printf("Read address %p in %s(): ", addr + l, __func__);
printf("%c\n", c);
l += 1024;
usleep(100000); /* Ralentir un peu le traitement */
}
exit(EXIT_SUCCESS);
}
VOIR AUSSI
fcntl(2), ioctl(2), ioctl_userfaultfd(2), madvise(2), mmap(2)
Documentation/admin-guide/mm/userfaultfd.rst dans l'arborescence des sources du noyau
Linux
TRADUCTION
La traduction française de cette page de manuel a été créée par Christophe Blaess
<https://www.blaess.fr/christophe/>, Stéphan Rafin <stephan.rafin@laposte.net>, Thierry
Vignaud <tvignaud@mandriva.com>, François Micaux, Alain Portal <aportal@univ-montp2.fr>,
Jean-Philippe Guérard <fevrier@tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-
luc.coulon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas Huriaux
<thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centraliens.net>, Florentin
Duneau <fduneau@gmail.com>, Simon Paillard <simon.paillard@resel.enst-bretagne.fr>, Denis
Barbier <barbier@debian.org>, David Prévot <david@tilapin.org> et Jean-Pierre Giraud
<jean-pierregiraud@neuf.fr>
Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General
Public License version 3 ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ concernant les
conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.
Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un
message à ⟨debian-l10n-french@lists.debian.org⟩.