SerCx2SystemDmaTransmitCreate function (sercx.h)
The SerCx2SystemDmaTransmitCreate method creates a SerCx2 system-DMA-transmit object, which version 2 of the serial framework extension (SerCx2) uses to perform system-DMA-transmit transactions.
Syntax
NTSTATUS SerCx2SystemDmaTransmitCreate(
[in] WDFDEVICE Device,
[in] PSERCX2_SYSTEM_DMA_TRANSMIT_CONFIG SystemDmaTransmitConfig,
[in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
[out] SERCX2SYSTEMDMATRANSMIT *SystemDmaTransmit
);
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] SystemDmaTransmitConfig
A pointer to a SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG structure. Before calling this method, the caller must call the SERCX2_SYSTEM_DMA_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 system-DMA-transmit transactions.
[in, optional] Attributes
A pointer to a WDF_OBJECT_ATTRIBUTES structure that describes the attributes to assign to the new system-DMA-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] SystemDmaTransmit
A pointer to a location to which this method writes a SERCX2SYSTEMDMATRANSMIT handle to the newly created system-DMA-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 |
|---|---|
|
A system-DMA-transmit object already exists from a previous SerCx2SystemDmaTransmitCreate call; or a custom-transmit object exists from a previous call to the SerCx2CustomTransmitCreate method; or a custom-receive object exists from a previous call to the SerCx2CustomReceiveCreate method; or SerCx2PioTransmitCreate has not yet been called to create a PIO-transmit object. |
|
The Config->Size value does not equal sizeof(SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG). |
|
A parameter value is not valid. |
|
Insufficient resources are available to create the system-DMA-transmit object. |
Remarks
Your serial controller driver can this method to create a system-DMA-transmit object. SerCx2 uses this object to perform system-DMA-transmit transactions, which are transactions that use the system DMA controller to write data to the serial controller to be transmitted.
Typically, a serial controller driver calls SerCx2SystemDmaTransmitCreate from its EvtDevicePrepareHardware callback function. This function receives a list of hardware resources, which can include system DMA channels.
The serial controller driver must successfully call the SerCx2InitializeDevice and SerCx2PioTransmitCreate methods before calling SerCx2SystemDmaTransmitCreate.
Before calling SerCx2SystemDmaTransmitCreate, the serial controller driver must call the SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG_INIT function to initialize the SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG structure pointed to by SystemDmaTransmitConfig. This function sets 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, SerCx2SystemDmaTransmitCreate fails and returns STATUS_INVALID_PARAMETER. The driver must implement either all three or none of the EvtSerCx2SystemDmaTransmitDrainFifo, EvtSerCx2SystemDmaTransmitCancelDrainFifo, and EvtSerCx2SystemDmaTransmitPurgeFifo functions.
As an option, a serial controller driver can use the Attributes parameter to create a context for the system-DMA-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 system-DMA-transmit objects, see SERCX2SYSTEMDMATRANSMIT. For more information about system-DMA-transmit transactions, see SerCx2 System-DMA-Transmit Transactions.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Available starting with Windows 8.1. |
| Target Platform | Universal |
| Header | sercx.h |
| IRQL | PASSIVE_LEVEL |
See also
EvtSerCx2SystemDmaTransmitCancelDrainFifo
EvtSerCx2SystemDmaTransmitCleanupTransaction
EvtSerCx2SystemDmaTransmitDrainFifo
EvtSerCx2SystemDmaTransmitInitializeTransaction
EvtSerCx2SystemDmaTransmitPurgeFifo
SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG