Функция SerCx2SystemDmaReceiveCreate (sercx.h)

Статья
10/30/2024

Метод SerCx2SystemDmaReceiveCreate создает объект serCx2 system-DMA-receive, который версии 2 расширения последовательной платформы (SerCx2) использует для выполнения транзакций получения системы DMA..

Синтаксис

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 вызывает эти функции для выполнения транзакций получения системных данных DMA.

[in, optional] Attributes

Указатель на структуру WDF_OBJECT_ATTRIBUTES, описывающую атрибуты для назначения новому объекту system-DMA-receive. Перед вызовом этого метода вызывающий объект должен вызвать функцию WDF_OBJECT_ATTRIBUTES_INIT для инициализации структуры. Этот параметр является необязательным и может быть указан как WDF_NO_OBJECT_ATTRIBUTES если драйвер последовательного контроллера не должен назначать атрибуты объекту. Дополнительные сведения см. в разделе "Примечания".

[out] SystemDmaReceive

Указатель на расположение, в которое этот метод записывает SERCX2SYSTEMDMARECEIVE дескриптор в только что созданный объект -DMA-receive. SerCx2 и драйвер последовательного контроллера используют этот дескриптор в последующих вызовах для ссылки на этот объект.

Возвращаемое значение

Этот метод возвращает STATUS_SUCCESS, если вызов выполнен успешно. Возможные значения возвращаемых ошибок включают следующие коды состояния.

Возвращаемый код	Описание
STATUS_INVALID_DEVICE_REQUEST	Объект system-DMA-receive уже существует из предыдущего вызова SerCx2SystemDmaReceiveCreate; или объект пользовательского получения уже существует из предыдущего вызова метода SerCx2CustomReceiveCreate; или объект пользовательской передачи существует из предыдущего вызова метода SerCx2CustomTransmitCreate; или SerCx2PioReceiveCreate еще не вызывается для создания объекта PIO-receive.
STATUS_INFO_LENGTH_MISMATCH	Значение размера конфигурациине равно размеру(SERCX2_SYSTEM_DMA_RECEIVE_CONFIG).
STATUS_INVALID_PARAMETER	Недопустимое значение параметра.
STATUS_INSUFFICIENT_RESOURCES	Недостаточно ресурсов для выполнения запрошенной операции.

Замечания

Этот метод вызывается драйвером последовательного контроллера для создания объекта system-DMA-receive. SerCx2 использует этот объект для выполнения транзакций приема системы DMA, которые являются транзакциями ввода-вывода, которые используют системный контроллер DMA для чтения данных, полученных последовательным контроллером.

Как правило, драйвер последовательного контроллера вызывает SerCx2SystemDmaReceiveCreate из функции обратного вызова EvtDevicePrepareHardware функции обратного вызова. Эта функция получает список аппаратных ресурсов, которые могут включать системные каналы DMA.

Драйвер последовательного контроллера должен успешно вызывать методы SerCx2InitializeDevice и SerCx2PioReceiveCreate перед вызовом SerCx2SystemDmaReceiveCreate.

Перед вызовом SerCx2SystemDmaReceiveCreateдрайвер последовательного контроллера должен вызвать функцию SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT или SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT_NEW_DATA_NOTIFICATION, чтобы инициализировать структуру SERCX2_SYSTEM_DMA_RECEIVE_CONFIG, на которую указывает systemDmaReceiveConfig. Эти функции задают следующие элементы структуры равным нулю:

MaximumScatterGatherFragments
MinimumTransferUnitOverride
DmaAlignment
MinimumTransactionLength
эксклюзивные

При необходимости драйвер последовательного контроллера может задать для любого из этих элементов ненулевое значение после возврата функции инициализации. Однако для удобства SerCx2SystemDmaReceiveCreate использует следующие значения по умолчанию, если эти члены равны нулю:

Если MaximumScatterGatherFragments равно нулю, SerCx2 задает максимальное количество элементов в списке точечной и сборной ((ULONG)-1).
Если MinimumTransferUnitOverride равно нулю, SerCx2 задает минимальное значение единицы передачи по умолчанию, указанное в структуре DMA_ADAPTER для контроллера DMA системы. Дополнительные сведения об этой структуре см. в WdfDmaEnablerWdmGetDmaAdapter.
Если DmaAlignment равно нулю, SerCx2 задает значение выравнивания минимальной единице передачи. Если MinimumTransferUnitOverride равно нулю, используется минимальная единица передачи по умолчанию.
Если MinimumTransactionLength равно нулю, SerCx2 задает минимальную длину транзакции в один байт.
Если монопольная равно нулю (FALSE), монопольный режим отключен.

Если вызывающий драйвер задает монопольную значение TRUE, члены MinimumTransferUnitOverride, DmaAlignmentи MinimumTransactionLength элементов должны быть нулевыми. Дополнительные сведения см. в SERCX2_SYSTEM_DMA_RECEIVE_CONFIG.

Если указанное сочетание реализованных функций обратного вызова недопустимо, SerCx2SystemDmaReceiveCreate завершается ошибкой и возвращает STATUS_INVALID_PARAMETER. Драйвер должен реализовать оба или ни один из EvtSerCx2SystemDmaReceiveEnableNewDataNotification и EvtSerCx2SystemDmaReceiveCancelNewDataNotification функций.

В качестве параметра драйвер последовательного контроллера может использовать параметр Атрибуты для создания контекста для объекта-получения system-DMA, а также для предоставления указателей на EvtCleanupCallback и Функции EvtDedataCallback, которые вызываются для подготовки объекта к удалению. Дополнительные сведения см. в разделе WDF_OBJECT_ATTRIBUTES.

Если параметр атрибутов указывает на структуру WDF_OBJECT_ATTRIBUTES, вызывающий объект не должен перезаписать значения, которые функция инициализации WDF_OBJECT_ATTRIBUTES_INIT записывает в ParentObject, ExecutionLevelи syncScope членов этой структуры.

Дополнительные сведения о создании объектов system-DMA-receive см. в SERCX2SYSTEMDMARECEIVE. Дополнительные сведения о транзакциях, получаемых системой DMA, см. в SerCx2 System-DMA-Receive Транзакций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Доступно начиная с Windows 8.1.
целевая платформа	Всеобщий
заголовка	sercx.h
IRQL	PASSIVE_LEVEL