Funzione WdfCommonBufferCreateWithConfig (wdfcommonbuffer.h)

Articolo
02/07/2025

[Si applica solo a KMDF]

Il metodo WdfCommonBufferCreateWithConfig crea un buffer di memoria a cui il driver e un dispositivo DMA (Direct Memory Access) possono accedere contemporaneamente e il metodo specifica anche le informazioni di configurazione del buffer.

Sintassi

NTSTATUS WdfCommonBufferCreateWithConfig(
  [in]           WDFDMAENABLER             DmaEnabler,
  [in]           size_t                    Length,
  [in]           PWDF_COMMON_BUFFER_CONFIG Config,
  [in, optional] PWDF_OBJECT_ATTRIBUTES    Attributes,
  [out]          WDFCOMMONBUFFER           *CommonBuffer
);

Parametri

[in] DmaEnabler

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

[in] Length

Dimensioni desiderate, in byte, del nuovo buffer.

[in] Config

Puntatore a una struttura WDF_COMMON_BUFFER_CONFIG che contiene informazioni di configurazione sul buffer.

[in, optional] Attributes

Puntatore a una struttura WDF_OBJECT_ATTRIBUTES che specifica gli attributi dell'oggetto oggetto per l'oggetto buffer comune. Il membro ParentObject della struttura deve essere NULL. Questo parametro è facoltativo e può essere WDF_NO_OBJECT_ATTRIBUTES.

[out] CommonBuffer

Puntatore a una variabile tipizzata WDFCOMMONBUFFER che riceve un handle per un oggetto buffer comune.

Valore restituito

WdfCommonBufferCreateWithConfig restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questo metodo potrebbe restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	Il driver ha fornito un parametro non valido.
STATUS_INSUFFICIENT_RESOURCES	Il framework non è riuscito ad allocare un oggetto buffer comune oppure il sistema non è riuscito ad allocare un buffer.

Se il driver fornisce un handle di oggetto non valido, si verifica un controllo di bug.

Osservazioni

Il metodo WdfCommonBufferCreateWithConfig alloca memoria ed esegue il mapping in modo che sia il driver che un dispositivo possano accedervi simultaneamente per le operazioni DMA.

Inoltre, WdfCommonBufferCreateWithConfig consente al driver di specificare un requisito di allineamento del buffer per il buffer. Il requisito di allineamento del buffer sostituisce il requisito di allineamento del buffer specificato dal driver quando viene chiamato WdfDeviceSetAlignmentRequirement. Il driver può usare WdfCommonBufferCreateWithConfig, anziché WdfCommonBufferCreate, se si vuole che il driver crei un buffer con un requisito di allineamento diverso da quello specificato WdfDeviceSetAlign mentRequirement.

Dopo che il driver chiama WdfCommonBufferCreateWithConfig, il driver deve:

Chiamare WdfCommonBufferGetAlignedVirtualAddress per ottenere l'indirizzo virtuale del buffer, che il driver può usare.
Chiamare WdfCommonBufferGetAlignedLogicalAddress per ottenere l'indirizzo logico del buffer, che il dispositivo può usare.

Un driver chiama in genere WdfCommonBufferCreateWithConfig dal proprio EvtDriverDeviceAdd funzione di callback.

Il sistema operativo determina se abilitare la memoria memorizzata nella cache nel buffer comune da allocare. Tale decisione si basa sull'architettura del processore e sul bus di dispositivo.

Nei computer con processori basati su x86, x64 e basati su Itanium è abilitata la memoria memorizzata nella cache. Nei computer con processori basati su ARM o ARM 64, il sistema operativo non abilita automaticamente la memoria memorizzata nella cache per tutti i dispositivi. Il sistema si basa sul metodo ACPI_CCA per ogni dispositivo per determinare se il dispositivo è coerente con la cache.

Per altre informazioni sui buffer comuni, vedere Using Common Buffers

Esempi

Nell'esempio di codice seguente viene inizializzata una struttura WDF_COMMON_BUFFER_CONFIG e quindi viene creato un buffer a 10 byte allineato su un limite di 32 byte.

WDF_COMMON_BUFFER_CONFIG  commonBufConfig;
WDFCOMMONBUFFER  commonBuffer;

WDF_COMMON_BUFFER_CONFIG_INIT(
                              &commonBufConfig,
                              FILE_32_BYTE_ALIGNMENT
                              );

status = WdfCommonBufferCreateWithConfig(
                                         DmaEnabler,
                                         10,
                                         &commonBufConfig,
                                         WDF_NO_OBJECT_ATTRIBUTES,
                                         &commonBuffer
                                         );
if (!NT_SUCCESS (status)) {
    return status;
}

Fabbisogno

Requisito	Valore
piattaforma di destinazione	Universale
versione minima di KMDF	1.1
intestazione	wdfcommonbuffer.h (include WdfCommonBuffer.h)
libreria	Wdf01000.sys (vedere Controllo delle versioni della libreria framework).
IRQL	PASSIVE_LEVEL
regole di conformità DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)