| 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 cmd, ...);
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, cmd, argp);
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) */
};
Le champ api reflète la version de l'API demandée par l'application.
Le noyau vérifie qu'il peut gérer la version de l'API demandée et il positionne les champs features et ioctls à des masques de bit représentant toutes les fonctions disponibles et les opérations ioctl(2) génériques disponibles.
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).
À partir de Linux 4.11, le champ features peut être utilisé pour demander si des fonctions particulières sont prises en charge et pour activer explicitement des fonctionnalités userfaultfd désactivées par défaut. Le noyau signale toujours toutes les fonctions disponibles dans le champ features.
Pour activer les fonctionnalités userfaultfd, l'application doit positionner un bit correspondant à chaque fonction qu'il veut activer dans le champ features. Si le noyau gère toutes les fonctionnalités demandées, il les activera. Sinon, il mettra zéro dans la structure uffdio_api renvoyée et il renverra EINVAL.
Les bits fonctionnels suivants peuvent être positionnés :
Le champ ioctls renvoyé peut contenir les bits suivants :
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 :
(Depuis Linux 4.3). Enregistrer une plage d'adresse mémoire avec l'objet userfaultfd. Les pages de cette plage doivent être « compatibles ». Veuillez vous reporter à la liste des modes d'enregistrement ci-dessous pour les dorsales de mémoire compatibles avec chaque 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 :
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 :
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 :
(Depuis Linux 4.3). Désenregistre une plage d'adresse mémoire de userfaultfd. Les pages de cette plage doivent être « compatibles » (voir la description de 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 :
(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 :
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 :
(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 :
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 :
(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 :
Verrouiller ou déverrouiller en écriture une plage de mémoire userfaultfd enregistrée avec les accès 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 :
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 :
(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 :
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 :
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 :
Ces opérations ioctl(2) sont spécifiques à 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.
| 15 décembre 2022 | Pages du manuel de Linux 6.03 |