gdbsupport/common-debug.h

   1 /* Declarations for debug printing functions.
   2
   3    Copyright (C) 2014-2024 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 <optional>
  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 template<typename PT>
  92 struct scoped_debug_start_end
  93 {
  94   /* DEBUG_ENABLED is a reference to a variable that indicates whether debugging
  95      is enabled, so if the debug statements should be printed.  Is is read
  96      separately at construction and destruction, such that the start statement
  97      could be printed but not the end statement, or vice-versa.
  98
  99      DEBUG_ENABLED should either be of type 'bool &' or should be a type
 100      that can be invoked.
 101
 102      MODULE and FUNC are forwarded to debug_prefixed_printf.
 103
 104      START_PREFIX and END_PREFIX are the statements to print on construction and
 105      destruction, respectively.
 106
 107      If the FMT format string is non-nullptr, then a `: ` is appended to the
 108      messages, followed by the rendering of that format string with ARGS.
 109      The format string is rendered during construction and is re-used as is
 110      for the message on exit.  */
 111
 112   scoped_debug_start_end (PT &debug_enabled, const char *module,
 113                           const char *func, const char *start_prefix,
 114                           const char *end_prefix, const char *fmt,
 115                           va_list args)
 116     ATTRIBUTE_NULL_PRINTF (7, 0)
 117     : m_debug_enabled (debug_enabled),
 118       m_module (module),
 119       m_func (func),
 120       m_end_prefix (end_prefix),
 121       m_with_format (fmt != nullptr)
 122   {
 123     if (is_debug_enabled ())
 124       {
 125         if (fmt != nullptr)
 126           {
 127             m_msg = string_vprintf (fmt, args);
 128             debug_prefixed_printf (m_module, m_func, "%s: %s",
 129                                    start_prefix, m_msg->c_str ());
 130           }
 131         else
 132           debug_prefixed_printf (m_module, m_func, "%s", start_prefix);
 133
 134         ++debug_print_depth;
 135         m_must_decrement_print_depth = true;
 136       }
 137   }
 138
 139   DISABLE_COPY_AND_ASSIGN (scoped_debug_start_end);
 140
 141   scoped_debug_start_end (scoped_debug_start_end &&other)
 142     : m_debug_enabled (other.m_debug_enabled),
 143       m_module (other.m_module),
 144       m_func (other.m_func),
 145       m_end_prefix (other.m_end_prefix),
 146       m_msg (other.m_msg),
 147       m_with_format (other.m_with_format),
 148       m_must_decrement_print_depth (other.m_must_decrement_print_depth),
 149       m_disabled (other.m_disabled)
 150   {
 151     /* Avoid the moved-from object doing the side-effects in its destructor.  */
 152     other.m_disabled = true;
 153   }
 154
 155   ~scoped_debug_start_end ()
 156   {
 157     if (m_disabled)
 158       return;
 159
 160     if (m_must_decrement_print_depth)
 161       {
 162         gdb_assert (debug_print_depth > 0);
 163         --debug_print_depth;
 164       }
 165
 166     if (is_debug_enabled ())
 167       {
 168         if (m_with_format)
 169           {
 170             if (m_msg.has_value ())
 171               debug_prefixed_printf (m_module, m_func, "%s: %s",
 172                                      m_end_prefix, m_msg->c_str ());
 173             else
 174               {
 175                 /* A format string was passed to the constructor, but debug
 176                    control variable wasn't set at the time, so we don't have the
 177                    rendering of the format string.  */
 178                 debug_prefixed_printf (m_module, m_func, "%s: <%s debugging was not enabled on entry>",
 179                                        m_end_prefix, m_module);
 180               }
 181           }
 182         else
 183           debug_prefixed_printf (m_module, m_func, "%s", m_end_prefix);
 184       }
 185   }
 186
 187 private:
 188
 189   /* This function is specialized based on the type PT.  Returns true if
 190      M_DEBUG_ENABLED indicates this debug setting is enabled, otherwise,
 191      return false.  */
 192   bool is_debug_enabled () const;
 193
 194   /* Reference to the debug setting, or a callback that can read the debug
 195      setting.  Access the value of this by calling IS_DEBUG_ENABLED.  */
 196   PT &m_debug_enabled;
 197
 198   const char *m_module;
 199   const char *m_func;
 200   const char *m_end_prefix;
 201
 202   /* The result of formatting the format string in the constructor.  */
 203   std::optional<std::string> m_msg;
 204
 205   /* True is a non-nullptr format was passed to the constructor.  */
 206   bool m_with_format;
 207
 208   /* This is used to handle the case where debugging is enabled during
 209      construction but not during destruction, or vice-versa.  We want to make
 210      sure there are as many increments are there are decrements.  */
 211   bool m_must_decrement_print_depth = false;
 212
 213   /* True if this object was moved from, and the destructor behavior must be
 214      inhibited.  */
 215   bool m_disabled = false;
 216 };
 217
 218 /* Implementation of is_debug_enabled when PT is an invokable type.  */
 219
 220 template<typename PT>
 221 inline bool
 222 scoped_debug_start_end<PT>::is_debug_enabled () const
 223 {
 224   return m_debug_enabled ();
 225 }
 226
 227 /* Implementation of is_debug_enabled when PT is 'bool &'.  */
 228
 229 template<>
 230 inline bool
 231 scoped_debug_start_end<bool &>::is_debug_enabled () const
 232 {
 233   return m_debug_enabled;
 234 }
 235
 236 /* Wrapper around the scoped_debug_start_end constructor to allow the
 237    caller to create an object using 'auto' type, the actual type will be
 238    based on the type of the PRED argument.  All arguments are forwarded to
 239    the scoped_debug_start_end constructor.  */
 240
 241 template<typename PT>
 242 static inline scoped_debug_start_end<PT &> ATTRIBUTE_NULL_PRINTF (6, 7)
 243 make_scoped_debug_start_end (PT &&pred, const char *module, const char *func,
 244                              const char *start_prefix,
 245                              const char *end_prefix, const char *fmt, ...)
 246 {
 247   va_list args;
 248   va_start (args, fmt);
 249   auto res = scoped_debug_start_end<PT &> (pred, module, func, start_prefix,
 250                                            end_prefix, fmt, args);
 251   va_end (args);
 252
 253   return res;
 254 }
 255
 256 /* Helper to define a module-specific start/end debug macro.  */
 257
 258 #define scoped_debug_start_end(debug_enabled, module, fmt, ...)         \
 259   auto CONCAT(scoped_debug_start_end, __LINE__)                         \
 260     = make_scoped_debug_start_end (debug_enabled, module,       \
 261                                    __func__, "start", "end",    \
 262                                    fmt, ##__VA_ARGS__)
 263
 264 /* Helper to define a module-specific enter/exit debug macro.  This is a special
 265    case of `scoped_debug_start_end` where the start and end messages are "enter"
 266    and "exit", to denote entry and exit of a function.  */
 267
 268 #define scoped_debug_enter_exit(debug_enabled, module)  \
 269   auto CONCAT(scoped_debug_start_end, __LINE__)                         \
 270     = make_scoped_debug_start_end (debug_enabled, module,       \
 271                                    __func__, "enter", "exit",   \
 272                                    nullptr)
 273
 274 #endif /* COMMON_COMMON_DEBUG_H */