PALLOCATE_ADAPTER_CHANNEL_EX fonction de rappel (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 lancer 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 périphérique DMA maître de bus du pilote ou le canal DMA système. 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 dans toutes les demandes d’allocation d’adaptateur. Pour annuler une demande d’allocation en attente, l’appelant doit fournir le contexte de transfert DMA de 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 inférieure du nombre de registres cartographiques nécessaires pour satisfaire la demande de transfert actuelle et le nombre de registres cartographiques disponibles. Le pilote a précédemment appelé la routine GetDmaTransferInfo pour obtenir le nombre de registres cartographiques nécessaires au transfert, puis appelé la routine IoGetDmaAdapter routine pour obtenir le nombre de registres cartographiques disponibles.
[in] Flags
Indicateurs d’allocation de canal d’adaptateur. L’indicateur suivant est pris en charge.
Si l’indicateur DMA_SYNCHRONOUS_CALLBACK est défini, le paramètre ExecutionRoutine est facultatif et peut être NULL. Pour plus d’informations sur cet indicateur, consultez la section Remarques.
[in, optional] ExecutionRoutine
Pointeur vers le pilote fourni AdapterControl routine qui lance le transfert DMA pour le pilote. Le gestionnaire d’E/S appelle la routine AdapterControl une fois les ressources requises allouées pour l’objet adaptateur. Une fois la routine AdapterControl retournée, le gestionnaire d’E/S libère automatiquement l’objet adaptateur. Le gestionnaire d’E/S peut également libérer les ressources qui ont été allouées pour cet objet, en fonction de la valeur retournée par cette routine.
Si l’indicateur de DMA_SYNCHRONOUS_CALLBACK est défini, le ExecutionRoutine est facultatif et peut être NULL. Dans ce cas, l’appelant peut utiliser les ressources allouées par AllocateAdapterChannelEx, puis libérer ces ressources en appelant la routine FreeAdapterObject. Pour plus d’informations, consultez la section Remarques.
[in, optional] ExecutionContext
Contexte de contrôle d’adaptateur déterminé par le pilote. Ce contexte est passé à la routine AdapterControl en tant que paramètre de contexte.
[out, optional] MapRegisterBase
Pointeur vers une variable dans laquelle la routine écrit un handle dans les registres de mappage alloués. L’appelant peut fournir ce handle en tant que paramètre au FlushAdapterBuffersEx, FlushAdapterBuffers, FreeMapRegistersou MapTransferEx routine.
Si l’indicateur de DMA_SYNCHRONOUS_CALLBACK est défini, MapRegisterBase doit être un pointeurNULL valide non. Si le paramètre ExecutionRoutine n’est pasNULL, MapRegisterBase doit être NULL. L’appel échoue si MapRegisterBase n’est pas NULL et si l’indicateur DMA_SYNCHRONOUS_CALLBACK n’est pas défini, ou si MapRegisterBase et ExecutionRoutine sont tous deux NULL.
Valeur de retour
AllocateAdapterChannelEx retourne STATUS_SUCCESS si l’appel réussit. Les valeurs de retour d’erreur possibles incluent les codes d’état suivants.
| Retourner le code | Description |
|---|---|
|
La routine a échoué en raison de valeurs de paramètre non valides passées par l’appelant. |
|
La routine n’a pas pu allouer de ressources requises pour le transfert DMA. |
Remarques
AllocateAdapterChannelEx 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. Pilotes obtiennent l’adresse de cette routine en appelant IoGetDmaAdapter avec le membre version du paramètre DeviceDes cription défini sur DEVICE_DESCRIPTION_VERSION3. Si IoGetDmaAdapter retourne NULL, la routine n’est pas disponible sur votre plateforme.
AllocateAdapterChannelEx alloue les ressources requises pour effectuer une opération DMA. Ces ressources incluent les canaux DMA et les registres cartographiques. Une fois toutes les ressources requises allouées pour une utilisation par l’adaptateur DMA, AllocateAdapterChannelEx appelle la routine AdapterControl fournie par l’appelant pour lancer l’opération DMA.
Par défaut, AllocateAdapterChannelEx retourne de façon asynchrone, sans attendre que l’allocation de ressources demandée soit terminé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 de 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 nécessaire pour fournir une routine AdapterControl si l’indicateur de DMA_SYNCHRONOUS_CALLBACK est défini.
- Si le pilote fournit une routine AdapterControl, l’indicateur DMA_SYNCHRONOUS_CALLBACK indique que cette routine doit être appelée dans le contexte du thread appelant, avant AllocateAdapterChannelEx retourne.
- Si le pilote ne fournit pas de routine AdapterControl, le pilote peut utiliser les ressources allouées après AllocateAdapterChannelEx retourne. Dans ce cas, le pilote doit appeler FreeAdapterObject une fois qu’il a terminé d’utiliser les ressources allouées.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Disponible à partir de Windows 8. |
| plateforme cible | Bureau |
| d’en-tête | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| IRQL | DISPATCH_LEVEL |