Funzione WdfDmaEnablerCreate (wdfdmaenabler.h)

[Si applica solo a KMDF]

Il metodo WdfDmaEnablerCreate crea un oggetto enabler DMA.

Sintassi

NTSTATUS WdfDmaEnablerCreate(
  [in]           WDFDEVICE               Device,
  [in]           PWDF_DMA_ENABLER_CONFIG Config,
  [in, optional] PWDF_OBJECT_ATTRIBUTES  Attributes,
  [out]          WDFDMAENABLER           *DmaEnablerHandle
);

Parametri

[in] Device

Handle per un oggetto dispositivo framework.

[in] Config

Puntatore a una struttura WDF_DMA_ENABLER_CONFIG . I driver devono inizializzare questa struttura chiamando WDF_DMA_ENABLER_CONFIG_INIT.

[in, optional] Attributes

Puntatore a una struttura WDF_OBJECT_ATTRIBUTES che specifica gli attributi dell'oggetto per il nuovo oggetto abilitante DMA. Questo parametro è facoltativo e può essere WDF_NO_OBJECT_ATTRIBUTES.

[out] DmaEnablerHandle

Handle a un nuovo oggetto di abilitazione DMA.

Valore restituito

WdfDmaEnablerCreate restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, il metodo potrebbe restituire uno dei valori seguenti.

Codice restituito Descrizione
STATUS_INVALID_PARAMETER
È stato rilevato un parametro non valido.
STATUS_INSUFFICIENT_RESOURCES

Memoria insufficiente per costruire un nuovo oggetto abilitante DMA.

STATUS_INFO_LENGTH_MISMATCH
Le dimensioni della struttura WDF_DMA_ENABLER_CONFIG non sono corrette.
STATUS_NOT_SUPPORTED
Il driver ha richiesto DMA versione 3 in un sistema operativo precedente a Windows 8.
 

Per un elenco di altri valori restituiti che il metodo WdfDmaEnablerCreate potrebbe restituire, vedere Errori di creazione dell'oggetto Framework.

Questo metodo potrebbe restituire anche altri valori NTSTATUS.

Un controllo di bug si verifica se il driver fornisce un handle di oggetti non valido.

Commenti

I driver basati su framework devono chiamare WdfDmaEnablerCreate prima di creare transazioni DMA per un dispositivo.

Prima che un driver chiami WdfDmaEnablerCreate, deve chiamare WdfDeviceSetAlignmentRequirement.

L'oggetto dispositivo framework che il parametro Device di WdfDmaEnablerCreate diventa sempre l'oggetto padre per il nuovo oggetto enabler DMA. Se il driver specifica un padre diverso nel membro ParentObject della struttura WDF_OBJECT_ATTRIBUTES , il framework ignora questo valore. Il framework elimina l'oggetto abilitante DMA quando elimina l'oggetto padre.

Quando viene chiamato con un parametro Config che richiede un profilo DMA in modalità sistema, WdfDmaEnablerCreate crea un abilitatore DMA parzialmente inizializzato. Il driver deve successivamente chiamare WdfDmaEnablerConfigureSystemProfile per configurare le impostazioni DMA per i canali sottostanti.

Per altre informazioni sugli oggetti enabler DMA e WdfDmaEnablerCreate, vedere Abilitazione delle transazioni DMA.

Esempio

L'esempio di codice seguente è dal driver di esempio PLX9x5x5x . In questo esempio viene impostato il requisito di un dispositivo per l'allineamento del buffer, inizializza una struttura WDF_DMA_ENABLER_CONFIG e chiama WdfDmaEnablerCreate.

//
// PLx PCI9656 DMA_TRANSFER_ELEMENTS must be 16-byte aligned.
//
WdfDeviceSetAlignmentRequirement(
                                 DevExt->WdfDevice,
                                 PCI9656_DTE_ALIGNMENT_16
                                 );

//
// Create a new DMA enabler object instance. 
// Use scatter/gather, 64-bit addresses, and duplex-type profile.
//
{
    WDF_DMA_ENABLER_CONFIG   dmaConfig;
    WDF_DMA_ENABLER_CONFIG_INIT(
                                &dmaConfig,
                                WdfDmaProfileScatterGather64Duplex,
                                DevExt->MaximumTransferLength
                                );
    status = WdfDmaEnablerCreate(
                                 DevExt->WdfDevice,
                                 &dmaConfig,
                                 WDF_NO_OBJECT_ATTRIBUTES,
                                 &DevExt->DmaEnabler
                                 );
    if (!NT_SUCCESS (status)) {
        // Cannot continue, so release device resources.
        return status;
    }
}

Requisiti

Requisito Valore
Piattaforma di destinazione Universale
Versione KMDF minima 1.0
Intestazione wdfdmaenabler.h (include Wdf.h)
Libreria Wdf01000.sys (vedere Framework Library Versioning).
IRQL PASSIVE_LEVEL
Regole di conformità DDI DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Vedi anche

WDF_DMA_ENABLER_CONFIG

WDF_DMA_ENABLER_CONFIG_INIT

WDF_OBJECT_ATTRIBUTES

WdfDeviceSetAlignmentRequirement