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

Artículo
08/07/2023

La función de devolución de llamada de eventos EvtSerCx2PioTransmitWriteBuffer se llama mediante la versión 2 de la extensión de marco serie (SerCx2) para usar E/S programada (PIO) para transferir el contenido de un búfer de escritura al FIFO de transmisión en el controlador serie.

Sintaxis

EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER EvtSercx2PioTransmitWriteBuffer;

ULONG EvtSercx2PioTransmitWriteBuffer(
  [in] SERCX2PIOTRANSMIT PioTransmit,
  [in] PUCHAR Buffer,
  [in] ULONG Length
)
{...}

Parámetros

[in] PioTransmit

Identificador de SERCX2PIOTRANSMIT a un objeto pio-transmit. El controlador de serie anteriormente llamó al método SerCx2PioTransmitCreate para crear este objeto.

[in] Buffer

Puntero al búfer de escritura. Este parámetro es la dirección virtual de un búfer bloqueado en la memoria del sistema.

[in] Length

Número de bytes en el búfer de escritura que están disponibles para transmitirse.

Valor devuelto

La función EvtSerCx2PioTransmitWriteBuffer devuelve el número de bytes de datos que transfirió correctamente desde el búfer de escritura al FIFO de transmisión en el hardware del controlador serie.

Comentarios

El controlador de controlador serie debe implementar esta función. El controlador registra la función en la llamada SerCx2PioTransmitCreate que crea el objeto pio-transmit.

SerCx2 podría llamar a la función EvtSerCx2PioTransmitWriteBuffer más de una vez durante una transacción de transmisión de PIO. Una sola llamada EvtSerCx2PioTransmitWriteBuffer es suficiente si esta llamada puede transferir todo el contenido del búfer de escritura al FIFO de transmisión. De lo contrario, SerCx2 sigue llamando a esta función, ya que hay más espacio disponible en el FIFO de transmisión, hasta que se vacía el búfer de escritura.

A partir del primer byte del búfer de escritura, la función EvtSerCx2PioTransmitWriteBuffer usa PIO para transferir tantos bytes como pueda desde el búfer al FIFO de transmisión. La función continúa transfiriendo datos del búfer siempre y cuando el búfer no esté vacío y el registro de estado de línea (LSR) indica que FIFO puede aceptar más datos. Si el LSR indica que FIFO no puede aceptar más datos, la función devuelve sin vaciar el búfer. De lo contrario, la función transfiere todos los bytes del búfer y devuelve. En cualquier caso, el valor devuelto por esta función es el número de bytes de datos que se transfirieron correctamente desde el búfer de escritura al FIFO de transmisión.

Normalmente, la función EvtSerCx2PioTransmitWriteBuffer no habilita interrupciones. En su lugar, si la función no puede transferir todo el contenido del búfer de escritura al FIFO de transmisión, SerCx2 llama a la función de devolución de llamada de evento EvtSerCx2PioTransmitEnableReadyNotification para habilitar una notificación lista, y esta función habilita una interrupción que se produce cuando el FIFO de transmisión se vuelve vacío.

Para cada llamada sucesiva a la función EvtSerCx2PioTransmitWriteBuffer , SerCx2 ajusta Buffer para que apunte a los datos restantes del búfer y establece Length en el número de bytes de datos que permanecen en el búfer.

La notificación lista nunca se habilita cuando SerCx2 llama a la función EvtSerCx2PioTransmitEnableReadyNotification . Sin embargo, SerCx2 podría llamar a esta función desde el mismo subproceso desde el que el controlador llamó al método SerCx2PioTransmitReady .

Si el controlador implementa una función EvtSerCx2PioTransmitInitializeTransaction , SerCx2 llama a esta función al inicio de una transacción pio-transmit, antes de la primera llamada a la función EvtSerCx2PioTransmitWriteBuffer . Si el controlador implementa una función EvtSerCx2PioTransmitCleanupTransaction , SerCx2 llama a esta función al final de una transacción pio-transmit, después de la última llamada EvtSerCx2PioTransmitWriteBuffer , y después de cualquier llamada a las funciones EvtSerCx2PioTransmitDrainFifo, EvtSerCx2PioTransmitCancelDrainFifo y EvtSerCx2PioTransmitPurgeFifo , si se implementan.

Para obtener más información sobre las transacciones de transmisión de PIO, consulte SerCx2 PIO-Transmit Transactions.

Ejemplos

Para definir una función de devolución de llamada EvtSerCx2PioTransmitWriteBuffer , 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 EvtSerCx2PioTransmitWriteBuffer denominada MyPioTransmitWriteBuffer, use el tipo de función EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER , como se muestra en este ejemplo de código:

EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER  MyPioTransmitWriteBuffer;

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

_Use_decl_annotations_
ULONG
  MyPioTransmitWriteBuffer(
    SERCX2PIOTRANSMIT  PioTransmit,
    PUCHAR Buffer,
    ULONG Length
    )
  {...}

El tipo de función EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER 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_PIO_TRANSMIT_WRITE_BUFFER 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.