Hardware Dev Center

EvtSerCxReceive function

The EvtSerCxReceive event callback function prepares the serial controller device (UART) to do a read (receive) operation.

Syntax


EVT_SERCX_RECEIVE EvtSerCxReceive;

NTSTATUS EvtSerCxReceive(
  _In_ WDFDEVICE Device,
  _In_ size_t    Length
)
{ ... }

Parameters

Device [in]

A WDFDEVICE handle to the framework device object that represents the serial controller.

Length [in]

The number of bytes to be received. The controller driver can use this value as a hint to decide whether to use PIO or DMA to perform the data transfer.

Return value

The EvtSerCxReceive function returns STATUS_SUCCESS if the call is successful. Otherwise, it returns an appropriate error status code.

Remarks

The serial framework extension (SerCx) calls this function to configure the controller hardware to receive data. If necessary, the EvtSerCxReceive function can enable interrupts.

The EvtSerCxReceive function does not necessarily read the input data from the receive FIFO buffer. Depending on the serial controller hardware or the type of transfer, this function might set up a DMA operation to read the data, or it might schedule a transmit/receive DPC function to read the data. The serial controller driver implements this DPC function to receive data from the controller and to transmit data to the serial controller. During the DPC, the DPC function determines whether data is available to be received and, if so, uses PIO to read the data from the receive FIFO in the serial controller.

If the receive FIFO in the serial controller is empty or nearly empty, but the FIFO's high-water-mark interrupt is enabled, the DPC routine can simply return. Later, the controller driver's ISR can schedule the DPC routine to run, and this routine can read more data from the receive FIFO.

To register an EvtSerCxReceive callback function, the controller driver calls the SerCxInitialize method during the EvtDriverDeviceAdd callback.

Examples

The function type for this callback is declared in Sercx.h, as follows.


typedef NTSTATUS
  EVT_SERCX_RECEIVE(
    __in WDFDEVICE Device
    );

To define an EvtSerCxReceive callback function that is named MyEvtSerCxReceive, you must first provide a function declaration that Static Driver Verifier (SDV) and other verification tools require, as follows.


EVT_SERCX_RECEIVE MyEvtSerCxReceive;

Then, implement your callback function as follows.


NTSTATUS
  MyEvtSerCxReceive(
    __in WDFDEVICE Device
    )
{ ... }

For more information about SDV requirements for function declarations, see Declaring Functions Using Function Role Types for KMDF Drivers.

Requirements

Target platform

Desktop

Version

Available starting with Windows 8.

Header

1.0\Sercx.h

IRQL

Called at IRQL <= DISPATCH_LEVEL

See also

EvtDriverDeviceAdd
SerCxInitialize
WdfDpcEnqueue

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft