UFFDIO_API¶

(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.

Pour les versions du noyau Linux antérieures à la 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 :

UFFD_FEATURE_EVENT_FORK (depuis Linux 4.11)

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

UFFD_FEATURE_EVENT_REMAP (depuis Linux 4.11)

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.

UFFD_FEATURE_EVENT_REMOVE (depuis Linux 4.11)

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.

UFFD_FEATURE_EVENT_UNMAP (depuis Linux 4.11)

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.

UFFD_FEATURE_MISSING_HUGETLBFS (depuis Linux 4.11)

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

UFFD_FEATURE_MISSING_SHMEM (depuis Linux 4.11)

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.

UFFD_FEATURE_SIGBUS (depuis Linux 4.14)

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.

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.

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'origine de l'erreur. Parmi les erreurs possibles :

EFAULT

argp renvoie à une adresse en dehors de l'espace d'adressage accessible du processus appelant.

EINVAL

Le userfaultfd a déjà été activé par une précédente opération UFFDIO_API.

EINVAL

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.

UFFDIO_REGISTER¶

(Depuis Linux 4.3). Enregistrer une plage d'adresse mémoire avec l'objet userfaultfd. Les pages de cette plage doivent être « compatibles »

Jusqu'au noyau 4.11 de Linux, seules les plages anonymes privées sont compatibles pour un enregistrement avec UFFDIO_REGISTER.

Depuis Linux 4.11, hugetlbfs et les plages de mémoire partagée sont aussi compatibles avec UFFDIO_REGISTER.

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 :

UFFDIO_REGISTER_MODE_MISSING

Retrouver les erreurs de pages du fait de pages absentes.

UFFDIO_REGISTER_MODE_WP

Retrouver des erreurs de page du fait de pages protégées en écriture.

Actuellement, le seul mode pris en charge est UFFDIO_REGISTER_MODE_MISSING.

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é est le même que pour UFFDIO_API.

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'origine de l'erreur. Parmi les erreurs possibles :

EBUSY

Un tableau de la plage indiquée est enregistré avec un autre objet userfaultfd.

EFAULT

argp renvoie à une adresse en dehors de l'espace d'adressage accessible du processus appelant.

EINVAL

Un bit non valable ou non pris en charge a été indiqué dans le champ mode ; ou le champ mode valait zéro.

EINVAL

Il n'y a pas de tableau dans la plage d'adresse indiquée.

EINVAL

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.

EINVAL

Un tableau incompatible est présent dans la plage d'adresse indiquée.

UFFDIO_UNREGISTER¶

(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'origine de l'erreur. Parmi les erreurs possibles :

EINVAL

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.

EINVAL

Un tableau incompatible est présent dans la plage d'adresse indiquée.

EINVAL

Il n'y avait pas de tableau dans la plage d'adresse spécifiée.

UFFDIO_COPY¶

(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 :

UFFDIO_COPY_MODE_DONTWAKE

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

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'origine de l'erreur. Parmi les erreurs possibles :

EAGAIN

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.

EINVAL

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.

EINVAL

Un bit non valable a été indiqué dans le champ mode.

ENOENT (depuis Linux 4.11)

Le processus fautif a modifié sa structure de mémoire virtuelle en même temps qu'une opération UFFDIO_COPY remarquable.

ENOSPC (de Linux 4.11 à Linux 4.13)

Le processus fautif a quitté au moment de l'opération UFFDIO_COPY.

ESRCH (depuis Linux 4.13)

Le processus fautif a quitté au moment de l'opération UFFDIO_COPY.

UFFDIO_ZEROPAGE¶

(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 :

UFFDIO_ZEROPAGE_MODE_DONTWAKE

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'origine de l'erreur. Parmi les erreurs possibles :

EAGAIN

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.

EINVAL

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.

EINVAL

Un bit non valable a été indiqué dans le champ mode.

ESRCH (depuis Linux 4.13)

Le processus fautif a quitté au moment de l'opération UFFDIO_ZEROPAGE.

UFFDIO_WAKE¶

(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'origine de l'erreur. Parmi les erreurs possibles :

EINVAL

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.