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

Artículo
02/07/2025

La rutina AllocateAdapterChannelEx asigna los recursos necesarios para realizar una transferencia DMA y, a continuación, llama a la rutina de 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 de 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 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 de 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 DMA. El controlador de 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. Anteriormente, el controlador llamó 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 del adaptador. Se admite la marca siguiente.

Bandera	Significado
DMA_SYNCHRONOUS_CALLBACK	La rutina AllocateAdapterChannelEx se denomina sincrónicamente. Si se establece esta marca y los recursos 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 al controlador proporcionado AdapterControl rutina 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. Después de que se devuelva 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 de DMA_SYNCHRONOUS_CALLBACK, el executionRoutine de es opcional y puede ser null. En este caso, el autor de la llamada puede usar los recursos asignados por AllocateAdapterChannelExy, posteriormente, liberar estos recursos llamando a la rutina freeAdapterObject de. 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 de como parámetro context de.

[out, optional] MapRegisterBase

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

Si se establece la marca DMA_SYNCHRONOUS_CALLBACK, MapRegisterBase debe ser un punteroNULL válido y no NULL. Si el parámetro executionRoutine no esNULL, MapRegisterBase debe ser NULL. Se produce un error en la llamada si MapRegisterBase no esNULL y la marca de DMA_SYNCHRONOUS_CALLBACK no está establecida, 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ámetro no válidos pasados por el autor de la llamada.
STATUS_INSUFFICIENT_RESOURCES	La rutina no pudo asignar recursos necesarios para la transferencia DMA.

Observaciones

AllocateAdapterChannelEx no es una rutina del sistema a la que se puede llamar directamente por nombre. Solo se puede llamar a esta rutina por puntero desde la dirección devuelta en una estructura de DMA_OPERATIONS. 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 su uso por el adaptador DMA, AllocateAdapterChannelEx llama a la rutina de 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 de DMA solicitados no están disponibles inmediatamente, AllocateAdapterChannelEx no espera recursos y no llama a la rutina adapterControl de. En su lugar, se produce un error en la AllocateAdapterChannelEx y devuelve STATUS_INSUFFICIENT_RESOURCES.
El controlador no es necesario para proporcionar una rutina de AdapterControl si se establece la marca DMA_SYNCHRONOUS_CALLBACK.
Si el controlador proporciona una rutina de AdapterControl, la marca DMA_SYNCHRONOUS_CALLBACK indica que se va a llamar a esta rutina en el contexto del subproceso de llamada, antes de que AllocateAdapterChannelEx devuelva.
Si el controlador no proporciona una rutina de AdapterControl, el controlador puede usar los recursos asignados después de AllocateAdapterChannelEx. 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	Valor
cliente mínimo admitido	Disponible a partir de Windows 8.
de la plataforma de destino de	Escritorio
encabezado de	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
irQL	DISPATCH_LEVEL