PALLOCATE_COMMON_BUFFER_EX función de devolución de llamada (wdm.h)
La rutina AllocateCommonBufferEx asigna memoria para un búfer común y asigna esta memoria para que el procesador pueda tener acceso a ella y a un dispositivo que realiza operaciones DMA.
Sintaxis
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
)
{...}
Parámetros
[in] DmaAdapter
Puntero a una estructura DMA_ADAPTER . Esta estructura es el objeto de adaptador que representa el dispositivo DMA maestro de bus del controlador o el canal DMA del sistema. El autor de la llamada obtuvo este puntero de una llamada anterior a la rutina IoGetDmaAdapter .
[in, optional] MaximumAddress
Puntero a una variable que contiene la dirección lógica máxima para el búfer común. Este parámetro indica que el búfer debe asignarse desde la memoria debajo de esta dirección. Este parámetro es opcional y se puede especificar como NULL para indicar que no hay ninguna dirección máxima.
[in] Length
Tamaño, en bytes, del búfer común que se va a asignar para la operación DMA.
[out] LogicalAddress
Puntero a una variable en la que esta rutina escribe la dirección lógica que el dispositivo puede usar para acceder al búfer común. El dispositivo DMA debe usar esta dirección lógica en lugar de la dirección física que devuelve una rutina como MmGetPhysicalAddress.
[in] CacheEnabled
Si la rutina debe habilitar o deshabilitar la memoria almacenada en caché en el búfer común que se va a asignar. Si es TRUE, el almacenamiento en caché está habilitado. Si es FALSE, está deshabilitado. Si la plataforma de hardware no aplica la coherencia de caché para las operaciones DMA, pase FALSE. Para obtener información sobre este parámetro en equipos de destino de procesadores basados en ARM o ARM 64, vea Comentarios.
[in] PreferredNode
Nodo NUMA preferido desde el que se asignará la memoria. Si N es el número de nodos NUMA en un sistema multiprocesador, PreferredNode es un número del intervalo entre 0 y N-1. Para un sistema de un procesador o un sistema multiprocesador que no sea NUMA, establezca PreferredNode en cero.
Valor devuelto
AllocateCommonBufferEx devuelve la dirección virtual de la memoria asignada para el búfer común. Si no se puede asignar el búfer, se devuelve NULL.
Comentarios
AllocateCommonBufferEx no es una rutina del sistema a la que se puede llamar directamente por nombre. Solo el puntero de la dirección devuelta en una estructura de DMA_OPERATIONS puede llamar a esta rutina. Los controladores obtienen la dirección de esta rutina llamando a IoGetDmaAdapter con el miembro Version del parámetro DeviceDescription establecido en DEVICE_DESCRIPTION_VERSION3. Si IoGetDmaAdapter devuelve NULL, la rutina no está disponible en la plataforma.
AllocateCommonBufferEx es una versión extendida de la rutina AllocateCommonBuffer . En la lista siguiente se resumen las características que solo están disponibles en la versión extendida:
El autor de la llamada puede especificar una dirección lógica máxima para el búfer común que se va a asignar.
El llamador puede especificar un nodo NUMA preferido en el que se asignará el búfer común.
En equipos con procesadores basados en ARM o ARM 64, la configuración de caché en el ACPI del sistema tiene una prioridad mayor que el valor del parámetro CacheEnabled pasado por el controlador. Si el método de _CCA ACPI indica que el dispositivo no es coherente con la memoria caché, el sistema operativo deshabilita el almacenamiento en caché aunque el controlador asigne memoria almacenada en caché con CacheEnabled establecido en TRUE.
En equipos con procesadores basados en ARM o ARM 64, el sistema operativo asigna un búfer común sin almacenar en caché como memoria del dispositivo. Para obtener más información sobre el búfer, consulte las secciones A3.5.1 y A3.5.6 del Manual de referencia de arquitectura de ARMv7.
El procesador no permite el acceso desalineado a la memoria del dispositivo. El controlador siempre debe acceder a los datos desde el búfer común mediante operaciones alineadas de forma natural. La mayoría de las rutinas de kernel no aceptan memoria del dispositivo como parámetros de entrada. Por ejemplo, un controlador de red no puede pasar memoria del dispositivo a NdisMIndicateReceiveNetBufferLists. Si el controlador necesita pasar datos de un búfer común de DMA a una rutina de kernel, asigne el búfer con CacheEnabled establecido en TRUE o copie los datos del búfer común sin almacenar en caché en una asignación de grupo temporal.
Para obtener más información sobre las operaciones de DMA que usan un búfer común, consulte los temas siguientes:
Uso de Common-Buffer Bus-Master DMA
Uso de DMA del sistema de Common-Buffer
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Disponible a partir de Windows 8. |
| Plataforma de destino | Escritorio |
| Encabezado | wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h) |
| IRQL | PASSIVE_LEVEL |