PALLOCATE_COMMON_BUFFER_EX funzione di callback (wdm.h)

Articolo
03/18/2023

La routine AllocateCommonBufferEx alloca la memoria per un buffer comune e esegue il mapping di questa memoria in modo che possa essere accessibile sia dal processore che da un dispositivo che esegue operazioni DMA.

Sintassi

PALLOCATE_COMMON_BUFFER_EX PallocateCommonBufferEx;

PVOID PallocateCommonBufferEx(
  [in]           PDMA_ADAPTER DmaAdapter,
  [in, optional] PPHYSICAL_ADDRESS MaximumAddress,
  [in]           ULONG Length,
  [out]          PPHYSICAL_ADDRESS LogicalAddress,
  [in]           BOOLEAN CacheEnabled,
  [in]           NODE_REQUIREMENT PreferredNode
)
{...}

Parametri

[in] DmaAdapter

Puntatore a una struttura DMA_ADAPTER . Questa struttura è l'oggetto adapter che rappresenta il dispositivo DMA master del driver o il canale DMA del sistema. Il chiamante ha ottenuto questo puntatore da una chiamata precedente alla routine IoGetDmaAdapter .

[in, optional] MaximumAddress

Puntatore a una variabile contenente l'indirizzo logico massimo per il buffer comune. Questo parametro indica che il buffer deve essere allocato dalla memoria seguente. Questo parametro è facoltativo e può essere specificato come NULL per indicare che non esiste alcun indirizzo massimo.

[in] Length

Dimensioni, in byte, del buffer comune da allocare per l'operazione DMA.

[out] LogicalAddress

Puntatore a una variabile in cui questa routine scrive l'indirizzo logico che il dispositivo può usare per accedere al buffer comune. Il dispositivo DMA deve usare questo indirizzo logico anziché l'indirizzo fisico restituito da una routine come MmGetPhysicalAddress.

[in] CacheEnabled

Se la routine deve abilitare o disabilitare la memoria memorizzata nella cache nel buffer comune da allocare. Se TRUE, la memorizzazione nella cache è abilitata. Se FALSE, è disabilitato. Se la piattaforma hardware non applica la coherency cache per le operazioni DMA, passare FALSE. Per informazioni su questo parametro sui processori basati su ARM o ARM 64, vedere Osservazioni.

[in] PreferredNode

Nodo NUMA preferito da cui deve essere allocata la memoria. Se N è il numero di nodi NUMA in un sistema multiprocessore, PreferredNode è un numero nell'intervallo da 0 a N-1. Per un sistema a un processore o un sistema multiprocessore non NUMA, impostare PreferredNode su zero.

Valore restituito

AllocateCommonBufferEx restituisce l'indirizzo virtuale della memoria allocata per il buffer comune. Se non è possibile allocare il buffer, viene restituito NULL.

Commenti

AllocateCommonBufferEx non è una routine di sistema che può essere chiamata direttamente per nome. Questa routine può essere chiamata solo dal puntatore dall'indirizzo restituito in una struttura DMA_OPERATIONS . I driver ottengono l'indirizzo di questa routine chiamando IoGetDmaAdapter con il membro Version del parametro DeviceDescription impostato su DEVICE_DESCRIPTION_VERSION3. Se IoGetDmaAdapter restituisce NULL, la routine non è disponibile nella piattaforma.

AllocateCommonBufferEx è una versione estesa della routine AllocateCommonBuffer . L'elenco seguente riepiloga le funzionalità disponibili solo nella versione estesa:

Il chiamante può specificare un indirizzo logico massimo per il buffer comune allocato.
Il chiamante può specificare un nodo NUMA preferito in cui deve essere allocato il buffer comune.

Nei computer con processori basati su ARM o ARM 64, le impostazioni della cache nel sistema ACPI hanno una precedenza maggiore rispetto al valore del parametro CacheEnabled passato dal driver. Se il metodo ACPI _CCA indica che il dispositivo non è coerente nella cache, il sistema operativo disabilita la memorizzazione nella cache anche se il driver alloca la memoria memorizzata nella cache con CacheEnabled impostata su TRUE.

Nei computer con processori basati su ARM o ARM 64, il sistema operativo alloca un buffer comune non memorizzato come Memoria dispositivo. Per altre informazioni sul buffer, vedere sezioni A3.5.1 e A3.5.6 dal manuale di riferimento sull'architettura ARMv7.

Il processore non consente l'accesso non allineato alla memoria del dispositivo. Il driver deve sempre accedere ai dati dal buffer comune usando operazioni allineate naturalmente. La maggior parte delle routine del kernel non accetta memoria del dispositivo come parametri di input. Ad esempio, un driver di rete non può passare memoria dispositivo in NdisMIndicateReceiveNetBufferLists. Se il driver deve passare dati da un buffer comune DMA a una routine del kernel, allocare il buffer con CacheEnabled impostato su TRUE o copiare i dati dal buffer comune non crittografato in un'allocazione temporanea del pool.

Per altre informazioni sulle operazioni DMA che usano un buffer comune, vedere gli argomenti seguenti:

Uso di buffer comuni

Uso di Common-Buffer Bus-Master DMA

Uso di Common-Buffer System DMA

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile a partire da Windows 8.
Piattaforma di destinazione	Desktop
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	PASSIVE_LEVEL

Vedi anche