Грамотная документация

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

Одной из самых объемных и важных документаций для программистов является MSDN (Microsoft Developer Network). Для низкоуровневых программистов и программистов драйверов существует отдельная документация WDK (Windows Driver Kit), входящая в состав MSDN. В MSDN перечислены функции, параметры к ним, объяснения, примеры кода и многое другое.

Большая документация - сложный продукт. В любом сложном продукте есть недочеты, ошибки и недоработки. Встречаются они и в документации, ведь все мы люди, все мы ошибаемся. Недавно с такой ошибкой столкнулся и я.

Операционная система Windows предоставляет специальную функцию, которая позволяет отслеживать различные изменения в системном реестре указанного ключа. Она есть как в пользовательском пространстве (RegNotifyChangeKeyValue), так и в пространстве ядра (ZwNotifyChangeKey), там, где работает сама операционная система и драйверы. Этой функцией пользуются как антивирусные продукты, так и вредоносный код, который следит за изменениями своих вредоносных веток антивирусом (обычно это лечение веток реестра).

Прототип функции ZwNotifyChangeKey выглядит так:

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

Функция должна быть определена так:

Не суть важно, что тут за параметры, главное - то, что у функции три аргумента. Это важно.

В одном из драйверов мне понадобилась эта функция. Я написал весь сопутствующий код, использовал функцию, скомпилировал драйвер, положил в нужное место и запустил. Система упала в BSOD. 'Не в первый и не в последний раз', - подумал я и начал проверять параметры функции. Все было идеально, все было правильно, а BSOD повторялся каждый раз.

Google не смог мне помочь с данной проблемой и пришлось разбираться самому. Потратив некоторое количество часов, я выяснил, что в недрах операционной системы при определенных обстоятельствах (PreviousMode == KernelMode) указатель PIO_APC_ROUTINE трактуется совершенно по-другому, как указатель на структуру WORK_QUEUE_ITEM, в которой содержится указатель на нами определенную функцию. И этого не было в документации, эту информацию я даже не смог найти в сети.

Структура выглядит следующим образом:

Функция должна быть определена так:

И она принимает всего один параметр. И это важно.

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

Ошибки бывают разные, но ошибки в документации дорогого стоят. До следующих ошибок, а они обязательно будут.