EVT_SERCX2_PIO_TRANSMIT_ENABLE_READY_NOTIFICATION callback function (sercx.h)

Article
10/21/2021

The EvtSerCx2PioTransmitEnableReadyNotification event callback function is called by version 2 of the serial framework extension (SerCx2) to enable the serial controller driver to notify SerCx2 when the transmit FIFO in the serial controller is ready to accept more data.

Syntax

EVT_SERCX2_PIO_TRANSMIT_ENABLE_READY_NOTIFICATION EvtSercx2PioTransmitEnableReadyNotification;

void EvtSercx2PioTransmitEnableReadyNotification(
  [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 must implement this function. The driver registers the function in the SerCx2PioTransmitCreate call that creates the PIO-transmit object.

If the ready notification for PIO-transmit transactions is enabled, the serial controller driver must call the SerCx2PioTransmitReady method to notify SerCx2 when the driver detects that the transmit FIFO in the serial controller hardware is ready to accept more data. If the transmit FIFO is ready to accept data when the ready notification is enabled, the driver immediately calls this method to notify SerCx2.

The ready notification for a PIO-transmit transaction is a one-shot notification. After sending a ready notification to SerCx2, the serial controller driver sends no further notifications until SerCx2 calls the EvtSerCx2PioTransmitEnableReadyNotification function to enable another notification.

An EvtSerCx2PioTransmitWriteBuffer function call might only partially complete a PIO-transmit transaction because no more room is immediately available in the transmit FIFO to write more data. In this case, SerCx2 calls the EvtSerCx2PioTransmitEnableReadyNotification function to enable a ready notification, in which case the serial controller driver must notify SerCx2 when the transmit FIFO has room for more data. In response to this notification, SerCx2 resumes the partially completed transmit transaction by calling the EvtSerCx2PioTransmitWriteBuffer function again.

Typically, an EvtSerCx2PioTransmitEnableReadyNotification function enables an interrupt that occurs when the transmit FIFO in the serial controller is ready to accept more data. In response to this interrupt, the serial controller driver calls SerCx2PioTransmitReady.

No more than one ready notification can be pending at a time. SerCx2 never calls the EvtSerCx2PioTransmitEnableReadyNotification function if the ready notification is already enabled.

SerCx2 never calls the EvtSerCx2PioTransmitWriteBuffer function when the ready notification is enabled.

A pending ready notification can be canceled if the associated write request times out or is canceled. To cancel a ready notification for a PIO-transmit transaction, SerCx2 calls the EvtSerCx2PioTransmitCancelReadyNotification event callback function.

For more information, see SerCx2 PIO-Transmit Transactions.

Examples

To define an EvtSerCx2PioTransmitEnableReadyNotification 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 EvtSerCx2PioTransmitEnableReadyNotification callback function that is named MyPioTransmitEnableReadyNotification, use the EVT_SERCX2_PIO_TRANSMIT_ENABLE_READY_NOTIFICATION function type, as shown in this code example:

EVT_SERCX2_PIO_TRANSMIT_ENABLE_READY_NOTIFICATION  MyPioTransmitEnableReadyNotification;

Then, implement your callback function as follows:

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

The EVT_SERCX2_PIO_TRANSMIT_ENABLE_READY_NOTIFICATION 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_ENABLE_READY_NOTIFICATION 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.