EVT_SERCX2_SELECT_NEXT_TRANSMIT_TRANSACTION_TYPE función de devolución de llamada (sercx.h)

Artículo
02/29/2024

La función de devolución de llamada de eventos EvtSerCx2SelectNextTransmitTransactionType se llama mediante la versión 2 de la extensión de marco serie (SerCx2) para determinar qué mecanismo de transferencia de datos se usará para la siguiente operación de escritura.

Sintaxis

EVT_SERCX2_SELECT_NEXT_TRANSMIT_TRANSACTION_TYPE EvtSercx2SelectNextTransmitTransactionType;

SERCX2_TRANSACTION_TYPE EvtSercx2SelectNextTransmitTransactionType(
  [in]  WDFDEVICE Device,
  [in]  PMDL Mdl,
  [in]  ULONG Offset,
  [in]  ULONG RemainingLength,
  [out] SERCX2CUSTOMTRANSMIT *CustomTransmit,
  [out] PULONG NextTransactionLength
)
{...}

Parámetros

[in] Device

Un controlador WDFDEVICE para el objeto de dispositivo de marco que representa el controlador serie. El controlador del controlador serie creó este objeto en su función de devolución de llamada EvtDriverDeviceAdd . Para obtener más información, vea SerCx2InitializeDevice.

[in] Mdl

Puntero a un MDL que describe las páginas de memoria que abarca el búfer de escritura para la siguiente transacción de transmisión. 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 .

[in] Offset

Desplazamiento inicial para la siguiente transferencia de datos. Este parámetro es un desplazamiento de bytes desde el principio de la región de búfer descrita por MDL. Si el MDL especifica un total de N bytes de espacio en búfer, los valores posibles de Offset se encuentran en el intervalo de 0 a N-1.

[in] RemainingLength

Número total de bytes de datos que se van a transferir en la solicitud de escritura actual (IRP_MJ_WRITE). Si el MDL especifica un total de N bytes de espacio en búfer, los valores posibles de Length se encuentran en el intervalo de 1 a N-Offset.

[out] CustomTransmit

Puntero a una ubicación en la que la función escribe el identificador de SERCX2CUSTOMTRANSMIT en el objeto de transmisión personalizada. Si la función devuelve SerCx2TransactionTypeCustom, la función debe proporcionar el identificador de objeto que el controlador de controlador serie creó en una llamada anterior al método SerCx2CustomTransmitCreate . Si el valor devuelto no es SerCx2TransactionTypeCustom, SerCx2 omite este valor de salida.

[out] NextTransactionLength

Puntero a una ubicación en la que la función escribe el número de bytes que se van a transferir en la siguiente transacción de transmisión. Si el valor devuelto es SerCx2TransactionTypeDefault, SerCx2 omite este valor de salida.

Valor devuelto

La función EvtSerCx2SelectNextTransmitTransactionType devuelve una constante de enumeración SERCX2_TRANSACTION_TYPE para indicar si se debe usar un tipo de transacción seleccionado por el controlador (E/S programada (PIO), DMA del sistema o transferencia de datos personalizados), o para permitir que SerCx2 elija qué tipo de transacción usar para la siguiente transacción de transmisión.

Comentarios

El controlador de controlador serie puede, como opción, implementar esta función. Si se implementa, el controlador registra esta función en la llamada al método SerCx2InitializeDevice que finaliza la inicialización del objeto de dispositivo de marco para el controlador serie.

Si el controlador de controlador serie no implementa una función EvtSerCx2SelectNextTransmitTransactionType , SerCx2 siempre decide qué tipo de mecanismo de transferencia de datos (PIO, DMA del sistema o personalizado) se usará para la siguiente transacción de transmisión. SerCx2 basa sus decisiones sobre la información de configuración de E/S proporcionada por el controlador de controlador serie. Un controlador que admite transacciones de transmisión del sistema DMA proporciona una estructura de SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG que contiene esta información. Un controlador que admite transacciones de transmisión personalizadas proporciona una estructura de SERCX2_CUSTOM_TRANSMIT_CONFIG que contiene esta información.

Si el controlador de controlador serie implementa una función EvtSerCx2SelectNextTransmitTransactionType , SerCx2 llama a esta función para determinar qué tipo de mecanismo de transferencia de datos (PIO, DMA del sistema o personalizado) se usará para la siguiente transacción de transmisión. Es posible que quiera implementar esta función si el controlador serie tiene funcionalidades de hardware especiales que no se pueden describir adecuadamente mediante la información de configuración de E/S en las estructuras SERCX2_XXX_TRANSMIT_CONFIG .

Nota Incluso si un controlador de controlador serie implementa una función EvtSerCx2SelectNextTransmitTransactionType , SerCx2 usa transacciones pio-transmit para realizar determinados tipos de transferencias de datos sin llamar primero a esta función.

Para obtener más información, consulte Introducción a las transacciones de E/S de SerCx2.

Ejemplos

Para definir una función de devolución de llamada EvtSerCx2CustomTransmitSelectNextTransactionType , primero debe proporcionar una declaración de función que identifique el tipo de función de devolución de llamada que está definiendo. Windows proporciona un conjunto de tipos de función de devolución de llamada para controladores. Declarar una función mediante los tipos de función de devolución de llamada ayuda a Análisis de código para controladores, Comprobador de controladores estáticos (SDV) y otras herramientas de comprobación encuentran errores y es un requisito para escribir controladores para el sistema operativo Windows.

Por ejemplo, para definir una función de devolución de llamada EvtSerCx2CustomTransmitSelectNextTransactionType denominada MyCustomTransmitSelectNextTransactionType, use el tipo de función EVT_SERCX2_CUSTOM_TRANSMIT_SELECT_NEXT_TRANSACTION_TYPE , como se muestra en este ejemplo de código:

EVT_SERCX2_CUSTOM_TRANSMIT_SELECT_NEXT_TRANSACTION_TYPE  MyCustomTransmitTransactionStart;

A continuación, implemente la función de devolución de llamada de la siguiente manera:

_Use_decl_annotations_
SERCX2_TRANSACTION_TYPE
  EvtSerCx2SelectNextTransmitTransactionType(
    WDFDEVICE  Device,
    PMDL  Mdl,
    ULONG  Offset,
    ULONG  RemainingLength,
    SERCX2CUSTOMTRANSMIT  *CustomTransmit,
    PULONG  NextTransactionLength
    )
  {...}

El tipo de función EVT_SERCX2_CUSTOM_TRANSMIT_SELECT_NEXT_TRANSACTION_TYPE se define en el archivo de encabezado Sercx.h. Para identificar con más precisión los errores al ejecutar las herramientas de análisis de código, asegúrese de agregar la anotación Use_decl_annotations a la definición de función. La anotación Use_decl_annotations garantiza que se usen las anotaciones que se aplican al tipo de función EVT_SERCX2_CUSTOM_TRANSMIT_SELECT_NEXT_TRANSACTION_TYPE en el archivo de encabezado. Para obtener más información sobre los requisitos de las declaraciones de función, consulte Declaración de funciones mediante tipos de rol de función para controladores KMDF. Para obtener más información sobre Use_decl_annotations, consulte Anotación del comportamiento de la función.

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible a partir de Windows 8.1.
Plataforma de destino	Escritorio
Encabezado	sercx.h
IRQL	Se llama en IRQL <= DISPATCH_LEVEL.