Funzione WdfDeviceSetAlignmentRequirement (wdfdevice.h)

  • Articolo

[Si applica solo a KMDF]

Il metodo WdfDeviceSetAlignmentRequirement registra l'allineamento degli indirizzi preferito del driver per i buffer di dati usati dal dispositivo durante le operazioni di trasferimento della memoria.

Sintassi

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

Parametri

[in] Device

Handle per un oggetto dispositivo framework.

[in] AlignmentRequirement

Requisito di allineamento dipendente dall'hardware per un buffer di dati. Questo valore deve essere minore del limite di allineamento. Ad esempio, è possibile specificare 15 per un limite di allineamento a 16 byte e 31 per un limite di allineamento a 32 byte. È anche possibile usare una delle costanti FILE_Xxxx_ALIGNMENT definite in Wdm.h, ad esempio:

//
// 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

Valore restituito

nessuno

Osservazioni

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

Un driver che usa L/O diretto può chiamare WdfDeviceSetAlignmentRequirement per registrare un requisito di allineamento preferito. L'allineamento si applica alle richieste di I/O che passano attraverso gestione I/O e non quelle inviate al driver da un altro driver che chiama IoCallDriver.

Poiché il gestore di I/O non usa sempre l'allineamento richiesto, il driver deve essere preparato per i buffer non idonei.

Il driver può chiamare WdfDeviceGetAlignmentRequirement per ottenere il valore corrente per il requisito di allineamento del dispositivo.

Il gestore I/O imposta un valore di allineamento per il dispositivo quando il driver chiama WdfDeviceCreate. Per altre informazioni sul valore del requisito di allineamento di un dispositivo e quando un driver deve modificare il valore, vedere Inizializzazione di un oggetto dispositivo nella documentazione di WDM.

Se il driver specifica un requisito di allineamento maggiore della dimensione della pagina del computer (PAGE_SIZE), gli indirizzi logici restituiti dal metodo WdfCommonBufferGetAlignedLogicalAddress sono sempre allineati al requisito di allineamento specificato, ma gli indirizzi virtuali restituiti dal metodo WdfCommonBufferGetAlignedVirtualAddress potrebbero non essere allineati al requisito di allineamento.

Se il driver specifica un requisito di allineamento minore delle dimensioni della pagina del computer, tutti gli indirizzi logici e virtuali sono allineati al requisito di allineamento specificato.

Per altre informazioni sulla chiamata a WdfDeviceSetAlignmentRequirement, vedere Abilitazione delle transazioni DMA e uso di buffer comuni.

Esempio

L'esempio di codice seguente proviene dal driver di esempio AMCC5933 . In questo esempio viene controllato il requisito di allineamento corrente di un dispositivo e viene impostato il requisito di allineamento su un nuovo valore, se necessario. Si noti che il valore di allineamento esatto dipende dall'hardware.

ULONG alignReq;

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

Requisiti

Requisito Valore
Piattaforma di destinazione Universale
Versione KMDF minima 1.0
Intestazione wdfdevice.h (includere 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

WdfCommonBufferGetAlignedLogicalAddress

WdfCommonBufferGetAlignedVirtualAddress

WdfDeviceGetAlignmentRequirement