PCREATE_COMMON_BUFFER_FROM_MDL fonction de rappel (wdm.h)

Article
02/27/2024

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 éventuellement 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.

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 la MDL qui sera mappée à une mémoire tampon commune.

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

La MDL doit avoir des pages qui sont toujours résidentes 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 :
La MDL est créée à partir d’une mémoire tampon dans le pool non paginé via MmBuildMdlForNonPagedPool.
La MDL a été verrouillée via MmProbeAndLockPages et mappée à l’espace système via MmGetSystemAddressForMdlSafe.
Les pages physiques de la MDL ont été allouées via MmAllocatePagesForMdlEx et mappées à l’espace système via MmGetSystemAddressForMdlSafe.
La MDL doit représenter une région alignée sur une page et être un multiple de PAGE_SIZE.
- Si la configuration étendue SubSection est utilisée, la partie de la MDL utilisée doit être alignée sur la page et être un multiple de PAGE_SIZE.
La MDL ne doit pas être une MDL chaînée.
- Si la configuration étendue SubSection est utilisée, une MDL chaînée peut être fournie, mais la partie de la MDL utilisée doit être contenue dans une seule MDL dans la chaîne.
Si le remapping DMA n’est pas utilisé, la 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 du 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

En cas de réussite, fournit l’adresse logique de la mémoire tampon commune résultante.

Valeur retournée

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

Code de retour	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 ne dispose pas de suffisamment de mémoire pour créer des métadonnées de gestion des livres et de mappage.

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 s’assurer que la mémoire tampon commune est correctement supprimée des structures de gestion des mémoires tampons courantes de l’adaptateur. Le pilote est toujours responsable du déverrouillage et de la libération de la MDL et de ses pages de sauvegarde.

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