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 enabler DMA. Questo parametro è facoltativo e può essere WDF_NO_OBJECT_ATTRIBUTES.

[out] DmaEnablerHandle

Handle per un nuovo oggetto enabler 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 Framework Object Creation Errors.

Questo metodo potrebbe anche restituire altri valori NTSTATUS .

Se il driver fornisce un handle di oggetto non valido, si verifica un controllo di bug.

Osservazioni:

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.

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 elemento 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, WdfDmaEnablerCreare 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.

Esempi

L'esempio di codice seguente proviene dal driver di esempio PLX9 x5x5x. Questo esempio imposta 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

Vedere anche

WDF_DMA_ENABLER_CONFIG

WDF_DMA_ENABLER_CONFIG_INIT

WDF_OBJECT_ATTRIBUTES

WdfDeviceSetAlignmentRequirement