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

Статья
10/30/2024

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

Синтаксис

NTSTATUS SerCx2SystemDmaTransmitCreate(
  [in]           WDFDEVICE                          Device,
  [in]           PSERCX2_SYSTEM_DMA_TRANSMIT_CONFIG SystemDmaTransmitConfig,
  [in, optional] PWDF_OBJECT_ATTRIBUTES             Attributes,
  [out]          SERCX2SYSTEMDMATRANSMIT            *SystemDmaTransmit
);

Параметры

[in] Device

Дескриптор WDFDEVICE для объекта устройства платформы, представляющего последовательный контроллер. Драйвер последовательного контроллера создал этот объект в своей функции обратного вызова EvtDriverDeviceAdd. Дополнительные сведения см. в разделе SerCx2InitializeDevice.

[in] SystemDmaTransmitConfig

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

[in, optional] Attributes

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

[out] SystemDmaTransmit

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

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

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

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

Замечания

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

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

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

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

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

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

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

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

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

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

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

Дополнительные сведения о создании объектов передачи system-DMA см. в SERCX2SYSTEMDMATRANSMIT. Дополнительные сведения о транзакциях передачи system-DMA см. в транзакций SerCx2 System-DMA-Transmit.

Требования

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