]> git.proxmox.com Git - mirror_frr.git/blame - lib/debug.h
Merge pull request #3045 from opensourcerouting/atoms
[mirror_frr.git] / lib / debug.h
CommitLineData
aea03ad6
QY
1/*
2 * Debugging utilities.
3 * Copyright (C) 2018 Cumulus Networks, Inc.
4 * Quentin Young
5 *
6 * This program is free software; you can redistribute it and/or modify it
7 * under the terms of the GNU General Public License as published by the Free
8 * Software Foundation; either version 2 of the License, or (at your option)
9 * any later version.
10 *
11 * This program is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
14 * more details.
15 *
16 * You should have received a copy of the GNU General Public License along
17 * with this program; see the file COPYING; if not, write to the Free Software
18 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
19 */
20#ifndef _FRRDEBUG_H
21#define _FRRDEBUG_H
22
23#include <zebra.h>
24#include "command.h"
25#include "frratomic.h"
26
5e244469
RW
27#ifdef __cplusplus
28extern "C" {
29#endif
30
aea03ad6
QY
31/*
32 * Debugging modes.
33 *
34 * FRR's convention is that a debug statement issued under the vty CONFIG_NODE
35 * persists to the config file, whereas the same debug statement issued from
36 * the ENABLE_NODE only persists for the current session. These are mapped to
37 * DEBUG_MODE_CONF and DEBUG_MODE_TERM respectively.
38 *
39 * They are not mutually exclusive and are placed in the MSB of the flags
40 * field in a debugging record.
41 */
42#define DEBUG_MODE_TERM 0x01000000
43#define DEBUG_MODE_CONF 0x02000000
44#define DEBUG_MODE_ALL (DEBUG_MODE_TERM | DEBUG_MODE_CONF)
45#define DEBUG_MODE_NONE 0x00000000
46#define DEBUG_OPT_ALL 0x00FFFFFF
47#define DEBUG_OPT_NONE 0x00000000
48
49
50/*
51 * Debugging record.
52 *
53 * All operations on this record exposed in this header are MT-safe.
54 *
55 * flags
56 * A bitfield with the following format (bytes high to low)
57 * - [0] Debugging mode field (MSB) | Mode
58 * - [1] Arbitrary flag field | Option
59 * - [2] Arbitrary flag field | Option
60 * - [3] Arbitrary flag field (LSB) | Option
61 *
62 * ALL THESE BYTES ARE YOURS - EXCEPT MODE.
63 * ATTEMPT NO BIT OPS THERE.
64 *
65 * The MSB of this field determines the debug mode, Use the DEBUG_MODE*
66 * macros to manipulate this byte.
67 *
68 * The low 3 bytes of this field may be used to store arbitrary information.
69 * Usually they are used to store flags that tune how detailed the logging
70 * for a particular debug record is. Use the DEBUG_OPT* macros to manipulate
71 * those bytes.
72 *
73 * All operations performed on this field should be done using the macros
74 * later in this header file. They are guaranteed to be atomic operations
75 * with respect to this field. Using anything except the macros to
76 * manipulate the flags field in a multithreaded environment results in
77 * undefined behavior.
78 *
79 * desc
80 * Human-readable description of this debugging record.
81 */
82struct debug {
c8a65463 83 atomic_uint_fast32_t flags;
aea03ad6
QY
84 const char *desc;
85};
86
87/*
88 * Callback set for debugging code.
89 *
90 * debug_set_all
91 * Function pointer to call when the user requests that all debugs have a
92 * mode set.
93 */
94struct debug_callbacks {
95 /*
96 * flags
97 * flags to set on debug flag fields
98 *
99 * set
100 * true: set flags
101 * false: unset flags
102 */
103 void (*debug_set_all)(uint32_t flags, bool set);
104};
105
106/*
107 * Check if a mode is set for a debug.
108 *
109 * MT-Safe
110 */
68881884
QY
111#define DEBUG_MODE_CHECK(name, mode) \
112 CHECK_FLAG_ATOMIC(&(name)->flags, (mode)&DEBUG_MODE_ALL)
aea03ad6
QY
113
114/*
115 * Check if an option bit is set for a debug.
116 *
117 * MT-Safe
118 */
68881884
QY
119#define DEBUG_OPT_CHECK(name, opt) \
120 CHECK_FLAG_ATOMIC(&(name)->flags, (opt)&DEBUG_OPT_ALL)
aea03ad6
QY
121
122/*
123 * Check if bits are set for a debug.
124 *
125 * MT-Safe
126 */
68881884 127#define DEBUG_FLAGS_CHECK(name, fl) CHECK_FLAG_ATOMIC(&(name)->flags, (fl))
aea03ad6
QY
128
129/*
130 * Set modes on a debug.
131 *
132 * MT-Safe
133 */
68881884
QY
134#define DEBUG_MODE_SET(name, mode, onoff) \
135 do { \
136 if (onoff) \
137 SET_FLAG_ATOMIC(&(name)->flags, \
138 (mode)&DEBUG_MODE_ALL); \
139 else \
140 UNSET_FLAG_ATOMIC(&(name)->flags, \
141 (mode)&DEBUG_MODE_ALL); \
142 } while (0)
aea03ad6 143
68881884
QY
144/* Convenience macros for specific set operations. */
145#define DEBUG_MODE_ON(name, mode) DEBUG_MODE_SET(name, mode, true)
146#define DEBUG_MODE_OFF(name, mode) DEBUG_MODE_SET(name, mode, false)
aea03ad6
QY
147
148/*
149 * Set options on a debug.
150 *
151 * MT-Safe
152 */
68881884
QY
153#define DEBUG_OPT_SET(name, opt, onoff) \
154 do { \
155 if (onoff) \
156 SET_FLAG_ATOMIC(&(name)->flags, (opt)&DEBUG_OPT_ALL); \
157 else \
158 UNSET_FLAG_ATOMIC(&(name)->flags, \
159 (opt)&DEBUG_OPT_ALL); \
160 } while (0)
aea03ad6 161
68881884
QY
162/* Convenience macros for specific set operations. */
163#define DEBUG_OPT_ON(name, opt) DEBUG_OPT_SET(name, opt, true)
164#define DEBUG_OPT_OFF(name, opt) DEBUG_OPT_SET(name, opt, true)
aea03ad6
QY
165
166/*
167 * Set bits on a debug.
168 *
169 * MT-Safe
170 */
68881884
QY
171#define DEBUG_FLAGS_SET(name, fl, onoff) \
172 do { \
173 if (onoff) \
174 SET_FLAG_ATOMIC(&(name)->flags, (fl)); \
175 else \
176 UNSET_FLAG_ATOMIC(&(name)->flags, (fl)); \
177 } while (0)
aea03ad6 178
68881884
QY
179/* Convenience macros for specific set operations. */
180#define DEBUG_FLAGS_ON(name, fl) DEBUG_FLAGS_SET(&(name)->flags, (type), true)
181#define DEBUG_FLAGS_OFF(name, fl) DEBUG_FLAGS_SET(&(name)->flags, (type), false)
aea03ad6
QY
182
183/*
184 * Unset all modes and options on a debug.
185 *
186 * MT-Safe
187 */
188#define DEBUG_CLEAR(name) RESET_FLAG_ATOMIC(&(name)->flags)
189
190/*
191 * Set all modes and options on a debug.
192 *
193 * MT-Safe
194 */
195#define DEBUG_ON(name) \
196 SET_FLAG_ATOMIC(&(name)->flags, DEBUG_MODE_ALL | DEBUG_OPT_ALL)
197
198/*
199 * Map a vty node to the correct debugging mode flags. FRR behaves such that a
200 * debug statement issued under the config node persists to the config file,
201 * whereas the same debug statement issued from the enable node only persists
202 * for the current session.
203 *
204 * MT-Safe
205 */
206#define DEBUG_NODE2MODE(vtynode) \
207 (((vtynode) == CONFIG_NODE) ? DEBUG_MODE_ALL : DEBUG_MODE_TERM)
208
68881884
QY
209/*
210 * Debug at the given level to the default logging destination.
211 *
212 * MT-Safe
213 */
214#define DEBUG(level, name, fmt, ...) \
215 do { \
216 if (DEBUG_MODE_CHECK(name, DEBUG_MODE_ALL)) \
217 zlog_##level(fmt, ##__VA_ARGS__); \
218 } while (0)
219
220/* Convenience macros for the various levels. */
221#define DEBUGE(name, fmt, ...) DEBUG(err, name, fmt, ##__VA_ARGS__)
222#define DEBUGW(name, fmt, ...) DEBUG(warn, name, fmt, ##__VA_ARGS__)
223#define DEBUGI(name, fmt, ...) DEBUG(info, name, fmt, ##__VA_ARGS__)
224#define DEBUGN(name, fmt, ...) DEBUG(notice, name, fmt, ##__VA_ARGS__)
225#define DEBUGD(name, fmt, ...) DEBUG(debug, name, fmt, ##__VA_ARGS__)
aea03ad6
QY
226
227/*
228 * Optional initializer for debugging. Highly recommended.
229 *
230 * This function installs common debugging commands and allows the caller to
231 * specify callbacks to take when these commands are issued, allowing the
232 * caller to respond to events such as a request to turn off all debugs.
233 *
234 * MT-Safe
235 */
236void debug_init(const struct debug_callbacks *cb);
237
5e244469
RW
238#ifdef __cplusplus
239}
240#endif
241
aea03ad6 242#endif /* _FRRDEBUG_H */