EVT_SERCX_WAITMASK callback function (sercx.h)

Article
10/21/2021

The EvtSerCxWaitmask event callback function configures the serial controller to monitor the events in a wait mask, which is a bitmask value that specifies a set of hardware events.

Syntax

EVT_SERCX_WAITMASK EvtSercxWaitmask;

NTSTATUS EvtSercxWaitmask(
  [in] WDFDEVICE Device
)
{...}

Parameters

[in] Device

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

Return value

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

Remarks

The serial controller driver implements this callback function. The serial framework extension (SerCx) calls this function to notify the driver when the wait mask changes. During this call, the EvtSerCxWaitmask function calls the SerCxGetWaitMask method to get the new wait mask. The driver immediately starts to monitor the events in the new wait mask, and discards any old wait mask that might have been supplied in a previous EvtSerCxWaitmask call. If the new wait mask is zero, the driver simply discards the old wait mask and ceases to monitor any wait mask events.

When SerCx receives an IOCTL_SERIAL_SET_WAIT_MASK request from a client, the request handler in SerCx calls the EvtSerCxWaitmask function to set the new wait mask. For more information about the types of events that can be specified by a wait mask, see SERIAL_EV_XXX.

The EvtSerCxWaitmask function configures the serial controller hardware to monitor the events in the new wait mask. Typically, the function enables interrupts for these events. After configuring the hardware, the function should return immediately, without waiting for an event in the wait mask to occur.

Later, when an event in the wait mask causes an interrupt to occur, the ISR in the serial controller driver schedules a DPC function to run. This DPC function calls the SerCxCompleteWait method to notify SerCx of the event.

Initially, after a client opens a connection to the serial port and before the first EvtSerCxWaitmask call, the wait mask is effectively zero, and the serial controller driver is not monitoring any SERIAL_EV_XXX events.

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

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

EVT_SERCX_WAITMASK MyEvtSerCxWaitmask;

Then, implement your callback function as follows.

NTSTATUS
  MyEvtSerCxWaitmask(
    __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