docs/design/console-framework.rst

8 The console framework supports a number of different UARTs, it is highly likely
9 that the driver of the UART that is needed is already implemented. If not, a driver
29         already been written before writing a new one.
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
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
65 skeleton_console.S``, this skeleton sets the rules for writing a new console_driver.
66 Have a look at ``drivers/arm/pl011/aarch64/pl011_console.S`` for an actual
77 This ASM Function is used to initialize and register a console. The caller needs
79 memory (e.g. a global or static local variable, *NOT* on the stack).
81 This function takes a ``console_t`` struct placed in x0 and additional
82 arguments placed in x1 - x7. It returns x0 with either a 0 on failure or 1
101 This ASM function is used to send a character to the UART's Transmit FIFO. It takes
102 two arguments, a character as int stored in w0, and the ``console_t`` struct pointer
103 stored in x1. It returns w0 with either the character on successs or a negative
104 value on error. In a crash context this function must only clobber x0 - x2, x16 - x17.
121 This ASM function is used to read a character from the receive FIFO. It takes a pointer
122 to the console_struct as an argument and returns a character on success or a negative
137 haven't been printed yet to the console. It takes a pointer to the console_struct
138 but doesn't return any value. In a crash context this function must only clobber
155 encapsulate the common setup that has to be done at the end of a console
160 ``console_set_scope`` function). This macro ends with a tail call that will
163 This macro requires ``console_t`` pointer in x0 and a valid return address in x30.
167 Registering a console using C
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.
179         A crash callback needs to be able to run without a stack. If crash mode
181         Assembly (only the putc and flush functions are needed in a crash
190 The multi-console API stores all registered consoles in a struct list ``console_list``.
199 be enabled if there is a need for it). The API can also help flush the transmit FIFO
213 This function adds a console to the ``console_list`` declared in
215 of a specific console in this list. This function is called by the
220 ``console_list`` it will return immediately with a value of 1, otherwise
224         The ``console_list`` is a list of type ``console_t``, it is an **extern**
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.
253 It takes a pointer to the console and an int value (which is provided as the
271 This function takes a console state as the function's only argument. This function
272 does not return a value.
282 Invoking this function sends a character to the ``console->putc`` (struct
284 BOOT logs will only be printed on consoles set with a BOOT scope. In the PL011
288 This function takes the int value of a character as an argument and returns the
289 int value of the character back on success or a negative int value on error.
304 This function is used to fetch a character from the receive FIFO that has
307 if there is a need for it.
309 This function doesn't take any argument but returns a character as an int.
322 This function has no arguments and do not return a value.
333 used to send a character to the ``console_putc()`` function to be printed to