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 mémoire 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 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 POOL_TYPE typée 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 allant jusqu’à quatre caractères, délimitées 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 du service en mode noyau de votre pilote. Si le nom du service commence par « WDF » (le nom n’est pas sensible à 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 les versions 1.5 et ultérieures de KMDF, 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 non nulle 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 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 avoir la valeur NULL.

Valeur de retour

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
STATUS_INVALID_PARAMETER
Un paramètre non valide a été détecté.
STATUS_INSUFFICIENT_RESOURCES
La mémoire était insuffisante.
 

Pour obtenir la liste d’autres valeurs de retour que la méthode WdfMemoryCreate peut retourner, consultez Erreurs de création d’objets 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 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 ne pas utiliser la mémoire pour l’allocation de mémoire, en particulier pour les allocations qui seront copiées dans un emplacement non approuvé (mode utilisateur, sur le réseau, etc.) pour éviter de divulguer des informations sensibles. WdfMemoryCreate n’initialise pas 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, il ne s’agit pas de la meilleure approche.

L’objet parent par défaut pour chaque objet mémoire est l’objet de pilote d’infrastructure qui représente le pilote appelé WdfMemoryCreate. Si votre pilote crée un objet mémoire qu’il utilise avec un objet de périphérique spécifique, un objet de requête ou un autre objet framework, 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 restent 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 demandés de mémoire. La mémoire tampon n’est pas nécessairement alignée sur la page, mais elle est alignée sur le nombre d’octets spécifiés par la constante MEMORY_ALLOCATION_ALIGNMENT 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. Les octets inutilisés de la dernière page allouée sont essentiellement gaspillés.

Pour plus d’informations sur les objets de mémoire d’infrastructure, consultez Utilisation des mémoires tampons.

Si votre pilote spécifie PagedPool pour PoolType, la méthode WdfMemoryCreate doit être appelée à IRQL <= APC_LEVEL. Sinon, la méthode peut être appelée à IRQL <= DISPATCH_LEVEL.

Exemples

L’exemple de code suivant crée un objet 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

   
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 Voir la section Notes.
Règles de conformité DDI DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), ParentObjectCheck(kmdf)

Voir aussi

POOL_TYPE

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT

WdfMemoryCreateFromLookaside

WdfMemoryCreatePreallocated

WdfMemoryGetBuffer

WdfObjectDelete