[Lldb-commits] [lldb] [LLDB] Add module hook implementation (PR #185465)

via lldb-commits lldb-commits at lists.llvm.org
Wed Apr 8 18:21:59 PDT 2026


================
@@ -5291,6 +5291,704 @@ class CommandObjectMultiwordTargetStopHooks : public CommandObjectMultiword {
   ~CommandObjectMultiwordTargetStopHooks() override = default;
 };
 
+#pragma mark CommandObjectTargetHookAdd
+
+#define LLDB_OPTIONS_target_hook_add
+#include "CommandOptions.inc"
+
+class CommandObjectTargetHookAdd : public CommandObjectParsed,
+                                   public IOHandlerDelegateMultiline {
+public:
+  class CommandOptions : public OptionGroup {
+  public:
+    CommandOptions() = default;
+    ~CommandOptions() override = default;
+
+    llvm::ArrayRef<OptionDefinition> GetDefinitions() override {
+      return llvm::ArrayRef(g_target_hook_add_options);
+    }
+
+    Status SetOptionValue(uint32_t option_idx, llvm::StringRef option_arg,
+                          ExecutionContext *execution_context) override {
+      Status error;
+      const int short_option =
+          g_target_hook_add_options[option_idx].short_option;
+      switch (short_option) {
+      case 'o':
+        m_use_one_liner = true;
+        m_one_liner.push_back(std::string(option_arg));
+        break;
+      case 'L':
+        m_on_load = true;
+        break;
+      case 'u':
+        m_on_unload = true;
+        break;
+      case 'S':
+        m_on_stop = true;
+        break;
+      case 's':
+        m_module_name = std::string(option_arg);
+        m_sym_ctx_specified = true;
+        break;
+      case 'x': {
+        uint32_t thread_index;
+        if (option_arg.getAsInteger(0, thread_index))
+          error = Status::FromErrorStringWithFormat("invalid thread index '%s'",
+                                                    option_arg.str().c_str());
+        else
+          m_thread_index = thread_index;
+        m_thread_specified = true;
+        break;
+      }
+      case 't': {
+        lldb::tid_t thread_id;
+        if (option_arg.getAsInteger(0, thread_id))
+          error = Status::FromErrorStringWithFormat("invalid thread id '%s'",
+                                                    option_arg.str().c_str());
+        else
+          m_thread_id = thread_id;
+        m_thread_specified = true;
+        break;
+      }
+      case 'T':
+        m_thread_name = std::string(option_arg);
+        m_thread_specified = true;
+        break;
+      case 'q':
+        m_queue_name = std::string(option_arg);
+        m_thread_specified = true;
+        break;
+      case 'f':
+        m_file_name = std::string(option_arg);
+        m_sym_ctx_specified = true;
+        break;
+      case 'l': {
+        uint32_t line;
+        if (option_arg.getAsInteger(0, line))
+          error = Status::FromErrorStringWithFormat(
+              "invalid start line number '%s'", option_arg.str().c_str());
+        else
+          m_line_start = line;
+        m_sym_ctx_specified = true;
+        break;
+      }
+      case 'e': {
+        uint32_t line;
+        if (option_arg.getAsInteger(0, line))
+          error = Status::FromErrorStringWithFormat(
+              "invalid end line number '%s'", option_arg.str().c_str());
+        else
+          m_line_end = line;
+        m_sym_ctx_specified = true;
+        break;
+      }
+      case 'c':
+        m_class_name = std::string(option_arg);
+        m_sym_ctx_specified = true;
+        break;
+      case 'n':
+        m_function_name = std::string(option_arg);
+        m_sym_ctx_specified = true;
+        break;
+      case 'G': {
+        bool value, success;
+        value = OptionArgParser::ToBoolean(option_arg, false, &success);
+        if (success)
+          m_auto_continue = value;
+        else
+          error = Status::FromErrorStringWithFormat(
+              "invalid boolean value '%s' passed for -G option",
+              option_arg.str().c_str());
+        break;
+      }
+      case 'I': {
+        bool value, success;
+        value = OptionArgParser::ToBoolean(option_arg, true, &success);
+        if (success)
+          m_at_initial_stop = value;
+        else
+          error = Status::FromErrorStringWithFormat(
+              "invalid boolean value '%s' passed for -I option",
+              option_arg.str().c_str());
+        break;
+      }
+      default:
+        llvm_unreachable("unhandled option");
+      }
+      return error;
+    }
+
+    void OptionParsingStarting(ExecutionContext *execution_context) override {
+      m_use_one_liner = false;
+      m_one_liner.clear();
+      m_on_load = false;
+      m_on_unload = false;
+      m_on_stop = false;
+      m_sym_ctx_specified = false;
+      m_thread_specified = false;
+      m_module_name.clear();
+      m_file_name.clear();
+      m_class_name.clear();
+      m_function_name.clear();
+      m_line_start = 0;
+      m_line_end = UINT_MAX;
+      m_thread_id = LLDB_INVALID_THREAD_ID;
+      m_thread_index = UINT32_MAX;
+      m_thread_name.clear();
+      m_queue_name.clear();
+      m_auto_continue = false;
+      m_at_initial_stop = true;
+    }
+
+    std::vector<std::string> m_one_liner;
+    bool m_use_one_liner = false;
+    bool m_on_load = false;
+    bool m_on_unload = false;
+    bool m_on_stop = false;
+
+    // Filter options (for stop trigger).
+    bool m_sym_ctx_specified = false;
+    bool m_thread_specified = false;
+    std::string m_module_name;
+    std::string m_file_name;
+    std::string m_class_name;
+    std::string m_function_name;
+    uint32_t m_line_start = 0;
+    uint32_t m_line_end = UINT_MAX;
+    lldb::tid_t m_thread_id = LLDB_INVALID_THREAD_ID;
+    uint32_t m_thread_index = UINT32_MAX;
+    std::string m_thread_name;
+    std::string m_queue_name;
+    bool m_auto_continue = false;
+    bool m_at_initial_stop = true;
+  };
+
+  CommandObjectTargetHookAdd(CommandInterpreter &interpreter)
+      : CommandObjectParsed(
+            interpreter, "target hook add",
+            "Add a hook to be executed on target lifecycle events.",
+            "target hook add"),
+        IOHandlerDelegateMultiline("DONE",
+                                   IOHandlerDelegate::Completion::LLDBCommand),
+        m_python_class_options("scripted hook", false, 'P') {
+    SetHelpLong(R"help(
+Command-based hooks:
+--------------------
+  Specify which triggers the hook responds to with --on-load (-L),
+  --on-unload (-u), and/or --on-stop (-S).  At least one trigger is required.
+  Provide commands with --one-liner (-o), or omit -o to enter an interactive
+  command editor.  All commands run for every trigger the hook is signed up
+  for; there is no per-trigger command list.
+
+  Examples:
+    target hook add -L -o "script print('module loaded')"
+    target hook add -L -u -o "script print('module event')"
+    target hook add -S -o "bt"
+    target hook add -L -u -S -o "script print('all events')"
+    target hook add -S -s mylib.so -n main -o "bt"
+    target hook add -S -G true -o "thread info"
+
+Python class hooks:
+-------------------
+  Provide a Python class with --python-class (-P).  The class controls which
+  events it handles by implementing the corresponding methods; you do not
+  specify triggers on the command line.  Use -k <key> -v <value> to pass
+  extra_args to the class constructor.
+
+  Examples:
+    target hook add -P mymodule.MyHook
+    target hook add -P mymodule.MyHook -k verbose -v true
+
+  The Python class should implement at least one of these methods:
+
+    class MyHook:
+        def __init__(self, target, extra_args, internal_dict):
+            self.target = target
+        def handle_module_loaded(self, stream):
+            pass
+        def handle_module_unloaded(self, stream):
+            pass
+        def handle_stop(self, exe_ctx, stream):
+            return True  # True = should_stop, False = continue
+
+Filter options:
+---------------
+  Filters (-s, -f, -l, -e, -c, -n, -x, -t, -T, -q) restrict when the hook
+  fires.  They apply to both command-based and Python class hooks.
+)help");
+    // Python class options (-P, -k, -v) are placed in Set 2 (dst_mask).
+    // src_mask must cover Set 1 | Set 2 to match the internal usage masks of
+    // OptionGroupPythonClassWithDict (class=Set1, key/value=Set2).
+    // Since -o, -L, -u, -S are Group<1> only, the parser prevents mixing.
+    m_all_options.Append(&m_python_class_options,
+                         LLDB_OPT_SET_1 | LLDB_OPT_SET_2, LLDB_OPT_SET_2);
+    m_all_options.Append(&m_options);
+    m_all_options.Finalize();
+  }
+
+  ~CommandObjectTargetHookAdd() override = default;
+
+  Options *GetOptions() override { return &m_all_options; }
+
+protected:
+  void IOHandlerActivated(IOHandler &io_handler, bool interactive) override {
+    if (interactive) {
+      if (lldb::LockableStreamFileSP output_sp =
+              io_handler.GetOutputStreamFileSP()) {
+        LockedStreamFile locked_stream = output_sp->Lock();
+        locked_stream.PutCString(
+            "Enter your hook command(s). Type 'DONE' to end.\n");
+      }
+    }
+  }
+
+  void IOHandlerInputComplete(IOHandler &io_handler,
+                              std::string &line) override {
+    if (m_hook_sp) {
+      if (line.empty()) {
+        if (lldb::LockableStreamFileSP error_sp =
+                io_handler.GetErrorStreamFileSP()) {
+          LockedStreamFile locked_stream = error_sp->Lock();
+          locked_stream.Printf("error: hook #%" PRIu64
+                               " aborted, no commands.\n",
+                               m_hook_sp->GetID());
+        }
+        GetTarget().UndoCreateHook(m_hook_sp->GetID());
+      } else {
+        auto *hook = static_cast<Target::HookCommandLine *>(m_hook_sp.get());
+        hook->SetActionFromString(line);
+        if (lldb::LockableStreamFileSP output_sp =
+                io_handler.GetOutputStreamFileSP()) {
+          LockedStreamFile locked_stream = output_sp->Lock();
+          locked_stream.Printf("Hook #%" PRIu64 " added.\n",
+                               m_hook_sp->GetID());
+        }
+      }
+      m_hook_sp.reset();
+    }
+    io_handler.SetIsDone(true);
+  }
+
+  void DoExecute(Args &command, CommandReturnObject &result) override {
+    m_hook_sp.reset();
+    Target &target = GetTarget();
+
+    bool is_python_class = !m_python_class_options.GetName().empty();
+
+    // Command-based hooks require at least one explicit trigger.
+    if (!is_python_class && !m_options.m_on_load && !m_options.m_on_unload &&
+        !m_options.m_on_stop) {
+      result.AppendError("at least one trigger must be specified: "
+                         "--on-load (-L), --on-unload (-u), or --on-stop (-S)");
+      return;
+    }
+
+    Target::Hook::HookKind hook_kind =
+        is_python_class ? Target::Hook::HookKind::ScriptBased
+                        : Target::Hook::HookKind::CommandBased;
+
+    Target::HookSP new_hook_sp = target.CreateHook(hook_kind);
+
+    if (!is_python_class) {
+      // Build trigger mask from explicit command-line flags.
+      auto *cmd_hook =
+          static_cast<Target::HookCommandLine *>(new_hook_sp.get());
+      uint32_t trigger_mask = 0;
+      if (m_options.m_on_load)
+        trigger_mask |= Target::Hook::kModulesLoaded;
+      if (m_options.m_on_unload)
+        trigger_mask |= Target::Hook::kModulesUnloaded;
+      if (m_options.m_on_stop)
+        trigger_mask |= Target::Hook::kProcessStop;
+      cmd_hook->SetTriggerMask(trigger_mask);
+    }
+    // Python class hooks: triggers are computed in SetScriptCallback based
+    // on which callback methods the class implements.
+
+    // Set up symbol context specifier if filter options were provided.
+    if (m_options.m_sym_ctx_specified) {
+      auto specifier_up = std::make_unique<SymbolContextSpecifier>(
+          GetDebugger().GetSelectedTarget());
+
+      if (!m_options.m_module_name.empty())
+        specifier_up->AddSpecification(
+            m_options.m_module_name.c_str(),
+            SymbolContextSpecifier::eModuleSpecified);
+
+      if (!m_options.m_class_name.empty())
+        specifier_up->AddSpecification(
+            m_options.m_class_name.c_str(),
+            SymbolContextSpecifier::eClassOrNamespaceSpecified);
+
+      if (!m_options.m_file_name.empty())
+        specifier_up->AddSpecification(m_options.m_file_name.c_str(),
+                                       SymbolContextSpecifier::eFileSpecified);
+
+      if (m_options.m_line_start != 0)
+        specifier_up->AddLineSpecification(
+            m_options.m_line_start,
+            SymbolContextSpecifier::eLineStartSpecified);
+
+      if (m_options.m_line_end != UINT_MAX)
+        specifier_up->AddLineSpecification(
+            m_options.m_line_end, SymbolContextSpecifier::eLineEndSpecified);
+
+      if (!m_options.m_function_name.empty())
+        specifier_up->AddSpecification(
+            m_options.m_function_name.c_str(),
+            SymbolContextSpecifier::eFunctionSpecified);
+
+      new_hook_sp->SetSCSpecifier(specifier_up.release());
+    }
+
+    // Set up thread specifier.
+    if (m_options.m_thread_specified) {
+      ThreadSpec *thread_spec = new ThreadSpec();
+
+      if (m_options.m_thread_id != LLDB_INVALID_THREAD_ID)
+        thread_spec->SetTID(m_options.m_thread_id);
+
+      if (m_options.m_thread_index != UINT32_MAX)
+        thread_spec->SetIndex(m_options.m_thread_index);
+
+      if (!m_options.m_thread_name.empty())
+        thread_spec->SetName(m_options.m_thread_name.c_str());
+
+      if (!m_options.m_queue_name.empty())
+        thread_spec->SetQueueName(m_options.m_queue_name.c_str());
+
+      new_hook_sp->SetThreadSpecifier(thread_spec);
+    }
+
+    new_hook_sp->SetAutoContinue(m_options.m_auto_continue);
+    new_hook_sp->SetRunAtInitialStop(m_options.m_at_initial_stop);
+
+    if (m_options.m_use_one_liner) {
+      auto *hook = static_cast<Target::HookCommandLine *>(new_hook_sp.get());
+      hook->SetActionFromStrings(m_options.m_one_liner);
+      result.AppendMessageWithFormat("Hook #%" PRIu64 " added.\n",
+                                     new_hook_sp->GetID());
+    } else if (!m_python_class_options.GetName().empty()) {
+      auto *hook = static_cast<Target::HookScripted *>(new_hook_sp.get());
+      Status callback_error =
+          hook->SetScriptCallback(m_python_class_options.GetName(),
+                                  m_python_class_options.GetStructuredData());
+      if (callback_error.Fail()) {
+        result.AppendErrorWithFormat("couldn't add hook: %s",
+                                     callback_error.AsCString());
+        target.UndoCreateHook(new_hook_sp->GetID());
+        return;
+      }
+      result.AppendMessageWithFormat("Hook #%" PRIu64 " added.\n",
+                                     new_hook_sp->GetID());
+    } else {
+      m_hook_sp = new_hook_sp;
+      m_interpreter.GetLLDBCommandsFromIOHandler("> ",   // prompt
+                                                 *this); // delegate
+    }
+    result.SetStatus(eReturnStatusSuccessFinishNoResult);
+  }
+
+private:
+  CommandOptions m_options;
+  OptionGroupPythonClassWithDict m_python_class_options;
+  OptionGroupOptions m_all_options;
+  Target::HookSP m_hook_sp;
+};
+
+#pragma mark CommandObjectTargetHookDelete
+
+class CommandObjectTargetHookDelete : public CommandObjectParsed {
+public:
+  CommandObjectTargetHookDelete(CommandInterpreter &interpreter)
+      : CommandObjectParsed(interpreter, "target hook delete", "Delete a hook.",
+                            "target hook delete [<id>]") {
+    AddSimpleArgumentList(eArgTypeStopHookID, eArgRepeatStar);
+  }
+
+  ~CommandObjectTargetHookDelete() override = default;
+
+protected:
+  void DoExecute(Args &command, CommandReturnObject &result) override {
+    Target &target = GetTarget();
+    if (command.GetArgumentCount() == 0) {
+      target.RemoveAllHooks();
----------------
jimingham wrote:

You might want to call CommandInterpreter::Confirm before doing this.  See CommandObjectBreakpointDelete for an example of its use.

https://github.com/llvm/llvm-project/pull/185465


More information about the lldb-commits mailing list