EVT_SERCX2_PIO_RECEIVE_READ_BUFFER callback function (sercx.h)

Article
10/21/2021

The EvtSerCx2PioReceiveReadBuffer event callback function is called by version 2 of the serial framework extension (SerCx2) to use programmed I/O (PIO) to transfer data from the receive FIFO in the serial controller to a read buffer.

Syntax

EVT_SERCX2_PIO_RECEIVE_READ_BUFFER EvtSercx2PioReceiveReadBuffer;

ULONG EvtSercx2PioReceiveReadBuffer(
  [in]  SERCX2PIORECEIVE PioReceive,
  [out] PUCHAR Buffer,
  [in]  ULONG Length
)
{...}

Parameters

[in] PioReceive

A SERCX2PIORECEIVE handle to a PIO-receive object. The serial controller driver previously called the SerCx2PioReceiveCreate method to create this object.

[out] Buffer

A pointer to the read buffer. This parameter is the virtual address of a locked-down buffer in system memory.

[in] Length

The number of bytes in the read buffer that are available to store received data.

Return value

The EvtSerCx2PioReceiveReadBuffer function returns the number of bytes of data that it successfully transferred from the receive FIFO in the serial controller hardware to the read buffer.

Remarks

Your serial controller driver must implement this function. The driver registers the function in the SerCx2PioReceiveCreate call that creates the PIO-receive object.

SerCx2 might call the EvtSerCx2PioReceiveReadBuffer function more than once during a PIO-receive transaction. A single EvtSerCx2PioReceiveReadBuffer call is sufficient if this call can fill the read buffer with data from the receive FIFO. Otherwise, SerCx2 continues to call this function, as more data becomes available in the receive FIFO, until the read buffer is filled.

The EvtSerCx2PioReceiveReadBuffer function uses PIO to transfer as many bytes as it can from the receive FIFO to the read buffer. The function continues to transfer data from the FIFO for as long as the buffer passed to this function is not full and the line status register (LSR) indicates that more data is available from the FIFO. If the LSR indicates that the FIFO is empty, the function returns without filling the buffer. Otherwise, the function fills the buffer and returns. In either case, the value returned by this function is the number of bytes of data that were successfully transferred to the read buffer from the receive FIFO.

Typically, the EvtSerCx2PioReceiveReadBuffer function does not enable any interrupts. Instead, if the receive FIFO runs out of data before the function can fill the read buffer, SerCx2 calls the EvtSerCx2PioReceiveEnableReadyNotification event callback function to enable a ready notification, and this function enables an interrupt that occurs when more data is available in the receive FIFO.

For each successive call to the EvtSerCx2PioReceiveReadBuffer function, SerCx2 adjusts Buffer to point to the next buffer region to be filled, and sets Length to the number of bytes of unfilled space that remain in the buffer.

The ready notification is never enabled when SerCx2 calls the EvtSerCx2PioReceiveEnableReadyNotification function. However, SerCx2 might call this function from the same thread from which the driver called the SerCx2PioReceiveReady method.

If the driver implements an EvtSerCx2PioReceiveInitializeTransaction function, SerCx2 calls this function at the start of a PIO-transmit transaction, before the first call to the EvtSerCx2PioReceiveReadBuffer function. If the driver implements an EvtSerCx2PioReceiveCleanupTransaction function, SerCx2 calls this function at the end of a PIO-receive transaction, after the final call to the EvtSerCx2PioReceiveReadBuffer function.

In addition to calling the EvtSerCx2PioReceiveReadBuffer function during PIO-receive transactions, SerCx2 calls this function to save the state of the receive FIFO just before the serial controller exits the D0 device power state. For more information, see SerCx2SaveReceiveFifoOnD0Exit.

For more information about PIO-receive transactions, see SerCx2 PIO-Receive Transactions.

Examples

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

EVT_SERCX2_PIO_RECEIVE_READ_BUFFER  MyPioReceiveReadBuffer;

Then, implement your callback function as follows:

_Use_decl_annotations_
ULONG
  MyPioReceiveReadBuffer(
    SERCX2PIORECEIVE  PioReceive,
    PUCHAR  Buffer,
    ULONG  Length

    )
  {...}

The EVT_SERCX2_PIO_RECEIVE_READ_BUFFER 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_RECEIVE_READ_BUFFER 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.