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.

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

Vedi anche

WDF_DMA_ENABLER_CONFIG

WDF_DMA_ENABLER_CONFIG_INIT

WDF_OBJECT_ATTRIBUTES

WdfDeviceSetAlignmentRequirement