gdbsupport/common-debug.h

   1 /* Declarations for debug printing functions.
   2
   3    Copyright (C) 2014-2022 Free Software Foundation, Inc.
   4
   5    This file is part of GDB.
   6
   7    This program is free software; you can redistribute it and/or modify
   8    it under the terms of the GNU General Public License as published by
   9    the Free Software Foundation; either version 3 of the License, or
  10    (at your option) any later version.
  11
  12    This program is distributed in the hope that it will be useful,
  13    but WITHOUT ANY WARRANTY; without even the implied warranty of
  14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15    GNU General Public License for more details.
  16
  17    You should have received a copy of the GNU General Public License
  18    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  19
  20 #ifndef COMMON_COMMON_DEBUG_H
  21 #define COMMON_COMMON_DEBUG_H
  22
  23 #include "gdbsupport/gdb_optional.h"
  24 #include "gdbsupport/preprocessor.h"
  25
  26 #include <stdarg.h>
  27
  28 /* Set to true to enable debugging of hardware breakpoint/
  29    watchpoint support code.  */
  30
  31 extern bool show_debug_regs;
  32
  33 /* Print a formatted message to the appropriate channel for
  34    debugging output for the client.  */
  35
  36 extern void debug_printf (const char *format, ...)
  37      ATTRIBUTE_PRINTF (1, 2);
  38
  39 /* Print a formatted message to the appropriate channel for
  40    debugging output for the client.  This function must be
  41    provided by the client.  */
  42
  43 extern void debug_vprintf (const char *format, va_list ap)
  44      ATTRIBUTE_PRINTF (1, 0);
  45
  46 /* Print a debug statement prefixed with the module and function name, and
  47    with a newline at the end.  */
  48
  49 extern void ATTRIBUTE_PRINTF (3, 4) debug_prefixed_printf
  50   (const char *module, const char *func, const char *format, ...);
  51
  52 /* Print a debug statement prefixed with the module and function name, and
  53    with a newline at the end.  */
  54
  55 extern void ATTRIBUTE_PRINTF (3, 0) debug_prefixed_vprintf
  56   (const char *module, const char *func, const char *format, va_list args);
  57
  58 /* Helper to define "_debug_print" macros.
  59
  60    DEBUG_ENABLED_COND is an expression that evaluates to true if the debugging
  61    statement is enabled and should be printed.
  62
  63    The other arguments, as well as the name of the current function, are
  64    forwarded to debug_prefixed_printf.  */
  65
  66 #define debug_prefixed_printf_cond(debug_enabled_cond, module, fmt, ...) \
  67   do \
  68     { \
  69       if (debug_enabled_cond) \
  70         debug_prefixed_printf (module, __func__, fmt, ##__VA_ARGS__); \
  71     } \
  72   while (0)
  73
  74 #define debug_prefixed_printf_cond_nofunc(debug_enabled_cond, module, fmt, ...) \
  75   do \
  76     { \
  77       if (debug_enabled_cond) \
  78         debug_prefixed_printf (module, nullptr, fmt, ##__VA_ARGS__); \
  79     } \
  80   while (0)
  81
  82 /* Nesting depth of scoped_debug_start_end objects.  */
  83
  84 extern int debug_print_depth;
  85
  86 /* Print a message on construction and destruction, to denote the start and end
  87    of an operation.  Increment DEBUG_PRINT_DEPTH on construction and decrement
  88    it on destruction, such that nested debug statements will be printed with
  89    an indent and appear "inside" this one.  */
  90
  91 struct scoped_debug_start_end
  92 {
  93   /* DEBUG_ENABLED is a reference to a variable that indicates whether debugging
  94      is enabled, so if the debug statements should be printed.  Is is read
  95      separately at construction and destruction, such that the start statement
  96      could be printed but not the end statement, or vice-versa.
  97
  98      MODULE and FUNC are forwarded to debug_prefixed_printf.
  99
 100      START_PREFIX and END_PREFIX are the statements to print on construction and
 101      destruction, respectively.
 102
 103      If the FMT format string is non-nullptr, then a `: ` is appended to the
 104      messages, followed by the rendering of that format string.  The format
 105      string is rendered during construction and is re-used as is for the
 106      message on exit.  */
 107
 108   scoped_debug_start_end (bool &debug_enabled, const char *module,
 109                           const char *func, const char *start_prefix,
 110                           const char *end_prefix, const char *fmt, ...)
 111     ATTRIBUTE_NULL_PRINTF (7, 8)
 112     : m_debug_enabled (debug_enabled),
 113       m_module (module),
 114       m_func (func),
 115       m_end_prefix (end_prefix),
 116       m_with_format (fmt != nullptr)
 117   {
 118     if (m_debug_enabled)
 119       {
 120         if (fmt != nullptr)
 121           {
 122             va_list args;
 123             va_start (args, fmt);
 124             m_msg = string_vprintf (fmt, args);
 125             va_end (args);
 126
 127             debug_prefixed_printf (m_module, m_func, "%s: %s",
 128                                    start_prefix, m_msg->c_str ());
 129           }
 130         else
 131           debug_prefixed_printf (m_module, m_func, "%s", start_prefix);
 132
 133         ++debug_print_depth;
 134         m_must_decrement_print_depth = true;
 135       }
 136   }
 137
 138   DISABLE_COPY_AND_ASSIGN (scoped_debug_start_end);
 139
 140   ~scoped_debug_start_end ()
 141   {
 142     if (m_must_decrement_print_depth)
 143       {
 144         gdb_assert (debug_print_depth > 0);
 145         --debug_print_depth;
 146       }
 147
 148     if (m_debug_enabled)
 149       {
 150         if (m_with_format)
 151           {
 152             if (m_msg.has_value ())
 153               debug_prefixed_printf (m_module, m_func, "%s: %s",
 154                                      m_end_prefix, m_msg->c_str ());
 155             else
 156               {
 157                 /* A format string was passed to the constructor, but debug
 158                    control variable wasn't set at the time, so we don't have the
 159                    rendering of the format string.  */
 160                 debug_prefixed_printf (m_module, m_func, "%s: <%s debugging was not enabled on entry>",
 161                                        m_end_prefix, m_module);
 162               }
 163           }
 164         else
 165           debug_prefixed_printf (m_module, m_func, "%s", m_end_prefix);
 166       }
 167   }
 168
 169 private:
 170   bool &m_debug_enabled;
 171   const char *m_module;
 172   const char *m_func;
 173   const char *m_end_prefix;
 174
 175   /* The result of formatting the format string in the constructor.  */
 176   gdb::optional<std::string> m_msg;
 177
 178   /* True is a non-nullptr format was passed to the constructor.  */
 179   bool m_with_format;
 180
 181   /* This is used to handle the case where debugging is enabled during
 182      construction but not during destruction, or vice-versa.  We want to make
 183      sure there are as many increments are there are decrements.  */
 184   bool m_must_decrement_print_depth = false;
 185 };
 186
 187 /* Helper to define a module-specific start/end debug macro.  */
 188
 189 #define scoped_debug_start_end(debug_enabled, module, fmt, ...) \
 190   scoped_debug_start_end CONCAT(scoped_debug_start_end, __LINE__) \
 191     (debug_enabled, module, __func__, "start", "end", fmt, ##__VA_ARGS__)
 192
 193 /* Helper to define a module-specific enter/exit debug macro.  This is a special
 194    case of `scoped_debug_start_end` where the start and end messages are "enter"
 195    and "exit", to denote entry and exit of a function.  */
 196
 197 #define scoped_debug_enter_exit(debug_enabled, module) \
 198   scoped_debug_start_end CONCAT(scoped_debug_start_end, __LINE__) \
 199     (debug_enabled, module, __func__, "enter", "exit", nullptr)
 200
 201 #endif /* COMMON_COMMON_DEBUG_H */