EVT_SERCX2_SYSTEM_DMA_TRANSMIT_PURGE_FIFO callback function (sercx.h)

Статья
10/21/2021

The EvtSerCx2SystemDmaTransmitPurgeFifo event callback function is called by version 2 of the serial framework extension (SerCx2) to discard any bytes of unsent data that remain in the transmit FIFO in the serial controller hardware.

Syntax

EVT_SERCX2_SYSTEM_DMA_TRANSMIT_PURGE_FIFO EvtSercx2SystemDmaTransmitPurgeFifo;

void EvtSercx2SystemDmaTransmitPurgeFifo(
  [in] SERCX2SYSTEMDMATRANSMIT SystemDmaTransmit,
  [in] ULONG BytesAlreadyTransmittedToHardware
)
{...}

Parameters

[in] SystemDmaTransmit

A SERCX2SYSTEMDMATRANSMIT handle to a system-DMA-transmit object. The serial controller driver previously called the SerCx2SystemDmaTransmitCreate method to create this object.

[in] BytesAlreadyTransmittedToHardware

The number of bytes that have already been loaded into the transmit FIFO during the current system-DMA-transmit transaction.

Return value

None

Remarks

Your serial controller driver can, as an option, implement this function. If implemented, the driver registers the function in the SerCx2SystemDmaTransmitCreate call that creates the system-DMA-transmit object.

Your driver should implement an EvtSerCx2SystemDmaTransmitPurgeFifo function if the serial controller has a hardware FIFO (or similar buffering mechanism) to hold transmit data. If your driver implements this function, it must also implement the EvtSerCx2SystemDmaTransmitDrainFifo and EvtSerCx2SystemDmaTransmitCancelDrainFifo event callback functions.

If a pending write (IRP_MJ_WRITE) request times out or is canceled, SerCx2 might need to terminate the current system-DMA transaction before it finishes. After the transaction is terminated, SerCx2 calls the EvtSerCx2SystemDmaTransmitPurgeFifo function, if it is implemented.

The EvtSerCx2SystemDmaTransmitPurgeFifo function halts the transfer of data from the write buffer to the transmit FIFO, and discards any previously transferred data that remains in the FIFO. After the transmit transaction is terminated, the driver must call the SerCx2SystemDmaTransmitPurgeFifoComplete method to notify SerCx2 that the FIFO was purged, and SerCx2 then completes the write request.

For more information, see SerCx2 System-DMA-Transmit Transactions.

Examples

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

EVT_SERCX2_SYSTEM_DMA_TRANSMIT_PURGE_FIFO  MySystemDmaTransmitPurgeFifo;

Then, implement your callback function as follows:

_Use_decl_annotations_
VOID
  MySystemDmaTransmitPurgeFifo(
    SERCX2SYSTEMDMATRANSMIT  SystemDmaTransmit,
    ULONG BytesAlreadyTransmittedToHardware
    )
  {...}

The EVT_SERCX2_SYSTEM_DMA_TRANSMIT_PURGE_FIFO 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_SYSTEM_DMA_TRANSMIT_PURGE_FIFO 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.

Поделиться через