PFLUSH_ADAPTER_BUFFERS_EX fonction de rappel (wdm.h)

Article
02/29/2024

La routine FlushAdapterBuffersEx vide toutes les données qui restent dans le cache de données à la fin d’une opération de transfert DMA effectuée par un contrôleur DMA système ou un appareil master bus.

Syntaxe

PFLUSH_ADAPTER_BUFFERS_EX PflushAdapterBuffersEx;

NTSTATUS PflushAdapterBuffersEx(
  [in] PDMA_ADAPTER DmaAdapter,
  [in] PMDL Mdl,
  [in] PVOID MapRegisterBase,
  [in] ULONGLONG Offset,
  [in] ULONG Length,
  [in] BOOLEAN WriteToDevice
)
{...}

Paramètres

[in] DmaAdapter

Pointeur vers une structure DMA_ADAPTER . Cette structure est l’objet d’adaptateur qui représente le canal DMA système du pilote ou le périphérique master bus. L’appelant a obtenu ce pointeur à partir d’un appel précédent à la routine IoGetDmaAdapter .

[in] Mdl

Pointeur vers la chaîne MDL qui décrit les pages de mémoire à vider. Définissez ce paramètre pour qu’il pointe vers la chaîne MDL utilisée pour le transfert DMA. Pour plus d’informations, consultez la description du paramètre Mdl dans GetScatterGatherListEx, BuildScatterGatherListEx ou MapTransferEx.

[in] MapRegisterBase

Un handle pour les registres de carte qui ont été précédemment alloués pour l’objet adaptateur.

[in] Offset

Décalage de début par rapport au début de la chaîne MDL à utiliser pour l’opération de vidage. Définissez ce paramètre sur la valeur utilisée comme décalage de départ pour le transfert DMA. Pour plus d’informations, consultez la description du paramètre Offset dans GetScatterGatherListEx, BuildScatterGatherListEx ou MapTransferEx.

[in] Length

Nombre d’octets de données à vider. Définissez ce paramètre sur la valeur utilisée comme longueur de transfert pour le transfert DMA. Pour plus d’informations, consultez la description du paramètre Length dans GetScatterGatherListEx, BuildScatterGatherListEx ou MapTransferEx.

[in] WriteToDevice

Direction du transfert DMA. Définissez ce paramètre sur la valeur utilisée comme direction de transfert pour le transfert DMA. Pour plus d’informations, consultez la description du paramètre WriteToDevice dans GetScatterGatherListEx, BuildScatterGatherListEx ou MapTransferEx.

Valeur retournée

FlushAdapterBuffersEx 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_PARAMETERS	La routine a échoué en raison de valeurs de paramètre non valides transmises par l’appelant.

Remarques

FlushAdapterBuffersEx n’est pas une routine système qui peut être appelée directement par nom. Cette routine peut être appelée uniquement par un pointeur à partir 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.

FlushAdapterBuffersEx active la cohérence du cache du processeur dans les plateformes matérielles qui n’implémentent pas la cohérence du cache appliqué au matériel (contrôle de bus). En outre, pour un transfert DMA système, FlushAdapterBuffersEx vide toutes les données qui restent dans le cache interne du contrôleur DMA système.

Le pilote qui initie un transfert DMA de diffusion/collecte doit s’assurer que toutes les données transférées sont vidées du cache une fois le transfert terminé. Le pilote doit appeler FlushAdapterBuffersEx avant que le pilote ne termine l’IRP qui a demandé le transfert DMA, et avant que le pilote libère les registres de carte. Pour plus d’informations, consultez Vidage des données mises en cache pendant les opérations DMA.

FlushAdapterBuffersEx est une version étendue de la routine FlushAdapterBuffers . FlushAdapterBuffersEx peut vider une liste de points/regroupements entière en un seul appel. En revanche, l’utilisation de FlushAdapterBuffers pour vider une liste de points/regroupements nécessite un appel distinct pour chaque MDL dans la chaîne MDL.

FlushAdapterBuffersEx peut être utilisé à la place de FlushAdapterBuffers pour vider la mémoire tampon pour un transfert DMA à un paquet. Dans ce cas, la chaîne MDL vers laquelle pointe le paramètre Mdl ne contient qu’un seul MDL. L’un des avantages de l’utilisation de FlushAdapterBuffersEx de cette façon est que l’appelant peut spécifier un décalage dans le MDL.

Si FlushAdapterBuffersEx est appelé avant la fin de l’opération de transfert DMA, cet appel peut annuler le transfert avant qu’il ne se termine ou entraîner un comportement non défini.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible à partir de Windows 8.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	wdm.h (inclure Wdm.h, Ntddk.h, Ntifs.h)
IRQL	<= DISPATCH_LEVEL