EVT_SERCX2_PIO_TRANSMIT_DRAIN_FIFO callback function (sercx.h)

Article
10/21/2021

The EvtSerCx2PioTransmitDrainFifo event callback function is called by version 2 of the serial framework extension (SerCx2) to drain the transmit FIFO in the serial controller hardware.

Syntax

EVT_SERCX2_PIO_TRANSMIT_DRAIN_FIFO EvtSercx2PioTransmitDrainFifo;

void EvtSercx2PioTransmitDrainFifo(
  [in] SERCX2PIOTRANSMIT PioTransmit
)
{...}

Parameters

[in] PioTransmit

A SERCX2PIOTRANSMIT handle to a PIO-transmit object. The serial controller driver previously called the SerCx2PioTransmitCreate method to create this object.

Return value

None

Remarks

Your serial controller driver can, as an option, implement this function. If your driver implements this function, it must also implement the EvtSerCx2PioTransmitCancelDrainFifo and EvtSerCx2PioTransmitPurgeFifo event callback functions. A driver that implements these functions registers them in the SerCx2PioTransmitCreate call that creates the PIO-transmit object.

SerCx2 calls the EvtSerCx2PioTransmitDrainFifo function, if it is implemented, to drain the transmit FIFO in the serial controller hardware at the end of a PIO-transmit transaction. This function makes sure that any data bytes that remain in the transmit FIFO are transmitted to the serially connected peripheral device. After the last byte is transmitted from the FIFO, the EvtSerCx2PioTransmitDrainFifo function calls the SerCx2PioTransmitDrainFifoComplete method to notify SerCx2.

If the serial controller driver implements an EvtSerCx2PioTransmitDrainFifo function, SerCx2 does not complete a pending write (IRP_MJ_WRITE) request until the driver calls SerCx2PioTransmitDrainFifoComplete.

If your serial controller has a hardware FIFO (or similar buffering mechanism) to hold transmit data, your driver should implement an EvtSerCx2PioTransmitDrainFifo function. Otherwise, SerCx2 cannot confirm that the transmit FIFO has drained before the pending write request is completed. Instead, SerCx2 completes this request after the last byte in the write buffer is written to the transmit FIFO. There can be no guarantee that data written to the transmit FIFO will be transmitted without a significant delay. Any data that remains in the FIFO after the write request is completed might be lost before it can be transmitted to the serially connected peripheral device. This unexpected data loss in a successfully completed write request can create reliability problems for the peripheral driver.

For example, a peripheral driver might send write requests to a serial port to which a peripheral device is connected. Until all outstanding write requests are completed, this driver should delay sending an IOCTL to change the baud rate at which the serial port transmits data. However, if no EvtSerCx2PioTransmitDrainFifo function is implemented, a write request to transmit 100 bytes of data might be completed while 50 data bytes still remain in the transmit FIFO. If the peripheral driver then sends an IOCTL to set a new baud rate, some of the remaining bytes in the FIFO might be transmitted at the new baud rate, causing an error.

Similarly, if a write request to transmit 100 bytes of data is completed while 50 data bytes still remain in the transmit FIFO, and the serial controller exits D0 to enter a low-power device state before the remaining bytes in the FIFO can be transmitted, the peripheral driver will not know that these bytes are lost.

For more information, see SerCx2 PIO-Transmit Transactions.

Examples

To define an EvtSerCx2PioTransmitDrainFifo callback function, you must first provide a function declaration that identifies the type of callback function you're defining. Windows provides a set of callback function types for drivers. Declaring a function using the callback function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it's a requirement for writing drivers for the Windows operating system.

For example, to define an EvtSerCx2PioTransmitDrainFifo callback function that is named MyPioTransmitDrainFifo, use the EVT_SERCX2_PIO_TRANSMIT_DRAIN_FIFO function type, as shown in this code example:

EVT_SERCX2_PIO_TRANSMIT_DRAIN_FIFO  MyPioTransmitDrainFifo;

Then, implement your callback function as follows:

_Use_decl_annotations_
VOID
  MyPioTransmitDrainFifo(
    SERCX2PIOTRANSMIT  PioTransmit
    )
  {...}

The EVT_SERCX2_PIO_TRANSMIT_DRAIN_FIFO function type is defined in the Sercx.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the Use_decl_annotations annotation to your function definition. The Use_decl_annotations annotation ensures that the annotations that are applied to the EVT_SERCX2_PIO_TRANSMIT_DRAIN_FIFO function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for KMDF Drivers. For more information about Use_decl_annotations, see Annotating Function Behavior.

Requirements

Requirement	Value
Minimum supported client	Available starting with Windows 8.1.
Target Platform	Desktop
Header	sercx.h
IRQL	Called at IRQL <= DISPATCH_LEVEL.