Операционная система ЗОСРВ «Нейтрино» > Руководство разработчика > Программные интерфейсы общего назначения > Системные библиотеки > Системные библиотеки > Системная библиотека > K > kprintf(), kprintf_setup(), ksnprintf(), ksprintf(), kvprintf(), kvsnprintf(), kcallout_putchar()

kprintf(), kprintf_setup(), ksnprintf(), ksprintf(), kvprintf(), kvsnprintf(), kcallout_putchar()

Печать в отладочный терминал

Прототип:

#include <sys/kprintf.h>
                                                                               
void kprintf_setup( void (*putcf)(const char),
                    const kprintf_mode_t mode );
int kprintf( const char *fmt,
             ... );
int ksnprintf( char *buf,
               size_t len,
               const char *fmt,
               ... );
int ksprintf( char *buf,
              const char *fmt,
              ... );
int kvprintf( const char *fmt,
              va_list args );
int kvsnprintf( char *buf,
                size_t len,
                const char *fmt,
                va_list args );
void kcallout_putchar( const char c );

Аргументы:

fmt

Строка, управляющая форматом вывода. Определяет дополнительные аргументы, которые необходимо передать функции.

args

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

buf

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

len

Максимальное количество символов для записи в буфер, включая нулевой завершающий символ.

putcf

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

mode

Битовая маска режимов работы kprintf. Режимы задаются следующими константами (определены в <sys/kprintf.h>):

KPRINTF_DEFAULT_BEHAVIOR

Выводить строку, переданную в kprintf(), ksnprintf(), ksprintf(), kvprintf(), kvsnprintf(), без предварительных операций.

KPRINTF_DO_INTERRUPT_DISABLE

Выключать прерывания на время вывода переданной в kprintf(), ksnprintf(), ksprintf(), kvprintf(), kvsnprintf() строки.

KPRINTF_DO_SPIN_LOCK

Активировать циклическую блокировку на время вывода переданной в kprintf(), ksnprintf(), ksprintf(), kvprintf(), kvsnprintf() строки.

c

Печатаемый символ.

Библиотека:

libc

Описание:

Функция kprintf_setup() настраивает поведение функций kprintf(), ksnprintf(), ksprintf(), kvprintf(), kvsnprintf().

В качестве параметра putcf нужно передать функцию печати символа в отладочный терминал.

Для выключения прерывания на время вывода переданной строки в качестве параметра do_interrupt_disable нужно передать true.

Функции kprintf(), kvprintf() выводят символы с помощью функции putcf, согласно спецификатору формата fmt.

Функция ksprintf() записывает символы в буфер buf, согласно спецификатору формата fmt.

Функции ksnprintf(), kvsnprintf() записывают символы в буфер buf согласно спецификатору формата fmt и имеют ограничение по размеру записываемых данных len.

Функция kcallout_putchar() выводит символ через функцию вывода в отладочную консоль (display_char callout).

---

Использование функций данного семейства в ISR безопасно лишь в случае использования kcallout_putchar() для вывода в отладочную консоль: kprintf_setup( kcallout_putchar, KPRINTF_DO_INTERRUPT_DISABLE | KPRINTF_DO_SPIN_LOCK );

---

Аргументы формата

Если после обработки fmt остались неучтенные аргументы, они игнорируются.

Управление форматом

Строка управления форматом состоит из:

Обычные символы

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

Спецификаторы преобразования

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

• ноль или флаги управления форматом флаги управления форматом, которые могут изменить конечный эффект директивы формата
• необязательное десятичное целое число или символ *, указывающая минимальную ширину поля ширина поля, которая должна быть зарезервирована для отформатированного элемента
• необязательный спецификатор длины типа спецификатор длины типа, один из: h, hh, l, ll, L или z .
• символ, определяющий тип преобразования спецификатор типа преобразования, который необходимо выполнить.

Флаги управления форматом

Допустимые флаги управления форматом:

-

выравнивание по левому краю отформатированного элемента в поле вывода; обычно элементы выравниваются по правому краю.

0 (zero)

Преобразуемое значение слева дополняется нулями (вместо пробелов) для d, b, o, u, x и X преобразований. Флаг «-» переопределяет этот флаг.

Ширина поля

Если не была указана ширина поля или заданное значение меньше числа символов в преобразованном значении, используется поле достаточной ширины, чтобы содержать преобразованное значение.

Если преобразованное значение содержит меньше символов, чем указано шириной поля, значение дополняется слева (или справа, в зависимости от флага выравнивания по левому краю) пробелами или нулевыми символами (0). Если ширина поля начинается с нуля, значение дополняется нулями; в противном случае значение дополняется пробелами.

Если ширина поля равна * (или 0*), значение типа int из списка аргументов используется (перед аргументом преобразования) в качестве минимальной ширины поля. Отрицательное значение ширины поля интерпретируется как флаг выравнивания по левому краю, за которым следует положительное значение ширины поля.

Спецификатор длины типа

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

• h устанавливает для целых преобразователей d, b, o, u, x или X соответствие аргументам short int или unsigned short int.

• hh аналогичен h, но обрабатывает аргумент как signed char или unsigned char.

• L устанавливает для целых преобразователей d, b, o, u, x или X размер, значение которого типа size_t извлекается из списка аргументов перед аргументом преобразования.

• l устанавливает для целых преобразователей d, b, o, u, x или X соответствие аргументам long или unsigned long.

• ll устанавливает для целых преобразователей d, b, o, u, x или X соответствие аргументам long long или unsigned long long.

• z устанавливает для целых преобразователей d, b, o, u, x, X соответствие аргументу size_t.

Спецификаторы типа преобразования

Допустимые спецификаторы типа преобразования:

c

Преобразование аргумента типа int в значение типа unsigned char.

d

Преобразование аргумента типа int в десятичную запись со знаком.

u

Преобразование аргумента типа unsigned в беззнаковую десятичную запись.

o

Преобразование аргумента типа unsigned в восьмеричное представление без знака.

b

Преобразование аргумента типа unsigned в двоичное представление без знака.

x, X

Преобразование аргумента типа unsigned в шестнадцатеричное представление без знака. Шестнадцатеричная запись использует цифры от 0 до 9 и символы от a до f или от A до F для преобразования x или X, соответственно, в качестве шестнадцатеричных цифр.

p

Преобразование аргумента типа void * в значение типа uintptr_t и форматирование значения как для шестнадцатеричного (x) преобразования. Ширина поля устанавливается в максимальное значение для типа uintptr_t. Значение дополняется слева нулевыми символами (0).

s

Вывод символов из строки, заданной аргументом типа char *, вплоть до завершающего символа NULL ('\0'), но не включая его.

%

Напечатать символ %.

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

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

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

>=0

Число записанных байт без завершающего NULL

Примеры:

#define _PADDR_BITS 64
#include <stdio.h>
#include <stdlib.h>
#include <sys/kprintf.h>
#include <sys/types.h>
 
static void
kputchar(const char c)
{
    putchar(c);
}
 
int main(int argc, char *argv[])
{
    paddr_t paddr = argc > 1 ? strtoull(argv[1], NULL, 0) : 0x4b504441;
     
    kprintf_setup(kputchar, KPRINTF_DEFAULT_BEHAVIOR);
    kprintf("%s(): paddr 0x%0*Lx\n", __func__, sizeof(paddr) * 2, sizeof(paddr), paddr);
     
    return (EXIT_SUCCESS);
}

Код генерирует следующий вывод:

$ ./a.out main(): paddr 0x000000004b504441

Классификация:

ЗОСРВ «Нейтрино»

Безопасность использования

Точка остановки потока

Нет

Обработчик прерываний

Да

Обработчик сигналов

Нет

В потоке

Да

Тематические ссылки:

putchar()

Предыдущий раздел: Описание API системной библиотеки