PALLOCATE_COMMON_BUFFER fonction de rappel (wdm.h)

Article
02/29/2024

La routine AllocateCommonBuffer alloue de la mémoire et la mappe afin qu’elle soit simultanément accessible à partir du processeur et d’un appareil pour les opérations DMA.

Syntaxe

PALLOCATE_COMMON_BUFFER PallocateCommonBuffer;

PVOID PallocateCommonBuffer(
  [in]  PDMA_ADAPTER DmaAdapter,
  [in]  ULONG Length,
  [out] PPHYSICAL_ADDRESS LogicalAddress,
  [in]  BOOLEAN CacheEnabled
)
{...}

Paramètres

[in] DmaAdapter

Pointeur vers la structure DMA_ADAPTER retournée par IoGetDmaAdapter qui représente l’adaptateur master bus ou le contrôleur DMA.

[in] Length

Spécifie le nombre d’octets de mémoire à allouer.

[out] LogicalAddress

Pointeur vers une variable qui reçoit l’adresse logique que l’appareil peut utiliser pour accéder à la mémoire tampon allouée. Utilisez cette adresse plutôt que d’appeler MmGetPhysicalAddress , car le système peut prendre en compte toutes les restrictions de mémoire spécifiques à la plateforme.

[in] CacheEnabled

Spécifie si la mémoire allouée peut être mise en cache.

Ce paramètre est ignoré. Le système d’exploitation détermine s’il faut activer la mémoire mise en cache dans la mémoire tampon commune à allouer. Cette décision est basée sur l’architecture du processeur et le bus d’appareil.

Sur les ordinateurs dotés de processeurs x86, x64 et Itanium, la mémoire mise en cache est activée. Il est supposé que toutes les opérations DMA effectuées par un appareil sont cohérentes avec les caches d’UC appropriés, ce qui peut mettre en cache cette mémoire. Si votre pilote doit désactiver la mise en cache, appelez Plutôt AllocateCommonBufferEx .

Sur les ordinateurs dotés de processeurs ARM ou ARM 64, le système d’exploitation n’active pas automatiquement la mémoire mise en cache pour tous les appareils. Le système s’appuie sur la méthode ACPI_CCA pour chaque appareil afin de déterminer si l’appareil est cohérent dans le cache.

Valeur retournée

AllocateCommonBuffer retourne l’adresse virtuelle de base de la plage allouée. Si la mémoire tampon ne peut pas être allouée, elle retourne NULL.

Remarques

AllocateCommonBuffer 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 à partir de l’adresse retournée dans une structure de DMA_OPERATIONS . Les pilotes obtiennent l’adresse de cette routine en appelant IoGetDmaAdapter.

AllocateCommonBuffer prend en charge DMA dans lequel l’appareil et le processeur communiquent en continu via la mémoire système, comme dans une structure de contrôle pour un appareil DMA master bus.

AllocateCommonBuffer prend également en charge les appareils subordonnés dont les pilotes utilisent le mode d’ininitialisation automatique d’un contrôleur DMA système.

AllocateCommonBuffer effectue les opérations suivantes :

Alloue la mémoire accessible à partir du processeur et de l’appareil. Cette mémoire apparaît contiguë à l’appareil.
Alloue des registres de carte pour mapper la mémoire tampon, si nécessaire par le système.
Configure une traduction pour l’appareil, y compris le chargement des registres de carte si nécessaire.

Pour utiliser la mémoire système résidente de manière économique, les pilotes doivent allouer le moins possible de ces mémoires tampons par appareil. AllocateCommonBuffer alloue au moins une page de mémoire, quelle que soit la longueur demandée. Une fois l’allocation réussie demandant moins de PAGE_SIZE octets, l’appelant peut accéder uniquement à la longueur demandée. Après une allocation réussie demandant plus d’un multiple intégral de PAGE_SIZE octets, tous les octets restants de la dernière page allouée sont inaccessibles à l’appelant.

Si un pilote a besoin de plusieurs pages d’espace tampon commun, mais que les pages n’ont pas besoin d’être contiguës, le pilote doit effectuer plusieurs demandes d’une page à AllocateCommonBuffer au lieu d’une requête volumineuse. Cette approche conserve la mémoire contiguë.

Les pilotes appellent généralement AllocateCommonBuffer dans le cadre du démarrage de l’appareil, lors de leur réponse à une demande de IRP_MN_START_DEVICE PnP. Après le démarrage, il est possible que seules les demandes d’une page réussissent, le cas échéant.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible à partir de Windows 2000.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	wdm.h (inclure Wdm.h, Ntddk.h, Ntifs.h)
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	IrqlDispatch(wdm)

Voir aussi