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

Статья
10/30/2024

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

Синтаксис

EVT_SERCX2_CUSTOM_TRANSMIT_TRANSACTION_START EvtSercx2CustomTransmitTransactionStart;

void EvtSercx2CustomTransmitTransactionStart(
  [in] SERCX2CUSTOMTRANSMITTRANSACTION CustomTransmitTransaction,
  [in] WDFREQUEST Request,
  [in] PMDL Mdl,
  [in] ULONG Offset,
  [in] ULONG Length
)
{...}

Параметры

[in] CustomTransmitTransaction

SERCX2CUSTOMTRANSMITTRANSACTION дескриптор пользовательского объекта передачи-транзакции. Драйвер последовательного контроллера, ранее называемый методом SerCx2CustomTransmitTransactionCreate для создания этого объекта.

[in] Request

Дескриптор объекта запроса платформы, связанный с пользовательской транзакцией передачи. Драйвер отвечает за выполнение этого запроса. Этот запрос может не быть запросом IRP_MJ_WRITE, отправленным клиентом, и поэтому драйвер последовательного контроллера не должен пытаться использовать этот запрос для доступа к буферу записи. Этот запрос в основном используется для отмены, завершения и пересылки очередей (при необходимости). Чтобы получить доступ к буферу записи для запроса на запись клиента, используйте параметрыMdl, Offsetи Length.

[in] Mdl

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

[in] Offset

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

[in] Length

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

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

Никакой

Замечания

Драйвер последовательного контроллера должен реализовать эту функцию, если она создает объект пользовательской передачи транзакций. Если он реализован, драйвер регистрирует функцию в вызове SerCx2CustomTransmitTransmitTransactionCreate, который создает этот объект.

Когда SerCx2 вызывает функцию EvtSerCx2CustomTransmitTransactionStart, драйвер последовательного контроллера инициирует транзакцию путем программирования пользовательского механизма передачи данных из буфера в запросе записи на передачу FIFO в оборудовании последовательного контроллера. Если запрос не может быть выполнен немедленно, прежде чем функция EvtSerCx2CustomTransmitTransaction Start возвращается, драйвер должен вызвать метод, например WdfRequestMarkCancelableEx, чтобы пометить запрос как отменяемый.

После завершения транзакции драйвер завершает ожидающий запрос на запись, SerCx2 вызывает функцию обратного вызова события EvtSerCx2CustomTransmitTransactionCleanup, если драйвер реализует эту функцию.

Если драйвер последовательного контроллера реализует функцию обратного вызова событий EvtSerCx2CustomTransmitTransactionInitialize, SerCx2 вызывает эту функцию перед вызовом функции EvtSerCx2CustomTransmitTransactionStart. Непосредственно перед вызовом EvtSerCx2CustomTransmitTransactionStart, а после вызова EvtSerCx2CustomTransmitTransactionInitialize возвращается таймер, который определяет время ожидания запроса записи. Дополнительные сведения см. в обсуждении общего времени ожидания в SERIAL_TIMEOUTS.

Драйвер последовательного контроллера должен завершить ожидающий запрос на запись только после последнего байта передачи FIFO, передаваемого на последовательно подключенное периферийное устройство. Невозможно гарантировать, что данные, записанные на передачу FIFO, будут передаваться без значительной задержки, а драйвер последовательного контроллера, предполагающий, что такая гарантия существует, может привести к проблемам надежности периферийных драйверов.

Если пользовательский механизм передачи данных является устройством DMA главного шины, Функция EvtSerCx2CustomTransmitTransactionStart может вызывать метод, например WdfDmaTransactionInitializeUsingOffset, чтобы инициировать транзакцию DMA, которая использует буфер записи, описанныйMdl, Offsetи Length.

Дополнительные сведения о параметрах Mdl, Offsetи Length см. в разделе "Примечания" в EvtSerCx2CustomTransmitTransactionInitialize.

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

Дополнительные сведения см. в разделе SerCx2 Custom-Transmit Транзакций.

Примеры

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

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

EVT_SERCX2_CUSTOM_TRANSMIT_TRANSACTION_START  MyCustomTransmitTransactionStart;

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

_Use_decl_annotations_
VOID
  MyCustomTransmitTransactionStart(
    SERCX2CUSTOMTRANSMITTRANSACTION  CustomTransmitTransaction,
    WDFREQUEST  Request,
    PMDL  Mdl,
    ULONG  Offset,
    ULONG  Length
    )
  {...}

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

Требования

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