Асинхронный форматированный вывод (log.h)

API определен в заголовочном файле sysroot-*-kos/include/kos/log.h из состава KasperskyOS SDK.

API позволяет осуществлять форматированный вывод аналогично функциям семейства printf, но асинхронно, то есть выполняя неблокирующие вызовы. Это дает возможность, например, осуществлять форматированный вывод в обработчиках прерываний, где нельзя выполнять вызовы, которые являются блокирующими и, как следствие, имеют неопределенную длительность.

Сведения о функциях API приведены в таблице ниже.

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

Типовой сценарий использования API включает следующие шаги:

1. Создание журнала.

   Чтобы выполнить этот шаг, нужно вызвать функцию KosLogCreateEx() или KosLogCreate(). Журнал представляет собой объект, который содержит очередь форматированных строк, организованную по принципу FIFO (англ. First In, First Out). При создании журнала автоматически создается поток исполнения, который в цикле извлекает первую строку из очереди в этом журнале и выполняет одно из следующих действий:

   • Помещает извлеченную из журнала строку в диагностический вывод, который записывается, например, в порт COM или USB (версии 3.0 или более поздней, с поддержкой DbC) в зависимости от конфигурации ядра.

     Этот вариант применяется, если журнал был создан вызовом функции KosLogCreateEx() со значением RTL_NULL в параметре logFunc либо вызовом функции KosLogCreate().

   • Передает извлеченную из журнала строку callback-функции, заданной через параметр logFunc функции KosLogCreateEx().

     Callback-функция получает указатель на форматированную строку и размер этой строки (без учета терминирующего нуля, в байтах) через свои параметры buf и len соответственно. Эта callback-функция может, например, записывать форматированную строку в буфер, вместо того чтобы помещать в диагностический вывод.

   При использовании функции KosLogCreate() максимальное число форматированных строк в журнале и их максимальный размер (с учетом терминирующего нуля, в байтах) определяются константами KOS_LOG_QUEUE_CAPACITY_DEFAULT и KOS_LOG_MSG_SIZE_DEFAULT соответственно. Функция KosLogCreateEx() позволяет задать эти параметры журнала.

2. Выполнение форматированного вывода.

   Чтобы выполнить вывод форматированной строки, нужно добавить эту строку в журнал вызовом функции KosLogVWrite() или KosLogWrite(). Функция KosLogWrite() опционально принимает последовательность параметров (...), значения которых нужно поместить в форматированную строку. Функция KosLogVWrite() принимает список значений для помещения в форматированную строку через параметр ap типа rtl_va_list, поэтому эту функцию нужно использовать совместно с макросами rtl_va_start() и rtl_va_end(), определенными в заголовочном файле sysroot-*-kos/include/rtl/stdarg.h из состава KasperskyOS SDK.

   Если журнал полностью заполнен, то функции KosLogVWrite() и KosLogWrite() завершаются с ошибкой rcOutOfMemory. При этом поток исполнения, который извлекает форматированные строки из журнала, помещает в диагностический вывод или передает иным способом (в зависимости от реализации callback-функции, заданной через параметр logFunc функции KosLogCreateEx()) сообщение о потере данных.

3. Удаление журнала.

   Чтобы выполнить этот шаг, нужно вызвать функцию KosLogDestroy().

   Перед удалением можно проверить, пуст ли журнал, вызовом функции KosLogIsEmpty().

Сведения о функциях API

Функции log.h