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

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

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

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

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

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

Создание журнала.
Чтобы выполнить этот шаг, нужно вызвать функцию 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() позволяет задать эти параметры журнала.
Выполнение форматированного вывода.
Чтобы выполнить вывод форматированной строки, нужно добавить эту строку в журнал вызовом функции 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()) сообщение о потере данных.
Удаление журнала.
Чтобы выполнить этот шаг, нужно вызвать функцию KosLogDestroy().

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

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

Функции log.h

Функция	Сведения о функции
`KosLogCreateEx()`	Назначение Создает журнал. Параметры [in] `msgSize` – максимальный размер форматированных строк в журнале, с учетом терминирующего нуля, в байтах. Не должен превышать значение константы `KOS_LOG_MSG_SIZE_MAX`. [in] `capacity` – максимальное число форматированных строк в журнале. Не должно превышать значение константы `KOS_LOG_QUEUE_CAPACITY_MAX`. [in,optional] `logFunc` – идентификатор callback-функции, вызываемой при извлечении каждой форматированной строки из журнала, или `RTL_NULL`, чтобы помещать извлекаемые из журнала форматированные строки в диагностической вывод. [out] `outH` – указатель на идентификатор журнала. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KosLogCreate()`	Назначение Создает журнал с параметрами по умолчанию. Параметры [out] `outH` – указатель на идентификатор журнала. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KosLogDestroy()`	Назначение Удаляет журнал. Параметры [in] `handle` – идентификатор журнала. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KosLogVWrite()`	Назначение Добавляет форматированную строку в журнал. Параметры [in] `handle` – идентификатор журнала. [in] `fmt` – указатель на строку форматирования (как для функций семейства `printf`). [in] `ap` – список параметров, значения которых нужно поместить в форматированную строку. Тип списка определен в заголовочном файле `sysroot-*-kos/include/rtl/stdarg.h` из состава KasperskyOS SDK. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки. Дополнительные сведения Потокобезопасная функция. Неблокирующий вызов.
`KosLogWrite()`	Назначение Добавляет форматированную строку в журнал. Параметры [in] `handle` – идентификатор журнала. [in] `fmt` – указатель на строку форматирования (как для функций семейства `printf`). [in,optional] `...` – последовательность параметров, значения которых нужно поместить в форматированную строку. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки. Дополнительные сведения Потокобезопасная функция. Неблокирующий вызов.
`KosLogIsEmpty()`	Назначение Проверяет, пуст ли журнал. Параметры [in] `handle` – идентификатор журнала. Возвращаемые значения В случае успешной проверки возвращает `rtl_true`, иначе возвращает `rtl_false`.

В начало