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

Artículo
10/30/2024

La función de devolución de llamada de eventos EvtSerCx2CustomTransmitTransaction Start llama a la versión 2 de la extensión del marco de serie (SerCx2) para iniciar una transacción de transmisión personalizada.

Sintaxis

EVT_SERCX2_CUSTOM_TRANSMIT_TRANSACTION_START EvtSercx2CustomTransmitTransactionStart;

void EvtSercx2CustomTransmitTransactionStart(
  [in] SERCX2CUSTOMTRANSMITTRANSACTION CustomTransmitTransaction,
  [in] WDFREQUEST Request,
  [in] PMDL Mdl,
  [in] ULONG Offset,
  [in] ULONG Length
)
{...}

Parámetros

[in] CustomTransmitTransaction

Identificador de SERCX2CUSTOMTRANSMITTRANSACTION a un objeto custom-transmit-transaction. El controlador de controlador serie llamó anteriormente al método SerCx2CustomTransmitTransactionCreate para crear este objeto.

[in] Request

Identificador del objeto de solicitud de marco asociado a la transacción de transmisión personalizada. El controlador es responsable de completar esta solicitud. Es posible que esta solicitud no sea la solicitud de IRP_MJ_WRITE enviada por el cliente y, por tanto, el controlador del controlador serie no debe intentar usar esta solicitud para acceder al búfer de escritura. Esta solicitud se usa principalmente para la cancelación, finalización y reenvío de cola (si es necesario). Para acceder al búfer de escritura de la solicitud de escritura del cliente, use los parámetros demdl , offsety length.

[in] Mdl

Puntero a un MDL que describe las páginas de memoria que abarca el búfer de escritura para la transacción de transmisión personalizada. La lista de dispersión y recopilación de la transferencia DMA usará la región de esta memoria especificada por el offset de y parámetros length. Para obtener más información sobre las cadenas MDL, consulte Uso de MDLs.

[in] Offset

Desplazamiento inicial de la transferencia de datos. Este parámetro es un desplazamiento de bytes desde el principio 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 desplazamiento están en el intervalo de 0 a N-1.

[in] Length

Tamaño, en bytes, de la transferencia de datos. Si MDL especifica un total de N bytes de espacio en búfer, los valores posibles de Longitud están en el intervalo de 1 a N-Desplazamiento.

Valor devuelto

Ninguno

Observaciones

El controlador de controlador serie debe implementar esta función si crea un objeto custom-transmit-transaction. Si se implementa, el controlador registra la función en el SerCx2CustomTransmitTransactionCreate llamada que crea este objeto.

Después de que SerCx2 llama a la función EvtSerCx2CustomTransmitTransactionStart, el controlador de controlador serie inicia la transacción mediante la programación del mecanismo de transferencia de datos personalizado para mover datos del búfer en la solicitud de escritura al FIFO de transmisión en el hardware del controlador serie. A menos que la solicitud se pueda completar inmediatamente, antes de que se devuelva la función EvtSerCx2CustomTransmitTransactionStart, el controlador debe llamar a un método como WdfRequestMarkCancelableEx para marcar la solicitud como cancelable.

Una vez finalizada la transacción y el controlador completa la solicitud de escritura pendiente, SerCx2 llama a la EvtSerCx2CustomTransmitTransactionCleanup función de devolución de llamada de eventos, si el controlador implementa esta función.

Si el controlador del controlador serie implementa un EvtSerCx2CustomTransmitTransactionInitialize función de devolución de llamada de eventos, SerCx2 llama a esta función antes de llamar a la función EvtSerCx2CustomTransmitTransactionStart. Justo antes de la llamada EvtSerCx2CustomTransmitTransactionStart y después de la llamada EvtSerCx2CustomTransmitTransactionInitialize devuelve, SerCx2 inicia el temporizador que detecta si se agota el tiempo de espera de la solicitud de escritura. Para obtener más información, consulte la explicación de los tiempos de espera totales en SERIAL_TIMEOUTS.

El controlador de controlador serie debe completar la solicitud de escritura pendiente solo después de que el último byte de la transmisión FIFO se haya transmitido al dispositivo periférico conectado en serie. No puede haber ninguna garantía de que los datos escritos en la transmisión FIFO se transmitan sin un retraso significativo, y un controlador de controlador serie que suponga que existe dicha garantía puede causar problemas de confiabilidad para los controladores periféricos.

Si el mecanismo de transferencia de datos personalizado es un dispositivo DMA maestro de bus, la función EvtSerCx2CustomTransmitTransactionStart puede llamar a un método como WdfDmaTransactionInitializeUsingOffset para iniciar una transacción DMA que use el búfer de escritura descrito por el Mdl, Offsety parámetros length.

Para obtener más información sobre los parámetros de Mdl, Offsety Length, vea Comentarios en EvtSerCx2CustomTransmitTransactionInitialize.

Si el objeto de solicitud identificado por el parámetro request contiene almacenamiento para un contexto privado, este almacenamiento podría no inicializarse la primera vez que el controlador del controlador serie accede al contexto. En el primer acceso, el controlador normalmente debe rellenar el contexto con ceros y, después, si es necesario, establecer explícitamente los campos en el contexto que requieran valores iniciales distintos de cero.

Para obtener más información, vea SerCx2 Custom-Transmit Transactions.

Ejemplos

Para definir un EvtSerCx2CustomTransmitTransactionStart función de devolución de llamada, 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 un EvtSerCx2CustomTransmitTransactionStart función de devolución de llamada denominada MyCustomTransmitTransactionStart, use el tipo de función EVT_SERCX2_CUSTOM_TRANSMIT_TRANSACTION_START, como se muestra en este ejemplo de código:

EVT_SERCX2_CUSTOM_TRANSMIT_TRANSACTION_START  MyCustomTransmitTransactionStart;

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

_Use_decl_annotations_
VOID
  MyCustomTransmitTransactionStart(
    SERCX2CUSTOMTRANSMITTRANSACTION  CustomTransmitTransaction,
    WDFREQUEST  Request,
    PMDL  Mdl,
    ULONG  Offset,
    ULONG  Length
    )
  {...}

El tipo de función EVT_SERCX2_CUSTOM_TRANSMIT_TRANSACTION_START 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_TRANSACTION_START 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, vea Anotación del comportamiento de la función.

Requisitos

Requisito	Valor
cliente mínimo admitido	Disponible a partir de Windows 8.1.
de la plataforma de destino de	Escritorio
encabezado de	sercx.h
irQL	Se llama a irQL <= DISPATCH_LEVEL.