Función MmMapLockedPagesSpecifyCache (wdm.h)

Artículo
03/08/2023

La rutina MmMapLockedPagesSpecifyCache asigna las páginas físicas que describe un MDL a una dirección virtual y permite al autor de la llamada especificar el atributo de caché que se usa para crear la asignación.

Sintaxis

PVOID MmMapLockedPagesSpecifyCache(
  [in]           PMDL                                                                          MemoryDescriptorList,
  [in]           __drv_strictType(KPROCESSOR_MODE / enum _MODE,__drv_typeConst)KPROCESSOR_MODE AccessMode,
  [in]           __drv_strictTypeMatch(__drv_typeCond)MEMORY_CACHING_TYPE                      CacheType,
  [in, optional] PVOID                                                                         RequestedAddress,
  [in]           ULONG                                                                         BugCheckOnFailure,
  [in]           ULONG                                                                         Priority
);

Parámetros

[in] MemoryDescriptorList

Puntero al MDL que se va a asignar. Este MDL debe describir las páginas físicas bloqueadas. Una MDL bloqueada se puede compilar mediante la rutina MmProbeAndLockPages o MmAllocatePagesForMdlEx . Para las asignaciones al espacio de usuario, se pueden usar mdL compiladas por la rutina MmBuildMdlForNonPagedPool .

[in] AccessMode

Especifica el modo de acceso en el que se asigna mdl: KernelMode o UserMode. Casi todos los controladores deben usar KernelMode.

[in] CacheType

Especifica un valor de MEMORY_CACHING_TYPE , que indica el atributo de caché que se va a usar para asignar el MDL. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

[in, optional] RequestedAddress

Si AccessMode UserMode = , este parámetro especifica la dirección virtual del usuario inicial a la que se asigna mdl o se establece en NULL para permitir que el sistema elija la dirección inicial. El sistema puede redondear la dirección solicitada para ajustarse a los requisitos de límite de direcciones, por lo que los autores de las llamadas deben comprobar el valor devuelto.

[in] BugCheckOnFailure

Especifica el comportamiento de la rutina para AccessMode = KernelMode si el MDL no se puede asignar debido a recursos bajos del sistema. Si es TRUE, el sistema emite una comprobación de errores. Si es FALSE, la rutina devuelve NULL. Los controladores deben establecer este parámetro en FALSE.

[in] Priority

Valor MM_PAGE_PRIORITY que indica la importancia del éxito cuando las entradas de la tabla de páginas (PTE) son escasas. A partir de Windows 8, el valor de prioridad especificado puede ser bit a bit-ORed con las marcas MdlMappingNoWrite o MdlMappingNoExecute para especificar la memoria en la que se deshabilitan las escrituras o la ejecución de instrucciones. Para obtener más información sobre los valores posibles de Priority, vea MmGetSystemAddressForMdlSafe.

Valor devuelto

MmMapLockedPagesSpecifyCache devuelve la dirección inicial de las páginas asignadas. Si las páginas no se pueden asignar y BugCheckOnFailure es FALSE, la rutina devuelve NULL.

Comentarios

Use MmUnmapLockedPages para desasignar las páginas físicas asignadas por MmMapLockedPagesSpecifyCache.

Si AccessMode es KernelMode y mmMapLockedPagesSpecifyCache no puede asignar las páginas especificadas, la rutina devuelve NULL (si BugCheckOnFailure = FALSE) o el sistema operativo emite una comprobación de errores (si BugCheckOnFailure = TRUE).

Si AccessMode es UserMode, tenga en cuenta los detalles siguientes:

Si no se pueden asignar las páginas especificadas, la rutina genera una excepción. Los autores de llamadas que especifican UserMode deben encapsular la llamada a MmMapLockedPagesSpecifyCache en un bloque try/except . Para obtener más información, consulte Control de excepciones.
La rutina devuelve una dirección de usuario válida en el contexto del proceso en el que se ejecuta el controlador. Por ejemplo, si un controlador de 64 bits se ejecuta en el contexto de una aplicación de 32 bits, el búfer se asigna a una dirección en el intervalo de direcciones de 32 bits de la aplicación.
Siempre se crea una asignación que no es ejecutable cuando AccessMode es UserMode. Por lo tanto, el uso de la marca MdlMappingNoExecute con el parámetro Priority no es necesario en este escenario. Sin embargo, la marca MdlMappingNoWrite todavía se puede usar con el parámetro Priority en este escenario para solicitar una asignación de solo lectura.
La protección no ejecutable de la asignación y cualquier protección de escritura de la asignación especificada mediante la marca MdlMappingNoWrite con el parámetro Priority no se puede cambiar por código que se ejecuta en modo de usuario. Por ejemplo, si un controlador asigna algunas páginas a un proceso de usuario y especifica la marca MdlMappingNoWrite , el sistema garantiza que el proceso no puede modificar las páginas.

La rutina usa el parámetro CacheType solo si las páginas descritas por MDL aún no tienen un tipo de caché asociado. Sin embargo, en casi todos los casos, las páginas ya tienen un tipo de caché asociado y la nueva asignación usa este tipo de caché. Una excepción a esta regla es para las páginas asignadas por MmAllocatePagesForMdl, que no tienen un tipo de caché específico asociado. Para estas páginas, el parámetro CacheType determina el tipo de caché de la asignación.

Un controlador no debe intentar crear más de una asignación de espacio de direcciones del sistema para un MDL. Además, dado que una MDL compilada por la rutina MmBuildMdlForNonPagedPool ya está asignada al espacio de direcciones del sistema, un controlador no debe intentar volver a asignar este MDL al espacio de direcciones del sistema mediante la rutina MmMapLockedPagesSpecifyCache (aunque se permiten asignaciones de espacio de direcciones de usuario). Si no se sabe si un MDL bloqueado ya tiene una asignación de espacio de direcciones del sistema, un controlador puede usar la macro MmGetSystemAddressForMdlSafe en lugar de MmMapLockedPagesSpecifyCache. Si el MDL ya está asignado al espacio de direcciones del sistema, MmGetSystemAddressForMdlSafe devolverá la asignación existente de espacio de direcciones del sistema en lugar de crear una nueva asignación.

Advertencia

Un controlador que asigna la memoria del kernel al espacio de direcciones del usuario debe evitar exponer datos de kernel potencialmente confidenciales a procesos que no son de confianza. Los búferes no inicializados, como los búferes asignados desde el grupo, deben rellenarse explícitamente con ceros antes de asignarlos. Además, el tamaño de un búfer en modo de usuario asignado desde el grupo debe ser un múltiplo del tamaño de página de memoria virtual para evitar que cualquier parte de las páginas del búfer se use para otras asignaciones. Por último, los búferes no se deben liberar de vuelta al grupo mientras siguen asignados al espacio de direcciones del usuario.

Si AccessMode es UserMode, el autor de la llamada debe ejecutarse en IRQL <= APC_LEVEL. Si AccessMode es KernelMode, el llamador debe ejecutarse en IRQL <= DISPATCH_LEVEL.

Requisitos

Requisito	Value
Plataforma de destino	Universal
Encabezado	wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	vea la sección Comentarios.
Reglas de cumplimiento de DDI	HwStorPortProhibitedDIs(storport)