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

Last change on this file since 583 was 583, checked in by alain, 6 years ago

Improve signals.
File size: 8.1 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 * function_name,
101            uint32_t     line,
102            cycle_t      cycle,
103            const char * format,
104            ... ) __attribute__((__noreturn__));
105
106/**********************************************************************************
107 * This macro displays a formated message on kernel TXT0 terminal,
108 * and forces the calling core in sleeping mode if a Boolean condition is false.
109 * Actually used to debug the kernel.
110 *
111 * Extra information printed by assert:
112 * - Current thread, process, and core
113 * - Function name / line number in file / cycle
114 **********************************************************************************
115 * @ condition     : condition that must be true.
116 * @ format        : formatted string
117 *********************************************************************************/
118#define assert( expr, format, ... )                                               \
119{                                                                                 \
120    uint32_t __line_at_expansion = __LINE__;                                      \
121    const volatile cycle_t __assert_cycle = hal_get_cycles();                     \
122    if ( ( expr ) == false )                                                      \
123    {                                                                             \
124        panic( __FUNCTION__,                                                      \
125               __line_at_expansion,                                               \
126               __assert_cycle,                                                    \
127               ( format ), ##__VA_ARGS__ );                                       \
128    }                                                                             \
129}
130
131/**********************************************************************************
132 * This function displays a non-formated message on kernel TXT0 terminal.
133 * This function is actually used to debug the assembly level kernel functions.
134 **********************************************************************************
135 * @ string   : non-formatted string.
136 *********************************************************************************/
137void puts( char * string );
138
139/**********************************************************************************
140 * This function displays a 32 bits value in hexadecimal on kernel TXT0 terminal.
141 * This function is actually used to debug the assembly level kernel functions.
142 **********************************************************************************
143 * @ val   : 32 bits unsigned value.
144 *********************************************************************************/
145void putx( uint32_t val );
146
147/**********************************************************************************
148 * This function displays a 64 bits value in hexadecimal on kernel TXT0 terminal.
149 * This function is actually used to debug the assembly level kernel functions.
150 **********************************************************************************
151 * @ val   : 64 bits unsigned value.
152 *********************************************************************************/
153void putl( uint64_t val );
154
155
156#endif  // _PRINTK_H
157
158// Local Variables:
159// tab-width: 4
160// c-basic-offset: 4
161// c-file-offsets:((innamespace . 0)(inline-open . 0))
162// indent-tabs-mode: nil
163// End:
164// vim: filetype=c:expandtab:shiftwidth=4:tabstop=4:softtabstop=4
165
Note: See TracBrowser for help on using the repository browser.