EVT_SERCX2_CUSTOM_TRANSMIT_TRANSACTION_START callback function (sercx.h)

Article
10/21/2021

The EvtSerCx2CustomTransmitTransactionStart event callback function is called by version 2 of the serial framework extension (SerCx2) to start a custom-transmit transaction.

Syntax

EVT_SERCX2_CUSTOM_TRANSMIT_TRANSACTION_START EvtSercx2CustomTransmitTransactionStart;

void EvtSercx2CustomTransmitTransactionStart(
  [in] SERCX2CUSTOMTRANSMITTRANSACTION CustomTransmitTransaction,
  [in] WDFREQUEST Request,
  [in] PMDL Mdl,
  [in] ULONG Offset,
  [in] ULONG Length
)
{...}

Parameters

[in] CustomTransmitTransaction

A SERCX2CUSTOMTRANSMITTRANSACTION handle to a custom-transmit-transaction object. The serial controller driver previously called the SerCx2CustomTransmitTransactionCreate method to create this object.

[in] Request

A handle to the framework request object associated with the custom-transmit transaction. The driver is responsible for completing this request. This request might not be the IRP_MJ_WRITE request sent by the client, and thus the serial controller driver should not try to use this request to access the write buffer. This request is primarily used for cancellation, completion, and queue forwarding (if needed). To access the write buffer for the client's write request, use the Mdl, Offset, and Length parameters.

[in] Mdl

A pointer to an MDL that describes the memory pages that are spanned by the write buffer for the custom-transmit transaction. The scatter/gather list for the DMA transfer will use the region of this memory that is specified by the Offset and Length parameters. For more information about MDL chains, see Using MDLs.

[in] Offset

The starting offset for the data transfer. This parameter is a byte offset from the start of the buffer region described by the MDL. If the MDL specifies a total of N bytes of buffer space, possible values of Offset are in the range 0 to N–1.

[in] Length

The size, in bytes, of the data transfer. If the MDL specifies a total of N bytes of buffer space, possible values of Length are in the range 1 to N–Offset.

Return value

None

Remarks

Your serial controller driver must implement this function if it creates a custom-transmit-transaction object. If implemented, the driver registers the function in the SerCx2CustomTransmitTransactionCreate call that creates this object.

After SerCx2 calls the EvtSerCx2CustomTransmitTransactionStart function, the serial controller driver initiates the transaction by programming the custom data-transfer mechanism to move data from the buffer in the write request to the transmit FIFO in the serial controller hardware. Unless the request can be completed immediately, before the EvtSerCx2CustomTransmitTransactionStart function returns, the driver must call a method such as WdfRequestMarkCancelableEx to mark the request as cancelable.

After the transaction finishes and the driver completes the pending write request, SerCx2 calls the EvtSerCx2CustomTransmitTransactionCleanup event callback function, if the driver implements this function.

If the serial controller driver implements an EvtSerCx2CustomTransmitTransactionInitialize event callback function, SerCx2 calls this function before calling the EvtSerCx2CustomTransmitTransactionStart function. Just before the EvtSerCx2CustomTransmitTransactionStart call, and after the EvtSerCx2CustomTransmitTransactionInitialize call returns, SerCx2 starts the timer that detects whether the write request times out. For more information, see the discussion of total time-outs in SERIAL_TIMEOUTS.

The serial controller driver should complete the pending write request only after the last byte in the transmit FIFO has been transmitted to the serially connected peripheral device. There can be no guarantee that data written to the transmit FIFO will be transmitted without a significant delay, and a serial controller driver that assumes that such a guarantee exists can cause reliability problems for peripheral drivers.

If the custom data-transfer mechanism is a bus-master DMA device, the EvtSerCx2CustomTransmitTransactionStart function can call a method such as WdfDmaTransactionInitializeUsingOffset to initiate a DMA transaction that uses the write buffer described by the Mdl, Offset, and Length parameters.

For more information about the Mdl, Offset, and Length parameters, see Remarks in EvtSerCx2CustomTransmitTransactionInitialize.

If the request object identified by the Request parameter contains storage for a private context, this storage might be uninitialized the first time the serial controller driver accesses the context. On first access, the driver typically should fill the context with zeros, and then, if needed, explicitly set any fields in the context that require nonzero initial values.

For more information, see SerCx2 Custom-Transmit Transactions.

Examples

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

EVT_SERCX2_CUSTOM_TRANSMIT_TRANSACTION_START  MyCustomTransmitTransactionStart;

Then, implement your callback function as follows:

_Use_decl_annotations_
VOID
  MyCustomTransmitTransactionStart(
    SERCX2CUSTOMTRANSMITTRANSACTION  CustomTransmitTransaction,
    WDFREQUEST  Request,
    PMDL  Mdl,
    ULONG  Offset,
    ULONG  Length
    )
  {...}

The EVT_SERCX2_CUSTOM_TRANSMIT_TRANSACTION_START 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_CUSTOM_TRANSMIT_TRANSACTION_START 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.