PALLOCATE_COMMON_BUFFER función de devolución de llamada (wdm.h)

  • Artículo

La rutina AllocateCommonBuffer asigna memoria y la asigna para que sea accesible simultáneamente desde el procesador y un dispositivo para las operaciones DMA.

Sintaxis

PALLOCATE_COMMON_BUFFER PallocateCommonBuffer;

PVOID PallocateCommonBuffer(
  [in]  PDMA_ADAPTER DmaAdapter,
  [in]  ULONG Length,
  [out] PPHYSICAL_ADDRESS LogicalAddress,
  [in]  BOOLEAN CacheEnabled
)
{...}

Parámetros

[in] DmaAdapter

Puntero a la estructura DMA_ADAPTER devuelta por IoGetDmaAdapter que representa el adaptador de bus-master o el controlador DMA.

[in] Length

Especifica el número de bytes de memoria que se van a asignar.

[out] LogicalAddress

Puntero a una variable que recibe la dirección lógica que el dispositivo puede usar para acceder al búfer asignado. Use esta dirección en lugar de llamar a MmGetPhysicalAddress porque el sistema puede tener en cuenta cualquier restricción de memoria específica de la plataforma.

[in] CacheEnabled

Especifica si la memoria asignada se puede almacenar en caché.

Este parámetro se ignora. El sistema operativo determina si se va a habilitar la memoria almacenada en caché en el búfer común que se va a asignar. Esa decisión se basa en la arquitectura del procesador y el bus de dispositivo.

En equipos con procesadores basados en x86, basados en x64 y basados en Itanium, se habilita la memoria almacenada en caché. Se supone que todas las operaciones de DMA realizadas por un dispositivo son coherentes con las memorias caché de CPU pertinentes, lo que podría estar almacenando en caché esa memoria. Si el controlador necesita deshabilitar el almacenamiento en caché, llame a AllocateCommonBufferEx en su lugar.

En equipos con procesadores basados en ARM o ARM 64, el sistema operativo no habilita automáticamente la memoria almacenada en caché para todos los dispositivos. El sistema se basa en el método ACPI_CCA para cada dispositivo para determinar si el dispositivo es coherente con la memoria caché.

Valor devuelto

AllocateCommonBuffer devuelve la dirección virtual base del intervalo asignado. Si no se puede asignar el búfer, devuelve NULL.

Comentarios

AllocateCommonBuffer no es una rutina del sistema a la que se puede llamar directamente por nombre. Esta rutina solo es invocable por puntero de la dirección devuelta en una estructura de DMA_OPERATIONS . Los controladores obtienen la dirección de esta rutina mediante una llamada a IoGetDmaAdapter.

AllocateCommonBuffer admite DMA en el que el dispositivo y el procesador se comunican continuamente a través de la memoria del sistema, como en una estructura de control para un dispositivo DMA maestro de bus.

AllocateCommonBuffer también admite dispositivos subordinados cuyos controladores usan el modo de inicialización automática de un controlador DMA del sistema.

AllocateCommonBuffer hace lo siguiente:

  • Asigna memoria que se puede acceder desde el procesador y el dispositivo. Esta memoria aparece contigua al dispositivo.
  • Asigna registros de mapa para asignar el búfer, si es necesario por el sistema.
  • Configura una traducción para el dispositivo, incluida la carga de registros de mapa si es necesario.
Para usar la memoria del sistema residente económicamente, los controladores deben asignar tan pocos de estos búferes por dispositivo como sea posible. AllocateCommonBuffer asigna al menos una página de memoria, independientemente de la longitud solicitada. Después de una asignación correcta que solicita menos de PAGE_SIZE bytes, el autor de la llamada solo puede tener acceso a la longitud solicitada. Después de una asignación correcta que solicita más de un múltiplo entero de PAGE_SIZE bytes, los bytes restantes de la última página asignada no son accesibles para el autor de la llamada.

Si un controlador necesita varias páginas de espacio de búfer común, pero las páginas no necesitan ser contiguas, el controlador debe realizar varias solicitudes de una página a AllocateCommonBuffer en lugar de una solicitud grande. Este enfoque conserva la memoria contigua.

Los controladores suelen llamar a AllocateCommonBuffer como parte del inicio del dispositivo, durante su respuesta a una solicitud de IRP_MN_START_DEVICE PnP. Después del inicio, es posible que solo las solicitudes de una página se realicen correctamente, si las hay.

Requisitos

Requisito Value
Cliente mínimo compatible Disponible a partir de Windows 2000.
Plataforma de destino Escritorio
Encabezado wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
IRQL PASSIVE_LEVEL
Reglas de cumplimiento de DDI IrqlDispatch(wdm)

Consulte también

DMA_ADAPTER

DMA_OPERATIONS

FreeCommonBuffer

IoGetDmaAdapter