PALLOCATE_ADAPTER_CHANNEL fonction de rappel (wdm.h)

Article
02/27/2024

La routine AllocateAdapterChannel prépare le système pour une opération DMA pour le compte de l’objet d’appareil cible, puis appelle la routine AdapterControl fournie par le pilote pour effectuer l’opération DMA.

Syntaxe

PALLOCATE_ADAPTER_CHANNEL PallocateAdapterChannel;

NTSTATUS PallocateAdapterChannel(
  [in] PDMA_ADAPTER DmaAdapter,
  [in] PDEVICE_OBJECT DeviceObject,
  [in] ULONG NumberOfMapRegisters,
  [in] PDRIVER_CONTROL ExecutionRoutine,
  [in] PVOID Context
)
{...}

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] DeviceObject

Pointeur vers l’objet d’appareil qui représente l’appareil cible pour une opération DMA demandée.

[in] NumberOfMapRegisters

Spécifie le nombre de registres de carte à utiliser dans le transfert. Cette valeur est la moins élevée du nombre de registres de carte nécessaires pour répondre à la demande de transfert actuelle et du nombre de registres de carte disponibles retournés par IoGetDmaAdapter.

[in] ExecutionRoutine

Pointeur vers une routine AdapterControl fournie par le pilote. La routine est appelée lorsque le contrôleur DMA système ou l’adaptateur master bus devient disponible.

[in] Context

Pointeur vers le contexte déterminé par le pilote à passer à la routine AdapterControl .

Valeur retournée

Cette routine peut retourner l’une des valeurs NTSTATUS suivantes.

Code de retour	Description
STATUS_SUCCESS	Le canal de l’adaptateur a été alloué. Le système appelle la routine AdapterControl une fois que l’opération DMA peut commencer.
STATUS_INSUFFICIENT_RESOURCES	La valeur NumberOfMapRegisters est supérieure à la valeur retournée par IoGetDmaAdapter. La routine AdapterControl n’est pas appelée.

Remarques

AllocateAdapterChannel 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.

Un pilote appelle la routine AllocateAdapterControl pour inscrire une routine AdapterControl qui effectue une opération DMA pour le pilote. La routine AdapterControl effectue une opération DMA à l’aide du contrôleur DMA système ou d’une carte master bus.

Si l’opération DMA peut être effectuée immédiatement, le système appelle immédiatement AdapterControl. Si le contrôleur DMA système ou l’adaptateur master bus est actuellement en cours d’utilisation, AllocateAdapterChannel met en file d’attente AdapterControl jusqu’à ce que l’adaptateur soit disponible. Dans les deux cas, AllocateAdapterChannel retourne STATUS_SUCCESS.

Si le système ne dispose pas des ressources nécessaires pour effectuer l’opération DMA, AllocateAdapterChannel retourne STATUS_INSUFFICIENT_RESOURCES. Dans ce cas, AdapterControl n’est pas mis en file d’attente et le pilote doit terminer l’IRP actuel avec le code d’erreur approprié (par exemple, STATUS_INSUFFICIENT_RESOURCES).

Cette routine réserve un accès exclusif à un canal de contrôleur DMA et mappe les registres pour une ou plusieurs opérations DMA requises pour répondre à la demande de transfert IRP actuelle pour l’appareil spécifié.

Une seule requête DMA peut être mise en file d’attente pour un objet d’appareil à la fois. Par conséquent, le pilote ne doit pas appeler à nouveau AllocateAdapterChannel pour une autre opération DMA sur le même objet d’appareil tant que la routine AdapterControl n’a pas terminé l’exécution. En outre, un pilote ne doit pas appeler AllocateAdapterChannel à partir de sa routine AdapterControl .

Le système transmet la valeur du membre CurrentIrp de DeviceObject comme paramètre Irpd’AdapterControl. Si AllocateAdapterChannel est appelé à partir de la routine StartIo d’un pilote, il est garanti de pointer vers l’IRP que StartIo a été appelé à traiter. Sinon, pour utiliser le paramètre Irpd’AdapterControl, le pilote doit définir CurrentIrp pour qu’il pointe vers l’IRP actuel avant d’appeler AllocateAdapterChannel.

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	DISPATCH_LEVEL
Règles de conformité DDI	IrqlDispatch(storport),IrqlDispatch(storport), IrqlDispatch(wdm)