funzione di callback PALLOCATE_ADAPTER_CHANNEL_EX (wdm.h)

Articolo
02/27/2024

La routine AllocateAdapterChannelEx alloca le risorse necessarie per eseguire un trasferimento DMA e quindi chiama la routine AdapterControl fornita dal driver per avviare il trasferimento DMA.

Sintassi

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
)
{...}

Parametri

[in] DmaAdapter

Puntatore a una struttura DMA_ADAPTER . Questa struttura è l'oggetto adapter che rappresenta il dispositivo DMA master del driver o il canale DMA del sistema. Il chiamante ha ottenuto questo puntatore da una chiamata precedente alla routine IoGetDmaAdapter .

[in] DeviceObject

Puntatore a una struttura DEVICE_OBJECT . Questa struttura è l'oggetto dispositivo fisico (PDO) che rappresenta il dispositivo di destinazione per l'operazione DMA richiesta.

[in] DmaTransferContext

Puntatore a un contesto di trasferimento DMA inizializzato. Questo contesto è stato inizializzato da una chiamata precedente alla routine InitializeDmaTransferContext . Questo contesto deve essere univoco in tutte le richieste di allocazione degli adattatori. Per annullare una richiesta di allocazione in sospeso, il chiamante deve fornire il contesto di trasferimento DMA per la richiesta alla routine CancelAdapterChannel .

[in] NumberOfMapRegisters

Numero di registri mappa da utilizzare nel trasferimento DMA. Il driver chiamante deve impostare questo valore sul numero minore di registri mappa necessari per soddisfare la richiesta di trasferimento corrente e il numero di registri mappa disponibili. Il driver precedentemente ha chiamato la routine GetDmaTransferInfo per ottenere il numero di registri mappa necessari per il trasferimento e ha chiamato la routine IoGetDmaAdapter per ottenere il numero di registri mappa disponibili.

[in] Flags

Flag di allocazione del canale dell'adattatore. È supportato il flag seguente.

Contrassegno	Significato
DMA_SYNCHRONOUS_CALLBACK	La routine AllocateAdapterChannelEx viene chiamata in modo sincrono. Se questo flag è impostato e le risorse DMA necessarie non sono immediatamente disponibili, la chiamata ha esito negativo e restituisce STATUS_INSUFFICIENT_RESOURCES.

Se il flag DMA_SYNCHRONOUS_CALLBACK è impostato, il parametro ExecutionRoutine è facoltativo e può essere NULL. Per altre informazioni su questo flag, vedere la sezione Osservazioni.

[in, optional] ExecutionRoutine

Puntatore alla routine AdapterControl fornita dal driver che avvia il trasferimento DMA per il driver. La gestione I/O chiama la routine AdapterControl dopo l'allocazione delle risorse necessarie per l'oggetto adapter. Al termine della routine AdapterControl , il gestore di I/O libera automaticamente l'oggetto adapter. Il gestore di I/O potrebbe anche liberare le risorse allocate per questo oggetto, a seconda del valore restituito da questa routine.

Se il flag DMA_SYNCHRONOUS_CALLBACK è impostato, ExecutionRoutine è facoltativo e può essere NULL. In questo caso, il chiamante può usare le risorse allocate da AllocateAdapterChannelEx e successivamente liberare queste risorse chiamando la routine FreeAdapterObject . Per altre informazioni, vedere la sezione Osservazioni.

[in, optional] ExecutionContext

Contesto di controllo dell'adattatore determinato dal driver. Questo contesto viene passato alla routine AdapterControl come parametro Context .

[out, optional] MapRegisterBase

Puntatore a una variabile in cui la routine scrive un handle nei registri della mappa allocata. Il chiamante può fornire questo handle come parametro alla routine FlushAdapterBuffersEx, FlushAdapterBuffers, FreeMapRegisters o MapTransferEx .

Se il flag DMA_SYNCHRONOUS_CALLBACK è impostato, MapRegisterBase deve essere un puntatore non NULL valido. Se il parametro ExecutionRoutine non è NULL, MapRegisterBase deve essere NULL. La chiamata ha esito negativo se MapRegisterBase è diverso da NULL e il flag DMA_SYNCHRONOUS_CALLBACK non è impostato oppure se MapRegisterBase ed ExecutionRoutine sono entrambi NULL.

Valore restituito

AllocateAdapterChannelEx restituisce STATUS_SUCCESS se la chiamata ha esito positivo. I valori restituiti di errore possibili includono i codici di stato seguenti.

Codice restituito	Descrizione
STATUS_INVALID_PARAMETERS	La routine non è riuscita a causa di valori di parametro non validi passati dal chiamante.
STATUS_INSUFFICIENT_RESOURCES	La routine non è riuscita ad allocare le risorse necessarie per il trasferimento DMA.

Commenti

AllocateAdapterChannelEx non è una routine di sistema che può essere chiamata direttamente per nome. Questa routine può essere chiamata solo dal puntatore dall'indirizzo restituito in una struttura DMA_OPERATIONS. I driver ottengono l'indirizzo di questa routine chiamando IoGetDmaAdapter con il membro Version del parametro DeviceDescription impostato su DEVICE_DESCRIPTION_VERSION3. Se IoGetDmaAdapter restituisce NULL, la routine non è disponibile nella piattaforma.

AllocateAdapterChannelEx alloca le risorse necessarie per eseguire un'operazione DMA. Queste risorse includono i canali DMA e i registri delle mappe. Dopo che tutte le risorse necessarie vengono allocate per l'uso dalla scheda DMA, AllocateAdapterChannelEx chiama la routine AdapterControl fornita dal chiamante per avviare l'operazione DMA.

Per impostazione predefinita, AllocateAdapterChannelEx restituisce in modo asincrono, senza attendere il completamento dell'allocazione delle risorse richiesta. Dopo questa restituzione, il chiamante può, se necessario, annullare la richiesta di allocazione in sospeso chiamando la routine CancelAdapterChannel .

Se il driver chiamante imposta il flag DMA_SYNCHRONOUS_CALLBACK , la routine AllocateAdapterChannelEx si comporta come segue:

Se le risorse DMA richieste non sono immediatamente disponibili, AllocateAdapterChannelEx non attende le risorse e non chiama la routine AdapterControl . AllocateAdapterChannelEx ha invece esito negativo e restituisce STATUS_INSUFFICIENT_RESOURCES.
Il driver non è necessario per fornire una routine AdapterControl se è impostato il flag di DMA_SYNCHRONOUS_CALLBACK .
Se il driver fornisce una routine AdapterControl , il flag DMA_SYNCHRONOUS_CALLBACK indica che questa routine deve essere chiamata nel contesto del thread chiamante, prima che AllocateAdapterChannelEx restituisca.
Se il driver non fornisce una routine AdapterControl , il driver può usare le risorse allocate dopo la restituzione di AllocateAdapterChannelEx . In questo caso, il driver deve chiamare FreeAdapterObject al termine dell'uso delle risorse allocate.

AllocateAdapterChannelEx è una versione estesa della routine AllocateAdapterChannel . Le funzionalità seguenti sono disponibili solo nella versione estesa:

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile a partire da Windows 8.
Piattaforma di destinazione	Desktop
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	DISPATCH_LEVEL