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

Artículo
08/07/2023

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

Sintaxis

EVT_SERCX2_SELECT_NEXT_RECEIVE_TRANSACTION_TYPE EvtSercx2SelectNextReceiveTransactionType;

SERCX2_TRANSACTION_TYPE EvtSercx2SelectNextReceiveTransactionType(
  [in]  WDFDEVICE Device,
  [in]  PMDL Mdl,
  [in]  ULONG Offset,
  [in]  ULONG RemainingLength,
  [out] SERCX2CUSTOMRECEIVE *CustomReceive,
  [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 una MDL que describe las páginas de memoria que abarca el búfer de lectura para la siguiente transacción de recepción. La lista de dispersión y recopilación de la transferencia 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 inicio de la región del búfer descrita por MDL. Si 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 actual de lectura (IRP_MJ_READ). Si 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] CustomReceive

Puntero a una ubicación en la que la función escribe el identificador de SERCX2CUSTOMRECEIVE en el objeto de recepción personalizado. 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 SerCx2CustomReceiveCreate . 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 recepción. Si el valor devuelto es SerCx2TransactionTypeDefault, serCx2 omite este valor de salida.

Valor devuelto

La función EvtSerCx2SelectNextReceiveTransactionType devuelve una constante de enumeración de 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 personalizada) o para permitir que SerCx2 elija qué tipo de transacción usar para la siguiente transacción de recepció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 EvtSerCx2SelectNextReceiveTransactionType , SerCx2 siempre decide qué tipo de mecanismo de transferencia de datos (PIO, system DMA o personalizado) usar para la siguiente transacción de recepció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 recepción de DMA del sistema proporciona una estructura de SERCX2_SYSTEM_DMA_RECEIVE_CONFIG que contiene esta información. Un controlador que admite transacciones de recepción personalizadas proporciona una estructura de SERCX2_CUSTOM_RECEIVE_CONFIG que contiene esta información.

Si el controlador del controlador serie implementa una función EvtSerCx2SelectNextReceiveTransactionType , SerCx2 llama a esta función para determinar qué tipo de mecanismo de transferencia de datos (PIO, system DMA o personalizado) se usará para la siguiente transacción de recepción. Es posible que desee 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_RECEIVE_CONFIG .

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

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

Ejemplos

Para definir una función de devolución de llamada EvtSerCx2CustomReceiveSelectNextTransactionType , 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 Code Analysis for Drivers, Static Driver Verifier (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 EvtSerCx2CustomReceiveSelectNextTransactionType denominada MyCustomReceiveSelectNextTransactionType, use el tipo de función EVT_SERCX2_CUSTOM_RECEIVE_SELECT_NEXT_TRANSACTION_TYPE , como se muestra en este ejemplo de código:

EVT_SERCX2_CUSTOM_RECEIVE_SELECT_NEXT_TRANSACTION_TYPE  MyCustomReceiveTransactionStart;

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

_Use_decl_annotations_
SERCX2_TRANSACTION_TYPE
  EvtSerCx2SelectNextReceiveTransactionType(
    WDFDEVICE  Device,
    PMDL  Mdl,
    ULONG  Offset,
    ULONG  RemainingLength,
    SERCX2CUSTOMRECEIVE  *CustomReceive,
    PULONG  NextTransactionLength
    )
  {...}

El tipo de función EVT_SERCX2_CUSTOM_RECEIVE_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_RECEIVE_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 roles 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.