SerCx2CustomTransmitCreate function (sercx.h)

Article
10/21/2021

The SerCx2CustomTransmitCreate method creates a custom-transmit object, which version 2 of the serial framework extension (SerCx2) uses to write transmit data to the serial controller by means of a custom data-transfer mechanism.

Syntax

NTSTATUS SerCx2CustomTransmitCreate(
  [in]  WDFDEVICE                      Device,
  [in]  PSERCX2_CUSTOM_TRANSMIT_CONFIG CustomTransmitConfig,
  [in]  PWDF_OBJECT_ATTRIBUTES         Attributes,
  [out] SERCX2CUSTOMTRANSMIT           *CustomTransmit
);

Parameters

[in] Device

A WDFDEVICE handle to the framework device object that represents the serial controller. The serial controller driver created this object in its EvtDriverDeviceAdd callback function. For more information, see SerCx2InitializeDevice.

[in] CustomTransmitConfig

A pointer to a SERCX2_CUSTOM_TRANSMIT_CONFIG structure. Before calling this method, the caller must call the SERCX2_CUSTOM_TRANSMIT_CONFIG_INIT function to initialize the structure. This structure contains pointers to a set of event callback routines that are implemented by the serial controller driver. SerCx2 calls these functions to perform custom-transmit transactions.

[in] Attributes

A pointer to a WDF_OBJECT_ATTRIBUTES structure that describes the attributes to assign to the new custom-transmit object. Before calling this method, the caller must call the WDF_OBJECT_ATTRIBUTES_INIT function to initialize the structure. This parameter is optional and can be specified as WDF_NO_OBJECT_ATTRIBUTES if the serial controller driver does not need to assign attributes to the object. For more information, see Remarks.

[out] CustomTransmit

A pointer to a location to which this method writes a SERCX2CUSTOMTRANSMIT handle to the newly created custom-transmit object. SerCx2 and the serial controller driver use this handle in subsequent calls to refer to this object.

Return value

This method returns STATUS_SUCCESS if the call is successful. Possible error return values include the following status codes.

Return code	Description
STATUS_INVALID_DEVICE_REQUEST	A custom-transmit object already exists from a previous SerCx2CustomTransmitCreate call; or a system-DMA-transmit object exists from a previous SerCx2SystemDmaTransmitCreate call; or a system-DMA-transmit object exists from a previous SerCx2SystemDmaTransmitCreate call; or SerCx2PioTransmitCreate has not yet been called to create a PIO-transmit object.
STATUS_INVALID_PARAMETER	A parameter value is not valid.
STATUS_INFO_LENGTH_MISMATCH	The Config->Size value does not equal sizeof(SERCX2_CUSTOM_TRANSMIT_CONFIG).
STATUS_INSUFFICIENT_RESOURCES	Insufficient resources are available to create the custom-transmit object.

Remarks

This method is called by the serial controller driver to create a custom-transmit object. SerCx2 uses this object to perform custom-transmit transactions, which are transactions that use a custom data-transfer mechanism to write transmit data to the serial controller.

A serial controller driver must successfully call the SerCx2InitializeDevice and SerCx2PioTransmitCreate methods before calling SerCx2CustomTransmitCreate.

Before calling SerCx2CustomTransmitCreate, the serial controller driver must call the SERCX2_CUSTOM_TRANSMIT_CONFIG_INIT function to initialize the SERCX2_CUSTOM_TRANSMIT_CONFIG structure pointed to by CustomTransmitConfig. This function sets the following members of the structure to zero:

Alignment
MinimumTransactionLength
MaximumTransactionLength
MinimumTransferUnit
Exclusive

If necessary, the serial controller driver can set any of these members to nonzero values after the initialization function returns. However, for convenience, SerCx2CustomTransmitCreate uses the following default values if these members are zero:

If Alignment is zero, SerCx2 sets the data alignment value to one, which means the write buffer can start on an arbitrary byte boundary in memory.
If MinimumTransactionLength is zero, SerCx2 sets the minimum transaction length to one byte.
If MaximumTransactionLength is zero, SerCx2 sets the maximum transaction length to ((ULONG)-1).
If MinimumTransferUnit is zero, SerCx2 sets the minimum transfer unit to one byte.
If Exclusive is zero (FALSE), exclusive mode is disabled.

If the calling driver sets Exclusive to TRUE, the MinimumTransferUnit, Alignment, and MinimumTransactionLength members must be zero. For more information, see SERCX2_CUSTOM_TRANSMIT_CONFIG.

As an option, a serial controller driver can use the Attributes parameter to create a context for the custom-transmit object, and to supply pointers to EvtCleanupCallback and EvtDestroyCallback functions that are called to prepare the object for deletion. For more information, see WDF_OBJECT_ATTRIBUTES.

If the Attributes parameter points to a WDF_OBJECT_ATTRIBUTES structure, the caller must not overwrite the values that the WDF_OBJECT_ATTRIBUTES_INIT initialization function writes to the ParentObject, ExecutionLevel, and SynchronizationScope members of this structure.

For more information about creating custom-transmit objects, see SERCX2CUSTOMTRANSMIT. For more information about custom-transmit transactions, see SerCx2 Custom-Transmit Transactions.

Requirements

Requirement	Value
Minimum supported client	Available starting with Windows 8.1.
Target Platform	Universal
Header	sercx.h
IRQL	PASSIVE_LEVEL