WdfMemoryCreate, fonction (wdfmemory.h)
[S’applique à KMDF et UMDF]
La méthode WdfMemoryCreate crée un objet de mémoire framework et alloue une mémoire tampon d’une taille spécifiée.
Syntaxe
NTSTATUS WdfMemoryCreate(
[in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
[in] POOL_TYPE PoolType,
[in, optional] ULONG PoolTag,
[in] size_t BufferSize,
[out] WDFMEMORY *Memory,
[out, optional] PVOID *Buffer
);
Paramètres
[in, optional] Attributes
Pointeur vers une structure de WDF_OBJECT_ATTRIBUTES qui contient des attributs d’objet pour le nouvel objet mémoire. Ce paramètre est facultatif et peut être WDF_NO_OBJECT_ATTRIBUTES.
[in] PoolType
Valeur de type POOL_TYPE qui spécifie le type de mémoire à allouer.
[in, optional] PoolTag
Balise de pool définie par le pilote pour la mémoire allouée. Les débogueurs affichent cette balise. Les pilotes spécifient généralement une chaîne de caractères de quatre caractères maximum, délimitée par des guillemets simples, dans l’ordre inverse (par exemple, « dcba »). La valeur ASCII de chaque caractère de la balise doit être comprise entre 0 et 127. Le débogage de votre pilote est plus facile si chaque balise de pool est unique.
Si PoolTag est égal à zéro, l’infrastructure fournit une balise de pool par défaut qui utilise les quatre premiers caractères du nom de service en mode noyau de votre pilote. Si le nom du service commence par « WDF » (le nom ne respecte pas la casse et n’inclut pas les guillemets), les quatre caractères suivants sont utilisés. Si moins de quatre caractères sont disponibles, « FxDr » est utilisé.
Pour KMDF versions 1.5 et ultérieures, votre pilote peut utiliser le membre DriverPoolTag de la structure WDF_DRIVER_CONFIG pour spécifier une balise de pool par défaut.
[in] BufferSize
Taille différente de zéro spécifiée, en octets, de la mémoire tampon.
[out] Memory
Pointeur vers un emplacement qui reçoit un handle vers le nouvel objet de mémoire.
[out, optional] Buffer
Pointeur vers un emplacement qui reçoit un pointeur vers la mémoire tampon associée au nouvel objet mémoire. Ce paramètre est facultatif et peut être NULL.
Valeur retournée
WdfMemoryCreate retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes :
| Code de retour | Description |
|---|---|
|
Un paramètre non valide a été détecté. |
|
La mémoire était insuffisante. |
Pour obtenir la liste des autres valeurs de retour que la méthode WdfMemoryCreate peut retourner, consultez Erreurs de création d’objet Framework.
Cette méthode peut également retourner d’autres valeurs NTSTATUS.
Remarques
La méthode WdfMemoryCreate alloue une mémoire tampon de la taille spécifiée par le paramètre BufferSize et crée un objet de mémoire framework qui représente la mémoire tampon.
Pour obtenir l’adresse de la mémoire tampon, votre pilote peut fournir une valeur non NULL pour le paramètre Buffer de la fonction WdfMemoryCreate, ou le pilote peut appeler WdfMemoryGetBuffer.
Il est recommandé de zéro mémoire pour l’allocation de mémoire, en particulier pour les allocations qui seront copiées vers un emplacement non approuvé (mode utilisateur, sur le réseau, etc.) afin d’éviter de divulguer des informations sensibles. WdfMemoryCreate n’initialise pas zéro la mémoire allouée par défaut.
En fonction du modèle d’utilisation du pilote de la mémoire allouée, la recommandation pour les enregistreurs de pilotes est de prendre en compte :
- RtlZeroMemory immédiatement après avoir appelé WdfMemoryCreate
- Vous pouvez également utiliser une API d’allocation zéro (ExAllocatePool2, ExAllocatePoolZero pour le mode noyau ; HeapAlloc avec l’indicateur HEAP_ZERO_MEMORY pour le mode utilisateur), suivi de WdfMemoryCreatePreallocated. Étant donné que la mémoire tampon pré-allouée n’est pas automatiquement supprimée dans le cadre de WDFMEMORY ou de sa suppression parente, cette approche n’est pas la meilleure.
L’objet parent par défaut pour chaque objet mémoire est l’objet pilote d’infrastructure qui représente le pilote appelé WdfMemoryCreate. Si votre pilote crée un objet de mémoire qu’il utilise avec un objet d’appareil, un objet de requête ou un autre objet framework spécifique, il doit définir le parent de l’objet mémoire de manière appropriée. L’objet mémoire et sa mémoire tampon sont supprimés lorsque l’objet parent est supprimé. Si vous ne modifiez pas l’objet parent par défaut, l’objet mémoire et sa mémoire tampon resteront jusqu’à ce que le gestionnaire d’E/S décharge votre pilote.
Un pilote peut également supprimer un objet mémoire et sa mémoire tampon en appelant WdfObjectDelete.
Si BufferSize est inférieur à PAGE_SIZE, le système d’exploitation donne à l’appelant exactement le nombre d’octets de mémoire demandés. La mémoire tampon n’est pas nécessairement alignée sur les pages, mais elle est alignée par le nombre d’octets que la constante MEMORY_ALLOCATION_ALIGNMENT spécifie dans Ntdef.h.
Si BufferSize est PAGE_SIZE ou supérieur, pour KMDF, seul le système alloue une mémoire tampon alignée sur les pages. Si le paramètre PoolType est NonPagedPool, le système alloue le nombre de pages nécessaires pour contenir tous les octets. Tous les octets inutilisés sur la dernière page allouée sont essentiellement gaspiller.
Pour plus d’informations sur les objets de mémoire framework, consultez Utilisation de mémoire tampons.
Si votre pilote spécifie PagedPool pour PoolType, la méthode WdfMemoryCreate doit être appelée à l’adresse IRQL <= APC_LEVEL. Sinon, la méthode peut être appelée à l’adresse IRQL <= DISPATCH_LEVEL.
Exemples
L’exemple de code suivant crée un objet de mémoire framework et alloue une mémoire tampon dont la taille est WRITE_BUFFER_SIZE. Le parent de l’objet mémoire est un objet de requête.
NTSTATUS status;
WDF_OBJECT_ATTRIBUTES attributes;
WDFMEMORY writeBufferMemHandle;
PVOID writeBufferPointer;
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = requestHandle;
status = WdfMemoryCreate(
&attributes,
NonPagedPool,
0,
WRITE_BUFFER_SIZE,
&writeBufferMemHandle,
&writeBufferPointer
);
Configuration requise
| Condition requise | Valeur |
|---|---|
| Plateforme cible | Universal |
| Version KMDF minimale | 1.0 |
| Version UMDF minimale | 2.0 |
| En-tête | wdfmemory.h (include Wdf.h) |
| Bibliothèque | Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF) |
| IRQL | Consultez la section Notes. |
| Règles de conformité DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), ParentObjectCheck(kmdf) |