PCREATE_COMMON_BUFFER_FROM_MDL fonction de rappel (wdm.h)

Article
02/07/2025

La routine CreateCommonBufferFromMdl tente de créer une mémoire tampon commune à partir d’un MDL en testant la compatibilité de l’accès aux appareils et en mappant potentiellement la mémoire à une plage logique contiguë en fonction du type de traduction. Comme toutes les autres fonctions d’allocation de mémoire tampon courantes, cette fonction ne fournit pas de garantie de progression vers l’avant.

Syntaxe

PCREATE_COMMON_BUFFER_FROM_MDL PcreateCommonBufferFromMdl;

NTSTATUS PcreateCommonBufferFromMdl(
  [in]  PDMA_ADAPTER DmaAdapter,
  [in]  PMDL Mdl,
  [in]  PDMA_COMMON_BUFFER_EXTENDED_CONFIGURATION ExtendedConfigs,
  [in]  ULONG ExtendedConfigsCount,
  [out] PPHYSICAL_ADDRESS LogicalAddress
)
{...}

Paramètres

[in] DmaAdapter

Fournit un pointeur vers l’adaptateur DMA qui effectue l’opération.

[in] Mdl

Fournit le MDL qui sera mappé à une mémoire tampon commune.

Pour qu’un MDL puisse sauvegarder une mémoire tampon commune, les conditions suivantes doivent être remplies :

Le MDL doit avoir des pages qui résident toujours pendant la durée de vie de la mémoire tampon commune et qui sont mappées dans l’espace d’adressage système. Pour ce faire, procédez comme suit :
Le MDL est créé à partir d’une mémoire tampon dans le pool non paginé via MmBuildMdlForNonPagedPool.
Le MDL a été verrouillé via MmProbeAndLockPages et mappé à l’espace système via MmGetSystemAddressForMdlSafe.
Les pages physiques du MDL ont été allouées via MmAllocatePagesForMdlEx et mappées à l’espace système via MmGetSystemAddressForMdlSafe.
Le MDL doit représenter une région alignée sur la page et être un multiple de PAGE_SIZE.
- Si la configuration étendue SubSection est utilisée, la partie du MDL utilisée doit être alignée sur les pages et être un multiple de PAGE_SIZE.
Le MDL ne doit pas être un MDL chaîné.
- Si la configuration étendue SubSection est utilisée, un MDL chaîné peut être fourni, mais la partie du MDL utilisée doit être contenue dans un MDL unique dans la chaîne.
Si le remapping DMA n’est pas utilisé, le MDL doit représenter la mémoire physiquement contiguë et être accessible à l’appareil.

[in] ExtendedConfigs

Fournit un tableau facultatif de structures DMA_COMMON_BUFFER_EXTENDED_CONFIGURATION pour configurer davantage la création de la mémoire tampon commune soutenue par MDL.

Si plusieurs configurations de la même DMA_COMMON_BUFFER_EXTENDED_CONFIGURATION_TYPE sont fournies dans le tableau, la création échoue.

[in] ExtendedConfigsCount

Fournit le nombre de configurations étendues dans le tableau ExtendedConfigs.

[out] LogicalAddress

Le succès fournit l’adresse logique de la mémoire tampon commune résultante.

Valeur de retour

CreateCommonBufferFromMdl retourner STATUS_SUCCESS si l’appel réussit. Les valeurs de retour d’erreur possibles incluent les codes d’état suivants.

Retourner le code	Description
STATUS_INVALID_PARAMETER	L’appelant a fourni une configuration MDL ou étendue incompatible.
STATUS_NOT_SUPPORTED	L’appelant a fourni une configuration étendue qui n’est pas prise en charge sur le système actuel.
STATUS_INSUFFICIENT_RESOURCES	Le système n’a pas suffisamment de mémoire pour créer des métadonnées de conservation et de mappage de livres.

Remarques

CreateCommonBufferFromMdl n’est pas une routine système qui peut être appelée directement par nom. Cette routine peut être appelée uniquement par le pointeur de l’adresse retournée dans une structure DMA_OPERATIONS. Les pilotes obtiennent l’adresse de cette routine en appelant IoGetDmaAdapter avec le membre version du paramètre DeviceDescription défini sur DEVICE_DESCRIPTION_VERSION3. Si IoGetDmaAdapter retourne NULL, la routine n’est pas disponible sur votre plateforme.

Une mémoire tampon commune créée par CreateCommonBufferFromMdl sera supprimée via FreeCommonBuffer. L’appelant doit fournir l’adresse virtuelle système en tant qu’adresse virtuelle pour vous assurer que la mémoire tampon commune est correctement supprimée des structures courantes de conservation des mémoires tampons de l’adaptateur. Le pilote est toujours responsable du déverrouillage et de la libération du MDL et de ses pages de stockage.

Pour créer une mémoire tampon commune où hal est responsable de la maintenance de la mémoire de stockage, utilisez AllocateCommonBufferWithBounds.