Funzione WdfDmaTransactionAllocateResources (wdfdmatransaction.h)

Articolo
03/05/2024

[Si applica solo a KMDF]

Il metodo WdfDmaTransactionAllocateResources riserva un abilitatore DMA a pacchetto singolo o in modalità 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 cui devono essere riservate le risorse DMA.

[in] DmaDirection

Valore tipizzato WDF_DMA_DIRECTION che specifica la direzione di trasferimento DMA per cui vengono riservate le risorse. 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 prenotare. Se zero, il framework deriva il numero richiesto di registri di mapping 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 dell'evento EvtReserveDma 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 denominato 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 a raccolta a dispersione.

Commenti

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 dell'evento EvtReserveDma del driver. Per altre informazioni sulla prenotazione delle risorse, vedere Prenotazione di risorse DMA.

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

Quando viene chiamato con un enabler DMA a dispersione/gather, WdfDmaTransactionAllocateResources causa un controllo di 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 quando i registri delle mappe sono stati liberati a HAL e quindi riallocati.

Un driver può chiamare WdfDmaTransactionAllocateResources nelle situazioni seguenti:

Il driver riceve un set di canali DMA nella relativa funzione di callback EvtDevicePrepareHardware . 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'abilitazione. 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 avvierà usando questa prenotazione. A tale scopo, il driver può chiamare [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 rispetto a 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 membro WdmDmaVersionOverride di WDF_DMA_ENABLER_CONFIG su 3.

Requisiti

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