SerCx2SystemDmaReceiveCreate function (sercx.h)
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 |
|---|---|
|
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. |
|
The Config->Size value does not equal sizeof(SERCX2_SYSTEM_DMA_RECEIVE_CONFIG). |
|
A parameter value is not valid. |
|
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 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 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 |
See also
EvtSerCx2SystemDmaReceiveCancelNewDataNotification
EvtSerCx2SystemDmaReceiveCleanupTransaction
EvtSerCx2SystemDmaReceiveEnableNewDataNotification
EvtSerCx2SystemDmaReceiveInitializeTransaction
SERCX2_SYSTEM_DMA_RECEIVE_CONFIG
SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT