WdfDeviceSetAlignmentRequirement, fonction (wdfdevice.h)

  • Article

[S’applique à KMDF uniquement]

La méthode WdfDeviceSetAlignmentRequirement enregistre l’alignement d’adresse préféré du pilote pour les mémoires tampons de données que l’appareil utilise pendant les opérations de transfert de mémoire.

Syntaxe

void WdfDeviceSetAlignmentRequirement(
  [in] WDFDEVICE Device,
  [in] ULONG     AlignmentRequirement
);

Paramètres

[in] Device

Handle pour un objet d’appareil d’infrastructure.

[in] AlignmentRequirement

Exigence d’alignement dépendant du matériel pour une mémoire tampon de données. Cette valeur doit être inférieure à la limite d’alignement. Par exemple, vous pouvez spécifier 15 pour une limite d’alignement de 16 octets et 31 pour une limite d’alignement de 32 octets. Vous pouvez également utiliser l’une des constantes FILE_Xxxx_ALIGNMENT définies dans Wdm.h, par exemple :

//
// Define alignment requirement values
//
#define FILE_BYTE_ALIGNMENT             0x00000000
#define FILE_WORD_ALIGNMENT             0x00000001
#define FILE_LONG_ALIGNMENT             0x00000003
#define FILE_QUAD_ALIGNMENT             0x00000007
#define FILE_OCTA_ALIGNMENT             0x0000000f
#define FILE_32_BYTE_ALIGNMENT          0x0000001f
#define FILE_64_BYTE_ALIGNMENT          0x0000003f
#define FILE_128_BYTE_ALIGNMENT         0x0000007f
#define FILE_256_BYTE_ALIGNMENT         0x000000ff
#define FILE_512_BYTE_ALIGNMENT         0x000001ff

Valeur de retour

None

Remarques

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

Un pilote qui utilise des E/S directes peut appeler WdfDeviceSetAlignmentRequirement pour inscrire une exigence d’alignement par défaut. L’alignement s’applique aux demandes d’E/S qui passent par le Gestionnaire d’E/S, et non à celles envoyées à votre pilote à partir d’un autre pilote qui appelle IoCallDriver.

Étant donné que le gestionnaire d’E/S n’utilise pas toujours l’alignement demandé, le pilote doit être préparé pour les mémoires tampons non alignées.

Le pilote peut appeler WdfDeviceGetAlignmentRequirement pour obtenir la valeur actuelle de l’exigence d’alignement de l’appareil.

Le gestionnaire d’E/S définit une valeur d’exigence d’alignement pour le périphérique lorsque le pilote appelle WdfDeviceCreate. Pour plus d’informations sur la valeur d’exigence d’alignement d’un appareil et sur le moment où un pilote doit modifier la valeur, consultez Initialisation d’un objet d’appareil dans la documentation WDM.

Si votre pilote spécifie une exigence d’alignement supérieure à la taille de page de l’ordinateur (PAGE_SIZE), les adresses logiques retournées par la méthode WdfCommonBufferGetAlignedLogicalAddress sont toujours alignées sur l’exigence d’alignement spécifiée, mais les adresses virtuelles retournées par la méthode WdfCommonBufferGetAlignedVirtualAddress peuvent ne pas être alignées sur l’exigence d’alignement.

Si votre pilote spécifie une exigence d’alignement inférieure à la taille de page de l’ordinateur, toutes les adresses logiques et virtuelles sont alignées sur l’exigence d’alignement spécifiée.

Pour plus d’informations sur l’appel de WdfDeviceSetAlignmentRequirement, consultez Activation des transactions DMA et Utilisation de mémoires tampons communes.

Exemples

L’exemple de code suivant provient de l’exemple de pilote AMCC5933 . Cet exemple vérifie l’exigence d’alignement actuelle d’un appareil et définit l’exigence d’alignement sur une nouvelle valeur, si nécessaire. Notez que la valeur d’alignement exacte dépend du matériel.

ULONG alignReq;

alignReq = WdfDeviceGetAlignmentRequirement(device);
if (alignReq < AMCC5933_ALIGNMENT__32BITS) {
//
// Set the S5933 alignment requirement to a new value.
//
WdfDeviceSetAlignmentRequirement(
                                 device,
                                 AMCC5933_ALIGNMENT__32BITS
                                 );
}

Configuration requise

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

Voir aussi

WdfCommonBufferGetAlignedLogicalAddress

WdfCommonBufferGetAlignedVirtualAddress

WdfDeviceGetAlignmentRequirement