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

Artículo
08/08/2023

La rutina CreateCommonBufferFromMdl intentará crear un búfer común a partir de una MDL probando la compatibilidad del acceso al dispositivo y asignando potencialmente la memoria a un intervalo lógico contiguo en función del tipo de traducción. Al igual que todas las demás funciones comunes de asignación de búferes, esta función no proporciona una garantía de progreso hacia delante.

Sintaxis

PCREATE_COMMON_BUFFER_FROM_MDL PcreateCommonBufferFromMdl;

NTSTATUS PcreateCommonBufferFromMdl(
  [in]  PDMA_ADAPTER DmaAdapter,
  [in]  PMDL Mdl,
  [in]  PDMA_COMMON_BUFFER_EXTENDED_CONFIGURATION ExtendedConfigs,
  [in]  ULONG ExtendedConfigsCount,
  [out] PPHYSICAL_ADDRESS LogicalAddress
)
{...}

Parámetros

[in] DmaAdapter

Proporciona un puntero al adaptador DMA que realiza la operación.

[in] Mdl

Proporciona la MDL que se asignará a un búfer común.

Para que una MDL pueda realizar una copia de seguridad de un búfer común, se deben cumplir las siguientes condiciones:

El MDL debe tener páginas que siempre residen durante la vigencia del búfer común y que se asignan al espacio de direcciones del sistema. Esto se puede lograr mediante los siguientes enfoques:
MdL se crea a partir de un búfer en el grupo no paginado a través de MmBuildMdlForNonPagedPool.
MdL se ha bloqueado a través de MmProbeAndLockPages y se ha asignado al espacio del sistema a través de MmGetSystemAddressForMdlSafe.
Las páginas físicas de MDL se han asignado a través de MmAllocatePagesForMdlEx y se han asignado al espacio del sistema a través de MmGetSystemAddressForMdlSafe.
MdL debe representar una región alineada con páginas y ser un múltiplo de PAGE_SIZE.
- Si se usa la configuración extendida de subsección, la parte del MDL que se usa debe estar alineada con páginas y ser un múltiplo de PAGE_SIZE.
MdL no debe ser una MDL encadenada.
- Si se usa la configuración extendida de subsección, se puede proporcionar una MDL encadenada, pero la parte del MDL que se usa debe estar contenida en una sola MDL de la cadena.
Si no se usa la reasignación de DMA, MDL debe representar memoria físicamente contigua y ser accesible para el dispositivo.

[in] ExtendedConfigs

Proporciona una matriz opcional de estructuras de DMA_COMMON_BUFFER_EXTENDED_CONFIGURATION para configurar aún más la creación del búfer común respaldado por MDL.

Si se proporcionan varias configuraciones de la misma DMA_COMMON_BUFFER_EXTENDED_CONFIGURATION_TYPE en la matriz, se producirá un error en la creación.

[in] ExtendedConfigsCount

Proporciona el número de configuraciones extendidas en la matriz ExtendedConfigs .

[out] LogicalAddress

Si se ejecuta correctamente, se proporciona la dirección lógica del búfer común resultante.

Valor devuelto

CreateCommonBufferFromMdl devuelve STATUS_SUCCESS si la llamada es correcta. Entre los posibles valores devueltos de error se incluyen los siguientes códigos de estado.

Código devuelto	Descripción
STATUS_INVALID_PARAMETER	El autor de la llamada ha proporcionado una configuración MDL o extendida incompatible.
STATUS_NOT_SUPPORTED	El autor de la llamada ha proporcionado una configuración extendida que no se admite en el sistema actual.
STATUS_INSUFFICIENT_RESOURCES	El sistema no tiene suficiente memoria para crear metadatos de asignación y mantenimiento de libros.

Comentarios

CreateCommonBufferFromMdl no es una rutina del sistema a la que se puede llamar directamente por su 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.

Se quitará un búfer común creado por CreateCommonBufferFromMdl a través de FreeCommonBuffer. El autor de la llamada debe proporcionar la dirección virtual del sistema como dirección virtual para asegurarse de que el búfer común se quita correctamente de las estructuras comunes de contabilidad del búfer del adaptador. El controlador sigue siendo responsable de desbloquear y liberar la MDL y sus páginas auxiliares.

Para crear un búfer común donde HAL es responsable de mantener la memoria de respaldo, use AllocateCommonBufferWithBounds.