SerCx2SystemDmaReceiveCreate function (sercx.h)

Article
10/21/2021

The SerCx2SystemDmaReceiveCreate method creates a SerCx2 system-DMA-receive object, which version 2 of the serial framework extension (SerCx2) uses to perform system-DMA-receive transactions.

Syntax

NTSTATUS SerCx2SystemDmaReceiveCreate(
  [in]           WDFDEVICE                         Device,
  [in]           PSERCX2_SYSTEM_DMA_RECEIVE_CONFIG SystemDmaReceiveConfig,
  [in, optional] PWDF_OBJECT_ATTRIBUTES            Attributes,
  [out]          SERCX2SYSTEMDMARECEIVE            *SystemDmaReceive
);

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] SystemDmaReceiveConfig

A pointer to a SERCX2_SYSTEM_DMA_RECEIVE_CONFIG structure. Before calling this method, the caller must call the SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT or SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT_NEW_DATA_NOTIFICATION 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 system-DMA-receive transactions.

[in, optional] Attributes

A pointer to a WDF_OBJECT_ATTRIBUTES structure that describes the attributes to assign to the new system-DMA-receive 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] SystemDmaReceive

A pointer to a location to which this method writes a SERCX2SYSTEMDMARECEIVE handle to the newly created system-DMA-receive 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 system-DMA-receive object already exists from a previous SerCx2SystemDmaReceiveCreate call; or a custom-receive object already exists from a previous call to the SerCx2CustomReceiveCreate method; or a custom-transmit object exists from a previous call to the SerCx2CustomTransmitCreate method; or SerCx2PioReceiveCreate has not yet been called to create a PIO-receive object.
STATUS_INFO_LENGTH_MISMATCH	The Config->Size value does not equal sizeof(SERCX2_SYSTEM_DMA_RECEIVE_CONFIG).
STATUS_INVALID_PARAMETER	A parameter value is not valid.
STATUS_INSUFFICIENT_RESOURCES	Insufficient resources are available to perform the requested operation.

Remarks

This method is called by the serial controller driver to create a system-DMA-receive object. SerCx2 uses this object to perform system-DMA-receive transactions, which are I/O transactions that use the system DMA controller to read data received by the serial controller.

Typically, a serial controller driver calls SerCx2SystemDmaReceiveCreate from its EvtDevicePrepareHardware callback function. This function receives a list of hardware resources, which can include system DMA channels.

A serial controller driver must successfully call the SerCx2InitializeDevice and SerCx2PioReceiveCreate methods before calling SerCx2SystemDmaReceiveCreate.

Before calling SerCx2SystemDmaReceiveCreate, the serial controller driver must call the SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT or SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT_NEW_DATA_NOTIFICATION function to initialize the SERCX2_SYSTEM_DMA_RECEIVE_CONFIG structure pointed to by SystemDmaReceiveConfig. These functions set the following members of the structure to zero:

MaximumScatterGatherFragments
MinimumTransferUnitOverride
DmaAlignment
MinimumTransactionLength
Exclusive

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

If MaximumScatterGatherFragments is zero, SerCx2 sets the maximum number of elements in a scatter/gather list to ((ULONG)-1).
If MinimumTransferUnitOverride is zero, SerCx2 sets the minimum transfer unit to its default value, which is specified in the DMA_ADAPTER structure for the system DMA controller. For more information about this structure, see WdfDmaEnablerWdmGetDmaAdapter.
If DmaAlignment is zero, SerCx2 sets the alignment value to the minimum transfer unit. If MinimumTransferUnitOverride is zero, the default minimum transfer unit is used.
If MinimumTransactionLength is zero, SerCx2 sets the minimum transaction length to one byte.
If Exclusive is zero (FALSE), exclusive mode is disabled.

If the calling driver sets Exclusive to TRUE, the MinimumTransferUnitOverride, DmaAlignment, and MinimumTransactionLength members must be zero. For more information, see SERCX2_SYSTEM_DMA_RECEIVE_CONFIG.

If the specified combination of implemented callback functions is not valid, SerCx2SystemDmaReceiveCreate fails and returns STATUS_INVALID_PARAMETER. The driver must implement either both or neither of the EvtSerCx2SystemDmaReceiveEnableNewDataNotification and EvtSerCx2SystemDmaReceiveCancelNewDataNotification functions.

As an option, a serial controller driver can use the Attributes parameter to create a context for the system-DMA-receive 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 system-DMA-receive objects, see SERCX2SYSTEMDMARECEIVE. For more information about system-DMA-receive transactions, see SerCx2 System-DMA-Receive Transactions.

Requirements

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