Funzione WdfCommonBufferCreate (wdfcommonbuffer.h)

[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:

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.

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

Vedi anche

EvtDriverDeviceAdd

WDF_OBJECT_ATTRIBUTES

WdfCommonBufferCreateWithConfig

WdfCommonBufferGetAlignedLogicalAddress

WdfCommonBufferGetAlignedVirtualAddress

WdfDeviceSetAlignmentRequirement

WdfDmaEnablerCreate