SerCxFifoMustEmpty method

[This documentation is preliminary and is subject to change.]

The SerCxFifoMustEmpty method notifies the serial framework extension (SerCx) that the receive FIFO in the serial controller device (UART) is partially full and must be emptied to prevent a possible FIFO overflow.

Syntax

SERCX_DPC_WORK SerCxFifoMustEmpty(
  [in]  WDFDEVICE Device,
  [in]  ULONG Length
);

Parameters

  • Device [in]
    A WDFDEVICE handle to the framework device object that represents the serial controller.

  • Length [in]
    The number of bytes of data that the caller wants to transfer from the FIFO to the buffer in memory. The buffer that is retrieved by a subsequent call to the SerCxRetrieveReceiveBuffer method will be no larger than the Length value unless a read request arrives before SerCxRetrieveReceiveBuffer is called.

Return value

SerCxFifoMustEmpty returns an SERCX_DPC_WORK enumeration value that indicates whether the caller can perform the FIFO-to-memory transfer immediately or must delay this transfer until later. For more information, see the following Remarks section.

Remarks

If a read operation is already pending, there is no need to call this method. However, if no read operation is pending and a sufficient amount of data is received from the serial port, the controller driver should call this method to notify SerCx that some or all of the data in the serial controller's receive FIFO should be transferred to a buffer in memory to avoid the risk of data loss.

Typically, SerCxFifoMustEmpty is called from the transmit/receive DPC function in the serial controller driver. This function runs during a DPC and must, therefore, avoid running for excessively long intervals, which would deny use of the processor to other tasks.

The return value from SerCxFifoMustEmpty indicates to the transmit/receive DPC function whether the function has time to perform the FIFO-to-memory transfer immediately, before it relinquishes the processor. The method returns SerCxDpcWorkAvailable if the function can perform the data transfer immediately. The method returns SerCxDpcWorkDelayed if the function has already run for over 100 milliseconds, in which case the function should schedule itself to be called again, during a later DPC, and return.

Requirements

Version

Available starting with Windows 8.

Header

Sercx.h

IRQL

<= DISPATCH_LEVEL

See also

SerCxRetrieveReceiveBuffer

SERCX_DPC_WORK

 

 

Build date: 1/19/2012