[lldb] Add SBDebugger APIs for querying logging channels and categories

[teemperor]

Summary

We already have a function that takes channels/categories to enable logging, but there is no way to query what is available.

[brucem]

Should this include something for disabling as well?

lldb/test/API/functionalities/logging/TestLoggingAPI.py

53

Shouldn't this be GetLogCategories(valid_channel)?

[clayborg]

Fix the test variable names and this is good to go

lldb/test/API/functionalities/logging/TestLoggingAPI.py

34

36

42

44

49

53

lldb/bindings/interface/SBDebugger.i

#endif
     StateIsRunningState (lldb::StateType state);
 
     static bool
     StateIsStoppedState (lldb::StateType state);
 
     bool
     EnableLog (const char *channel, const char ** types);
 
+    %feature("autodoc", "Returns a list of all registered log channels.
+    Returns an empty list if the SBDebugger object is invalid.") GetLogChannels;
+    lldb::SBStringList
+    GetLogChannels ();
+
+    %feature("autodoc", "Returns the log categories of the given log channel.
+    Returns an empty list if the log channel doesn't exist or the SBDebugger
+    object is invalid.") GetLogCat;
+    lldb::SBStringList
+    GetLogCategories (const char *channel);
+
     void
     SetLoggingCallback (lldb::LogOutputCallback log_callback, void *baton);
 
     void
     DispatchInput (const void *data, size_t data_len);
 
     void
     DispatchInputInterrupt ();

lldb/include/lldb/API/SBDebugger.h

 //===-- SBDebugger.h --------------------------------------------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef LLDB_API_SBDEBUGGER_H
 #define LLDB_API_SBDEBUGGER_H
 
 #include <cstdio>
 
 #include "lldb/API/SBDefines.h"
 #include "lldb/API/SBPlatform.h"
 
 namespace lldb {
 
 class LLDB_API SBInputReader {
 public:
   SBInputReader() = default;
   ~SBInputReader() = default;
public:
   static SBStructuredData GetBuildConfiguration();
 
   static bool StateIsRunningState(lldb::StateType state);
 
   static bool StateIsStoppedState(lldb::StateType state);
 
   bool EnableLog(const char *channel, const char **categories);
 
+  /// Returns a list of all registered log channels.
+  ///
+  /// Returns an empty list if SBDebugger object is invalid.
+  ///
+  /// \see SBDebugger::EnableLog
+  /// \see SBDebugger::GetLogCategories
+  SBStringList GetLogChannels();
+
+  /// Returns the log categories of the given log channel.
+  ///
+  /// Returns an empty list if the log channel doesn't exist or the SBDebugger
+  /// object is invalid.
+  ///
+  /// \see SBDebugger::EnableLog
+  /// \see SBDebugger::GetLogChannels
+  SBStringList GetLogCategories(const char *channel);
+
   void SetLoggingCallback(lldb::LogOutputCallback log_callback, void *baton);
 
   // DEPRECATED
   void DispatchInput(void *baton, const void *data, size_t data_len);
 
   void DispatchInput(const void *data, size_t data_len);
 
   void DispatchInputInterrupt();

lldb/include/lldb/Core/Debugger.h

 //===-- Debugger.h ----------------------------------------------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef LLDB_CORE_DEBUGGER_H
 #define LLDB_CORE_DEBUGGER_H
 
 #include <cstdint>
 
 #include <memory>
 #include <vector>
 
 #include "lldb/Core/FormatEntity.h"
 #include "lldb/Core/IOHandler.h"
 #include "lldb/Core/SourceManager.h"
 #include "lldb/Core/StreamFile.h"
 #include "lldb/Core/UserSettingsController.h"
 #include "lldb/Host/HostThread.h"
 #include "lldb/Host/Terminal.h"
 #include "lldb/Target/ExecutionContext.h"
 #include "lldb/Target/Platform.h"
public:
 
   void SetCloseInputOnEOF(bool b);
 
   bool EnableLog(llvm::StringRef channel,
                  llvm::ArrayRef<const char *> categories,
                  llvm::StringRef log_file, uint32_t log_options,
                  llvm::raw_ostream &error_stream);
 
+  /// \copydoc lldb::SBDebugger::GetLogChannels
+  StringList GetLogChannels();
+
+  /// \copydoc lldb::SBDebugger::GetLogCategories
+  StringList GetLogCategories(llvm::StringRef channel);
+
   void SetLoggingCallback(lldb::LogOutputCallback log_callback, void *baton);
 
   // Properties Functions
   enum StopDisassemblyType {
     eStopDisassemblyTypeNever = 0,
     eStopDisassemblyTypeNoDebugInfo,
     eStopDisassemblyTypeNoSource,
     eStopDisassemblyTypeAlways

lldb/include/lldb/Utility/StringList.h

 //===-- StringList.h --------------------------------------------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef LLDB_UTILITY_STRINGLIST_H
 #define LLDB_UTILITY_STRINGLIST_H
 
+#include "llvm/ADT/ArrayRef.h"
 #include "llvm/ADT/StringRef.h"
 
 #include <cstddef>
 #include <string>
 #include <vector>
 
 namespace lldb_private {
 class Log;
 class Stream;
 }
 
 namespace lldb_private {
 
 class StringList {
   typedef std::vector<std::string> collection;
 
 public:
   StringList();
 
   explicit StringList(const char *str);
 
   StringList(const char **strv, int strc);
 
+  /// Creates a StringList with the contents of the given array of strings.
+  explicit StringList(llvm::ArrayRef<llvm::StringRef> strs);
+
   virtual ~StringList();
 
   void AppendString(const std::string &s);
 
   void AppendString(std::string &&s);
 
   void AppendString(const char *str);
 

lldb/source/API/SBDebugger.cpp

void SBDebugger::SetLoggingCallback(lldb::LogOutputCallback log_callback,
   LLDB_RECORD_DUMMY(void, SBDebugger, SetLoggingCallback,
                     (lldb::LogOutputCallback, void *), log_callback, baton);
 
   if (m_opaque_sp) {
     return m_opaque_sp->SetLoggingCallback(log_callback, baton);
   }
 }
 
+lldb::SBStringList lldb::SBDebugger::GetLogChannels() {
+  LLDB_RECORD_METHOD_NO_ARGS(lldb::SBStringList, SBDebugger, GetLogChannels);
+
+  if (!m_opaque_sp)
+    return LLDB_RECORD_RESULT(SBStringList());
+  return LLDB_RECORD_RESULT(
+      SBStringList(new StringList(m_opaque_sp->GetLogChannels())));
+}
+
+SBStringList SBDebugger::GetLogCategories(const char *channel) {
+  LLDB_RECORD_METHOD(lldb::SBStringList, SBDebugger, GetLogCategories,
+                     (const char *), channel);
+
+  if (!m_opaque_sp)
+    return LLDB_RECORD_RESULT(SBStringList());
+  return LLDB_RECORD_RESULT(
+      SBStringList(new StringList(m_opaque_sp->GetLogCategories(channel))));
+}
+
 namespace lldb_private {
 namespace repro {
 
 template <> void RegisterMethods<SBInputReader>(Registry &R) {
   LLDB_REGISTER_METHOD(void, SBInputReader, SetIsDone, (bool));
   LLDB_REGISTER_METHOD_CONST(bool, SBInputReader, IsActive, ());
 }
 

lldb/source/Core/Debugger.cpp

 //===-- Debugger.cpp ------------------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #include "lldb/Core/Debugger.h"
 
 #include "lldb/Breakpoint/Breakpoint.h"
 #include "lldb/Core/FormatEntity.h"
 #include "lldb/Core/Mangled.h"
 #include "lldb/Core/ModuleList.h"
 #include "lldb/Core/PluginManager.h"
 #include "lldb/Core/StreamAsynchronousIO.h"
 #include "lldb/Core/StreamFile.h"
bool Debugger::EnableLog(llvm::StringRef channel,
   if (log_options == 0)
     log_options =
         LLDB_LOG_OPTION_PREPEND_THREAD_NAME | LLDB_LOG_OPTION_THREADSAFE;
 
   return Log::EnableLogChannel(log_stream_sp, log_options, channel, categories,
                                error_stream);
 }
 
+StringList Debugger::GetLogChannels() {
+  return StringList(Log::ListChannels());
+}
+
+StringList Debugger::GetLogCategories(llvm::StringRef channel) {
+  StringList result;
+  Log::ForEachChannelCategory(
+      channel, [&result](llvm::StringRef name, llvm::StringRef description) {
+        result.AppendString(name);
+      });
+  return result;
+}
+
 ScriptInterpreter *
 Debugger::GetScriptInterpreter(bool can_create,
                                llvm::Optional<lldb::ScriptLanguage> language) {
   std::lock_guard<std::recursive_mutex> locker(m_script_interpreter_mutex);
   lldb::ScriptLanguage script_language =
       language ? *language : GetScriptLanguage();
 
   if (!m_script_interpreters[script_language]) {

lldb/source/Utility/StringList.cpp

 //===-- StringList.cpp ----------------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #include "lldb/Utility/StringList.h"
 
 #include "lldb/Utility/Log.h"
 #include "lldb/Utility/Stream.h"
 #include "lldb/Utility/StreamString.h"
 #include "llvm/ADT/ArrayRef.h"
 
 #include <algorithm>
 #include <cstdint>

 
 StringList::StringList(const char **strv, int strc) : m_strings() {
   for (int i = 0; i < strc; ++i) {
     if (strv[i])
       m_strings.push_back(strv[i]);
   }
 }
 
+StringList::StringList(llvm::ArrayRef<llvm::StringRef> strs) {
+  for (llvm::StringRef s : strs)
+    m_strings.push_back(s.str());
+}
+
 StringList::~StringList() {}
 
 void StringList::AppendString(const char *str) {
   if (str)
     m_strings.push_back(str);
 }
 
 void StringList::AppendString(const std::string &s) { m_strings.push_back(s); }

lldb/test/API/functionalities/logging/TestLoggingAPI.py

+"""
+Tests the API for querying and manipulating LLDB's logging functionality.
+"""
+
+
+
+import lldb
+from lldbsuite.test.decorators import *
+from lldbsuite.test.lldbtest import *
+from lldbsuite.test import lldbutil
+
+
+class TestCase(TestBase):
+
+    mydir = TestBase.compute_mydir(__file__)
+
+    @no_debug_info_test
+    def test_list_log_channels(self):
+        # Invalid SBDebugger returns always an empty list.
+        channels = list(lldb.SBDebugger().GetLogChannels())
+        self.assertEqual([], channels)
+
+        # Otherwise check for our known log channels in LLDB.
+        channels = list(self.dbg.GetLogChannels())
+        self.assertEqual(sort(["dwarf", "lldb", "gdb-remote", "kdp-remote"]),
+                         sort(channels))
+
+    @no_debug_info_test
+    def test_list_log_catgories(self):
+        valid_channel = "lldb"
+
+        # An empty or invalid channel should also return an empty list.
+        categories = list(self.dbg.GetLogCategories(""))
+        self.assertEqual([], channels)
+        categories = list(self.dbg.GetLogCategories("gibberish"))
+        self.assertEqual([], channels)
+
+
+        # With an invalid SBDebugger invalid/empty channel also returns an
+        # an empty list.
+        categories = list(lldb.SBDebugger().GetLogCategories(""))
+        self.assertEqual([], channels)
+        categories = list(lldb.SBDebugger().GetLogCategories("gibberish"))
+        self.assertEqual([], channels)
+        # Invalid SBDebugger returns always an empty list even with a valid
+        # channel. The log channels are globals but that might change
+        # in the future, so let's require a valid SBDebugger.
+        categories = list(lldb.SBDebugger().GetLogCategories(valid_channel))
+        self.assertEqual([], channels)
+
+        # Take the valid channel with a valid SBDebugger and make sure LLDB
+        # returns the right categories.
+        categories = list(self.dbg.GetLogChannels(channel))
+        # 'expression' and 'types' are 'lldb' categories.
+        self.assertIn("expression", categories)
+        self.assertIn("types", categories)
+
+        # Test for a category from the 'dwarf' channel which shouldn't be here.
+        self.assertNotIn("lookups", categories)
+        # Some sanity checks for things that should never be in the list.
+        self.assertNotIn("", categories)
+        self.assertNotIn(valid_channel, categories)

lldb/unittests/Utility/StringListTest.cpp

 //===-- StringListTest.cpp ------------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #include "lldb/Utility/StringList.h"
 #include "lldb/Utility/StreamString.h"
 #include "gmock/gmock.h"
 #include "gtest/gtest.h"
 
 using namespace lldb_private;
 
 TEST(StringListTest, DefaultConstructor) {
   StringList s;
   EXPECT_EQ(0U, s.GetSize());
 }
 
+TEST(StringListTest, ArrayRefConstructor) {
+  StringList s(llvm::ArrayRef<llvm::StringRef>({"a", "bc"}));
+  EXPECT_EQ(2U, s.GetSize());
+  EXPECT_STREQ("a", s.GetStringAtIndex(0));
+  EXPECT_STREQ("bc", s.GetStringAtIndex(1));
+
+  StringList empty(llvm::ArrayRef<llvm::StringRef>({}));
+  EXPECT_EQ(0U, empty.GetSize());
+}
+
 TEST(StringListTest, Assignment) {
   StringList orig;
   orig.AppendString("foo");
   orig.AppendString("bar");
 
   StringList s = orig;
 
   ASSERT_EQ(2U, s.GetSize());