forked from lolo859/vystem
54 lines
3.2 KiB
Markdown
54 lines
3.2 KiB
Markdown
# Print primitives
|
|
|
|
## Introduction
|
|
|
|
The standard library provides his own abstraction to print strings. This abstraction can be used before the APs bootstrap and must be used after the APs bootstrap. The print implementation in the standard library is fully thread-safe. The print implementation is defined inside `shelter/lib/include/std/print.h` and implemented inside `shelter/lib/include/std/print.c`.
|
|
|
|
The format syntax is the same used in the kernel logging API. See [format syntax](../kernel/log.md).
|
|
|
|
## Print initialization
|
|
|
|
Before the initialization of the print implementation, all output using `sh_print` and `sh_printf` is redirected to the kernel logging API.
|
|
|
|
The initialization of the print implementation is done through `sh_print_setup_ring_buffers_per_ap()`. This function initializes a ring buffer for each CPU, including the bootstrap CPU. The size of each ring buffer is the amount of bytes for the global logging ring buffer divided by the amount of CPU.
|
|
|
|
Every single print primitives (except `sh_sprintf`, which doesn't print anything) respect the log level specified in the kernel boot configuration.
|
|
|
|
## Characteristics
|
|
|
|
This print implementation differ of the kernel logging API by these differences:
|
|
- It doesn't support displaying the name of the subsystem
|
|
- It shows the logical CPU id of the AP that called the print implementation
|
|
|
|
It also defines its own macros for the type of output: `SH_DEBUG`, `SH_LOG`, `SH_WARNING`, `SH_ERROR`, `SH_CRITICAL`, `SH_FATAL`, `SH_TEST`, `SH_FAULT`
|
|
|
|
## Normal printing
|
|
|
|
### API
|
|
|
|
The print implementation provide two functions for normal printing:
|
|
- `sh_print(sh_log_OUTPUT_TYPE output_type,char *text)`: print a normal string without formatting the text before hand
|
|
- `sh_printf(sh_log_OUTPUT_TYPE output_type,char* format,...)`: format and print the formatted string byte by byte
|
|
|
|
### Detailled processus
|
|
|
|
For normal printing, the outputed text goes through two main steps:
|
|
|
|
First, each byte is outputed into the local printing ring buffer. We keep track of the amount of bytes outputed using the attribute in the per-CPU struct of this CPU.
|
|
|
|
Then, extracting the outputed byte from the local printing ring buffer, all outputed bytes are sent to the serial port, no without locking a global serial spinlock before.
|
|
|
|
## Interrupts printing
|
|
|
|
The print system also provides a dedicated path for interrupt handlers. In this mode, output bypasses the local ring buffer and is written directly to the serial port after acquiring the serial spinlock. If the lock is already held by another CPU, the function will block until it becomes available.
|
|
|
|
The API is as follows:
|
|
- `sh_iprint(sh_log_OUTPUT_TYPE output_type,char *text)`: same as `sh_print` but for interrupt handlers
|
|
- `SH_STATUS sh_iprintf(sh_log_OUTPUT_TYPE output_type,char* format,...)`: same as `sh_iprintf` but for interrupt handlers
|
|
|
|
## String formatting
|
|
|
|
Finally, the print implementation provides a way to easely format strings using the same format syntax, using `sh_sprintf(char *output_string,sh_uint64 output_len,char *format,...)`.
|
|
|
|
This function writes into the provided buffer only. It doesn't print to the serial port, doesn't use ring buffers, and doesn't allocate memory via `sh_malloc`.
|