1 //===-- Log.h ---------------------------------------------------*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 
9 #ifndef LLDB_UTILITY_LOG_H
10 #define LLDB_UTILITY_LOG_H
11 
12 #include "lldb/Utility/Flags.h"
13 #include "lldb/lldb-defines.h"
14 
15 #include "llvm/ADT/ArrayRef.h"
16 #include "llvm/ADT/STLExtras.h"
17 #include "llvm/ADT/StringMap.h"
18 #include "llvm/ADT/StringRef.h"
19 #include "llvm/Support/Error.h"
20 #include "llvm/Support/FormatVariadic.h"
21 #include "llvm/Support/ManagedStatic.h"
22 #include "llvm/Support/RWMutex.h"
23 
24 #include <atomic>
25 #include <cstdarg>
26 #include <cstdint>
27 #include <memory>
28 #include <mutex>
29 #include <string>
30 #include <type_traits>
31 
32 namespace llvm {
33 class raw_ostream;
34 }
35 // Logging Options
36 #define LLDB_LOG_OPTION_VERBOSE (1u << 1)
37 #define LLDB_LOG_OPTION_PREPEND_SEQUENCE (1u << 3)
38 #define LLDB_LOG_OPTION_PREPEND_TIMESTAMP (1u << 4)
39 #define LLDB_LOG_OPTION_PREPEND_PROC_AND_THREAD (1u << 5)
40 #define LLDB_LOG_OPTION_PREPEND_THREAD_NAME (1U << 6)
41 #define LLDB_LOG_OPTION_BACKTRACE (1U << 7)
42 #define LLDB_LOG_OPTION_APPEND (1U << 8)
43 #define LLDB_LOG_OPTION_PREPEND_FILE_FUNCTION (1U << 9)
44 
45 // Logging Functions
46 namespace lldb_private {
47 
48 class LogHandler {
49 public:
50   virtual ~LogHandler() = default;
51   virtual void Emit(llvm::StringRef message) = 0;
52 
53   virtual bool isA(const void *ClassID) const { return ClassID == &ID; }
54   static bool classof(const LogHandler *obj) { return obj->isA(&ID); }
55 
56 private:
57   static char ID;
58 };
59 
60 class StreamLogHandler : public LogHandler {
61 public:
62   StreamLogHandler(int fd, bool should_close, size_t buffer_size = 0);
63   ~StreamLogHandler() override;
64 
65   void Emit(llvm::StringRef message) override;
66   void Flush();
67 
68   bool isA(const void *ClassID) const override { return ClassID == &ID; }
69   static bool classof(const LogHandler *obj) { return obj->isA(&ID); }
70 
71 private:
72   std::mutex m_mutex;
73   llvm::raw_fd_ostream m_stream;
74   static char ID;
75 };
76 
77 class CallbackLogHandler : public LogHandler {
78 public:
79   CallbackLogHandler(lldb::LogOutputCallback callback, void *baton);
80 
81   void Emit(llvm::StringRef message) override;
82 
83   bool isA(const void *ClassID) const override { return ClassID == &ID; }
84   static bool classof(const LogHandler *obj) { return obj->isA(&ID); }
85 
86 private:
87   lldb::LogOutputCallback m_callback;
88   void *m_baton;
89   static char ID;
90 };
91 
92 class RotatingLogHandler : public LogHandler {
93 public:
94   RotatingLogHandler(size_t size);
95 
96   void Emit(llvm::StringRef message) override;
97   void Dump(llvm::raw_ostream &stream) const;
98 
99   bool isA(const void *ClassID) const override { return ClassID == &ID; }
100   static bool classof(const LogHandler *obj) { return obj->isA(&ID); }
101 
102 private:
103   size_t NormalizeIndex(size_t i) const;
104   size_t GetNumMessages() const;
105   size_t GetFirstMessageIndex() const;
106 
107   mutable std::mutex m_mutex;
108   std::unique_ptr<std::string[]> m_messages;
109   const size_t m_size = 0;
110   size_t m_next_index = 0;
111   size_t m_total_count = 0;
112   static char ID;
113 };
114 
115 class Log final {
116 public:
117   /// The underlying type of all log channel enums. Declare them as:
118   /// enum class MyLog : MaskType {
119   ///   Channel0 = Log::ChannelFlag<0>,
120   ///   Channel1 = Log::ChannelFlag<1>,
121   ///   ...,
122   ///   LLVM_MARK_AS_BITMASK_ENUM(LastChannel),
123   /// };
124   using MaskType = uint64_t;
125 
126   template <MaskType Bit>
127   static constexpr MaskType ChannelFlag = MaskType(1) << Bit;
128 
129   // Description of a log channel category.
130   struct Category {
131     llvm::StringLiteral name;
132     llvm::StringLiteral description;
133     MaskType flag;
134 
135     template <typename Cat>
136     constexpr Category(llvm::StringLiteral name,
137                        llvm::StringLiteral description, Cat mask)
138         : name(name), description(description), flag(MaskType(mask)) {
139       static_assert(
140           std::is_same<Log::MaskType, std::underlying_type_t<Cat>>::value, "");
141     }
142   };
143 
144   // This class describes a log channel. It also encapsulates the behavior
145   // necessary to enable a log channel in an atomic manner.
146   class Channel {
147     std::atomic<Log *> log_ptr;
148     friend class Log;
149 
150   public:
151     const llvm::ArrayRef<Category> categories;
152     const MaskType default_flags;
153 
154     template <typename Cat>
155     constexpr Channel(llvm::ArrayRef<Log::Category> categories,
156                       Cat default_flags)
157         : log_ptr(nullptr), categories(categories),
158           default_flags(MaskType(default_flags)) {
159       static_assert(
160           std::is_same<Log::MaskType, std::underlying_type_t<Cat>>::value, "");
161     }
162 
163     // This function is safe to call at any time. If the channel is disabled
164     // after (or concurrently with) this function returning a non-null Log
165     // pointer, it is still safe to attempt to write to the Log object -- the
166     // output will be discarded.
167     Log *GetLog(MaskType mask) {
168       Log *log = log_ptr.load(std::memory_order_relaxed);
169       if (log && log->GetMask().AnySet(mask))
170         return log;
171       return nullptr;
172     }
173   };
174 
175 
176   // Static accessors for logging channels
177   static void Register(llvm::StringRef name, Channel &channel);
178   static void Unregister(llvm::StringRef name);
179 
180   static bool
181   EnableLogChannel(const std::shared_ptr<LogHandler> &log_handler_sp,
182                    uint32_t log_options, llvm::StringRef channel,
183                    llvm::ArrayRef<const char *> categories,
184                    llvm::raw_ostream &error_stream);
185 
186   static bool DisableLogChannel(llvm::StringRef channel,
187                                 llvm::ArrayRef<const char *> categories,
188                                 llvm::raw_ostream &error_stream);
189 
190   static bool DumpLogChannel(llvm::StringRef channel,
191                              llvm::raw_ostream &output_stream,
192                              llvm::raw_ostream &error_stream);
193 
194   static bool ListChannelCategories(llvm::StringRef channel,
195                                     llvm::raw_ostream &stream);
196 
197   /// Returns the list of log channels.
198   static std::vector<llvm::StringRef> ListChannels();
199   /// Calls the given lambda for every category in the given channel.
200   /// If no channel with the given name exists, lambda is never called.
201   static void ForEachChannelCategory(
202       llvm::StringRef channel,
203       llvm::function_ref<void(llvm::StringRef, llvm::StringRef)> lambda);
204 
205   static void DisableAllLogChannels();
206 
207   static void ListAllLogChannels(llvm::raw_ostream &stream);
208 
209   // Member functions
210   //
211   // These functions are safe to call at any time you have a Log* obtained from
212   // the Channel class. If logging is disabled between you obtaining the Log
213   // object and writing to it, the output will be silently discarded.
214   Log(Channel &channel) : m_channel(channel) {}
215   ~Log() = default;
216 
217   void PutCString(const char *cstr);
218   void PutString(llvm::StringRef str);
219 
220   template <typename... Args>
221   void Format(llvm::StringRef file, llvm::StringRef function,
222               const char *format, Args &&... args) {
223     Format(file, function, llvm::formatv(format, std::forward<Args>(args)...));
224   }
225 
226   template <typename... Args>
227   void FormatError(llvm::Error error, llvm::StringRef file,
228                    llvm::StringRef function, const char *format,
229                    Args &&... args) {
230     Format(file, function,
231            llvm::formatv(format, llvm::toString(std::move(error)),
232                          std::forward<Args>(args)...));
233   }
234 
235   /// Prefer using LLDB_LOGF whenever possible.
236   void Printf(const char *format, ...) __attribute__((format(printf, 2, 3)));
237 
238   void Error(const char *fmt, ...) __attribute__((format(printf, 2, 3)));
239 
240   void Verbose(const char *fmt, ...) __attribute__((format(printf, 2, 3)));
241 
242   void Warning(const char *fmt, ...) __attribute__((format(printf, 2, 3)));
243 
244   const Flags GetOptions() const;
245 
246   const Flags GetMask() const;
247 
248   bool GetVerbose() const;
249 
250   void VAPrintf(const char *format, va_list args);
251   void VAError(const char *format, va_list args);
252 
253 private:
254   Channel &m_channel;
255 
256   // The mutex makes sure enable/disable operations are thread-safe. The
257   // options and mask variables are atomic to enable their reading in
258   // Channel::GetLogIfAny without taking the mutex to speed up the fast path.
259   // Their modification however, is still protected by this mutex.
260   llvm::sys::RWMutex m_mutex;
261 
262   std::shared_ptr<LogHandler> m_handler;
263   std::atomic<uint32_t> m_options{0};
264   std::atomic<MaskType> m_mask{0};
265 
266   void WriteHeader(llvm::raw_ostream &OS, llvm::StringRef file,
267                    llvm::StringRef function);
268   void WriteMessage(const std::string &message);
269 
270   void Format(llvm::StringRef file, llvm::StringRef function,
271               const llvm::formatv_object_base &payload);
272 
273   std::shared_ptr<LogHandler> GetHandler() {
274     llvm::sys::ScopedReader lock(m_mutex);
275     return m_handler;
276   }
277 
278   void Enable(const std::shared_ptr<LogHandler> &handler_sp, uint32_t options,
279               uint32_t flags);
280 
281   void Disable(uint32_t flags);
282 
283   bool Dump(llvm::raw_ostream &stream);
284 
285   typedef llvm::StringMap<Log> ChannelMap;
286   static llvm::ManagedStatic<ChannelMap> g_channel_map;
287 
288   static void ForEachCategory(
289       const Log::ChannelMap::value_type &entry,
290       llvm::function_ref<void(llvm::StringRef, llvm::StringRef)> lambda);
291 
292   static void ListCategories(llvm::raw_ostream &stream,
293                              const ChannelMap::value_type &entry);
294   static uint32_t GetFlags(llvm::raw_ostream &stream, const ChannelMap::value_type &entry,
295                            llvm::ArrayRef<const char *> categories);
296 
297   Log(const Log &) = delete;
298   void operator=(const Log &) = delete;
299 };
300 
301 // Must be specialized for a particular log type.
302 template <typename Cat> Log::Channel &LogChannelFor() = delete;
303 
304 /// Retrieve the Log object for the channel associated with the given log enum.
305 ///
306 /// Returns a valid Log object if any of the provided categories are enabled.
307 /// Otherwise, returns nullptr.
308 template <typename Cat> Log *GetLog(Cat mask) {
309   static_assert(std::is_same<Log::MaskType, std::underlying_type_t<Cat>>::value,
310                 "");
311   return LogChannelFor<Cat>().GetLog(Log::MaskType(mask));
312 }
313 
314 } // namespace lldb_private
315 
316 /// The LLDB_LOG* macros defined below are the way to emit log messages.
317 ///
318 /// Note that the macros surround the arguments in a check for the log
319 /// being on, so you can freely call methods in arguments without affecting
320 /// the non-log execution flow.
321 ///
322 /// If you need to do more complex computations to prepare the log message
323 /// be sure to add your own if (log) check, since we don't want logging to
324 /// have any effect when not on.
325 ///
326 /// However, the LLDB_LOG macro uses the llvm::formatv system (see the
327 /// ProgrammersManual page in the llvm docs for more details).  This allows
328 /// the use of "format_providers" to auto-format datatypes, and there are
329 /// already formatters for some of the llvm and lldb datatypes.
330 ///
331 /// So if you need to do non-trivial formatting of one of these types, be
332 /// sure to grep the lldb and llvm sources for "format_provider" to see if
333 /// there is already a formatter before doing in situ formatting, and if
334 /// possible add a provider if one does not already exist.
335 
336 #define LLDB_LOG(log, ...)                                                     \
337   do {                                                                         \
338     ::lldb_private::Log *log_private = (log);                                  \
339     if (log_private)                                                           \
340       log_private->Format(__FILE__, __func__, __VA_ARGS__);                    \
341   } while (0)
342 
343 #define LLDB_LOGF(log, ...)                                                    \
344   do {                                                                         \
345     ::lldb_private::Log *log_private = (log);                                  \
346     if (log_private)                                                           \
347       log_private->Printf(__VA_ARGS__);                                        \
348   } while (0)
349 
350 #define LLDB_LOGV(log, ...)                                                    \
351   do {                                                                         \
352     ::lldb_private::Log *log_private = (log);                                  \
353     if (log_private && log_private->GetVerbose())                              \
354       log_private->Format(__FILE__, __func__, __VA_ARGS__);                    \
355   } while (0)
356 
357 // Write message to log, if error is set. In the log message refer to the error
358 // with {0}. Error is cleared regardless of whether logging is enabled.
359 #define LLDB_LOG_ERROR(log, error, ...)                                        \
360   do {                                                                         \
361     ::lldb_private::Log *log_private = (log);                                  \
362     ::llvm::Error error_private = (error);                                     \
363     if (log_private && error_private) {                                        \
364       log_private->FormatError(::std::move(error_private), __FILE__, __func__, \
365                                __VA_ARGS__);                                   \
366     } else                                                                     \
367       ::llvm::consumeError(::std::move(error_private));                        \
368   } while (0)
369 
370 #endif // LLDB_UTILITY_LOG_H
371 
372 // TODO: Remove this and fix includes everywhere.
373