ioctl_userfaultfd(2) System Calls Manual ioctl_userfaultfd(2)

ioctl_userfaultfd - Créer un descripteur de fichier pour gérer les erreurs de pagination dans l'espace utilisateur

Bibliothèque C standard (libc, -lc)

#include <linux/userfaultfd.h>  /* Définition des constantes UFFD* */
#include <sys/ioctl.h>
int ioctl(int fd, int op, ...);

Diverses opérations ioctl(2) peuvent être effectuées sur un objet userfaultfd (créé par un appel à userfaultfd(2)) en utilisant des appels sous la forme :


ioctl(fd, op, argp);

In the above, fd is a file descriptor referring to a userfaultfd object, op is one of the operations listed below, and argp is a pointer to a data structure that is specific to op.

Les opérations ioctl(2) sont décrites ci-dessous. Celles UFFDIO_API, UFFDIO_REGISTER et UFFDIO_UNREGISTER sont utilisées pour configurer le comportement de userfaultfd. Ces opérations permettent à l'appelant de choisir les fonctionnalités qui seront activées et le type d'événement transmis à l'application. Ces opérations permettent à l'application appelante de résoudre des événements de problèmes de pages.

(Depuis Linux 4.3). Activer l'opération de userfaultfd et effectuer la poignée de main de l'API.

Le paramètre argp est un pointeur vers une structure uffdio_api, définie en tant que :


struct uffdio_api {
    __u64 api;        /* Version de l'API demandée (entrée) */
    __u64 features;   /* Fonctionnalités demandées (entrée/sortie) */
    __u64 ioctls;     /* Opérations ioctl() disponibles (sortie) */
};

The api field denotes the API version requested by the application. The kernel verifies that it can support the requested API version, and sets the features and ioctls fields to bit masks representing all the available features and the generic ioctl(2) operations available.

Since Linux 4.11, applications should use the features field to perform a two-step handshake. First, UFFDIO_API is called with the features field set to zero. The kernel responds by setting all supported feature bits.

Applications which do not require any specific features can begin using the userfaultfd immediately. Applications which do need specific features should call UFFDIO_API again with a subset of the reported feature bits set to enable those features.

Avant Linux 4.11, le champ features doit être initialisé à zéro avant l'appel UFFDIO_API, et zéro (c'est-à-dire pas de bit de fonctionnalité) est mis dans le champ features par le noyau à partir du retour de ioctl(2).

If the application sets unsupported feature bits, the kernel will zero out the returned uffdio_api structure and return EINVAL.

Les bits fonctionnels suivants peuvent être positionnés :

Quand cette fonctionnalité est activée, les objets userfaultfd associés à un processus parent sont dupliqués dans un processus enfant lors d'un fork(2) et un événement UFFD_EVENT_FORK est généré sur le moniteur du userfaultfd
Si cette fonctionnalité est activée, quand le processus fautif appelle mremap(2), le moniteur userfaultfd recevra un événement de type UFFD_EVENT_REMAP.
Si cette fonctionnalité est ativée, quand le processus fautif appelle madvise(2) avec les valeurs MADV_DONTNEED ou MADV_REMOVE pour libérer une zone de mémoire virtuelle, le moniteur userfaultfd recevra un événement de type UFFD_EVENT_REMOVE.
Si cette fonctionnalité est activée, quand le processus fautif désassocie la mémoire virtuelle explicitement avec munmap(2), ou implicitement lors d'un mmap(2) ou d'un mremap(2), le moniteur userfaultfd recevra un événement de type UFFD_EVENT_UNMAP.
Si ce bit fonctionnel est positionné, le noyau gère l'enregistrement des plages userfaultfd par défaut dans les zones hugetlbfs de mémoire virtuelle
Si ce bit fonctionnel est positionné, le noyau prend en charge l'enregistrement de plages userfaultfd dans les zones de mémoire partagées. Cela comprend toutes les APIs de mémoire partagée du noyau : la mémoire partagée System V, tmpfs(5), les tableaux partagés de /dev/zero, mmap(2) avec l'attribut MAP_SHARED positionné, memfd_create(2) et ainsi de suite.
Si ce bit fonctionnel est positionné, aucun événement d'erreur de page (UFFD_EVENT_PAGEFAULT) ne sera généré. Un signal SIGBUS sera plutôt envoyé au processus fautif. Les applications qui utilisent cette fonctionnalité n'exigeront pas qu'on utilise un moniteur userfaultfd pour gérer les accès mémoire aux régions enregistrées avec userfaultfd.
Si ce bit de fonctionnalité est positionné, uffd_msg.pagefault.feat.ptid sera positionné sur l'identifiant du thread fautif pour chaque message d'erreur de pagination.
If this feature bit is set, userfaultfd supports write-protect faults for anonymous memory. (Note that shmem / hugetlbfs support is indicated by a separate feature.)
Si ce bit fonctionnel est positionné, le noyau gère l'enregistrement des plages userfaultfd en mode mineur dans les zones hugetlbfs-backed de mémoire.
Si ce bit fonctionnel est positionné, le noyau gère l'enregistrement des plages userfaultfd en mode mineur dans les zones shmem-backed de mémoire.
Si ce bit fonctionnel est positionné, uffd_msg.pagefault.address sera réglé à l'adresse exacte de l'erreur de pagination rapportée par le matériel et ne masque pas le décalage dans la page. Notez que les versions anciennes de Linux pourraient indiquer aussi l'adresse exacte, même si bit fonctionnel n'est pas positionné.
If this feature bit is set, userfaultfd supports write-protect faults for hugetlbfs and shmem / tmpfs memory.
If this feature bit is set, the kernel will handle anonymous memory the same way as file memory, by allowing the user to write-protect unpopulated page table entries.
If this feature bit is set, the kernel supports resolving faults with the UFFDIO_POISON ioctl.
If this feature bit is set, the write protection faults would be asynchronously resolved by the kernel.

Le champ ioctls renvoyé peut contenir les bits suivants :

1 << _UFFDIO_API
L'opération UFFDIO_API est prise en charge.
1 << _UFFDIO_REGISTER
L'opération UFFDIO_REGISTER est prise en charge.
1 << _UFFDIO_UNREGISTER
L'opération UFFDIO_UNREGISTER est prise en charge.

This ioctl(2) operation returns 0 on success. On error, -1 is returned and errno is set to indicate the error. If an error occurs, the kernel may zero the provided uffdio_api structure. The caller should treat its contents as unspecified, and reinitialize it before re-attempting another UFFDIO_API call. Possible errors include:

argp renvoie à une adresse en dehors de l'espace d'adressage accessible du processus appelant.
La version de l'API demandée dans le champ api n'est pas prise en charge par ce noyau ou le champ features passé au noyau comprend des bits non gérés par la version actuelle du noyau.
A previous UFFDIO_API call already enabled one or more features for this userfaultfd. Calling UFFDIO_API twice, the first time with no features set, is explicitly allowed as per the two-step feature detection handshake.
The UFFD_FEATURE_EVENT_FORK feature was enabled, but the calling process doesn't have the CAP_SYS_PTRACE capability.

(Since Linux 4.3.) Register a memory address range with the userfaultfd object. The pages in the range must be “compatible”. Please refer to the list of register modes below for the compatible memory backends for each mode.

Le paramètre argp est un pointeur vers une structure uffdio_register, définie en tant que :


struct uffdio_range {
    __u64 start;    /* Début de la plage */
    __u64 len;      /* Longueur de la plage (octets) */
};
struct uffdio_register {
    struct uffdio_range range;
    __u64 mode;     /* Mode désiré de l'opération (entrée) */
    __u64 ioctls;   /* Opérations ioctl() disponibles (sortie) */
};

Le champ range définit une plage de mémoire commençant à start et s'étendant sur len octets qui doit être gérée par userfaultfd.

Le champ mode définit le mode d'opération désiré pour cette région de mémoire. Les valeurs suivantes peuvent être mises en bits et liées pour positionner le mode userfaultfd pour la plage indiquée :

Suivre les erreurs de pagination sur les pages absentes. Depuis Linux 4.3, seules les plages anonymes privées sont compatibles. Depuis Linux 4.11, les plages hugetlbfs et de mémoire partagée sont également compatibles.
Suivre les erreurs de pagination sur les pages protégées en écriture. Depuis Linux 5.7, seules les plages anonymes et privées sont compatibles.
Suivre les petites erreurs de pagination. Depuis Linux 5.13, seules les plages hugetlbfs sont compatibles. Depuis Linux 5.14, la compatibilité avec les plages shmem a été ajoutée.

Si l'opération réussit, le noyau modifie le champ du masque de bit ioctls pour indiquer les opérations ioctl(2) disponibles sur la plage indiquée. Ce masque de bit renvoyé peut contenir les bits suivants :

1 << _UFFDIO_COPY
L'opération UFFDIO_COPY est prise en charge.
1 << _UFFDIO_WAKE
L'opération UFFDIO_WAKE est prise en charge.
1 << _UFFDIO_WRITEPROTECT
The UFFDIO_WRITEPROTECT operation is supported.
1 << _UFFDIO_ZEROPAGE
L'opération UFFDIO_ZEROPAGE est prise en charge.
1 << _UFFDIO_CONTINUE
L'opération UFFDIO_CONTINUE est prise en charge.
1 << _UFFDIO_POISON
The UFFDIO_POISON operation is supported.

Cette opération ioctl(2) renvoie 0 en cas de succès. En cas d'erreur, -1 est renvoyé et errno est positionné pour indiquer l'erreur. Parmi les erreurs possibles :

Un tableau de la plage indiquée est enregistré avec un autre objet userfaultfd.
argp renvoie à une adresse en dehors de l'espace d'adressage accessible du processus appelant.
Un bit non valable ou non pris en charge a été indiqué dans le champ mode ; ou le champ mode valait zéro.
Il n'y a pas de tableau dans la plage d'adresse indiquée.
range.start ou range.len n'est pas un multiple de la taille de la page du système ; ou range.len vaut zéro ; ou ces champs ne sont pas valables pour d'autres raisons.
Un tableau incompatible est présent dans la plage d'adresse indiquée.

(Since Linux 4.3.) Unregister a memory address range from userfaultfd. The pages in the range must be “compatible” (see the description of UFFDIO_REGISTER.)

La plage d'adresse à désenregistrer est indiquée dans la structure uffdio_range vers laquelle pointe argp.

Cette opération ioctl(2) renvoie 0 en cas de succès. En cas d'erreur, -1 est renvoyé et errno est positionné pour indiquer l'erreur. Parmi les erreurs possibles :

Le champ start ou len de la structure ufdio_range n'était pas un multiple de la taille de la page système ; ou bien le champ len valait zéro ; ou ces champs n'étaient pas valables pour d'autres raisons.
Un tableau incompatible est présent dans la plage d'adresse indiquée.
Il n'y avait pas de tableau dans la plage d'adresse spécifiée.

(Depuis Linux 4.3). Copier de manière atomique un bloc de mémoire continu dans la plage enregistrée pour le userfault et réveiller éventuellement les threads bloqués. Les adresses source et cible et le nombre d'octets à copier sont indiqués dans les champs src, dst et len de la structure uffdio_copy vers laquelle pointe argp :


struct uffdio_copy {
    __u64 dst;    /* Cible de la copie */
    __u64 src;    /* Origine de la copie */
    __u64 len;    /* Nombre d'octets à copier */
    __u64 mode;   /* Drapeaux contrôlant le comportement de la copie */
    __s64 copy;   /* Nombre d'octets copiés ou erreurs de refus */
};

La valeur suivante peut être liée en bits à mode pour modifier le comportement de l'opération UFFDIO_COPY :

Ne pas réveiller le thread qui attend la résolution d'une erreur de page
Copier les pages avec des droits en lecture seule. Cela permet à l'utilisateur de récupérer la prochaine écriture sur la page qui bloquera et qui génèrera un autre message userfault de protection en écriture. Cela n'est utilisé que lorsque les modes UFFDIO_REGISTER_MODE_MISSING et UFFDIO_REGISTER_MODE_WP sont activés pour la plage enregistrée.

Le champ copy est utilisé par le noyau pour renvoyer le nombre d'octets copiés ou une erreur (une valeur négative à la façon errno). Si la valeur renvoyée dans copy ne correspond pas à celle indiquée dans len, l'opération échoue avec l'erreur EAGAIN. Le champ copy n'est fait que pour la sortie ; il n'est pas lu par l'opération UFFDIO_COPY.

Cette opération ioctl(2) renvoie 0 en cas de succès. Dans ce cas, toute la zone a été copiée. En cas d'erreur, -1 est renvoyé et errno est positionné pour indiquer l'erreur. Parmi les erreurs possibles :

Le nombre d'octets copiés (à savoir la valeur renvoyée dans le champ copy) n'est pas la même que celle indiquée dans le champ len.
dst ou len n'était pas un multiple de la taille de la page du système ou la plage indiquée dans src et len ou dst et len n'était pas valable.
Un bit non valable a été indiqué dans le champ mode.
Le processus fautif a modifié sa structure de mémoire virtuelle en même temps qu'une opération UFFDIO_COPY remarquable.
Le processus fautif a quitté au moment de l'opération UFFDIO_COPY.
Le processus fautif a quitté au moment de l'opération UFFDIO_COPY.

(Depuis Linux 4.3). Remplit de zéros une plage mémoire enregistrée avec userfaultfd.

La plage demandée est indiquée par le champ range de la structure uffdio_zeropage vers laquelle pointe argp :


struct uffdio_zeropage {
    struct uffdio_range range;
    __u64 mode;     /* Drapeaux contrôlant le comportement de la copie */
    __s64 zeropage; /* Nombre d'octets remplis de zéros ou d'erreurs de refus */
};

La valeur suivante peut être mise en bit et liée dans mode pour modifier le comportement de l'opération UFFDIO_ZEROPAGE :

Ne pas réveiller le thread qui attend la résolution d'une erreur de page.

Le champ zeropage est utilisé par le noyau pour renvoyer le nombre d'octets remplis de zéros, ou une erreur de la même manière que UFFDIO_COPY. Si la valeur renvoyée dans le champ zeropage ne correspond pas à celle indiquée dans range.len, l'opération échoue avec l'erreur EAGAIN. Le champ zeropage ne sert qu'à la sortie ; il n'est pas lu par l'opération UFFDIO_ZEROPAGE.

L'opération ioctl(2) renvoie 0 en cas de succès. Dans ce cas, toute la zone a été remplie de zéros. En cas d'erreur, -1 est renvoyé et errno est positionné pour indiquer l'erreur. Parmi les erreurs possibles :

Le nombre d'octets remplis de zéros (c'est-à-dire la valeur renvoyée dans le champ zeropage) ne correspond pas à la valeur indiquée dans le champ range.len.
range.start ou range.len n'était pas un multiple de la taille de la page du système ; ou range.len était de zéro ; ou la plage indiquée n'était pas valable.
Un bit non valable a été indiqué dans le champ mode.
Le processus fautif a quitté au moment de l'opération UFFDIO_ZEROPAGE.

(Depuis Linux 4.3). Réveiller le thread qui attend la résolution de l'erreur de page sur une plage d'adresse mémoire indiquée.

L'opération UFFDIO_WAKE est utilisée avec les opérations UFFDIO_COPY et UFFDIO_ZEROPAGE, dont le bit UFFDIO_COPY_MODE_DONTWAKE ou UFFDIO_ZEROPAGE_MODE_DONTWAKE est défini dan le champ mode. Le moniteur userfault peut effectuer plusieurs opérations UFFDIO_COPY et UFFDIO_ZEROPAGE automatiquement, puis réveiller explicitement le thread fautif en utilisant UFFDIO_WAKE.

Le paramètre argp est un pointeur vers une structure uffdio_range (présentée ci-dessus) qui indique la plage d'adresse.

Cette opération ioctl(2) renvoie 0 en cas de succès. En cas d'erreur, -1 est renvoyé et errno est positionné pour indiquer l'erreur. Parmi les erreurs possibles :

Le champ start ou len de la structure ufdio_range n'était pas un multiple de la taille de la page système ; ou len était zéro ; ou la plage indiquée n'était pas valable pour une autre raison.

(Since Linux 5.7.) Write-protect or write-unprotect a userfaultfd-registered memory range registered with mode UFFDIO_REGISTER_MODE_WP.

Le paramètre argp est un pointeur vers une structure uffdio_range, comme indiqué ci-dessous :


struct uffdio_writeprotect {
    struct uffdio_range range; /* Plage pour modifier le droit d'écriture*/
    __u64 mode;                /* Mode pour changer le droit d'écriture */
};

Deux bits de droit sont pris en charge dans cette structure :

Quand ce bit de droits est positionné, l'ioctl sera une opération protégée en écriture sur la plage mémoire indiquée par range. Sinon, il s'agira d'une opération non protégée en écriture sur la plage indiquée, ce qui peut être utile pour résoudre une erreur de pagination de protection en écriture userfaultfd.
Quand ce bit de droit est positionné, ne pas réveiller de thread qui attend la résolution d'une erreur de pagination après l'opération. Cela ne peut être indiqué que si UFFDIO_WRITEPROTECT_MODE_WP n'est pas indiqué.

Cette opération ioctl(2) renvoie 0 en cas de succès. En cas d'erreur, -1 est renvoyé et errno est positionné pour indiquer l'erreur. Parmi les erreurs possibles :

Le champ start ou len de la structure ufdio_range n'était pas un multiple de la taille de la page système ; ou len était zéro ; ou la plage indiquée n'était pas valable pour une autre raison.
Le processus a été interrompu ; réessayez cet appel.
La plage indiquée dans range n'est pas valable. Par exemple, l'adresse virtuelle n'existe pas ou n'est pas enregistrée en mode protection d'écriture userfaultfd.
Une erreur générique a été rencontrée lors du traitement.

(Depuis Linux 5.13). Résoudre une erreur de pagination mineure en installant des entrées de tabl de pagination pour les pages existantes dans le cache de page.

Le paramètre argp est un pointeur vers une structure uffdio_continue, telle que présentée ci-dessous :


struct uffdio_continue {
    struct uffdio_range range;
                   /* Plage pour installer les PTEs for et continue */
    __u64 mode;    /* Attributs contrôlant le comportement de continue */
    __s64 mapped;  /* Nombre d'octets projetés ou erreur refusée */0
};

La valeur suivante peut être liée en bits à mode pour modifier le comportement de l'opération UFFDIO_CONTINUE :

Ne pas réveiller le thread qui attend la résolution d'une erreur de page.

Le champ mapped est utilisé par le noyau pour renvoyer le nombre d'octets projetés ou une erreur de la même manière que UFFDIO_COPY. Si la valeur renvoyée dans le champ mapped ne correspond pas à celle indiquée dans range.len, l'opération échoue avec l'erreur EAGAIN. Le champ mapped ne sert qu'à la sortie ; il n'est pas lu par l'opération UFFDIO_CONTINUE.

Cette opération ioctl(2) renvoie 0 en cas de succès. Dans ce cas, toute la zone a été copiée. En cas d'erreur, -1 est renvoyé et errno est positionné pour indiquer l'erreur. Parmi les erreurs possibles :

Le nombre d'octets projetés (c'est-à-dire la valeur renvoyée dans le champ mapped) ne correspond pas à la valeur indiquée dans le champ range.len.
Une ou plusieurs pages ont déjà été projetées dans la plage donnée.
Aucune page existante n'a été trouvée dans le cache de page pour la plage donnée.
range.start ou range.len n'était pas un multiple de la taille de la page du système ; ou range.len était de zéro ; ou la plage indiquée n'était pas valable.
Un bit non valable a été indiqué dans le champ mode.
Le processus fautif a modifié sa structure de mémoire virtuelle en même temps qu'une opération UFFDIO_COTINUE remarquable.
L'allocation de la mémoire nécessaire pour installer les projetctions de tables de pages a échoué.
Le processus fautif a quitté au moment de l'opération UFFDIO_CONTINUE.

(Since Linux 6.6.) Mark an address range as "poisoned". Future accesses to these addresses will raise a SIGBUS signal. Unlike MADV_HWPOISON this works by installing page table entries, rather than "really" poisoning the underlying physical pages. This means it only affects this particular address space.

The argp argument is a pointer to a uffdio_poison structure as shown below:


struct uffdio_poison {
	struct uffdio_range range;
	                /* Range to install poison PTE markers in */
	__u64 mode;     /* Flags controlling the behavior of poison */
	__s64 updated;  /* Number of bytes poisoned, or negated error */
};

The following value may be bitwise ORed in mode to change the behavior of the UFFDIO_POISON operation:

Ne pas réveiller le thread qui attend la résolution d'une erreur de page.

The updated field is used by the kernel to return the number of bytes that were actually poisoned, or an error in the same manner as UFFDIO_COPY. If the value returned in the updated field doesn't match the value that was specified in range.len, the operation fails with the error EAGAIN. The updated field is output-only; it is not read by the UFFDIO_POISON operation.

This ioctl(2) operation returns 0 on success. In this case, the entire area was poisoned. On error, -1 is returned and errno is set to indicate the error. Possible errors include:

The number of bytes mapped (i.e., the value returned in the updated field) does not equal the value that was specified in the range.len field.
range.start ou range.len n'était pas un multiple de la taille de la page du système ; ou range.len était de zéro ; ou la plage indiquée n'était pas valable.
Un bit non valable a été indiqué dans le champ mode.
Une ou plusieurs pages ont déjà été projetées dans la plage donnée.
The faulting process has changed its virtual memory layout simultaneously with an outstanding UFFDIO_POISON operation.
Allocating memory for page table entries failed.
The faulting process has exited at the time of a UFFDIO_POISON operation.

Voir les descriptions des opérations individuelles ci-dessus.

Voir les descriptions des opérations individuelles ci-dessus. En outre, les erreurs générales suivantes peuvent se produire pour toutes les opérations décrites ci-dessus :

argp pointe vers une adresse illégale.
(Pour toutes les opérations, sauf UFFDIO_API). L'objet userfaultfd n'a pas encore été activé (avec l'opération UFFDIO_API).

Linux.

Afin de détecter les fonctionnalités userfault disponibles et d'activer des sous-parties de celles-ci, le descripteur de fichier userfaultfd doit être fermé après la première opération UFFDIO_API qui recherche la disponibilité des fonctionnalités, puis réouvert avant la deuxième opération UFFDIO_API qui active les fonctionnalités désirées.

Voir userfaultfd(2).

ioctl(2), mmap(2), userfaultfd(2)

Documentation/admin-guide/mm/userfaultfd.rst dans l'arborescence des sources du noyau Linux

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-Philippe MENGUAL <jpmengual@debian.org>

Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General Public License version 3 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.

2 mai 2024 Pages du manuel de Linux 6.8