KeSetKernelStackSwapEnable, fonction (ntifs.h)

La routine KeSetKernelStackSwapEnable active et désactive l’échange de la pile de l’appelant sur 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é et en dehors 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 où l’appel a été lancé. Cette valeur est TRUE si l’échange de pile a été activé précédemment et est FALSE s’il a été désactivé.

Notes

Un pilote en mode noyau peut appeler cette routine pour contrôler si sa pile est paginable ou verrouillée en 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. Ne faites cela que dans de rares cas. Pour obtenir un exemple qui traite des 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 appartiennent au thread en attente. Toutefois, si la pile contient des éléments de données qui doivent rester résident en mémoire pendant la durée d’attente, le thread peut empêcher la pile d’être paginée en appelant KeSetKernelStackSwapEnable et en spécifiant Activer = FALSE.

Un thread ne doit pas quitter (se terminer) pendant que l’échange de pile est désactivé ou qu’une vérification de bogue système 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 une 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 en 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é.

Spécifications

   
Client minimal pris en charge Disponible à partir de Windows 2000.
Plateforme cible Universal
En-tête ntifs.h (include Ntifs.h, Fltkernel.h)
Bibliothèque NtosKrnl.lib
DLL NtosKrnl.exe
IRQL <= APC_LEVEL

Voir aussi

KeInitializeEvent

KeWaitForSingleObject