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 |
|---|---|
|
È stato rilevato un parametro non valido. |
|
Memoria insufficiente per costruire un nuovo oggetto abilitante DMA. |
|
Le dimensioni della struttura WDF_DMA_ENABLER_CONFIG non sono corrette. |
|
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) |