KeSetKernelStackSwapEnable, fonction (ntifs.h)

La routine KeSetKernelStackSwapEnable active et désactive l’échange de la pile de l’appelant vers le disque.

Syntaxe

BOOLEAN KeSetKernelStackSwapEnable(
  [in] BOOLEAN Enable
);

Paramètres

[in] Enable

Spécifie s’il faut activer l’échange de la pile qui appartient au thread appelant. Si la valeur est TRUE, l’échange est activé et le contenu de la pile peut être paginé dans et hors de la mémoire. Si la valeur est FALSE, l’échange est désactivé et la pile est résidente en mémoire.

Valeur retournée

KeSetKernelStackSwapEnable retourne une valeur BOOLEAN qui indique si l’échange de pile a été activé au moment du lancement de l’appel. Cette valeur est TRUE si l’échange de pile a été activé précédemment et est FALSE s’il a été désactivé.

Remarques

Un pilote en mode noyau peut appeler cette routine pour contrôler si sa pile est paginable ou verrouillée dans la mémoire.

L’échange de pile ne peut se produire que si le thread est dans un état d’attente provoqué par une requête d’une application en mode utilisateur. L’échange de pile ne se produit jamais pour les états d’attente initiés par les composants en mode noyau, que l’échange de pile soit activé ou non.

Il n’est généralement pas nécessaire de désactiver l’échange de pile. Effectuez cette opération uniquement dans de rares cas. Pour obtenir un exemple qui décrit les alternatives à la désactivation de l’échange de pile, consultez la section Exemple ci-dessous.

Dans un appel à une routine d’attente en mode noyau, telle que KeWaitForSingleObject, l’appelant spécifie un paramètre WaitMode pour indiquer si l’appelant attend en mode noyau ou en mode utilisateur. Si WaitMode = UserMode et si la durée d’attente est suffisamment longue, le gestionnaire de mémoire peut pager des sections de la pile qui appartient au thread en attente. Toutefois, si la pile contient des éléments de données qui doivent rester résidents de la mémoire pendant la durée de l’attente, le thread peut empêcher le paginage de la pile en appelant KeSetKernelStackSwapEnable et en spécifiant Activer = FALSE.

Un thread ne doit pas quitter (arrêter) tant que l’échange de pile est désactivé ou qu’un bogue système case activée se produit.

Exemple

Dans l’exemple de code suivant, un thread de pilote alloue un événement sur sa pile et appelle KeSetKernelStackSwap pour verrouiller temporairement la pile en mémoire jusqu’à ce que l’événement soit signalé. Le pilote appelle KeWaitForSingleObject avec un WaitReason de UserRequest pour indiquer que son thread est dans un état d’attente provoqué par une requête d’une application en mode utilisateur, et WaitMode défini sur KernelMode pour indiquer que l’attente se produit en mode noyau. Une fois l’attente terminée, le thread appelle à nouveau KeSetKernelStackSwap , si nécessaire, pour restaurer l’état d’échange de pile d’origine du thread.

KEVENT event;
BOOLEAN oldSwapEnable;
NTSTATUS status;

oldSwapEnable = KeSetKernelStackSwapEnable(FALSE);

KeInitializeEvent(&event, SynchronizationEvent, FALSE);

//
// TO DO: Insert code here to pass the event to another thread
// that will set the event to the signaled state.
//
...

status = KeWaitForSingleObject(&event, UserRequest, KernelMode, FALSE, NULL);

if (oldSwapEnable)
{
    KeSetKernelStackSwapEnable(TRUE);
}

Un objet d’événement doit être résident de la mémoire alors qu’il peut être défini sur un état signal ou non signé, ou pendant qu’un thread attend l’événement. Pour plus d’informations, consultez Définition et utilisation d’un objet d’événement.

Souvent, l’utilisation de la routine KeSetKernelStackSwap est inutile et peut être évitée en allouant uniquement des éléments de données paginables sur la pile. Dans l’exemple précédent, le thread de pilote doit verrouiller la pile, car l’objet d’événement est alloué sur la pile. Une meilleure alternative peut être d’allouer simplement l’événement à partir d’un pool non paginé.

Configuration requise

Voir aussi

KeInitializeEvent

KeWaitForSingleObject