функция обратного вызова EVT_SERCX2_SYSTEM_DMA_RECEIVE_CONFIGURE_DMA_CHANNEL (sercx.h)

Статья
10/30/2024

Функция обратного вызова событий EvtSerCx2SystemDmaReceiveConfigureDmaChannel вызывается версией 2 расширения последовательной платформы (SerCx2), чтобы драйвер последовательного контроллера мог выполнять любую настраиваемую конфигурацию адаптера DMA, который может потребоваться перед началом каждой передачи в транзакции приема системы DMA.

Синтаксис

EVT_SERCX2_SYSTEM_DMA_RECEIVE_CONFIGURE_DMA_CHANNEL EvtSercx2SystemDmaReceiveConfigureDmaChannel;

NTSTATUS EvtSercx2SystemDmaReceiveConfigureDmaChannel(
  [in] SERCX2SYSTEMDMARECEIVE SystemDmaReceive,
  [in] PMDL Mdl,
  [in] ULONG Offset,
  [in] ULONG Length
)
{...}

Параметры

[in] SystemDmaReceive

Дескриптор SERCX2SYSTEMDMARECEIVE объекту system-DMA-receive. Драйвер последовательного контроллера ранее вызвал метод SerCx2SystemDmaReceiveCreate для создания этого объекта.

[in] Mdl

Указатель на MDL-, описывающий страницы памяти, охватываемые буфером чтения для транзакции получения системы-DMA. Список точечной и сборной для передачи DMA будет использовать область этой памяти, указанную параметрами смещения и длины.

[in] Offset

Начальная смещение для передачи данных. Этот параметр является смещением байтов с начала буферной области, описанной MDL. Если MDL задает общее количество байтов буферного пространства, возможные значения Offset находятся в диапазоне от 0 до N–1.

[in] Length

Размер передачи данных в байтах. Если MDL задает общее число байтов буферного пространства, возможные значения длины находятся в диапазоне 1 до N–смещения.

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

Функция EvtSerCx2SystemDmaReceiveConfigureDmaChan nel возвращает STATUS_SUCCESS, если вызов выполнен успешно. В противном случае возвращается соответствующий код состояния ошибки.

Замечания

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

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

Драйвер последовательного контроллера может вызывать такой метод, как SerCx2SystemDmaReceiveGetDmaEnabler для получения средства включения DMA для контроллера DMA системы, используемого для транзакций получения системной DMA.

Дополнительные сведения см. в разделе SerCx2 System-DMA-Receive Transactions.

Примеры

Чтобы определить функцию обратного вызова EvtSerCx2SystemDmaReceiveConfigureDmaChannel, необходимо сначала указать объявление функции, определяющее тип определяемой функции обратного вызова. Windows предоставляет набор типов функций обратного вызова для драйверов. Объявление функции с помощью типов функций обратного вызова помогает анализ кода для драйверов, статический проверяющий драйвер (SDV) и другие средства проверки подлинности, и это требование для написания драйверов для операционной системы Windows.

Например, чтобы определить функцию обратного вызова EvtSerCx2SystemDmaReceiveConfigureDmaChannel, которая называется MySystemDmaReceiveConfigureDmaChannel, используйте тип функции EVT_SERCX2_SYSTEM_DMA_RECEIVE_CONFIGURE_DMA_CHANNEL, как показано в этом примере кода:

EVT_SERCX2_SYSTEM_DMA_RECEIVE_CONFIGURE_DMA_CHANNEL  MySystemDmaReceiveConfigureDmaChannel;

Затем реализуйте функцию обратного вызова следующим образом:

_Use_decl_annotations_
NTSTATUS
  MySystemDmaReceiveConfigureDmaChannel(
    SERCX2SYSTEMDMARECEIVE SystemDmaReceive,
    PMDL Mdl,
    ULONG Offset,
    ULONG Length
    )
  {...}

Тип функции EVT_SERCX2_SYSTEM_DMA_RECEIVE_CONFIGURE_DMA_CHANNEL определен в файле заголовка Sercx.h. Чтобы более точно определить ошибки при запуске средств анализа кода, обязательно добавьте в определение функции заметку Use_decl_annotations. Заметка Use_decl_annotations гарантирует, что используются заметки, применяемые к типу функции EVT_SERCX2_SYSTEM_DMA_RECEIVE_CONFIGURE_DMA_CHANNEL в файле заголовка. Дополнительные сведения о требованиях к объявлениям функций см. в объявлении функций с помощью типов ролей функций для драйверов KMDF. Дополнительные сведения о Use_decl_annotationsсм. в поведению функции.

Требования

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

См. также

MDL

SERCX2SYSTEMDMARECEIVE

SerCx2SystemDmaReceiveCreate

SerCx2SystemDmaReceiveGetDmaEnabler

Поделиться через