Skip to content

Latest commit

 

History

History
110 lines (75 loc) · 6.07 KB

nc-sercx-evt_sercx2_system_dma_transmit_initialize_transaction.md

File metadata and controls

110 lines (75 loc) · 6.07 KB
Raw
UID title description old-location tech.root ms.date keywords ms.keywords req.header req.include-header req.target-type req.target-min-winverclnt req.target-min-winversvr req.kmdf-ver req.umdf-ver req.ddi-compliance req.unicode-ansi req.idl req.max-support req.namespace req.assembly req.type-library req.lib req.dll req.irql targetos req.typenames f1_keywords topic_type api_type api_location api_name
NC:sercx.EVT_SERCX2_SYSTEM_DMA_TRANSMIT_INITIALIZE_TRANSACTION
EVT_SERCX2_SYSTEM_DMA_TRANSMIT_INITIALIZE_TRANSACTION (sercx.h)
The EvtSerCx2SystemDmaTransmitInitializeTransaction 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-transmit transaction.
serports\evtsercx2systemdmatransmitinitializetransaction.htm
serports
04/23/2018
EVT_SERCX2_SYSTEM_DMA_TRANSMIT_INITIALIZE_TRANSACTION callback function
2/EvtSerCx2SystemDmaTransmitInitializeTransaction, EVT_SERCX2_SYSTEM_DMA_TRANSMIT_INITIALIZE_TRANSACTION, EVT_SERCX2_SYSTEM_DMA_TRANSMIT_INITIALIZE_TRANSACTION callback, EvtSerCx2SystemDmaTransmitInitializeTransaction, EvtSerCx2SystemDmaTransmitInitializeTransaction callback function [Serial Ports], serports.evtsercx2systemdmatransmitinitializetransaction
sercx.h
Desktop
Available starting with Windows 8.1.
Called at IRQL <= DISPATCH_LEVEL.
Windows
EVT_SERCX2_SYSTEM_DMA_TRANSMIT_INITIALIZE_TRANSACTION
sercx/EVT_SERCX2_SYSTEM_DMA_TRANSMIT_INITIALIZE_TRANSACTION
APIRef
kbSyntax
UserDefined
2.0\Sercx.h
EVT_SERCX2_SYSTEM_DMA_TRANSMIT_INITIALIZE_TRANSACTION

EVT_SERCX2_SYSTEM_DMA_TRANSMIT_INITIALIZE_TRANSACTION callback function

-description

The EvtSerCx2SystemDmaTransmitInitializeTransaction 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-transmit transaction.

-parameters

-param SystemDmaTransmit [in]

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

-param Length [in]

The number of bytes to be transferred in the system-DMA-transmit transaction.

-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 EvtSerCx2SystemDmaTransmitInitializeTransaction function if it needs to initialize the serial controller and associated hardware in preparation for a new system-DMA-transmit transaction. SerCx2 calls this function, if it is implemented, before a system-DMA-transmit transaction starts. In response to this call, the serial controller driver must call the SerCx2SystemDmaTransmitInitializeTransactionComplete method to notify SerCx2 after the initialization is finished.

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

Examples

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

EVT_SERCX2_SYSTEM_DMA_TRANSMIT_INITIALIZE_TRANSACTION  MySystemDmaTransmitInitializeTransaction;

Then, implement your callback function as follows:

_Use_decl_annotations_
VOID
  MySystemDmaTransmitInitializeTransaction(
    SERCX2SYSTEMDMATRANSMIT  SystemDmaTransmit,
    ULONG Length
    )
  {...}

The EVT_SERCX2_SYSTEM_DMA_TRANSMIT_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_TRANSMIT_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.

-see-also

SERCX2SYSTEMDMATRANSMIT

SerCx2SystemDmaTransmitCreate

SerCx2SystemDmaTransmitInitializeTransactionComplete