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

Artículo
03/08/2023

La rutina AllocateAdapterChannelEx asigna los recursos necesarios para realizar una transferencia DMA y, a continuación, llama a la rutina AdapterControl proporcionada por el controlador para iniciar la transferencia DMA.

Sintaxis

PALLOCATE_ADAPTER_CHANNEL_EX PallocateAdapterChannelEx;

NTSTATUS PallocateAdapterChannelEx(
  [in]            PDMA_ADAPTER DmaAdapter,
  [in]            PDEVICE_OBJECT DeviceObject,
  [in]            PVOID DmaTransferContext,
  [in]            ULONG NumberOfMapRegisters,
  [in]            ULONG Flags,
  [in, optional]  PDRIVER_CONTROL ExecutionRoutine,
  [in, optional]  PVOID ExecutionContext,
  [out, optional] PVOID *MapRegisterBase
)
{...}

Parámetros

[in] DmaAdapter

Puntero a una estructura DMA_ADAPTER . Esta estructura es el objeto de adaptador que representa el dispositivo DMA maestro de bus del controlador o el canal DMA del sistema. El autor de la llamada obtuvo este puntero de una llamada anterior a la rutina IoGetDmaAdapter .

[in] DeviceObject

Puntero a una estructura de DEVICE_OBJECT . Esta estructura es el objeto de dispositivo físico (PDO) que representa el dispositivo de destino para la operación DMA solicitada.

[in] DmaTransferContext

Puntero a un contexto de transferencia de DMA inicializado. Este contexto se inicializó mediante una llamada anterior a la rutina InitializeDmaTransferContext . Este contexto debe ser único en todas las solicitudes de asignación de adaptadores. Para cancelar una solicitud de asignación pendiente, el autor de la llamada debe proporcionar el contexto de transferencia de DMA para la solicitud a la rutina CancelAdapterChannel .

[in] NumberOfMapRegisters

Número de registros de mapa que se van a usar en la transferencia de DMA. El controlador que realiza la llamada debe establecer este valor en 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. El controlador llamó previamente a la rutina GetDmaTransferInfo para obtener el número de registros de mapa necesarios para la transferencia y llamó a la rutina IoGetDmaAdapter para obtener el número de registros de mapa disponibles.

[in] Flags

Marcas de asignación del canal de adaptador. Se admite la marca siguiente.

Marca	Significado
DMA_SYNCHRONOUS_CALLBACK	La rutina AllocateAdapterChannelEx se denomina sincrónicamente. Si se establece esta marca y los recursos de DMA necesarios no están disponibles inmediatamente, se produce un error en la llamada y se devuelve STATUS_INSUFFICIENT_RESOURCES.

Si se establece la marca DMA_SYNCHRONOUS_CALLBACK , el parámetro ExecutionRoutine es opcional y puede ser NULL. Para obtener más información sobre esta marca, vea la sección Comentarios.

[in, optional] ExecutionRoutine

Puntero a la rutina AdapterControl proporcionada por el controlador que inicia la transferencia DMA para el controlador. El administrador de E/S llama a la rutina AdapterControl después de asignar los recursos necesarios para el objeto de adaptador. Una vez que se devuelve la rutina AdapterControl , el administrador de E/S libera automáticamente el objeto de adaptador. El administrador de E/S podría liberar además los recursos asignados para este objeto, en función del valor devuelto por esta rutina.

Si se establece la marca DMA_SYNCHRONOUS_CALLBACK , ExecutionRoutine es opcional y puede ser NULL. En este caso, el autor de la llamada puede usar los recursos asignados por AllocateAdapterChannelEx y, posteriormente, liberar estos recursos llamando a la rutina FreeAdapterObject . Para obtener más información, vea la sección Comentarios.

[in, optional] ExecutionContext

Contexto de control de adaptador determinado por el controlador. Este contexto se pasa a la rutina AdapterControl como parámetro Context .

[out, optional] MapRegisterBase

Puntero a una variable en la que la rutina escribe un identificador en los registros de mapa asignados. El llamador puede proporcionar este identificador como parámetro a la rutina FlushAdapterBuffersEx, FlushAdapterBuffers, FreeMapRegisters o MapTransferEx .

Si se establece la marca DMA_SYNCHRONOUS_CALLBACK , MapRegisterBase debe ser un puntero válido que no sea NULL . Si el parámetro ExecutionRoutine no es NULL, MapRegisterBase debe ser NULL. Se produce un error en la llamada si MapRegisterBase no es NULL y no se establece la marca DMA_SYNCHRONOUS_CALLBACK , o si MapRegisterBase y ExecutionRoutine son NULL.

Valor devuelto

AllocateAdapterChannelEx devuelve STATUS_SUCCESS si la llamada se realiza correctamente. Entre los posibles valores devueltos de error se incluyen los siguientes códigos de estado.

Código devuelto	Descripción
STATUS_INVALID_PARAMETERS	Error en la rutina debido a valores de parámetros no válidos pasados por el autor de la llamada.
STATUS_INSUFFICIENT_RESOURCES	La rutina no pudo asignar los recursos necesarios para la transferencia de DMA.

Comentarios

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

AllocateAdapterChannelEx asigna los recursos necesarios para realizar una operación DMA. Estos recursos incluyen canales DMA y registros de mapa. Una vez asignados todos los recursos necesarios para que los use el adaptador DMA, AllocateAdapterChannelEx llama a la rutina AdapterControl proporcionada por el autor de la llamada para iniciar la operación DMA.

De forma predeterminada, AllocateAdapterChannelEx devuelve de forma asincrónica, sin esperar a que se complete la asignación de recursos solicitada. Después de esta devolución, el autor de la llamada puede, si es necesario, cancelar la solicitud de asignación pendiente llamando a la rutina CancelAdapterChannel .

Si el controlador de llamada establece la marca DMA_SYNCHRONOUS_CALLBACK , la rutina AllocateAdapterChannelEx se comporta de la siguiente manera:

Si los recursos DMA solicitados no están disponibles inmediatamente, AllocateAdapterChannelEx no espera recursos y no llama a la rutina AdapterControl . En su lugar, AllocateAdapterChannelEx produce un error y devuelve STATUS_INSUFFICIENT_RESOURCES.
El controlador no es necesario para proporcionar una rutina AdapterControl si se establece la marca DMA_SYNCHRONOUS_CALLBACK .
Si el controlador proporciona una rutina AdapterControl , la marca DMA_SYNCHRONOUS_CALLBACK indica que se llamará a esta rutina en el contexto del subproceso que realiza la llamada, antes de que Se devuelva AllocateAdapterChannelEx .
Si el controlador no proporciona una rutina AdapterControl , el controlador puede usar los recursos asignados después de que AllocateAdapterChannelEx devuelva. En este caso, el controlador debe llamar a FreeAdapterObject después de que termine de usar los recursos asignados.

AllocateAdapterChannelEx es una versión extendida de la rutina AllocateAdapterChannel . Las siguientes características solo están disponibles en la versión extendida:

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible a partir de Windows 8.
Plataforma de destino	Escritorio
Encabezado	wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
IRQL	DISPATCH_LEVEL