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

Artículo
02/27/2024

La rutina AllocateAdapterChannel prepara el sistema para una operación DMA en nombre del objeto de dispositivo de destino y, a continuación, llama a la rutina AdapterControl proporcionada por el controlador para llevar a cabo la operación DMA.

Sintaxis

PALLOCATE_ADAPTER_CHANNEL PallocateAdapterChannel;

NTSTATUS PallocateAdapterChannel(
  [in] PDMA_ADAPTER DmaAdapter,
  [in] PDEVICE_OBJECT DeviceObject,
  [in] ULONG NumberOfMapRegisters,
  [in] PDRIVER_CONTROL ExecutionRoutine,
  [in] PVOID Context
)
{...}

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] DeviceObject

Puntero al objeto de dispositivo que representa el dispositivo de destino para una operación DMA solicitada.

[in] NumberOfMapRegisters

Especifica el número de registros de mapa que se van a usar en la transferencia. Este valor es el menor del número de registros de mapa necesarios para satisfacer la solicitud de transferencia actual y el número de registros de mapa disponibles devueltos por IoGetDmaAdapter.

[in] ExecutionRoutine

Puntero a una rutina AdapterControl proporcionada por el controlador. Se llama a la rutina cuando el controlador DMA del sistema o el adaptador de bus-master están disponibles.

[in] Context

Puntero al contexto determinado por el controlador que se va a pasar a la rutina AdapterControl .

Valor devuelto

Esta rutina puede devolver uno de los siguientes valores NTSTATUS.

Código devuelto	Descripción
STATUS_SUCCESS	Se ha asignado el canal de adaptador. El sistema llamará a la rutina AdapterControl una vez que se pueda iniciar la operación DMA.
STATUS_INSUFFICIENT_RESOURCES	NumberOfMapRegisters es mayor que el valor devuelto por IoGetDmaAdapter. No se llamará a la rutina AdapterControl .

Comentarios

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

Un controlador llama a la rutina AllocateAdapterControl para registrar una rutina AdapterControl que realiza una operación DMA para el controlador. La rutina AdapterControl lleva a cabo una operación DMA mediante el controlador DMA del sistema o un adaptador de bus-master.

Si la operación DMA se puede realizar inmediatamente, el sistema llama inmediatamente a AdapterControl. Si el controlador DMA del sistema o el adaptador de bus-master está actualmente en uso, AllocateAdapterChannel pone en cola AdapterControl hasta que el adaptador esté disponible. En cualquier caso, AllocateAdapterChannel devuelve STATUS_SUCCESS.

Si el sistema carece de los recursos para realizar la operación DMA, AllocateAdapterChannel devuelve STATUS_INSUFFICIENT_RESOURCES. En ese caso, AdapterControl no está en cola y el controlador debe completar el IRP actual con el código de error adecuado (como STATUS_INSUFFICIENT_RESOURCES).

Esta rutina reserva acceso exclusivo a un canal de controlador DMA y registra los registros de asignación para las operaciones de DMA necesarias para satisfacer la solicitud de transferencia del IRP actual para el dispositivo especificado.

Solo se puede poner en cola una solicitud DMA para un objeto de dispositivo en cualquier momento. Por lo tanto, el controlador no debe llamar de nuevo a AllocateAdapterChannel para otra operación DMA en el mismo objeto de dispositivo hasta que la rutina AdapterControl haya completado la ejecución. Además, un controlador no debe llamar a AllocateAdapterChannel desde su rutina AdapterControl .

El sistema pasa el valor del miembro CurrentIrp de DeviceObject como parámetro Irp de AdapterControl. Si se llama a AllocateAdapterChannel desde la rutina StartIo de un controlador, se garantiza que apunte al IRP al que se llamó a StartIo para procesar. De lo contrario, para usar el parámetro Irp de AdapterControl, el controlador debe establecer CurrentIrp para que apunte al IRP actual antes de llamar a AllocateAdapterChannel.

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	DISPATCH_LEVEL
Reglas de cumplimiento de DDI	IrqlDispatch(storport), IrqlDispatch(storport), IrqlDispatch(wdm)