PMAP_TRANSFER_EX función de devolución de llamada (wdm.h)
La rutina MapTransferEx configura los registros de mapa para asignar las direcciones físicas de una lista de dispersión y recopilación a las direcciones lógicas necesarias para realizar una transferencia DMA.
Sintaxis
PMAP_TRANSFER_EX PmapTransferEx;
NTSTATUS PmapTransferEx(
[in] PDMA_ADAPTER DmaAdapter,
[in] PMDL Mdl,
[in] PVOID MapRegisterBase,
[in] ULONGLONG Offset,
[in] ULONG DeviceOffset,
[in, out] PULONG Length,
[in] BOOLEAN WriteToDevice,
[out, optional] PSCATTER_GATHER_LIST ScatterGatherBuffer,
[in] ULONG ScatterGatherBufferLength,
[in, optional] PDMA_COMPLETION_ROUTINE DmaCompletionRoutine,
[in, optional] PVOID CompletionContext
)
{...}
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] Mdl
Puntero a una cadena MDL que describe el diseño de página físico de una colección de búferes bloqueados en memoria virtual. La lista de dispersión y recopilación de la transferencia de DMA usará la región de esta memoria especificada por los parámetros Offset y Length . Para obtener más información sobre las cadenas MDL, consulte Uso de MDL.
[in] MapRegisterBase
Identificador de los registros de mapa asignados para el objeto de adaptador. El autor de la llamada obtuvo previamente este identificador de la rutina AllocateAdapterChannelEx .
[in] Offset
Desplazamiento de bytes desde el principio de la memoria descrita por la cadena MDL. Este desplazamiento especifica el inicio del búfer de datos de E/S que se usa para la transferencia de DMA. Si se proporciona una lista de dispersión y recopilación al autor de la llamada, este desplazamiento determina la dirección inicial del primer fragmento de búfer de la lista. Si las MDL de la cadena MDL describen un total de N bytes de memoria, los valores válidos de Offset se encuentran en el intervalo de 0 a N-1. Para obtener más información, vea la sección Comentarios.
[in] DeviceOffset
Desplazamiento de bytes del registro de datos del dispositivo de destino o FIFO desde la dirección base del dispositivo. Este parámetro se aplica a los dispositivos que tienen varios FIFOs a los que puede acceder un controlador DMA del sistema. Este parámetro solo se usa para las transferencias DMA del sistema. En el caso de las transferencias de bus-master, establezca este parámetro en cero.
[in, out] Length
Puntero a una variable que contiene la longitud, en bytes, del búfer de datos de E/S que se usa para la transferencia DMA. En la entrada, esta variable contiene la longitud solicitada por el controlador que realiza la llamada. Antes de devolver, la rutina escribe la longitud real del búfer asignado en esta variable. El valor de *Length en la devolución de MapTransferEx indica cuántos bytes se asignaron. Si el número de registros de mapa y el tamaño del búfer de dispersión y recopilación son suficientes para asignar la longitud completa solicitada por el autor de la llamada, los valores de entrada y salida de *Length son idénticos. Si las MDL de la cadena MDL describen un total de N bytes de memoria, los valores válidos de *Length se encuentran en el intervalo de 0 a N-Offset.
[in] WriteToDevice
Dirección de la transferencia DMA. Establezca este parámetro en TRUE para una operación de escritura, que transfiere datos al dispositivo desde la memoria. Establezca este parámetro en FALSE para una operación de lectura, que transfiere datos del dispositivo a la memoria.
[out, optional] ScatterGatherBuffer
Puntero a un búfer asignado por el autor de la llamada en el que la rutina escribe la lista de dispersión y recopilación para la transferencia de DMA. Esta lista comienza con una estructura SCATTER_GATHER_LIST , seguida inmediatamente de una matriz de SCATTER_GATHER_ELEMENT . Para un controlador que usa un dispositivo DMA maestro de bus, ScatterGatherBuffer es un parámetro necesario. Para un controlador que usa un controlador DMA del sistema, el parámetro ScatterGatherBuffer es opcional y puede ser NULL. Para obtener más información, vea la sección Comentarios.
[in] ScatterGatherBufferLength
Tamaño, en bytes, del búfer al que apunta el parámetro ScatterGatherBuffer . El tamaño del búfer asignado debe ser lo suficientemente grande como para contener la lista de dispersión y recopilación, además de los datos internos que el sistema operativo almacena en este búfer. Para determinar el tamaño de búfer necesario, llame a la rutina GetDmaTransferInfo o CalculateScatterGatherList . Si ScatterGatherBuffer es NULL, establezca ScatterGatherBufferLength en cero.
[in, optional] DmaCompletionRoutine
Puntero a una rutina DmaCompletionRoutine proporcionada por el autor de la llamada que se llamará cuando se complete la transferencia de DMA. Se llama a esta rutina si el dispositivo de destino usa un controlador DMA del sistema que genera una interrupción de finalización de DMA. Se llama a la rutina DmaCompletionRoutine en DISPATCH_LEVEL una vez completada la transferencia de DMA. Para un adaptador DMA del sistema, este parámetro es opcional y puede ser NULL. Para un adaptador bus-master, establezca este parámetro en NULL.
[in, optional] CompletionContext
Contexto determinado por el controlador para la rutina DmaCompletionRoutine . Este contexto se proporciona como parámetro CompletionContext a la rutina DmaCompletionRoutine . Si el parámetro DmaCompletionRoutine es NULL, establezca CompletionContext en NULL.
Valor devuelto
MapTransferEx 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 |
|---|---|
|
Error en la rutina debido a valores de parámetros no válidos pasados por el autor de la llamada. |
|
El búfer proporcionado por el autor de la llamada en ScatterGatherBuffer es demasiado pequeño para contener la lista de dispersión y recopilación. |
|
La rutina no pudo asignar los recursos necesarios para la transferencia de DMA. |
|
Esta transferencia se canceló. |
Comentarios
MapTransferEx no es una rutina del sistema a la que se puede llamar directamente por su 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.
Para una transferencia que usa un controlador DMA del sistema, el autor de la llamada puede, como opción, proporcionar una rutina de devolución de llamada DmaCompletionRoutine a la que se llama cuando finaliza la transferencia. El sistema operativo programa esta devolución de llamada en respuesta a la interrupción de finalización de DMA del controlador DMA del sistema.
El número de registros de mapa que puede configurar MapTransferEx no puede superar el máximo obtenido del controlador de IoGetDmaAdapter.
Los parámetros Mdl, Offset y Length describen el búfer de datos de E/S para la transferencia DMA solicitada. Es posible que el número de registros de mapa asignados no sea suficiente para asignar toda la memoria de este búfer, o es posible que el búfer de dispersión o recopilación al que apunta ScatterGatherBuffer no sea lo suficientemente grande como para describir todo el búfer. MapTransferEx escribe un valor de salida en *Length para indicar al controlador la cantidad de memoria del búfer para la transferencia DMA solicitada asignada por la rutina. La rutina escribe una lista de dispersión y recopilación en el búfer al que apunta ScatterGatherBuffer. En esta lista se describen los fragmentos de búfer que la rutina ha asignado correctamente.
Si una llamada a MapTransferEx se realiza correctamente, MapTransferEx escribe el valor de salida *Length antes de que devuelva. Si el autor de la llamada especifica una DmaCompletionRoutine, el valor de salida *Length actualizado siempre se escribe antes de que se ejecute DmaCompletionRoutine . Para obtener más información, vea Varias llamadas a MapTransferEx.
El parámetro Offset especifica el desplazamiento inicial en la cadena MDL que describe la memoria en el búfer de datos de E/S. Por ejemplo, supongamos que la cadena MDL contiene dos MDL, MDL₁ y MDL₁ que MDL₁ describe N₁ bytes de memoria, y MDL₁ describe los bytes N₁. Si Offset = N, donde N₁ < N < ₁ + N₁ , el búfer no contiene ninguna de la memoria descrita por MDL₁, y comienza en un desplazamiento de N - N₁ bytes en la memoria descrita por MDL Núm.
Si la transferencia usa un controlador DMA del sistema, el autor de la llamada puede establecer ScatterGatherBuffer = NULL, en cuyo caso MapTransferEx usa un búfer predeterminado asignado internamente para contener la lista de dispersión y recopilación. Se garantiza que el búfer predeterminado es lo suficientemente grande como para contener una lista de dispersión y recopilación de al menos un elemento. Si el búfer predeterminado se usa para una transferencia de dispersión o recopilación de muchos elementos, es posible que se necesiten muchas llamadas a MapTransferEx para completar la transferencia. Si el hardware del controlador DMA admite transferencias de dispersión y recopilación, el uso del búfer predeterminado podría degradar el rendimiento.
Si ScatterGatherBuffer no es NULL y ScatterGatherBufferSize especifica un tamaño demasiado pequeño para contener una lista de dispersión o recopilación de al menos un elemento, MapTransferEx produce un error y devuelve STATUS_INVALID_PARAMETER.
MapTransferEx es una versión extendida de la rutina MapTransfer . La versión extendida tiene estas ventajas:
- MapTransferEx puede procesar todos los fragmentos de búfer de una cadena MDL en una llamada, pero MapTransfer solo puede procesar un fragmento de búfer físicamente contiguo por llamada.
- MapTransferEx puede generar una lista completa de dispersión y recopilación en una llamada, pero MapTransfer solo puede generar un elemento de lista de dispersión y recopilación por llamada.
- MapTransferEx puede asignar todos los fragmentos de búfer en una lista de dispersión y recopilación en una llamada, pero MapTransfer solo puede asignar un fragmento de búfer físicamente contiguo por llamada.
- MapTransferEx solo requiere el desplazamiento inicial para toda la lista de dispersión y recopilación, pero MapTransfer requiere una dirección virtual inicial para cada fragmento de búfer físicamente contiguo.
- Una llamada a MapTransferEx puede asignar un búfer que se extiende a través de uno o varios MDL, pero una llamada a MapTransfer solo puede asignar un fragmento de búfer físicamente contiguo en la memoria descrita por un MDL.
- Para una transferencia DMA del sistema, MapTransferEx permite al autor de la llamada proporcionar una rutina de devolución de llamada DmaCompletionRoutine para recibir notificaciones una vez completada la transferencia, pero MapTransfer no proporciona una manera de notificar al autor de la llamada cuando se completa una transferencia DMA.
Para obtener más información, vea Usar la rutina MapTransferEx.
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 |