docs/design/console-framework.rst

4 The TF-A console framework is used to register consoles for different boot states
8 The console framework supports a number of different UARTs, it is highly likely
40 The console framework supports multiple consoles. Multiple instances of a UART
41 can be registered at any given moment. Any registered console can have a single
44 console will display only boot logs, the runtime console will display only the
45 runtime output, while the crash console will be used to print the crash log in the
46 event of a crash. Similarly, a console with all three scopes will display any and
52 * Having a single console for both Runtime and Boot messages
53 * Having no runtime console at all and just having a single Boot console.
54 * Having a separate console for crash reporting when debugging.
56 .. Registering a console:
58 Registering a console
60 To register a console in TF-A check if the hardware (UART) that is going to be used
64 A skeleton console driver (assembly) is provided in TF-A ``drivers/console/aarch64/
77 This ASM Function is used to initialize and register a console. The caller needs
89         The ``xxx`` in the function name is replaced with the console driver
109         Avoid the direct use of this function for printing to the console, instead use
137 haven't been printed yet to the console. It takes a pointer to the console_struct
149     xxx      : name of the console driver
155 encapsulate the common setup that has to be done at the end of a console
167 Registering a console using C
170 A console can be implemented in pure C, which is much easier than using assembly.
171 Currently there is no C template for implementing a console driver in C but it can
173 for an implementation of a console driver in C.
175 The assembly functions in `Registering a console`_ section can be written in C when
176 implementing a console driver using C.
180         support is required then the console driver will need to be written in
187 TF-A uses the multi-console API to manage the registered console instances and the
188 characters print queue. This can be found in ``drivers/console/multi_console.c``.
190 The multi-console API stores all registered consoles in a struct list ``console_list``.
213 This function adds a console to the ``console_list`` declared in
214 ``include/drivers/console.h`` and makes sure that there is only one instance
215 of a specific console in this list. This function is called by the
216 ``finish_console_register`` asm macro function, at the end of the console
219 This function always return 1. If the console is already present in the
221 it will add the console to the ``console_list`` and then return 1.
225         variable declared in ``include/drivers/console.h``.
235 This function removes a console from the ``console_list``. It will return the
236 removed console on success or a ``NULL`` character upon failure.
246 This function is used to set the scope of the registered console. A console
253 It takes a pointer to the console and an int value (which is provided as the
264 This function sets the console state (scope) for printing, i.e, TF-A will
269 console state.
271 This function takes a console state as the function's only argument. This function
282 Invoking this function sends a character to the ``console->putc`` (struct
285 implementation ``console->putc`` call points to the ``console_pl011_putc()``
294         messages on the active console.
305 not been printed to the console yet. This function is disabled by default for
334 the active console.