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 TRUE, l’échange est activé et le contenu de la pile peut être paginé et hors mémoire. Si FAUX, l’échange est désactivé et la pile est résidente en mémoire.
Valeur de retour
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 si elle a été désactivée.
Remarques
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 peut se produire uniquement si le thread est dans un état d’attente qui a été 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. Faites cela uniquement 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 = UserModeet 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 d’attente. Toutefois, si la pile contient des éléments de données qui doivent rester résidant en mémoire pendant la durée de l’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 (terminer) pendant que l’échange de pile est désactivé ou qu’une vérification des bogues 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 un WaitReason d'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 KeSetKernelStackSwap à nouveau, 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 pendant 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.
Fréquemment, 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é.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows 2000 |
| plateforme cible | Universel |
| d’en-tête | ntifs.h (include Ntifs.h, Fltkernel.h) |
| bibliothèque | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | <= APC_LEVEL |