EreTIk's Box » Заметки о WinDbg » Debugger Markup Language (DML): краткий обзор


Меня всегда поражало построение документации у Microsoft: с одной стороны многое тщательно документировано, но с другой… бывало, что в новом MSDN’е возьмут, да и выкинут формат отладочной информации CodeView, например. Или рассмотрим ситуацию с WinDbg. У отладчика есть свой chm-help, в котором описано множество команд и встроенных расширений, но о языке разметки (Debugger Markup Language - DML), который поддерживается с версии 6.6.07, ничего не описано. Для того, что бы понять, что это такое нужно открыть файл, который располагается в директории установлено отладчика: dml.doc. Здесь я приведу основные выдержки из этого документа, но советую прочитать содержимое dml.doc.


Итак, как понятно из названия, DML это язык разметки вывода отладчика. С помощью DML можно линковать между собой информацию, которую вы считаете связанной, а так же немного «раскрасить» вывод в отладочную консоль. Линковка осуществляется гиперссылками, пример которой можно увидеть при возникновении Bug Check: отладчик выводит ссылку на команду !analyze -v .


Язык DML имеет тэговую разметку, похожую на HTML. Формат тэга следующий:

<tagname [args]> text </tagname>

Описание тэгов DML


Тэг link служит для формирования гиперссылки. Формат тэга:

<link [name="text"] [cmd="debugger_command"] [section="name"]>link text</link>

В результате, в отладочном выводе, будет сформирована гиперссылка. Тест гиперссылки будет соответствовать "link text", а действие при клике соответствует "debugger_command". Действие (команда) может быть любой командой отладчика. Параметры name и section служат для навигации между связанными ссылками.


Тэг exec более простая версия тэга link, который служит для вывода ссылок на команды отладчика в виде гиперссылок. Формат тэга:

<exec cmd=”debugger_command” >descriptive text</exec>

Параметр cmd аналогичен тэгу link. С помощью exec можно организовать довольно сложное меню.


Тэги изменения стиля теста: <b>text</b>, <i>text</i>, <u>text</u>. Эти тэги меняют стиль написания текста на жирный, наклонный и подчеркнутый


Тэг изменения цвета текста - col. Формат тэга:

<col fg=”col_name1” bg=”col_name2”>text</col>

Параметры fg bg задают цвет теста и фона соответственно. Цвета можно выбрать из следующих значений:

wbg, wfg Системные цвета по умолчанию для теста и фона
cbg, cfg Системные цвета по умолчанию для выделенного теста и фона
changed Цвет, используемый WinDbg для выделения низменных значений (регистров, переменных). По умолчанию - красный
srcnum, srcchar, srcstr, srcid, srckw, srcpair, srccmnt, srcdrct, srcspid, srcannot Цвета, используемые WinDbg для раскраски исходных текстов
empbg, emphfg Цвет выделенного текста в Windbg. По умолчанию - голубой
subbg, subfg Системные цвета неактивного цвета и фона
normbg, normfg, warnbg, warnfg, errbg, errfg, verbbg, verbfg Цвета уровней вывода в WinDbg

Использование DML


Собственно, фабула. Существует как минимум 3-и основных применения DML:

  • скрипты отладчика
  • отладочный вывод процесса или драйвера
  • библиотеки расширений

Для вывода форматированного текста в скриптах используется токен .print. Для того, что бы выводимый текст интерпретировался как DML, необходимо использовать опцию /D. Например:

.printf /D "Example: <exec cmd=\"version\">Show debugger version</exec>\n"

Выведет на экран гиперссылку Show debugger version , при клике на которую будет выполнена команда version.


DML можно использовать и в отладочном выводе, который формируется функциями OutputDebugString(…) и DbgPrint(…). Для этого используется ключевой тэг <?dml?>. Часть строки, следующая за этим тэгом, будет трактоваться как DML. Что бы вывести вышеописанный пример из кода нужно:

DbgPrint("Example: <?dml?><exec cmd=\"version\">Show debugger version</exec>\n");

Разработчиков библиотек дополнений к WinDbg тоже не обделили прелестями DML. Для формирования вывода можно использовать метод IDebugControl::ControlledOutput. Ниже приведен пример функции, написанной на C++, и ее использования. На выходе будет сформирован вышеописанный пример. 

void PrintDmlExec(__in PCSTR szCommand, __in PCSTR szText)
{
    CString csDmlCommand;
    csDmlCommand.Format(_T("<exec cmd=\"%s\">%s</exec>"), szCommand, szText);
    g_pDbgControl->ControlledOutput(
        DEBUG_OUTCTL_AMBIENT_DML,
        DEBUG_OUTPUT_NORMAL,
        csDmlCommand);
}

    ...
    PrintDmlExec("version", "Show debugger version");
    ...

Переменная g_pDbgControl должна содержать указатель на интерфейс IDebugControl.


Расширение стандартных команд WinDbg DML


Многие стандартные команды были расширены DML’ем, ходя с chm-help’е об этом не сказано. Токен .printf с параметром /D я уже описал выше. Краткое описание других команд:

  • .help /D - вывод помощи в виде меню, организованного гиперссылками
  • .chain /D - отображение цепочки расширений
  • .extmatch /D - вывод расширений, имя которых совпадает с заданной маской
  • lmD - отображение списка загруженных модулей. Гиперссылками можно просматривать детализированную информацию о модуле
  • kM - отображение стека вызовов. Гиперссылками отображается номер фрейма в стеке.


ΞρεΤΙκ