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

Статья
02/27/2024

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

Функция обратного вызова KBUGCHECK_REASON_CALLBACK_ROUTINE предоставляет больше возможностей, чем предыдущий обратный вызов.

Синтаксис

KBUGCHECK_CALLBACK_ROUTINE KbugcheckCallbackRoutine;

void KbugcheckCallbackRoutine(
  [in] IN PVOID Buffer,
  [in] IN ULONG Length
)
{...}

Параметры

[in] Buffer

Указатель на буфер, указанный при регистрации обратного вызова.

[in] Length

Указывает длину (в байтах) буфера, на который указывает параметр Buffer .

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

None

Remarks

Драйверы могут предоставить BugCheckCallback, который сбрасывает устройство в известное состояние, если система выдает ошибку проверка.

Используйте KeRegisterBugCheckCallback , чтобы зарегистрировать подпрограмму BugCheckCallback . Впоследствии драйвер может удалить обратный вызов с помощью процедуры KeDeregisterBugCheckCallback . Если драйвер можно выгрузить, он должен удалить все зарегистрированные обратные вызовы в подпрограмме unload .

Подпрограмма BugCheckCallback строго ограничена действиями, которые она может предпринять. Дополнительные сведения см. в статье Написание процедуры обратного вызова проверки ошибок. Подпрограмма может безопасно использовать процедуры READ_PORT_XXX, READ_REGISTER_XXX, WRITE_PORT_XXX и WRITE_REGISTER_XXX для взаимодействия с устройством.

Драйверы, требующие более сложного взаимодействия с системой, так как она выдает ошибку проверка, могут вместо этого реализовать процедуры KbCallbackDumpIo или KbCallbackSecondaryDumpData.

Обратите внимание, что начиная с операционных систем Windows XP с пакетом обновления 1 (SP1) и Windows Server 2003 подпрограммы BugCheckCallback выполняются после того, как файл дампа сбоя системы уже был записан. (В более ранних версиях Windows подпрограммы выполняются перед записью файла аварийного дампа.) Таким образом, все данные, хранящиеся в буфере, указанном параметром Buffer , не будут отображаться в файле аварийного дампа. Драйверы, необходимые для записи данных в файл аварийного дампа, вместо этого реализуют подпрограмму KbCallbackSecondaryDumpData. (В более ранних версиях Windows данные, записанные в Buffer , отображаются в файле аварийного дампа.)

Примеры

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

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

KBUGCHECK_CALLBACK_ROUTINE MyBugCheckCallback;

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

_Use_decl_annotations_
VOID
  MyBugCheckCallback(
    PVOID  Buffer,
    ULONG  Length
    )
  {
      // Function body
  }

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

Требования

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

См. также раздел

Написание процедуры обратного вызова проверки ошибок

KeDeregisterBugCheckCallback

KeRegisterBugCheckCallback

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