Фронтенд (frontend). Первичная система обработки сообщений. Отвечает за их форматирование и постановку в очередь.

Бэкенд (backend). Низкоуровневая система вывода символьных данных лога наружу. Чаще всего это UART0.

Более сложные системы могут состоять из нескольких доменов (физических процессоров), где для каждого домена имеется отдельный бинарник. Примерами доменов могут служить многоядерные SoC, или один из бинарников (Secure или Nonsecure) на ядре ARM TrustZone.

Трассировка и отладка в мультидоменной системе более сложна, и требует наличия эффективной системы лога. Для структурирования этой системы регистрации можно использовать два подхода:

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

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

В многодоменной системе существует 3 типа доменов:

• Конечный домен (end domain), содержащий реализацию ядра лога и бэкенд, отвечающий за обмен между доменами (cross-domain backend). Параллельно у него могут быть другие домены бэкенды.
• Релейный домен (relay domain) у которого есть один или большее количество связей (link) с другими доменами, но у него нет бэкендов, которые выводят логи для пользователя. У него есть cross-domain backend либо для другого релея, либо для корневого домена.
• Корневой домен (root domain), у которого есть один или несколько связей и бэкенд, который выводит логи для пользователя.

На следующем рисунке показан пример настройки multi-domain лога:

Рис. 1. Пример мультидоменного лога.

В этой архитектуре линк может обрабатывать несколько доменов. Для примера рассмотрим SoC с двумя ядрами ARM Cortex-M33 с TrustZone: ядро A и ядро B (см. рис. 1). В системе имеется 4 домена, поскольку в каждом ядре есть домены Secure и Nonsecure domain. Если ядро A nonsecure (A_NS) это корневой домен, то у него 2 линка: один до ядра A secure (A_NS-A_S), и один до ядра B nonsecure (A_NS-B_NS). У домена B_NS есть один линк до ядра B secure (B_NS-B_S), и бэкенд для A_NS.

Поскольку во всех экземплярах существует стандартная подсистема лога, всегда можно иметь несколько бэкендов и одновременно выводить на них сообщения. Пример этого показан на рис. 1 как обозначенный пунктиром UART бэкенд в домене B_NS.

Domain ID. Источник в каждом сообщении лога идентифицируется следующими полями в заголовке: source_id и domain_id.

Значение, назначенное для domain_id, относительное. Каждый раз, когда домен создает сообщение лога, он устанавливает свой domain_id в 0. Когда сообщение пересекает домен, то domain_id меняется, поскольку увеличивается на смещение линка. Смещение линка назначается при инициализации, где ядро логгера просматривает все зарегистрированные линки и назначенные им смещения.

У первого линка смещение установлено в 1. Следующее смещение равно смещению предыдущего линка плюс количество доменов в предыдущем линке.

Следующий пример, показанный на картинке ниже, где назначенные domain_id показаны для каждого домена:

Рис. 2. Пример назначения идентификаторов домена (Domain ID).

Рассмотрим сообщение лога, созданное в домене B_S:

1. Изначально у него domain_id, установленный в 0.
2. Когда линк B_NS-B_S принимает сообщение, он увеличивает domain_id на 1 путем добавления смещения B_NS-B_S.
3. Сообщение переходит к A_NS.
4. Когда линк A_NS-B_NS принимает сообщение, он добавляет смещение (2) к domain_id. В конце сообщения устанавливается domain_id в 3, что уникально идентифицирует отправителя сообщения.

Сообщение, передаваемое между доменами (Cross-domain log message). В большинстве случаев адресное пространство в каждом домене уникально, и один домен не может напрямую получить доступ к данным в другом домене. По этой причине бэкенд может частично обработать сообщение перед тем, как передать его в другой домен. Частичная обработка может включать преобразование пакета строки в полную самостоятельную версию (копирование строк, доступных только для чтения, в тело пакета).

У каждого домена может быть свой, отдельный источник метки времени в контексте частоты и смещения. Система лога не выполняет преобразование метки времени.

Runtime-фильтрация. В случае одного домена каждый источник лога имеет выделенную переменную с runtime-фильтрацией для каждого бэкенда в системе. В случае нескольких доменов инициатор сообщения не знает о количестве бэкендов в корневом домене.

Таким образом, для фильтрации в нескольких доменах источник требует установки runtime-фильтрации в каждом домене на пути в корневой домен. Поскольку в момент компиляции количество источников в других доменах неизвестно, runtime-фильтрация дальних источников должна использовать динамически выделяемую память (одно слово на источник). Когда бэкенд в корневом домене меняет фильтрацию модуля из дальнего домена, локальный фильтр обновляется. После обновления проверяется общий фильтр (максимум из всех локальных бэкендов), и если было изменение, то дальний домен информируется об этом изменении. При таком подходе runtime-фильтрация работает идентично как в сценарии с несколькими доменами, так и с одним доменом.

Упорядочивание сообщений. Система лога не предоставляет механизм синхронизации меток времени в нескольких доменах:

• Если у доменов отдельные источники меток времени, то сообщения будут обрабатываться в том порядке, в каком они достигли буфера в корневом домене.

• Если у доменов один и тот же источник метки времени, или если существует механизм пересчета меток времени, то возможны 2 варианта:

- Сообщения обрабатываются по мере поступления в буфер корневого домена. Сообщения не упорядочиваются, но они могут сортироваться хостом, поскольку метка времени показывает, когда сообщение было сгенерировано.
- У линков есть свои выделенные буферы. При обработки голова каждого буфера проверяется, и самое старое сообщение обрабатывается первым.

При таком подходе возможно поддерживать порядок следования сообщений ценой не очень оптимального использования памяти (поскольку нет общего буфера) и увеличенной латентности обработки (см. [5]).

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

Обратите внимание, что long double не поддерживается модулем struct языка Python. Таким образом, сообщения с long double не будут корректно отображать значения.

Конфигурация. Следующие опции kconfig относятся к dictionary-based logging:

• CONFIG_LOG_DICTIONARY_SUPPORT разрешает поддержку лога на основе словаря. Должно быть выбрано бэкендами, которым это необходимо.

• UART-бэкенд может использовать логгинг на основе словаря. Дополнительная конфигурация для такого случая:

- CONFIG_LOG_BACKEND_UART_OUTPUT_DICTIONARY_HEX говорит UART-бэкенду выводить шестнадцатеричные символы для лога на основе словаря. Это полезно, когда данные лога должны быть захвачены вручную через терминалы и консоли.
- CONFIG_LOG_BACKEND_UART_OUTPUT_DICTIONARY_BIN говорит UART-бэкенду выводить двоичные данные.

Использование. Когда разрешен логгинг на основе словаря через разрешенные связанные бэкенды лога, в директории build будет создан файл базы данных JSON с именем log_dictionary.json. Этот файл базы данных содержит информацию для парсера, чтобы корректно обработать данные лога. Обратите внимание, что эта база данных работает только в пределах одной и той же сборки, и не может быть использован для других сборок.

Для использования парсера лога:

$ ./scripts/logging/dictionary/log_parser.py /log_dictionary.json

Парсер принимает 2 необходимых аргумента, где первый из них это полный путь до файла базы данных JSON, и второй это файл, содержащий данные лога. Добавьте опциональный аргумента --hex в конце, если файл данных лога содержит hex-символы (например, когда CONFIG_LOG_BACKEND_UART_OUTPUT_DICTIONARY_HEX=y). Это укажет парсеру, что надо преобразовать шестнадцатеричные символы в двоичные данные перед применением парсинга.

Как использовать парсер лога, см. пример [6].

На эмуляторе qemu_x86 было проведено несколько тестов из tests/subsys/logging/log_benchmark. Это дает грубое сравнение, позволяющее получить общий обзор производительности.

Примечания:

(1, 2, 3) Разрешена опция CONFIG_LOG_SPEED.
(4) Количество сообщений лога с различным количеством аргументов, которое соответствует 2048 байтам, выделенным для ведения лога.
(5) Затраты памяти на подсистему лога в tests/subsys/logging/log_benchmark, когда не используется фильтрация и функции форматирования.
(6) Затраты памяти на подсистему лога в samples/subsys/logging/logger.
(7) Средний размер сообщения лога (исключая строку) с двумя аргументами на Cortex M3.

Использование стека. Когда разрешен логгинг, это влияет на использование стека в контексте выполнения, где используется logging API. Если стек оптимизирован, то это может вызвать его переполнение. Утилизация стека зависит от режима и оптимизации компилятора. Это также может значительно меняться в зависимости от платформы. В общем, когда используется CONFIG_LOG_MODE_DEFERRED, расход стека меньше, поскольку логгинг ограничивается созданием и сохранением сообщения лога. Если используется CONFIG_LOG_MODE_IMMEDIATE, то сообщение лога обрабатывается бэкендом, что включает форматирование строки. В таком случае утилизация стека зависит от того, какой бэкенд используется.

Тест tests/subsys/logging/log_stack используется для проверки использования стека в зависимости от режима, оптимизации и платформы. Тест использует только бэкенд по умолчанию.

Результаты тестирования некоторых платформ для сообщения лога с двумя целочисленными аргументами:

Шаг 1. В файле prj.conf проекта определите следующие опции:

# Config logger
CONFIG_LOG=y
CONFIG_USE_SEGGER_RTT=y
CONFIG_LOG_BACKEND_RTT=y
CONFIG_LOG_BACKEND_UART=n
CONFIG_LOG_PRINTK=y

Шаг 2. В модуле (или в файле исходного кода), где нужен вывод в лог с помощью макросов LOG_XXX, зарегистрировать систему лога:

LOG_MODULE_REGISTER(имя_модуля);

Здесь вместо "имя_модуля" лучше указать короткое, понятное имя. Например, для файла main.c это может быть вот так:

LOG_MODULE_REGISTER(main);

Или так, здесь во втором параметре указывается ограничение уровня вывода (может быть LOG_LEVEL_ERR, LOG_LEVEL_WRN или, если хотите видеть все сообщения, то LOG_LEVEL_DBG):

LOG_MODULE_REGISTER(main, LOG_LEVEL_XXX);

Шаг 3. Закомментируйте в модуле макрос LOCK_SWD.

На этом все! Теперь можно выводить отладочные сообщения с помощью макросов LOG_ERR, LOG_WRN, LOG_INF, LOG_DBG и функции printk.

Как просматривать сообщения. Пример тестового вывода в лог:

#include "main.h"

// #define LOCK_SWD

LOG_MODULE_REGISTER(main, LOG_LEVEL_DBG);

void approtect(void);

int main(void)
{
   log_init();

#ifdef LOCK_SWD
   approtect();

#endif
   ota_uart_gpio_init();
   dk_leds_init();

   for (;;)
   {
printk("---------------\n");
LOG_ERR("ERR %d", LOG_LEVEL_ERR);
LOG_WRN("WRN %d", LOG_LEVEL_WRN);
LOG_INF("INF %d", LOG_LEVEL_INF);
LOG_DBG("DBG %d", LOG_LEVEL_DBG);
      uart_update_state = ota_uart_handle();
      ...

Запустите JLinkRTTViewer, выберите в меню File -> Connect (F2), введите серийный номер J-Link, кликните OK.

После запуска приложения и подключения к отладчику в окне JLinkRTTViewer можно увидеть примерно следующее:

Группа log_api. Определяет макросы вывода сообщений различного уровня. Параметр (...) это строка, которая опционально может содержать спецификаторы формата в стиле printf, за которой могут идти аргументы.

Заголовочный файл log.h.

LOG_ERR(...)

Вывод сообщения уровня ERROR. Этот макрос предназначен для сообщения о серьезных ошибках, из которых система не может восстановиться. При включении подкраски сообщение ERROR выделяется красным цветом.

LOG_WRN(...)

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

LOG_INF(...)

Вывод сообщения уровня INFO. Это обычные пользовательские информационные сообщения. При включении подкраски сообщение INFO выделяется зеленым цветом.

LOG_DBG(...)

Вывод сообщения уровня DEBUG. Это обозначает информационное сообщение, предназначенное для разработчика.

LOG_PRINTK(...)

Безусловно выводит в лог сообщение, независимо от активированного уровня лога. Результат этого макроса тот же самый, как если бы использовалась функция printk. Отличие только в том, что вывод сообщения в лог происходит через инфраструктуру логгинга, т. е. его вывод зависит от режима лога, например это может быть deferred mode для лога.

LOG_RAW(...)

Безусловно выводит в лог сообщение, независимо от активированного уровня лога (так же, как и LOG_PRINTK). Строка выводится так, как была предоставлена, без добавления специальных символов (т. е. без ESC-последовательностей управления цветом или символов новой строки).

LOG_INST_ERR(_log_inst, ...)

Вывод сообщения уровня ERROR, связанного с экземпляром модуля.

Сообщение ошибки, связанное с определенным экземпляром модуля, у которого есть независимые настройки фильтрации (если runtime-фильтрация разрешена) и префикс сообщения (.).

Параметр _log_inst – указатель на структуру лога, связанную с экземпляром модуля.

LOG_INST_WRN(_log_inst, ...)

Вывод сообщения уровня WARNING, связанного с экземпляром модуля.

LOG_INST_INF(_log_inst, ...)

Вывод сообщения уровня INFO, связанного с экземпляром модуля.

LOG_INST_DBG(_log_inst, ...)

Вывод сообщения уровня DEBUG, связанного с экземпляром модуля.

LOG_HEXDUMP_ERR(_data, _length, _str)

Вывод hexdump-сообщения уровня ERROR. Параметры:

_data – указатель на данные, которые должны быть выведены в лог.
_length – длина данных (в байтах).
_str – постоянная, не обработанная строка.

LOG_HEXDUMP_WRN(_data, _length, _str)

Вывод hexdump-сообщения уровня WARNING.

LOG_HEXDUMP_INF(_data, _length, _str)

Вывод hexdump-сообщения уровня INFO.

LOG_HEXDUMP_DBG(_data, _length, _str)

Вывод hexdump-сообщения уровня DEBUG.

LOG_INST_HEXDUMP_ERR(_log_inst, _data, _length, _str)

Вывод hexdump-сообщения уровня ERROR, связанного с экземпляром модуля.

LOG_INST_HEXDUMP_WRN(_log_inst, _data, _length, _str)

Вывод hexdump-сообщения уровня WARNING, связанного с экземпляром модуля.

LOG_INST_HEXDUMP_INF(_log_inst, _data, _length, _str)

Вывод hexdump-сообщения уровня INFO, связанного с экземпляром модуля.

LOG_INST_HEXDUMP_DBG(_log_inst, _data, _length, _str)

Вывод hexdump-сообщения уровня DEBUG, связанного с экземпляром модуля.

LOG_MODULE_REGISTER(...)

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

Регистрация модуля может быть опущена в двух случаях:

• Модуль состоит больше чем одного файла, и другой файл использовал этот макрос (LOG_MODULE_DECLARE() должен использоваться вместо него ово всех других файлах этого модуля).
• Используется экземпляр логгинга, и здесь не нужно создавать элемент модуля. Таком случае должен использоваться LOG_LEVEL_SET(), чтобы установить уровень лога, используемый в файле.

Макрос принимает один или два параметра:

• Имя модуля.
• Опциональный уровень лога. Если этот параметр не предоставлен, то в этом файле используется уровень лога по умолчанию.

Примеры использования:

• LOG_MODULE_REGISTER(foo, CONFIG_FOO_LOG_LEVEL)
• LOG_MODULE_REGISTER(foo)

См. также LOG_MODULE_DECLARE.

Примечание: определяется состояние модуля и регистрируется модуль только если LOG_LEVEL для текущего исходного файла ненулевой или не определен, и значение CONFIG_LOG_DEFAULT_LEVEL ненулевое. В других случаях этот макрос не дает эффекта.

LOG_MODULE_DECLARE(...)

Макрос для декларации лога модуля (без его регистрации). Модули, которые разделены на несколько файлов, должны иметь только один файл, где используется LOG_MODULE_REGISTER(), чтобы создать специфичное для модуля состояния и зарегистрировать модуль для ядра системы лога.

Другие файлы в модуле должны использовать этот макрос вместо декларирования того же самого состояния (иначе LOG_INF() и подобные макросы не могут ссылаться на переменные состояния конкретного модуля).

Макрос принимает один или два параметра:

• Имя модуля.
• Опциональный уровень лога. Если этот параметр не предоставлен, то в этом файле используется уровень лога по умолчанию.

Примеры использования:

• LOG_MODULE_DECLARE(foo, CONFIG_FOO_LOG_LEVEL)
• LOG_MODULE_DECLARE(foo)

См. также LOG_MODULE_REGISTER.

Примечание: состояние модуля декларируется только если LOG_LEVEL для текущего исходного файла ненулевой или не определен, и CONFIG_LOG_DEFAULT_LEVEL ненулевой. В других случаях этот макрос не дает эффекта.

LOG_LEVEL_SET(level)

Макрос для установки уровня лога в файле или функции, где использовался logging API.

Группа log_ctrl, API для управления логгером.

Заголовочный файл log_ctrl.h.

Макросы:

LOG_CORE_INIT()
LOG_INIT()
LOG_PANIC()
LOG_PROCESS()

Определение типа:

typedef log_timestamp_t (*log_timestamp_get_t)(void)

Функции:

void log_core_init(void)

Системная функция инициализации логгера. Эта функция запускается во время запуска приложения (start up), чтобы позволить вывод в лог до того, как пользователь может явно инициализировать логгер.

void log_init(void)

Пользовательская функция для инициализации логгера.

void log_thread_set(k_tid_t process_tid)

Функция, предоставляющая поток, который обрабатывает логи. См. CONFIG_LOG_PROCESS_TRIGGER_THRESHOLD.

Примечание: функция имеет вызов assert и не дает эффекта, когда установлена опция CONFIG_LOG_PROCESS_THREAD.

Параметр process_tid задает идентификатор обрабатывающего потока. Используется для пробуждения потока.

int log_set_timestamp_func(log_timestamp_get_t timestamp_getter, uint32_t freq)

Функция для предоставления метки времени.

Параметры:

timestamp_getter – функция метки времени.
freq – частота меток времени.

Возвращаемое значение: 0 при успехе или ненулевое значение в случае ошибки.

void log_panic(void)

Переключает подсистему лога в режим паники. Выполнит немедленный возврат, если логгер уже находится в panic mode.

При панике подсистема логгера информирует все бэкенды о panic mode. бэкенды должны переключиться в блокирующий режим, или остановиться (halt). После переключения в режим паники все ожидающие вывод логи сбрасываются (flushed). В режиме паники все сообщения лога должны быть обработаны в контексте своего вызова.

bool log_process(void)

Обработает одно ожидающее вывода сообщение лога.

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

true – есть еще сообщения, ожидающие обработки.
false – нет сообщений, ожидающих обработки.

uint32_t log_buffered_cnt(void)

Возвратит текущее количество забуферизированных сообщений лога.

uint32_t log_src_cnt_get(uint32_t domain_id)

Возвратит количество независимых источников логгера (модулей и экземпляров).

Параметр domain_id – указывает на идентификатор домена (Domain ID).

const char *log_source_name_get(uint32_t domain_id, uint32_t source_id)

Извлекает имя источника (модуля или экземпляра).

Параметры:

domain_id – Domain ID.
source_id – Source ID.

Возвратит имя источника или NULL, если указаны неправильные аргументы.

static inline uint8_t log_domains_count(void)

Возвратит количество доменов, имеющихся в системе. Должен быть как минимум 1 локальный домен.

const char *log_domain_name_get(uint32_t domain_id)

Возвратит имя домена по его идентификатору domain_id.

int log_source_id_get(const char *name)

Функция найдет идентификатор источника по его имени. Возвратит Source ID или отрицательное число, если источник не найден.

uint32_t log_filter_get(struct log_backend const *const backend,
                        uint32_t domain_id,
                        int16_t source_id,
                        bool runtime)

Извлекает фильтр источника для предоставленного бэкенда.

Параметры:

backend – экземпляр бэкенда.
domain_id – идентификатор домена.
source_id – идентификатор источника (модуля или экземпляра).
runtime – true для runtime-фильтра, или false для фильтра, определенного во время компиляции.

Возвращаемое значение: severity level (уровень лога).

uint32_t log_filter_set(struct log_backend const *const backend,
                        uint32_t domain_id,
                        int16_t source_id,
                        uint32_t level)

Установит фильтр на определенном источнике для предоставленного бэкенда.

Параметры:

backend – экземпляр бэкенда.
domain_id – идентификатор домена.
source_id – идентификатор источника (модуля или экземпляра).
level – severity level (уровень лога).

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

void log_backend_enable(struct log_backend const *const backend,
                        void *ctx,
                        uint32_t level)

Разрешит бэкенд с начальным максимальным уровнем фильтрации.

Параметры:

backend – экземпляр бэкенда.
ctx – контекст пользователя.
level – severity level (уровень лога).

void log_backend_disable(struct log_backend const *const backend)

Запретит бэкенд.

Параметры:

backend – экземпляр бэкенда.

const struct log_backend *log_backend_get_by_name(const char *backend_name)¶

Извлекает бэкенд по имени.

Параметры:

backend_name – [in] имя бэкенда, как это было определено макросом LOG_BACKEND_DEFINE.

Возвращаемое значение: указатель на найденный экземпляр бэкенда, или NULL если бэкенд не найден.

const struct log_backend *log_format_set_all_active_backends(size_t log_type)

Установит формат логгинга для всех активных бэкендов.

Параметры:

log_type – формат лога.

Возвращаемое значение: указатель на последний бэкенд, на котором установка формата была неудачной, или NULL для успеха.

static inline bool log_data_pending(void)

Проверяет, есть ли ожидающие обработки данные лога. Функция может использоваться для того, чтобы определить, все ли логи были слиты (flushed). Функция вернет false, когда deferred mode не разрешен.

Возвратит true, если есть данные для обработки, или false если нет данных для обработки.

int log_set_tag(const char *tag)

Конфигурирует тег, используемый для префикса каждого сообщения.

Параметры:

tag – Tag.

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

0 – успех операции.
-ENOTSUP – если функция запрещена.
-ENOMEM – если строка слишком длинная, и больше чем размер буфера. В этом случае тег будет урезан.

int log_mem_get_usage(uint32_t *buf_size, uint32_t *usage)

Извлекает информацию по текущему использованию памяти.

Параметры:

buf_size – [out] емкость буфера, используемого для сохранения сообщений лога.
usage – [out] количество байт, в настоящее время занятых под сообщения, ожидающие обработки.

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

-EINVAL – если режим логгинга не использует буфер.
0 – информация успешно собрана.

int log_mem_get_max_usage(uint32_t *max)

Извлечет информацию по максимальному использованию памяти. Требует опции CONFIG_LOG_MEM_UTILIZATION.

Параметры:

max – [out] максимальное количество байт, использовавшихся для сообщений, ожидающих обработки.

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

-EINVAL – если режим логгинга не использует буфер.
-ENOTSUP – если специальный код (instrumentation) не был разрешен.
0 – информация успешно собрана.

Группа log_msg, API-функции сообщения лога.

Заголовочный файл log_msg.h.

Определения:

LOG_MSG_GENERIC_HDR

Типы данных:

struct log_msg_desc
union log_msg_source
struct log_msg_hdr
struct log_msg
struct log_msg_generic_hdr
union log_msg_generic
union mpsc_pbuf_generic buf

Функции:

static inline uint32_t log_msg_get_total_wlen(const struct log_msg_desc desc)

Извлекает общую длину (в 32-разрядных словах) сообщения лога.

Параметры:

desc – дескриптор сообщения лога.

static inline uint32_t log_msg_generic_get_wlen(const union mpsc_pbuf_generic *item)

Извлекает длину элемента лога в 32-битных словах.

static inline uint8_t log_msg_get_domain(struct log_msg *msg)

Извлекает идентификатор домена (domain ID) сообщения сообщения лога.

static inline uint8_t log_msg_get_level(struct log_msg *msg)

Извлекает уровень лога для сообщения.

static inline const void *log_msg_get_source(struct log_msg *msg)

Извлекает источник сообщения лога. Возвратит указатель на источник данных.

static inline log_timestamp_t log_msg_get_timestamp(struct log_msg *msg)

Извлекает метку времени сообщения лога.

static inline void *log_msg_get_tid(struct log_msg *msg)

Извлекает идентификатор потока (Thread ID) сообщения лога.

static inline uint8_t *log_msg_get_data(struct log_msg *msg, size_t *len)

Возвратит указатель на буфер данных сообщения лога.

Параметры:

msg – сообщение лога.
len – место в памяти, куда будет записана длина данных.

static inline uint8_t *log_msg_get_package(struct log_msg *msg, size_t *len)

Возвратит указатель на пакет строки сообщения лога.

Параметры:

msg – сообщение лога.
len – место в памяти, куда будет записана длина пакета строки.

Группа log_backend, интерфейс бэкенда логгера.

Заголовочный файл log_backend.h.

Определения:

LOG_BACKEND_DEFINE(_name, _api, _autostart, ...)

Макрос для создания экземпляра бэкенда логгера.

Параметры:

_name – имя экземпляра бэкенда.
_api – Logger backend API.
_autostart – если true, то бэкенд инициализируется и активируется вместе с подсистемой лога.
... – опциональный контекст.

Перечисления:

enum log_backend_evt

События бэкенда.

Значения:

enum LOG_BACKEND_EVT_PROCESS_THREAD_DONE

Событие, когда поток обработки лога завершает обработку. Это событие генерируется, когда поток обработки завершил обработку ожидающих сообщений лога.

Примечание: это событие не генерируется при отсутствии ожидающих обработки сообщений лога. Применимо только к deferred mode.

enum LOG_BACKEND_EVT_MAX

Максимальное количество событий бэкенда.

Функции:

static inline void log_backend_init(const struct log_backend *const backend)

Инициализирует или инициирует бэкенд логгинга.

В случае, когда инициализация внутреннего бэкенда занимает больше времени, это может заблокировать поток лога, если бэкенд запускается автоматически. Причина в том, что все бэкенды инициализируются в контексте потока лога. В таком случае бэкенд должен предоставить функцию для опроса готовности (log_backend_is_ready).

Параметры:
backend – [in] указатель на экземпляр бэкенда.

static inline int log_backend_is_ready(const struct log_backend *const backend)

Опрашивает готовность бэкенда. Если бэкенд приходит в готовност сразу после инициализации, то тогда бэкенд может не предоставлять эту функцию.

Параметры:

backend – [in] указатель на экземпляр бэкенда.

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

0 – если бэкенд в готовности.
-EBUSY – если бэкенд пока еще не готов к работе.

static inline void log_backend_msg_process(const struct log_backend *const backend,
                                           union log_msg_generic *msg)

Обрабатывает сообщение. Эта функция используется в режимах deferred и immediate. При возврате содержимое сообщения обрабатывается бэкендом и память может быть освобождена.

Параметры:

backend – [in] указатель на экземпляр бэкенда.
msg – [in] указатель на сообщение с записью в логе.

static inline void log_backend_dropped(const struct log_backend *const backend, uint32_t cnt)

Оповещает бэкенд по поводу отброшенных сообщений лога. Эта функция опциональна.

Параметры:

backend – [in] указатель на экземпляр бэкенда.
cnt – [in] количество отброшенных логов с момента последнего оповещения.

static inline void log_backend_panic(const struct log_backend *const backend)

Переконфигурирует бэкенд в режим паники.

Параметры:

backend – [in] указатель на экземпляр бэкенда.

static inline void log_backend_id_set(const struct log_backend *const backend, uint8_t id)

Установит идентификатор бэкенда. Эта функция используется внутренне в логгере.

Параметры:

backend – [in] указатель на экземпляр бэкенда.
id – идентификатор.

static inline uint8_t log_backend_id_get(const struct log_backend *const backend)

Возвратит идентификатор бэкенда. Эта функция используется внутренне в логгере.

Параметры:

backend – [in] указатель на экземпляр бэкенда.

static inline const struct log_backend *log_backend_get(uint32_t idx)

Возвратит бэкенд (указатель на экземпляр бэкенда).

Параметры:

backend – [in] указатель на экземпляр бэкенда.

static inline int log_backend_count_get(void)

Возвратит количество бэкендов.

static inline void log_backend_activate(const struct log_backend *const backend, void *ctx)

Активирует бэкенд.

Параметры:

backend – [in] указатель на экземпляр бэкенда.
ctx – [in] пользовательский контекст.

static inline void log_backend_deactivate(const struct log_backend *const backend)

Деактивирует бэкенд.

Параметры:

backend – [in] указатель на экземпляр бэкенда.

static inline bool log_backend_is_active(const struct log_backend *const backend)

Проверит состояние бэкенда.

Параметры:

backend – [in] указатель на экземпляр бэкенда.

Возвращаемое значение: если бэкенд активен, то вернет true, иначе вернет false.

static inline int log_backend_format_set(const struct log_backend *backend,
                                         uint32_t log_type)

Установит формат логгинга.

Параметры:

backend – [in] указатель на экземпляр бэкенда.
log_type – формат лога.

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

-ENOTSUP – если бэкенд не поддерживает изменение типов формата.
-EINVAL – если ввод недопустим.
0 – в случае успеха.

static inline void log_backend_notify(const struct log_backend *const backend,
                                      enum log_backend_evt event,
                                      union log_backend_evt_arg *arg)

Оповещает бэкенд о событии.

Параметры:

backend – [in] указатель на экземпляр бэкенда.
event – оповещаемое событие.
arg – указатель на аргумент (аргументы).

Группа log_output, API вывода лога.

Заголовочные файлы log_output.h, log_output_custom.h.

void log_custom_output_msg_process(const struct log_output *log_output,
                                   struct log_msg *msg,
                                   uint32_t flags)

Пользовательское форматирование вывода лога. Сообщения лога обрабатываются внешней функцией, установленной log_custom_output_msg_set. Функция использует предоставленный контекст с буфером и функцию для обработки строки формата и вывода данных.

Параметры:

log_output – указатель на экземпляр вывода лога.
msg – сообщение лога.
flags – опциональные флаги.

Определения:

LOG_OUTPUT_TEXT

Поддерживаемы бэкендом типы формата для использования log_format_set() API, чтобы переключать формат лога runtime.

LOG_OUTPUT_SYST
LOG_OUTPUT_DICT
LOG_OUTPUT_CUSTOM

LOG_OUTPUT_DEFINE(_name, _func, _buf, _size)

Создает экземпляр log_output.

Параметры:

_name – имя экземпляра.
_func – функция для обработки вывода данных.
_buf – указатель на выходной буфер.
_size – размер выходного буфера.

Определения типов:

typedef int (*log_output_func_t)(uint8_t *buf, size_t size, void *ctx)

Прототип функции, обрабатывающей выводимые данные.

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

Параметры:

buf - буфер данных.
size - размер буфера.
ctx - пользовательский контекст.

Возвратит количество обработанных или отброшенных байт.

typedef void (*log_format_func_t)(const struct log_output *output,
                                  struct log_msg *msg,
                                  uint32_t flags)

Определение указателя на таблицу функций "format_table".

Параметры:

output - указатель на структуру log_output.
msg - указатель на структуру log_msg.
flags - флаги, используемые для опций форматирования текста.

Возвращает указатель на функцию на основе Kconfig, определенных для бэкендов.

Функции:

log_format_func_t log_format_func_t_get(uint32_t log_type)

Декларация подпрограммы get для таблицы указателей на функцию format_table.

void log_output_msg_process(const struct log_output *log_output,
                            struct log_msg *msg,
                            uint32_t flags)

Обработка сообщений лога v2 для читаемых строк.

Функция использует предоставленный контекст с буфером и функцию для обработки строки формата и вывода данных.

Параметры:

log_output – указатель на экземпляр лога вывода.
msg – сообщение лога.
flags – опциональные флаги, см. описание флагов форматирования.

void log_output_process(const struct log_output *log_output,
                        log_timestamp_t timestamp,
                        const char *domain,
                        const char *source,
                        const k_tid_t tid,
                        uint8_t level,
                        const uint8_t *package,
                        const uint8_t *data,
                        size_t data_len,
                        uint32_t flags)

Обрабатывает входные данные в читаемую строку.

Параметры:

log_output – указатель на экземпляр лога вывода.
timestamp – метка времени.
domain – строка имени домена. Может быть NULL.
source – строка имени источника. Может быть NULL.
tid – идентификатор потока (Thread ID).
level – уровень критичности сообщения.
package – пакет Cbprintf со строкой сообщения лога.
data – данные, переданные в hexdump API. Может быть NULL.
data_len – длина данных.
flags – флаги форматирования, см. описание флагов форматирования.

void log_output_msg_syst_process(const struct log_output *log_output,
                                 struct log_msg *msg,
                                 uint32_t flags)

Обрабатывает сообщения лога v2 с преобразованием в формат SYS-T. Функция использует предоставленный контекст с буфером и функцией для обработки строки формата и вывода данных в формате лога sys-t.

Параметры:

log_output – указатель на экземпляр вывода лога.
msg – сообщение лога.
flags – опциональные флаги форматирования, см. описание флагов форматирования.

void log_output_dropped_process(const struct log_output *output, uint32_t cnt)

Обрабатывает индикацию отброшенных сообщений. Функция печатает сообщение ошибки, показывающее потерю сообщений лога.

Параметры:

output – указатель на экземпляр вывода лога.
cnt – количество отброшенных сообщений.

void log_output_flush(const struct log_output *output)

Сливает буфер вывода.

Параметры:

output – указатель на экземпляр вывода лога.

static inline void log_output_ctx_set(const struct log_output *output, void *ctx)

Функция для установки контекста пользователя, передаваемого в функцию вывода.

Параметры:

output – указатель на экземпляр вывода лога.
ctx – контекст пользователя.

static inline void log_output_hostname_set(const struct log_output *output,
                                           const char *hostname)

Функция для установки имени хоста этого устройства.

Параметры:

output – указатель на экземпляр вывода лога.
hostname – имя хоста для этого устройства.

void log_output_timestamp_freq_set(uint32_t freq)

Установит частоту меток времени.

Параметры:

freq – частота в Гц.

uint64_t log_output_timestamp_to_us(log_timestamp_t timestamp)

Преобразует метку времени в сообщения в микросекунды. Возвратит значение метки времени в единицах микросекунд.

Параметры:

timestamp – метка времени сообщения.

Типы данных: 

struct log_output_control_block
struct log_output