SerCx2SystemDmaReceiveCreate 函数 (sercx.h)

项目
02/29/2024

SerCx2SystemDmaReceiveCreate 方法创建 SerCx2 system-DMA-receive 对象，SerCx2) (串行框架扩展的第 2 版用于执行 system-DMA-receive 事务。

语法

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

参数

[in] Device

表示串行控制器的框架设备对象的 WDFDEVICE 句柄。串行控制器驱动程序在其 EvtDriverDeviceAdd 回调函数中创建此对象。有关详细信息，请参阅 SerCx2InitializeDevice。

[in] SystemDmaReceiveConfig

指向 SERCX2_SYSTEM_DMA_RECEIVE_CONFIG 结构的指针。在调用此方法之前，调用方必须调用 SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT 或 SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT_NEW_DATA_NOTIFICATION 函数来初始化结构。此结构包含指向由串行控制器驱动程序实现的一组事件回调例程的指针。 SerCx2 调用这些函数以执行 system-DMA-receive 事务。

[in, optional] Attributes

指向 WDF_OBJECT_ATTRIBUTES 结构的指针，该结构描述要分配给新的 system-DMA-receive 对象的属性。在调用此方法之前，调用方必须调用 WDF_OBJECT_ATTRIBUTES_INIT 函数来初始化结构。此参数是可选的，如果串行控制器驱动程序不需要向对象分配属性，则可以指定为WDF_NO_OBJECT_ATTRIBUTES。有关详细信息，请参阅“备注”。

[out] SystemDmaReceive

指向将 SERCX2SYSTEMDMARECEIVE 句柄写入新创建的 system-DMA-receive 对象的位置的指针。 SerCx2 和串行控制器驱动程序在后续调用中使用此句柄来引用此对象。

返回值

如果调用成功，此方法将返回STATUS_SUCCESS。可能的错误返回值包括以下状态代码。

返回代码	说明
STATUS_INVALID_DEVICE_REQUEST	已存在来自以前的 SerCx2SystemDmaReceiveCreate 调用的 system-DMA-receive 对象;或自定义接收对象已存在于对 SerCx2CustomReceiveCreate 方法的先前调用中;或自定义传输对象存在于对 SerCx2CustomTransmitCreate 方法的先前调用中;或 SerCx2PioReceiveCreate 尚未调用以创建 PIO 接收对象。
STATUS_INFO_LENGTH_MISMATCH	Config->Size 值不等于 (SERCX2_SYSTEM_DMA_RECEIVE_CONFIG) 的大小。
STATUS_INVALID_PARAMETER	参数值无效。
STATUS_INSUFFICIENT_RESOURCES	资源不足，无法执行请求的操作。

注解

此方法由串行控制器驱动程序调用，以创建 system-DMA-receive 对象。 SerCx2 使用此对象执行系统-DMA-receive 事务，即使用系统 DMA 控制器读取串行控制器接收的数据的 I/O 事务。

通常，串行控制器驱动程序从其 EvtDevicePrepareHardware 回调函数调用 SerCx2SystemDmaReceiveCreate。此函数接收硬件资源列表，其中可能包括系统 DMA 通道。

在调用 SerCx2SystemDmaReceiveCreate 之前，串行控制器驱动程序必须成功调用 SerCx2InitializeDevice 和 SerCx2PioReceiveCreate 方法。

在调用 SerCx2SystemDmaReceiveCreate 之前，串行控制器驱动程序必须调用 SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT 或 SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT_NEW_DATA_NOTIFICATION 函数来初始化 SystemDmaReceiveConfig 指向的SERCX2_SYSTEM_DMA_RECEIVE_CONFIG结构。这些函数将结构的以下成员设置为零：

MaximumScatterGatherFragments
MinimumTransferUnitOverride
DmaAlignment
MinimumTransactionLength
独占

如有必要，串行控制器驱动程序可以在初始化函数返回后将其中任何成员设置为非零值。但是，为方便起见，如果这些成员为零， SerCx2SystemDmaReceiveCreate 使用以下默认值：

如果 MaximumScatterGatherFragments 为零，则 SerCx2 将散点/收集列表中的最大元素数设置为 ( (ULONG) -1) 。
如果 MinimumTransferUnitOverride 为零，SerCx2 会将最小传输单元设置为其默认值，该值在系统 DMA 控制器的DMA_ADAPTER 结构中指定。有关此结构的详细信息，请参阅 WdfDmaEnablerWdmGetDmaAdapter。
如果 DmaAlignment 为零，则 SerCx2 将对齐值设置为最小传输单位。如果 MinimumTransferUnitOverride 为零，则使用默认的最小传输单位。
如果 MinimumTransactionLength 为零，则 SerCx2 将最小事务长度设置为 1 字节。
如果 Exclusive 为零 (FALSE) ，则禁用独占模式。

如果调用驱动程序将 Exclusive 设置为 TRUE， 则 MinimumTransferUnitOverride、 DmaAlignment 和 MinimumTransactionLength 成员必须为零。有关详细信息，请参阅 SERCX2_SYSTEM_DMA_RECEIVE_CONFIG。

如果实现的回调函数的指定组合无效， SerCx2SystemDmaReceiveCreate 将失败并返回STATUS_INVALID_PARAMETER。驱动程序必须同时实现或不实现 EvtSerCx2SystemDmaReceiveEnableNewDataNotification 和 EvtSerCx2SystemDmaReceiveCancelNewDataNotification 函数。

作为选项，串行控制器驱动程序可以使用 Attributes 参数为 system-DMA-receive 对象创建上下文，并提供指向 EvtCleanupCallback 和 EvtDestroyCallback 函数的指针，这些函数被调用以准备要删除的对象。有关详细信息，请参阅 WDF_OBJECT_ATTRIBUTES。

如果 Attributes 参数指向 WDF_OBJECT_ATTRIBUTES 结构，则调用方不得覆盖 WDF_OBJECT_ATTRIBUTES_INIT 初始化函数写入此结构的 ParentObject、 ExecutionLevel 和 SynchronizationScope 成员的值。

有关创建 system-DMA-receive 对象的详细信息，请参阅 SERCX2SYSTEMDMARECEIVE。有关 system-DMA-receive 事务的详细信息，请参阅 SerCx2 System-DMA-Receive Transactions。