src/base/trace.hh

   1 /*
   2  * Copyright (c) 2014, 2019 ARM Limited
   3  * All rights reserved
   4  *
   5  * Copyright (c) 2001-2006 The Regents of The University of Michigan
   6  * All rights reserved.
   7  *
   8  * Redistribution and use in source and binary forms, with or without
   9  * modification, are permitted provided that the following conditions are
  10  * met: redistributions of source code must retain the above copyright
  11  * notice, this list of conditions and the following disclaimer;
  12  * redistributions in binary form must reproduce the above copyright
  13  * notice, this list of conditions and the following disclaimer in the
  14  * documentation and/or other materials provided with the distribution;
  15  * neither the name of the copyright holders nor the names of its
  16  * contributors may be used to endorse or promote products derived from
  17  * this software without specific prior written permission.
  18  *
  19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30  *
  31  * Authors: Nathan Binkert
  32  *          Steve Reinhardt
  33  *          Andrew Bardsley
  34  */
  35
  36 #ifndef __BASE_TRACE_HH__
  37 #define __BASE_TRACE_HH__
  38
  39 #include <string>
  40
  41 #include "base/cprintf.hh"
  42 #include "base/debug.hh"
  43 #include "base/match.hh"
  44 #include "base/types.hh"
  45 #include "sim/core.hh"
  46
  47 namespace Trace {
  48
  49 /** Debug logging base class.  Handles formatting and outputting
  50  *  time/name/message messages */
  51 class Logger
  52 {
  53   protected:
  54     /** Name match for objects to ignore */
  55     ObjectMatch ignore;
  56
  57   public:
  58     /** Log a single message */
  59     template <typename ...Args>
  60     void dprintf(Tick when, const std::string &name, const char *fmt,
  61                  const Args &...args)
  62     {
  63         dprintf_flag(when, name, "", fmt, args...);
  64     }
  65
  66     /** Log a single message with a flag prefix. */
  67     template <typename ...Args>
  68     void dprintf_flag(Tick when, const std::string &name,
  69             const std::string &flag,
  70             const char *fmt, const Args &...args)
  71     {
  72         if (!name.empty() && ignore.match(name))
  73             return;
  74         std::ostringstream line;
  75         ccprintf(line, fmt, args...);
  76         logMessage(when, name, flag, line.str());
  77     }
  78
  79     /** Dump a block of data of length len */
  80     void dump(Tick when, const std::string &name,
  81             const void *d, int len, const std::string &flag);
  82
  83     /** Log formatted message */
  84     virtual void logMessage(Tick when, const std::string &name,
  85             const std::string &flag, const std::string &message) = 0;
  86
  87     /** Return an ostream that can be used to send messages to
  88      *  the 'same place' as formatted logMessage messages.  This
  89      *  can be implemented to use a logger's underlying ostream,
  90      *  to provide an ostream which formats the output in some
  91      *  way, or just set to one of std::cout, std::cerr */
  92     virtual std::ostream &getOstream() = 0;
  93
  94     /** Set objects to ignore */
  95     void setIgnore(ObjectMatch &ignore_) { ignore = ignore_; }
  96
  97     /** Add objects to ignore */
  98     void addIgnore(const ObjectMatch &ignore_) { ignore.add(ignore_); }
  99
 100     virtual ~Logger() { }
 101 };
 102
 103 /** Logging wrapper for ostreams with the format:
 104  *  <when>: <name>: <message-body> */
 105 class OstreamLogger : public Logger
 106 {
 107   protected:
 108     std::ostream &stream;
 109
 110   public:
 111     OstreamLogger(std::ostream &stream_) : stream(stream_)
 112     { }
 113
 114     void logMessage(Tick when, const std::string &name,
 115             const std::string &flag, const std::string &message) override;
 116
 117     std::ostream &getOstream() override { return stream; }
 118 };
 119
 120 /** Get the current global debug logger.  This takes ownership of the given
 121  *  logger which should be allocated using 'new' */
 122 Logger *getDebugLogger();
 123
 124 /** Get the ostream from the current global logger */
 125 std::ostream &output();
 126
 127 /** Delete the current global logger and assign a new one */
 128 void setDebugLogger(Logger *logger);
 129
 130 /** Enable/disable debug logging */
 131 void enable();
 132 void disable();
 133
 134 } // namespace Trace
 135
 136 // This silly little class allows us to wrap a string in a functor
 137 // object so that we can give a name() that DPRINTF will like
 138 struct StringWrap
 139 {
 140     std::string str;
 141     StringWrap(const std::string &s) : str(s) {}
 142     const std::string &operator()() const { return str; }
 143 };
 144
 145 // Return the global context name "global".  This function gets called when
 146 // the DPRINTF macros are used in a context without a visible name() function
 147 const std::string &name();
 148
 149 // Interface for things with names. (cf. SimObject but without other
 150 // functionality).  This is useful when using DPRINTF
 151 class Named
 152 {
 153   protected:
 154     const std::string _name;
 155
 156   public:
 157     Named(const std::string &name_) : _name(name_) { }
 158
 159   public:
 160     const std::string &name() const { return _name; }
 161 };
 162
 163 //
 164 // DPRINTF is a debugging trace facility that allows one to
 165 // selectively enable tracing statements.  To use DPRINTF, there must
 166 // be a function or functor called name() that returns a const
 167 // std::string & in the current scope.
 168 //
 169 // If you desire that the automatic printing not occur, use DPRINTFR
 170 // (R for raw)
 171 //
 172
 173 #if TRACING_ON
 174
 175 #define DTRACE(x) (Debug::x)
 176
 177 #define DDUMP(x, data, count) do {               \
 178     using namespace Debug;                       \
 179     if (DTRACE(x))                               \
 180         Trace::getDebugLogger()->dump(           \
 181             curTick(), name(), data, count, #x); \
 182 } while (0)
 183
 184 #define DPRINTF(x, ...) do {                     \
 185     using namespace Debug;                       \
 186     if (DTRACE(x)) {                             \
 187         Trace::getDebugLogger()->dprintf_flag(   \
 188             curTick(), name(), #x, __VA_ARGS__); \
 189     }                                            \
 190 } while (0)
 191
 192 #define DPRINTFS(x, s, ...) do {                        \
 193     using namespace Debug;                              \
 194     if (DTRACE(x)) {                                    \
 195         Trace::getDebugLogger()->dprintf_flag(          \
 196                 curTick(), s->name(), #x, __VA_ARGS__); \
 197     }                                                   \
 198 } while (0)
 199
 200 #define DPRINTFR(x, ...) do {                          \
 201     using namespace Debug;                             \
 202     if (DTRACE(x)) {                                   \
 203         Trace::getDebugLogger()->dprintf_flag(         \
 204             (Tick)-1, std::string(), #x, __VA_ARGS__); \
 205     }                                                  \
 206 } while (0)
 207
 208 #define DDUMPN(data, count) do {                                       \
 209     Trace::getDebugLogger()->dump(curTick(), name(), data, count);     \
 210 } while (0)
 211
 212 #define DPRINTFN(...) do {                                             \
 213     Trace::getDebugLogger()->dprintf(curTick(), name(), __VA_ARGS__);  \
 214 } while (0)
 215
 216 #define DPRINTFNR(...) do {                                                 \
 217     Trace::getDebugLogger()->dprintf((Tick)-1, std::string(), __VA_ARGS__); \
 218 } while (0)
 219
 220 #define DPRINTF_UNCONDITIONAL(x, ...) do {    \
 221     Trace::getDebugLogger()->dprintf_flag(    \
 222         curTick(), name(), #x, __VA_ARGS__);  \
 223 } while (0)
 224
 225 #else // !TRACING_ON
 226
 227 #define DTRACE(x) (false)
 228 #define DDUMP(x, data, count) do {} while (0)
 229 #define DPRINTF(x, ...) do {} while (0)
 230 #define DPRINTFS(x, ...) do {} while (0)
 231 #define DPRINTFR(...) do {} while (0)
 232 #define DDUMPN(data, count) do {} while (0)
 233 #define DPRINTFN(...) do {} while (0)
 234 #define DPRINTFNR(...) do {} while (0)
 235 #define DPRINTF_UNCONDITIONAL(x, ...) do {} while (0)
 236
 237 #endif  // TRACING_ON
 238
 239 #endif // __BASE_TRACE_HH__