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

Статья
03/08/2023

Подпрограмма обратного вызова DmaCompletionRoutine уведомляет драйвер, который ранее запросил передачу DMA системы, о том, что эта передача завершена.

Синтаксис

DMA_COMPLETION_ROUTINE DmaCompletionRoutine;

void DmaCompletionRoutine(
  [in] PDMA_ADAPTER DmaAdapter,
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PVOID CompletionContext,
  [in] DMA_COMPLETION_STATUS Status
)
{...}

Параметры

[in] DmaAdapter

Указатель на структуру DMA_ADAPTER . Эта структура является объектом адаптера, который представляет системный канал DMA драйвера.

[in] DeviceObject

Указатель на структуру DEVICE_OBJECT . Эта структура представляет собой объект физического устройства (PDO), представляющий целевое устройство для запрошенной операции DMA.

[in] CompletionContext

Указатель на определенный драйвером контекст для подпрограммы DmaCompletionRoutine . Этот контекст представляет собой значение параметра CompletionContext , которое драйвер ранее передал в вызов MapTransferEx , который инициировал передачу системного DMA.

[in] Status

Состояние завершения передачи DMA. Этот параметр представляет собой значение перечисления DMA_COMPLETION_STATUS, указывающее, успешно ли выполнена передача DMA.

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

None

Remarks

В качестве варианта драйвер может реализовать подпрограмму DmaCompletionRoutine . Когда драйвер запрашивает передачу DMA системы, драйвер может указать указатель на эту подпрограмму вместе с запросом. После завершения передачи DMA автоматически вызывается подпрограмма DmaCompletionRoutine для уведомления драйвера.

Подпрограмма DmaCompletionRoutine драйвера вызывается только в том случае, если передача DMA, запрошенная драйвером, использует системный контроллер DMA, который может создать прерывание после завершения передачи DMA. Драйвер, использующий устройство DMA master шины или системный контроллер DMA, который не создает прерываний, должен использовать другие средства для определения завершения передачи DMA. Например, этот драйвер может использовать прерывание таймера для периодического опроса состояния передачи DMA.

Драйвер может предоставить указатель на подпрограмму DmaCompletionRoutine в качестве необязательного параметра для процедуры MapTransferEx .

Примеры

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

Например, чтобы определить подпрограмму обратного вызова DmaCompletionRoutine с именем MyDmaCompletionRoutine, используйте тип DMA_COMPLETION_ROUTINE, как показано в следующем примере кода:

DMA_COMPLETION_ROUTINE MyDmaCompletionRoutine;

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

_Use_decl_annotations_
VOID
  MyDmaCompletionRoutine(
    PDMA_ADAPTER DmaAdapter,
    PDEVICE_OBJECT DeviceObject,
    PVOID CompletionContext,
    DMA_COMPLETION_STATUS Status
    )
  {
      // Function body
  }

Тип функции DMA_COMPLETION_ROUTINE определяется в файле заголовка Wdm.h. Чтобы более точно определить ошибки при запуске средств анализа кода, обязательно добавьте заметку в _Use_decl_annotations_ определение функции. Заметка _Use_decl_annotations_ гарантирует использование заметок, которые применяются к типу функции DMA_COMPLETION_ROUTINE в файле заголовка. Дополнительные сведения о требованиях к объявлениям функций см. в разделе Объявление функций с помощью типов ролей функций для драйверов WDM. Сведения о _Use_decl_annotations_ см. в статье Поведение функции с заметками.

Требования

Требование	Значение
Минимальная версия клиента	Доступно начиная с Windows 8.
Целевая платформа	Персональный компьютер
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
IRQL	Звонил на DISPATCH_LEVEL.