EVT_SERCX2_SYSTEM_DMA_RECEIVE_INITIALIZE_TRANSACTION callback function (sercx.h)

Articolo
10/21/2021

The EvtSerCx2EvtSerCx2SystemDmaReceiveInitializeTransaction event callback function is called by version 2 of the serial framework extension (SerCx2) to prepare the serial controller driver to perform a system-DMA-receive transaction.

Syntax

EVT_SERCX2_SYSTEM_DMA_RECEIVE_INITIALIZE_TRANSACTION EvtSercx2SystemDmaReceiveInitializeTransaction;

void EvtSercx2SystemDmaReceiveInitializeTransaction(
  [in] SERCX2SYSTEMDMARECEIVE SystemDmaReceive,
  [in] ULONG Length
)
{...}

Parameters

[in] SystemDmaReceive

A SERCX2SYSTEMDMARECEIVE handle to a system-DMA-receive object. The serial controller driver previously called the SerCx2SystemDmaReceiveCreate method to create this object.

[in] Length

The number of bytes to be transferred in the system-DMA-receive 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 SerCx2SystemDmaReceiveCreate call that creates the system-DMA-receive object.

Your driver should implement an EvtSerCx2EvtSerCx2SystemDmaReceiveInitializeTransaction function if it needs to initialize the serial controller and associated hardware in preparation for a new system-DMA-receive transaction. SerCx2 calls this function, if it is implemented, before a system-DMA-receive transaction starts. In response to this call, the serial controller driver must call the SerCx2SystemDmaReceiveInitializeTransactionComplete method to notify SerCx2 after the initialization is finished.

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

Examples

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

EVT_SERCX2_SYSTEM_DMA_RECEIVE_INITIALIZE_TRANSACTION  MySystemDmaReceiveInitializeTransaction;

Then, implement your callback function as follows:

_Use_decl_annotations_
VOID
  MySystemDmaReceiveInitializeTransaction(
    SERCX2SYSTEMDMARECEIVE  SystemDmaReceive,
    ULONG  Length
    )
  {...}

The EVT_SERCX2_SYSTEM_DMA_RECEIVE_INITIALIZE_TRANSACTION 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_RECEIVE_INITIALIZE_TRANSACTION 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.

Condividi tramite