WdfDmaEnablerGetFragmentLength, fonction (wdfdmaenabler.h)

  • Article

[S’applique uniquement à KMDF]

La méthode WdfDmaEnablerGetFragmentLength retourne la longueur de transfert maximale prise en charge par le système d’exploitation pour un transfert DMA unique.

Syntaxe

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

Paramètres

[in] DmaEnabler

Handle pour un objet d’activation DMA que le pilote a obtenu à partir d’un appel précédent à WdfDmaEnablerCreate.

[in] DmaDirection

Valeur de type WDF_DMA_DIRECTION qui spécifie le sens de l’opération de transfert DMA. Pour plus d'informations, consultez la section Notes qui suit.

Valeur retournée

WdfDmaEnablerGetFragmentLength retourne la longueur maximale d’un transfert DMA, en octets, que le système d’exploitation peut prendre en charge, ou zéro si la valeur du paramètre DmaDirection n’est pas valide.

Un bogue case activée se produit si le pilote fournit un handle d’objet non valide.

Remarques

La longueur maximale de transfert DMA que le système d’exploitation peut prendre en charge dépend du nombre de registres de carte disponibles. Si suffisamment de registres de carte sont disponibles, WdfDmaEnablerGetFragmentLength retourne la même valeur que WdfDmaEnablerGetMaximumLength . Sinon, la valeur retournée par WdfDmaEnablerGetFragmentLength sera inférieure à la valeur retournée par WdfDmaEnablerGetMaximumLength .

Votre pilote peut déterminer le nombre de registres de carte disponibles à l’aide de la macro BYTE_TO_PAGES, comme suit :

BYTE_TO_PAGES(WdfDmaEnablerGetFragmentLength()) + 1

Si votre pilote a spécifié un profil duplex lorsqu’il a appelé WdfDmaEnablerCreate, la valeur du paramètre DmaDirection doit être WdfDmaDirectionReadFromDevice pour obtenir la longueur de transfert maximale pour les opérations de lecture et WdfDmaDirectionWriteToDevice pour obtenir la longueur de transfert maximale pour les opérations d’écriture. Si votre pilote n’a pas spécifié de profil duplex, il peut spécifier WdfDmaDirectionReadFromDevice ou WdfDmaDirectionWriteToDevice pour DmaDirection.

Notez que si l’appareil de votre pilote prend en charge l’opération duplex, WdfDmaEnablerGetFragmentLength peut retourner des valeurs différentes pour les directions de lecture et d’écriture spécifiées par le paramètre DmaDirection . Cette différence est due au fait que l’infrastructure crée un objet d’adaptateur distinct pour chaque direction et que le système d’exploitation peut fournir un nombre différent de registres de carte à chaque objet d’adaptateur.

Exemples

L’exemple de code suivant détermine le nombre minimal de registres de carte nécessaires pour gérer les opérations de lecture d’un appareil de carte réseau, calcule le nombre de registres de carte disponibles et signale une erreur si le nombre de registres de carte alloués est insuffisant.

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;
}

Configuration requise

Condition requise Valeur
Plateforme cible Universal
Version KMDF minimale 1.1
En-tête wdfdmaenabler.h (inclure Wdf.h)
Bibliothèque Wdf01000.sys (consultez Gestion de version de la bibliothèque d’infrastructure.)
IRQL <=DISPATCH_LEVEL
Règles de conformité DDI DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Voir aussi

WDF_DMA_DIRECTION

WdfDmaEnablerCreate

WdfDmaEnablerGetMaximumLength