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 acceder a ella y a un dispositivo que realice 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 del 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 devuelta por 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 va a 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 solo procesador o un sistema de varios procesadores 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.
Observaciones
AllocateCommonBufferEx no es una rutina del sistema a la que se puede llamar directamente por nombre. Este puntero solo puede llamar a esta rutina desde la dirección devuelta en una estructura de DMA_OPERATIONS. 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 autor de la llamada 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 más alta que el valor de 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é incluso si el controlador asigna 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 de .
El procesador no permite el acceso desalineado a la memoria del dispositivo. El controlador siempre debe acceder a los datos del búfer común mediante operaciones alineadas de forma natural. La mayoría de las rutinas de kernel no aceptan memoria de dispositivo como parámetros de entrada. Por ejemplo, un controlador de red no puede pasar memoria de 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
usar DMA del sistema Common-Buffer
Requisitos
| Requisito | Valor |
|---|---|
| cliente mínimo admitido | Disponible a partir de Windows 8. |
| de la plataforma de destino de | Escritorio |
| encabezado de | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| irQL | PASSIVE_LEVEL |