EVT_SERCX_TRANSMIT callback function (sercx.h)

Article
02/22/2024

The EvtSerCxTransmit event callback function prepares the serial controller device (UART) to do a write (transmit) operation.

Syntax

EVT_SERCX_TRANSMIT EvtSercxTransmit;

NTSTATUS EvtSercxTransmit(
  [in] WDFDEVICE Device,
  [in] size_t Length
)
{...}

Parameters

[in] Device

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

[in] Length

The number of bytes to be transmitted. 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 EvtSerCxTransmit 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 serial controller hardware to transmit data. If necessary, the EvtSerCxTransmit function can enable interrupts.

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

If the transmit FIFO in the serial controller is full or nearly full, but the FIFO's low-water-mark interrupt is enabled, the EvtSerCxTransmit function can simply return. Later, the controller driver's ISR can schedule the transmit/receive DPC function to run, and this function can transfer more output data to the transmit FIFO.

To register an EvtSerCxTransmit 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_TRANSMIT(
    __in WDFDEVICE Device
    );

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

EVT_SERCX_TRANSMIT MyEvtSerCxTransmit;

Then, implement your callback function as follows.

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

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

Requirements

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