source: trunk/kernel/kern/printk.h @ 569

Last change on this file since 569 was 564, checked in by alain, 7 years ago

Complete restructuration of kernel locks.
File size: 8.5 KB
Line 
1/*
2 * printk.h - Kernel Log & debug messages API definition.
3 *
4 * authors  Alain Greiner (2016,2017,2018)
5 *
6 * Copyright (c) UPMC Sorbonne Universites
7 *
8 * This file is part of ALMOS-MKH.
9 *
10 * ALMOS-MKH is free software; you can redistribute it and/or modify it
11 * under the terms of the GNU General Public License as published by
12 * the Free Software Foundation; version 2.0 of the License.
13 *
14 * ALMOS-MKH is distributed in the hope that it will be useful, but
15 * WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
17 * General Public License for more details.
18 *
19 * You should have received a copy of the GNU General Public License
20 * along with ALMOS-MKH; if not, write to the Free Software Foundation,
21 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
22 */
23
24///////////////////////////////////////////////////////////////////////////////////
25// The printk.c and printk.h files define the functions used by the kernel
26// to display messages on a text terminal.
27// Two access modes are supported:
28// - The printk() function displays kernel messages on the kernel terminal TXT0,
29//   using a busy waiting policy: It calls directly the relevant TXT driver,
30//   after taking the TXT0 busylock for exclusive access to the TXT0 terminal.
31// - The user_printk() function displays messages on the calling thread private
32//   terminal, using a descheduling policy: it register the request in the selected
33//   TXT chdev waiting queue and deschedule. The calling thread is reactivated by
34//   the IRQ signalling completion.
35// Both functions use the generic TXT device to call the proper implementation
36// dependant TXT driver.
37// Finally these files define a set of conditional trace <***_dmsg> for debug.
38///////////////////////////////////////////////////////////////////////////////////
39
40#ifndef _PRINTK_H
41#define _PRINTK_H
42
43#include <hal_kernel_types.h>
44#include <stdarg.h>
45
46#include <hal_special.h> // hal_get_cycles()
47
48/**********************************************************************************
49 * This function build a formatted string.
50 * The supported formats are defined below :
51 *   %c : single character
52 *   %d : signed decimal 32 bits integer
53 *   %u : unsigned decimal 32 bits integer
54 *   %x : hexadecimal 32 bits integer
55 *   %l : hexadecimal 64 bits integer
56 *   %s : NUL terminated character string
57 **********************************************************************************
58 * @ string     : pointer on target buffer (allocated by caller).
59 * @ length     : target buffer length (number of bytes).
60 * @ format     : format respecting the printf syntax.
61 * @ returns the string length (including NUL) if success / return -1 if error.
62 *********************************************************************************/
63uint32_t snprintf( char     * string,
64                   uint32_t   length,
65                   char     * format, ... );
66
67/**********************************************************************************
68 * This function displays a formatted string on the kernel terminal TXT0,
69 * after taking the TXT0 lock.
70 * It uses a busy waiting policy, calling directly the relevant TXT driver,
71 **********************************************************************************
72 * @ format     : formatted string.
73 *********************************************************************************/
74void printk( char* format, ... );
75
76/**********************************************************************************
77 * This function displays a formatted string on the kernel terminal TXT0,
78 * without taking the TXT0 lock.
79 * It uses a busy waiting policy, calling directly the relevant TXT driver,
80 **********************************************************************************
81 * @ format     : formatted string.
82 *********************************************************************************/
83void nolock_printk( char* format, ... );
84
85
86/**********************************************************************************
87 * This function is called in case of kernel panic. It printt a detailed message
88 * on the TXT0 terminal after taking the TXT0 lock, and call the hal_core_sleep()
89 * function to block the calling core.  It is used by the assert macro (below).
90 **********************************************************************************
91 * @ file_name     : File where the assert macro was invoked
92 * @ function_name : Name of the calling function.
93 * @ line          : Line number where the assert macro was invoked
94 * @ cycle         : Cycle where the macro was invoked
95 * @ format        : Formatted string
96 * ...             : arguments of the format string
97 *
98 * See assert macro documentation for information about printed information.
99 *********************************************************************************/
100void panic( const char * file_name,
101            const char * function_name,
102            uint32_t     line,
103            cycle_t      cycle,
104            const char * format,
105            ... ) __attribute__((__noreturn__));
106
107/**********************************************************************************
108 * This macro displays a formated message on kernel TXT0 terminal,
109 * and forces the calling core in sleeping mode if a Boolean condition is false.
110 * Actually used to debug the kernel.
111 *
112 * Information printed by assert:
113 * Current running thread:
114 *   - thread descriptior adress
115 *   - thread id (trdid)
116 *
117 * Current Process:
118 *   - Process descriptor adress
119 *   - Process id (pid)
120 *
121 * Current Core:
122 *   - local cluster position (local_cxy)
123 *   - local core id (lid)
124 *
125 * File name (__FILE__) and were the assert is invoked.
126 * And the assert message.
127 *
128 * Cycle: before the assert branchment.
129 * Note: cycle may change due to compiler optimisation.
130 *
131 * Exemple:
132 * assert( my_ptr != NULL, "my_ptr should not be NULL")
133 **********************************************************************************
134 * @ condition     : condition that must be true.
135 * @ format        : formatted string
136 *********************************************************************************/
137#define assert( expr, format, ... )                                               \
138{                                                                                 \
139    uint32_t __line_at_expansion = __LINE__;                                      \
140    const volatile cycle_t __assert_cycle = hal_get_cycles();                     \
141    if ( ( expr ) == false )                                                      \
142    {                                                                             \
143        panic( __FILE__, __FUNCTION__,                                            \
144               __line_at_expansion, __assert_cycle,                               \
145               ( format ), ##__VA_ARGS__ );                                       \
146    }                                                                             \
147}
148
149/**********************************************************************************
150 * This function displays a non-formated message on kernel TXT0 terminal.
151 * This function is actually used to debug the assembly level kernel functions.
152 **********************************************************************************
153 * @ string   : non-formatted string.
154 *********************************************************************************/
155void puts( char * string );
156
157/**********************************************************************************
158 * This function displays a 32 bits value in hexadecimal on kernel TXT0 terminal.
159 * This function is actually used to debug the assembly level kernel functions.
160 **********************************************************************************
161 * @ val   : 32 bits unsigned value.
162 *********************************************************************************/
163void putx( uint32_t val );
164
165/**********************************************************************************
166 * This function displays a 64 bits value in hexadecimal on kernel TXT0 terminal.
167 * This function is actually used to debug the assembly level kernel functions.
168 **********************************************************************************
169 * @ val   : 64 bits unsigned value.
170 *********************************************************************************/
171void putl( uint64_t val );
172
173
174#endif  // _PRINTK_H
175
176// Local Variables:
177// tab-width: 4
178// c-basic-offset: 4
179// c-file-offsets:((innamespace . 0)(inline-open . 0))
180// indent-tabs-mode: nil
181// End:
182// vim: filetype=c:expandtab:shiftwidth=4:tabstop=4:softtabstop=4
183
Note: See TracBrowser for help on using the repository browser.