Función WdfMemoryCreate (wdfmemory.h)

Artículo
02/29/2024

[Se aplica a KMDF y UMDF]

El método WdfMemoryCreate crea un objeto de memoria de marco y asigna un búfer de memoria de un tamaño especificado.

Sintaxis

NTSTATUS WdfMemoryCreate(
  [in, optional]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [in]            POOL_TYPE              PoolType,
  [in, optional]  ULONG                  PoolTag,
  [in]            size_t                 BufferSize,
  [out]           WDFMEMORY              *Memory,
  [out, optional] PVOID                  *Buffer
);

Parámetros

[in, optional] Attributes

Puntero a una estructura WDF_OBJECT_ATTRIBUTES que contiene atributos de objeto para el nuevo objeto de memoria. Este parámetro es opcional y puede ser WDF_NO_OBJECT_ATTRIBUTES.

[in] PoolType

Valor de tipo POOL_TYPE que especifica el tipo de memoria que se va a asignar.

[in, optional] PoolTag

Etiqueta de grupo definida por el controlador para la memoria asignada. Los depuradores muestran esta etiqueta. Normalmente, los controladores especifican una cadena de caracteres de hasta cuatro caracteres, delimitadas por comillas simples, en orden inverso (por ejemplo, "dcba"). El valor ASCII de cada carácter de la etiqueta debe estar comprendido entre 0 y 127. La depuración del controlador es más fácil si cada etiqueta de grupo es única.

Si PoolTag es cero, el marco proporciona una etiqueta de grupo predeterminada que usa los cuatro primeros caracteres del nombre del servicio en modo kernel del controlador. Si el nombre del servicio comienza por "WDF" (el nombre no distingue mayúsculas de minúsculas y no incluye las comillas), se usan los cuatro caracteres siguientes. Si hay menos de cuatro caracteres disponibles, se usa "FxDr".

Para las versiones 1.5 y posteriores de KMDF, el controlador puede usar el miembro DriverPoolTag de la estructura de WDF_DRIVER_CONFIG para especificar una etiqueta de grupo predeterminada.

[in] BufferSize

Tamaño distinto de cero especificado, en bytes, del búfer.

[out] Memory

Puntero a una ubicación que recibe un identificador para el nuevo objeto de memoria.

[out, optional] Buffer

Puntero a una ubicación que recibe un puntero al búfer asociado al nuevo objeto de memoria. Este parámetro es opcional y puede ser NULL.

Valor devuelto

WdfMemoryCreate devuelve STATUS_SUCCESS si la operación se realiza correctamente. De lo contrario, este método podría devolver uno de los siguientes valores:

Código devuelto	Descripción
STATUS_INVALID_PARAMETER	Se ha detectado un parámetro no válido.
STATUS_INSUFFICIENT_RESOURCES	No había memoria suficiente.

Para obtener una lista de otros valores devueltos que puede devolver el método WdfMemoryCreate , vea Errores de creación de objetos de marco.

Este método también podría devolver otros valores NTSTATUS.

Comentarios

El método WdfMemoryCreate asigna un búfer del tamaño que el parámetro BufferSize especifica y crea un objeto de memoria de marco que representa el búfer.

Para obtener la dirección del búfer, el controlador puede proporcionar un valor distinto de NULL para el parámetro Buffer de la función WdfMemoryCreate o el controlador puede llamar a WdfMemoryGetBuffer.

Es recomendable que no haya memoria para la asignación de memoria, especialmente para las asignaciones que se copiarán en una ubicación que no es de confianza (modo de usuario, a través de la red, etc.) para evitar la divulgación de información confidencial. WdfMemoryCreate no inicializa la memoria asignada de forma predeterminada.

Según el patrón de uso del controlador de la memoria asignada, se debe tener en cuenta la recomendación para los escritores de controladores:

RtlZeroMemory inmediatamente después de llamar a WdfMemoryCreate
O bien, use una API de asignación cero (ExAllocatePool2, ExAllocatePoolZero para el modo kernel; HeapAlloc con la marca HEAP_ZERO_MEMORY para el modo de usuario), seguida de WdfMemoryCreatePreallocated. Dado que el búfer asignado previamente no se elimina automáticamente como parte de WDFMEMORY o su eliminación primaria, este no es el mejor enfoque.

El objeto primario predeterminado para cada objeto de memoria es el objeto de controlador de marco que representa el controlador que llamó a WdfMemoryCreate. Si el controlador crea un objeto de memoria que usa con un objeto de dispositivo específico, un objeto de solicitud u otro objeto de marco, debe establecer correctamente el elemento primario del objeto de memoria. El objeto de memoria y su búfer se eliminarán cuando se elimine el objeto primario. Si no cambia el objeto primario predeterminado, el objeto de memoria y su búfer permanecerán hasta que el administrador de E/S descargue el controlador.

Un controlador también puede eliminar un objeto de memoria y su búfer llamando a WdfObjectDelete.

Si BufferSize es menor que PAGE_SIZE, el sistema operativo proporciona al autor de la llamada exactamente el número de bytes de memoria solicitados. El búfer no está necesariamente alineado con páginas, pero está alineado por el número de bytes que la constante MEMORY_ALLOCATION_ALIGNMENT especifica en Ntdef.h.

Si BufferSize es PAGE_SIZE o superior, para KMDF solo el sistema asigna un búfer alineado con páginas. Si el parámetro PoolType es NonPagedPool, el sistema asigna el número de páginas necesarias para contener todos los bytes. Los bytes sin usar de la última página asignada se desperdician básicamente.

Para obtener más información sobre los objetos de memoria del marco, vea Uso de búferes de memoria.

Si el controlador especifica PagedPool para PoolType, se debe llamar al método WdfMemoryCreate en IRQL <= APC_LEVEL. De lo contrario, se puede llamar al método en IRQL <= DISPATCH_LEVEL.

Ejemplos

En el ejemplo de código siguiente se crea un objeto de memoria de marco y se asigna un búfer cuyo tamaño es WRITE_BUFFER_SIZE. El elemento primario del objeto de memoria es un objeto de solicitud.

NTSTATUS  status;
WDF_OBJECT_ATTRIBUTES  attributes;
WDFMEMORY  writeBufferMemHandle;
PVOID  writeBufferPointer;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = requestHandle;
status = WdfMemoryCreate(
                         &attributes,
                         NonPagedPool,
                         0,
                         WRITE_BUFFER_SIZE,
                         &writeBufferMemHandle,
                         &writeBufferPointer
                         );

Requisitos

Requisito	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.0
Versión mínima de UMDF	2.0
Encabezado	wdfmemory.h (incluir Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	vea la sección Comentarios.
Reglas de cumplimiento de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), ParentObjectCheck(kmdf)