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
STATUS_INVALID_DEVICE_REQUEST
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.
STATUS_INFO_LENGTH_MISMATCH
The Config->Size value does not equal sizeof(SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG).
STATUS_INVALID_PARAMETER
A parameter value is not valid.
STATUS_INSUFFICIENT_RESOURCES
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 necessary, the serial controller driver can set any of these members to nonzero values after the initialization function returns. However, for convenience, SerCx2SystemDmaTransmitCreate 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_TRANSMIT_CONFIG.

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

DMA_ADAPTER

EvtCleanupCallback

EvtDestroyCallback

EvtDevicePrepareHardware

EvtDriverDeviceAdd

EvtSerCx2SystemDmaTransmitCancelDrainFifo

EvtSerCx2SystemDmaTransmitCleanupTransaction

EvtSerCx2SystemDmaTransmitDrainFifo

EvtSerCx2SystemDmaTransmitInitializeTransaction

EvtSerCx2SystemDmaTransmitPurgeFifo

SERCX2SYSTEMDMATRANSMIT

SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG

SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG_INIT

SerCx2InitializeDevice

SerCx2PioTransmitCreate

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT

WdfDmaEnablerWdmGetDmaAdapter