Funzione WdfDmaTransactionAllocateResources (wdfdmatransaction.h)

[Si applica solo a KMDF]

Il metodo WdfDmaTransactionAllocateResources riserva un abilitatore DMA a pacchetto singolo o in modalità di sistema per l'uso esclusivo (e ripetuto) con l'oggetto transazione specificato. Il driver può inizializzare e avviare la transazione più volte mantenendo le risorse riservate.

Sintassi

NTSTATUS WdfDmaTransactionAllocateResources(
  [in] WDFDMATRANSACTION   DmaTransaction,
  [in] WDF_DMA_DIRECTION   DmaDirection,
  [in] ULONG               RequiredMapRegisters,
  [in] PFN_WDF_RESERVE_DMA EvtReserveDmaFunction,
  [in] PVOID               EvtReserveDmaContext
);

Parametri

[in] DmaTransaction

Handle per l'oggetto transazione DMA per il quale le risorse DMA devono essere riservate.

[in] DmaDirection

Valore WDF_DMA_DIRECTIONtipizzato che specifica la direzione di trasferimento DMA per cui le risorse vengono riservate. Se il driver non ha specificato un profilo duplex, il framework ignora questo valore.

[in] RequiredMapRegisters

Il numero di mappe registra il driver che vuole riservare. Se zero, il framework deriva il numero richiesto di registri mappa dalla transazione inizializzata.

[in] EvtReserveDmaFunction

Puntatore alla funzione di callback dell'evento evtReserveDma del driver.

[in] EvtReserveDmaContext

Puntatore a un buffer contenente il contesto da fornire alla funzione di callback degli eventi evtReserveD ma del driver.

Valore restituito

WdfDmaTransactionAllocateResources restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questo metodo restituisce uno dei valori seguenti.

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	Il parametro DmaDirection contiene un valore non valido.
STATUS_INSUFFICIENT_RESOURCES	Il numero di richieste di registrazione mappa supera il numero assegnato all'abilitatore oppure il driver precedentemente chiamato WdfDmaTransactionSetImmediateExecution e le risorse necessarie per la richiesta non sono disponibili.
STATUS_INVALID_DEVICE_REQUEST	DMA versione 3 o successiva non è abilitato o il driver ha chiamato questo metodo per un abilitatore DMA di raccolta a dispersione.

Osservazioni:

WdfDmaTransactionAllocateResources invia una richiesta di registrazione delle mappe al motore DMA di sistema. Quando la richiesta è stata soddisfatta, il framework chiama la funzione di callback degli eventi evtReserveDma del driver. Per altre informazioni sulla prenotazione delle risorse, vedere Riservare risorse DMA.

I driver basati su framework chiamano in genere WdfDmaTransactionAllocateResources dall'interno di un gestore di richieste I/O . Un driver può anche chiamare WdfDmaTransactionAllocateResources dalla relativa EvtDriverDeviceAdd funzione di callback, dopo aver creato un oggetto enabler DMA.

Quando viene chiamato con un abilitatore DMA a dispersione/raccolta, WdfDmaTransactionAllocateResources causa un controllo dei bug del classificatore.

Il driver deve creare la transazione specificata da DmaTransaction prima di chiamare WdfDmaTransactionAllocateResources. Dopo aver chiamato WdfDmaTransactionAllocateResources, il driver inizializza e avvia la transazione. Il driver può reinizializzare e reinizializzare più volte lo stesso oggetto transazione, evitando il ritardo che altrimenti si verificherebbe tra le transazioni perché i registri delle mappe sono stati liberati all'HAL e quindi riallocati.

Un driver può chiamare WdfDmaTransactionAllocateResources nelle situazioni seguenti:

• Il driver riceve un set di canali DMA nel relativo EvtDevicePrepareHardware funzione di callback. In EvtDevicePrepareHardware, il driver inizializza una transazione DMA e chiama WdfDmaTransactionAllocateResources per riservare l'abilitazione per l'uso esclusivo con questa transazione. In alternativa, il driver può chiamare WdfDmaTransactionAllocateResources da un gestore di richieste e quindi avviare la transazione più volte.
• Il driver deve eseguire una serie di transazioni nell'abilitatore. Il driver riserva l'abilitatore, inizializza e avvia più transazioni usando lo stesso oggetto transazione e quindi rilascia l'abilitatore.

Prima di chiamare WdfDmaTransactionAllocateResources, il driver deve determinare il numero di registri mappa necessari per qualsiasi transazione che inizierà a usare questa prenotazione. A tale scopo, il driver può chiamare il [ADDRESS_AND_SIZE_TO_SPAN_PAGES](.. Macro /wdm/nf-wdm-address_and_size_to_span_pages.md) o WdfDmaTransactionGetTransferInfo.

Quando si chiama WdfDmaTransactionAllocateResources, il driver non deve richiedere più registri mappa di quanto richiesto al momento della creazione dell'abilitatore.

Per chiamare WdfDmaTransactionAllocateResources in modo non bloccante, il driver deve prima chiamare WdfDmaTransactionSetImmediateExecution.

WdfDmaTransactionAllocateResources richiede DMA versione 3. Per selezionare DMA versione 3, impostare il WdmDmaVersionOverride membro di WDF_DMA_ENABLER_CONFIG su 3.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
versione minima di KMDF	1.11
intestazione	wdfdmatransaction.h (include Wdf.h)
Biblioteca	Wdf01000.sys (vedere Controllo delle versioni della libreria framework).
IRQL	<=DISPATCH_LEVEL
regole di conformità DDI	DriverCreate(kmdf)

Vedere anche

EvtDevicePrepareHardware

WdfDmaEnablerCreare

WdfDmaTransactionCreare

WdfDmaTransactionExecute

WdfDmaTransactionFreeResources

WdfDmaTransactionSetImmediateExecution