Funzione WdfDmaEnablerGetFragmentLength (wdfdmaenabler.h)

  • Articolo

[Si applica solo a KMDF]

Il metodo WdfDmaEnablerGetFragmentLength restituisce la lunghezza massima di trasferimento supportata dal sistema operativo per un singolo trasferimento DMA.

Sintassi

size_t WdfDmaEnablerGetFragmentLength(
  [in] WDFDMAENABLER     DmaEnabler,
  [in] WDF_DMA_DIRECTION DmaDirection
);

Parametri

[in] DmaEnabler

Handle a un oggetto abilitante DMA ottenuto dal driver da una chiamata precedente a WdfDmaEnablerCreate.

[in] DmaDirection

Valore WDF_DMA_DIRECTION tipizzato che specifica la direzione dell'operazione di trasferimento DMA. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

Valore restituito

WdfDmaEnablerGetFragmentLength restituisce la lunghezza massima di un trasferimento DMA, in byte, che il sistema operativo può supportare o zero se il valore del parametro DmaDirection non è valido.

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

Commenti

La lunghezza massima di trasferimento DMA supportata dal sistema operativo dipende dal numero di registri mappa disponibili. Se sono disponibili registri mappa sufficienti, WdfDmaEnablerGetFragmentLength restituisce lo stesso valore restituito da WdfDmaEnablerGetMaximumLength . In caso contrario, il valore restituito da WdfDmaEnablerGetFragmentLength sarà minore del valore restituito da WdfDmaEnablerGetMaximumLength .

Il driver può determinare il numero di registri mappa disponibili usando la macro BYTE_TO_PAGES, come indicato di seguito:

BYTE_TO_PAGES(WdfDmaEnablerGetFragmentLength()) + 1

Se il driver ha specificato un profilo duplex quando si chiama WdfDmaEnablerCreate, il valore del parametro DmaDirection deve essere WdfDmaDirectionReadFromDevice per ottenere la lunghezza massima di trasferimento per le operazioni di lettura e WdfDmaDirectionWriteToDevice per ottenere la lunghezza massima di trasferimento per le operazioni di scrittura. Se il driver non ha specificato un profilo duplex, il driver può specificare WdfDmaDirectionReadFromDevice o WdfDmaDirectionWriteToDevice per DmaDirection.

Si noti che se il dispositivo del driver supporta l'operazione duplex, WdfDmaEnablerGetFragmentLength può restituire valori diversi per le direzioni di lettura e scrittura specificate dal parametro DmaDirection . Questa differenza è dovuta al fatto che il framework crea un oggetto adapter separato per ogni direzione e il sistema operativo potrebbe fornire un numero diverso di registri mappa a ogni oggetto adapter.

Esempio

L'esempio di codice seguente determina il numero minimo di registri mappa necessari per gestire le operazioni di lettura di un dispositivo di interfaccia di rete, calcola il numero di registri mappa disponibili e segnala un errore se il numero di registri mappa allocati non è sufficiente.

ULONG  minimumMapRegisters;
ULONG  maxLengthSupported;
ULONG  mapRegistersAllocated;

miniMapRegisters = BYTES_TO_PAGES(NIC_MAX_PACKET_SIZE) + 1;

maxLengthSupported = 
    (ULONG) WdfDmaEnablerGetFragmentLength(
                                           FdoData->WdfDmaEnabler,
                                           WdfDmaDirectionReadFromDevice
                                           );

mapRegistersAllocated = BYTES_TO_PAGES(maxLengthSupported) + 1;

if (mapRegistersAllocated < minimumMapRegisters) {
    status = STATUS_INSUFFICIENT_RESOURCES;
    return status;
}

Requisiti

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

Vedi anche

WDF_DMA_DIRECTION

WdfDmaEnablerCreate

WdfDmaEnablerGetMaximumLength