Fonction de rappel PALLOCATE_ADAPTER_CHANNEL_EX (WDM. h)

La routine AllocateAdapterChannelEx alloue les ressources nécessaires pour effectuer un transfert DMA, puis appelle la routine AdapterControl fournie par le pilote pour initier le transfert DMA.

Syntaxe

PALLOCATE_ADAPTER_CHANNEL_EX PallocateAdapterChannelEx;

NTSTATUS PallocateAdapterChannelEx(
  [in]            PDMA_ADAPTER DmaAdapter,
  [in]            PDEVICE_OBJECT DeviceObject,
  [in]            PVOID DmaTransferContext,
  [in]            ULONG NumberOfMapRegisters,
  [in]            ULONG Flags,
  [in, optional]  PDRIVER_CONTROL ExecutionRoutine,
  [in, optional]  PVOID ExecutionContext,
  [out, optional] PVOID *MapRegisterBase
)
{...}

Paramètres

[in] DmaAdapter

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

[in] DeviceObject

Pointeur vers une structure DEVICE_OBJECT . Cette structure est l’objet d’appareil physique (PDO) qui représente l’appareil cible pour l’opération DMA demandée.

[in] DmaTransferContext

Pointeur vers un contexte de transfert DMA initialisé. Ce contexte a été initialisé par un appel précédent à la routine InitializeDmaTransferContext . Ce contexte doit être unique pour toutes les demandes d’allocation d’adaptateur. Pour annuler une demande d’allocation en attente, l’appelant doit fournir le contexte de transfert DMA pour la demande à la routine CancelAdapterChannel .

[in] NumberOfMapRegisters

Nombre de registres cartographiques à utiliser dans le transfert DMA. Le pilote appelant doit définir cette valeur sur la valeur la plus petite entre le nombre de registres de mappage requis pour satisfaire la demande de transfert actuelle et le nombre de registres de mappage disponibles. Le pilote a précédemment appelé la routine GetDmaTransferInfo pour obtenir le nombre de registres de mappage nécessaires pour le transfert, et a appelé la routine IoGetDmaAdapter pour obtenir le nombre de registres Map disponibles.

[in] Flags

Indicateurs d’allocation du canal de l’adaptateur. L’indicateur suivant est pris en charge.

Indicateur Signification
DMA_SYNCHRONOUS_CALLBACK
La routine AllocateAdapterChannelEx est appelée de façon synchrone. Si cet indicateur est défini et que les ressources DMA requises ne sont pas immédiatement disponibles, l’appel échoue et retourne STATUS_INSUFFICIENT_RESOURCES.

Si l’indicateur DMA_SYNCHRONOUS_CALLBACK est défini, le paramètre ExecutionRoutine est facultatif et peut avoir la valeur null. Pour plus d’informations sur cet indicateur, consultez la section Notes.

[in, optional] ExecutionRoutine

Pointeur vers la routine AdapterControl fournie par le pilote qui initie le transfert DMA pour le pilote. Le gestionnaire d’e/s appelle la routine AdapterControl après que les ressources requises ont été allouées pour l’objet carte. Une fois la routine AdapterControl retournée, le gestionnaire d’e/s libère automatiquement l’objet carte. Le gestionnaire d’e/s peut en outre libérer les ressources allouées pour cet objet, en fonction de la valeur renvoyée par cette routine.

Si l’indicateur DMA_SYNCHRONOUS_CALLBACK est défini, ExecutionRoutine est facultatif et peut avoir la valeur null. Dans ce cas, l’appelant peut utiliser les ressources allouées par AllocateAdapterChannelEx, puis libérer ultérieurement ces ressources en appelant la routine FreeAdapterObject . Pour plus d'informations, consultez la section Notes.

[in, optional] ExecutionContext

Contexte de contrôle de l’adaptateur, déterminé par le pilote. Ce contexte est passé à la routine AdapterControl comme paramètre de contexte .

[out, optional] MapRegisterBase

Pointeur vers une variable dans laquelle la routine écrit un handle vers les registres de mappage alloués. L’appelant peut fournir ce descripteur en tant que paramètre à la routine FlushAdapterBuffersEx, FlushAdapterBuffers, FreeMapRegistersou MapTransferEx .

Si l’indicateur DMA_SYNCHRONOUS_CALLBACK est défini, MapRegisterBase doit être un pointeur nonnull valide. Si le paramètre ExecutionRoutine n’a pas lavaleur null, MapRegisterBase doit avoir la valeur null. L’appel échoue si MapRegisterBase n’est pasnull et que l’indicateur DMA_SYNCHRONOUS_CALLBACK n’est pas défini, ou si MapRegisterBase et ExecutionRoutine ont la valeur null.

Valeur de retour

AllocateAdapterChannelEx retourne STATUS_SUCCESS si l’appel réussit. Les codes d’état suivants sont des valeurs de retour d’erreur possibles.

Code de retour Description
STATUS_INVALID_PARAMETERS
La routine a échoué en raison de valeurs de paramètre non valides passées par l’appelant.
STATUS_INSUFFICIENT_RESOURCES
La routine n’a pas pu allouer les ressources requises pour le transfert DMA.

Notes

AllocateAdapterChannelEx n’est pas une routine système qui peut être appelée directement par son nom. Cette routine ne peut être appelée que 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 la valeur null, la routine n’est pas disponible sur votre plateforme.

AllocateAdapterChannelEx alloue les ressources requises pour effectuer une opération DMA. Ces ressources incluent des canaux DMA et des registres map. Une fois que toutes les ressources requises sont allouées pour une utilisation par la carte DMA, AllocateAdapterChannelEx appelle la routine AdapterControl fournie par l’appelant pour lancer l’opération DMA.

Par défaut, AllocateAdapterChannelEx retourne de manière asynchrone, sans attendre la fin de l’allocation de ressources demandée. Après ce retour, l’appelant peut, le cas échéant, annuler la demande d’allocation en attente en appelant la routine CancelAdapterChannel .

Si le pilote appelant définit l’indicateur DMA_SYNCHRONOUS_CALLBACK , la routine AllocateAdapterChannelEx se comporte comme suit :

  • Si les ressources DMA demandées ne sont pas immédiatement disponibles, AllocateAdapterChannelEx n’attend pas les ressources et n’appelle pas la routine AdapterControl . Au lieu de cela, AllocateAdapterChannelEx échoue et retourne STATUS_INSUFFICIENT_RESOURCES.
  • Le pilote n’est pas obligé de fournir une routine AdapterControl si l’indicateur DMA_SYNCHRONOUS_CALLBACK est défini.
  • Si le pilote fournit une routine AdapterControl , l’indicateur de DMA_SYNCHRONOUS_CALLBACK indique que cette routine doit être appelée dans le contexte du thread appelant, avant que AllocateAdapterChannelEx retourne.
  • Si le pilote ne fournit pas de routine AdapterControl , le pilote peut utiliser les ressources allouées après le retour de AllocateAdapterChannelEx . Dans ce cas, le pilote doit appeler FreeAdapterObject une fois qu’il a fini d’utiliser les ressources allouées.
AllocateAdapterChannelEx est une version étendue de la routine AllocateAdapterChannel . Les fonctionnalités suivantes sont disponibles uniquement dans la version étendue :

Spécifications

   
Client minimal pris en charge Disponible à partir de Windows 8.
Plateforme cible Bureau
En-tête WDM. h (inclure WDM. h, Ntddk. h, Ntifs. h)
NIVEAU DISPATCH_LEVEL

Voir aussi

AdapterControl

AllocateAdapterChannel

CancelAdapterChannel

DEVICE_OBJECT

DMA_ADAPTER

DMA_OPERATIONS

FlushAdapterBuffers

FlushAdapterBuffersEx

FreeAdapterObject

FreeMapRegisters

GetDmaTransferInfo

InitializeDmaTransferContext

IoGetDmaAdapter

MapTransferEx