Funzione WdfCommonBufferCreate (wdfcommonbuffer.h)

Articolo
02/29/2024

[Si applica solo a KMDF]

Il metodo WdfCommonBufferCreate crea un buffer di memoria a cui il driver e un dispositivo DMA (Direct Memory Access) possono accedere simultaneamente.

Sintassi

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

Parametri

[in] DmaEnabler

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

[in] Length

Dimensioni desiderate, in byte, del nuovo buffer. La dimensione massima consentita del buffer è (MAXULONG - PAGE_SIZE) byte.

[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 a un oggetto buffer comune.

Valore restituito

WdfCommonBufferCreate 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 a allocare un oggetto buffer comune oppure il sistema non è riuscito a allocare un buffer.

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

Commenti

Il metodo WdfCommonBufferCreate alloca la memoria e la esegue il mapping in modo che sia il driver che un dispositivo possa accedervi simultaneamente per le operazioni DMA. Dopo che il driver chiama WdfCommonBufferCreate, 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 WdfCommonBufferCreate dall'interno della sua funzione EvtDriverDeviceAdd callback.

Prima che il driver chiami WdfDmaEnablerCreate, può chiamare WdfDeviceSetAlignmentRequirement per impostare un requisito di allineamento del buffer. Se il driver non chiama WdfDeviceSetAlignmentRequirement, i buffer vengono allineati ai limiti delle parole. Se il driver crea più abilitanti DMA, ognuno con un requisito di allineamento del buffer diverso, il driver può chiamare WdfDeviceSetAlignmentRequirement prima di ogni chiamata a WdfDmaEnablerCreate.

Per creare un buffer comune che ha un requisito di allineamento diverso dal requisito di allineamento specificato dal driver specificato con WdfDeviceSetAlquirementRequirement, il driver può chiamare WdfCommonBufferCreateWithConfig anziché WdfCommonBufferCreate.

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

Nei computer con processori basati su x86, basati su x64 e basati su Itanium, la memoria memorizzata nella cache è abilitata. 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.

L'oggetto enabler DMA che il parametro DmaEnabler di WdfCommonBufferCreate diventa l'oggetto padre per il nuovo oggetto buffer comune. Il driver non può modificare questo elemento padre e il membro ParentObject della struttura WDF_OBJECT_ATTRIBUTES deve essere NULL. Il framework elimina ogni oggetto buffer comune quando elimina l'oggetto abilitante DMA padre. In alternativa, è possibile eliminare in modo esplicito l'oggetto buffer comune chiamando WdfObjectDelete.

Per altre informazioni sui buffer comuni, vedere Uso di buffer comuni.

Esempio

Nell'esempio di codice seguente viene illustrato come ottenere un buffer comune. Nell'esempio vengono archiviate informazioni sul buffer comune nello spazio di contesto definito dal driver identificato dal puntatore DevExt .

DevExt->CommonBufferSize = sizeof(COMMON_BUFFER_STRUCT);  // Your structure size
status = WdfCommonBufferCreate(
                               DevExt->DmaEnabler,
                               DevExt->CommonBufferSize,
                               WDF_NO_OBJECT_ATTRIBUTES,
                               &DevExt->CommonBuffer
                               );
if (status == STATUS_SUCCESS) {
    DevExt->CommonBufferBaseVA = 
        WdfCommonBufferGetAlignedVirtualAddress(DevExt->CommonBuffer);
    DevExt->CommonBufferBaseLA =
        WdfCommonBufferGetAlignedLogicalAddress(DevExt->CommonBuffer); 
}

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1,0
Intestazione	wdfcommonbuffer.h (include WdfCommonBuffer.h)
Libreria	Wdf01000.sys (vedere Framework Library Versioning).
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)