[lldb] Introduce StackFrameRecognizer

[kubamracek]

Summary

This patch introduces a concept of "frame recognizer" and "recognized frame". This should be an extensible mechanism that retrieves information about special frames based on ABI, arguments or other special properties of that frame, even without source code. A few examples where that could be useful could be 1) objc_exception_throw, where we'd like to get the current exception, 2) terminate_with_reason and extracting the current terminate string, 3) recognizing Objective-C frames and automatically extracting the receiver+selector, or perhaps all arguments (based on selector).

[jingham]

This seems like a good place to start. Certainly producing synthetic function arguments is one of the fixed things these recognizers can do, and we can build on that as we go. The inputs are all types that we know how to bind to Python, so it will be easy to make wrappers and eventually an affordance for making Python based frame recognizers. I don't think that needs to be a part of this patch, though that would make writing tests easier. How were you planning to add tests for this?

include/lldb/Target/StackFrame.h

558–559

Do we need m_recognized? Wouldn't it be enough to check !m_recognized_frame?

Also, we prepend SharedPointers with _sp as a general rule since it's really handy to know that w/o having to look up the definition.

source/Plugins/LanguageRuntime/ObjC/AppleObjCRuntime/AppleObjCStackFrameRecognizer.cpp

27–28 ↗

(On Diff #138835)

In the rest of the Apple support for ObjC we use either AppleObjCRuntimeV1 and AppleObjCRuntimeV2, and then use AppleObjCRuntime for support that crosses versions. It would be better not to introduce another name here.

source/Target/StackFrameRecognizer.cpp

27–31

Because of the way you search, you're doing first one in wins for any conflicts. I'm not sure we need to overthink conflicts at this point, but at least it should be last one in wins. And maybe start out returning an Status so that if there are conflicts we can warn about them?

[kubamracek]

Updating StackFrameRecognizer with a Python plugin implementation and a testcase using a Python recognizer. Also removing the Darwin-specific parts.

[kubamracek]

@jingham, @jasonmolenda, I haven't addresses the comments yet, but I'll do that in the next round. I'd seeking approval of the high-level approach first. The patch is getting a bit large, but the added test (and the Python implementation of a recognizer) should showcase what I'm trying to achieve.

[kubamracek]

source/Commands/CommandObjectFrame.cpp

833

Note to self: We should also require -m and -n (otherwise the default is that the recognizer will be called on every single stop point).

[jingham]

This is going as I imagined it should, looks great!

We probably want to turn this on by default for "frame var" or no one will ever discover it. The IDE folks can decide on their own what to do from the SB API's. Since you are doing module filtering and this only triggers when you explicitly run "frame var" I think having it on by default will not be a big deal.

Does this work with "frame var paths" as well? That is, if I do:

(lldb) frame var
(struct Foo *) recognized_variable = 0x12345

Will we find it again if I do:

(lldb) frame var *recognized_variable

or

(lldb) frame var recognized_variable.some_interesting_ivar

I think this should just work, but it's worth checking.

[kubamracek]

In D44603#1133149, @jingham wrote:

This is going as I imagined it should, looks great!
We probably want to turn this on by default for "frame var" or no one will ever discover it. The IDE folks can decide on their own what to do from the SB API's. Since you are doing module filtering and this only triggers when you explicitly run "frame var" I think having it on by default will not be a big deal.
Does this work with "frame var paths" as well? That is, if I do:

It does not work. The reason is that the current patch is not creating VariableSP objects, so things like m_variable_list_sp (in StackFrame) don't contain these new "recognized arguments". Right now, I'm just creating ValueObjects and GetVariableList/GetInScopeVariableList doesn't know about them. Do you think we should go that way instead? In that case I think we'd need to extend or subclass Variable so that we can actually create Variable objects that are not backed by DWARF and SymbolContextScope and stuff like that.

If you think that makes sense, I'll be happy to work on that. Also, if you think it's not necessary for an initial commit, I can send a separate follow-up patch (to avoid growing this already large patch).

[jingham]

I think ultimately we should make this presentation of variables as symmetrical with locals as we can or it's going to confuse users.

I don't think it is necessary for the first version. The first uses, I would imagine, are to make available some variables in situations where none existed before - mostly digging info out of frames with no debug info - so it's strictly better than what was there before already...

[kubamracek]

Cleaned up patch, clang-formatted, respects 80-columns now. Expanded test case. Implemented all "frame recognizer" commands (add, delete, clear, list). Changed iteration order on the list of active recognizers (so that last added wins). Hopefully addressed all comments now.

[kubamracek]

Rebasing to current master.

[jingham]

This code looks fine to me. The docs are a little thin.

You don't say how to make a recognizer anywhere except in the test example. There should probably be an example in the long help for CommandObjectFrameRecognizerAdd. Look for instance at the help for "breakpoint command add" which tells you the signature of the Python function you need to add and gives an example. You should also add a section to www/python-reference.html since that's where people go to see "how can I extend lldb using the Python interface."

[kubamracek]

Switched on showing recognized args by default in "frame variable". Switched "-t" to mean "omit" instead of "include".
Added documentation and an example into "help frame recognizer add" and into python-reference.html.

[kubamracek]

Fixing up test (it was using the "-t" flag).
Removing a leftover printf().

[kubamracek]

friendly ping :)

[jingham]

This is good. I had a few inline comments, mostly about the command syntax. I think you should switch "-m" to "-s" since that's what we use in the other similar places.

For the "type summary" etc. commands which have a similar registry & match function, Enrico added:

(lldb) type summary info expression

that tell you what summary formatter will match the given expression. It might be nice to have:

(lldb) recognizer info <FRAME_NUMBER>

that would tell you what recognizer is going to be in force for this frame. The isn't terribly important if there's only a few recognizers, but if there are more, or when you're trying to get one to work, having this info is really handy. That's not required - and I'm fine with doing that as a follow-on, however.

source/API/SBFrame.cpp

1062

You can say:

for (auto &rec_value_sp : recognized_arg_list->GetObjects()) {
   SBValue value_sb;
  value_sb.SetSP(rec_value_sp, use_dynamic);
   value_list.Append(value_sb);
}

That's a little easier to read.

source/Commands/CommandObjectFrame.cpp

721

Should be able to use GetObjects here too.

761

In most of the other places where we limit a search to a shared library (e.g. breakpoint set, source list & target var) we use "s" and "shlib" in the command line. It would be better to stay consistent with that.

Also the type of the argument should be eArgTypeShlibName (though these types don't do anything yet, they should eventually get hooked up to completers. But since they don't you can also add the module completer by setting:

CommandCompletions::eModuleCompletion

in the completers slot. See for instance the setting of "shlib" in g_breakpoint_set_options in CommandObjectBreakpoint.cpp.

The few places that don't follow this rule (like image list) take a list of shared libraries as arguments, so don't fall within this rule.

Also, for module and name entries I've been allowing multiple instances of the option, and then accumulating them in a list. So for instance, you can set:

(lldb) br s -n foo -n main -s Sketch -s libsystem_c.dylib

There's no automatic way to indicate that you are doing this, I always note it explicitly in the help:

(lldb) help break set
...
       -n <function-name> ( --name <function-name> )
            Set the breakpoint by function name.  Can be repeated multiple times to make one breakpoint for multiple
            names

That might also be useful here.

858–859

Why?

www/python-reference.html

749

Grammatically it would be better to say "Frame recognizers allow FOR retrieving..."

752–753

They can also be used to augment extant function arguments, so this isn't exactly right. It's just the most obvious use. Might be good to be clear about that?

754

I'd say "Adding a custom frame recognizer is DONE by implementing..."

You are at this point telling somebody how to do it, not what can be done...

776–777

Again, say why. Presumably this is for performance reasons, but from this comment I can't tell if it would crash otherwise or what bad thing might happen...

[kubamracek]

Updating patch, addressing most comments. Changed '-m' to '-s'. Added 'frame recognizer info' subcommand. Improved wording in documentation.

I didn't add the possibility to specify multiple '-s' and '-n' args. Do you think I should add this to the first iteration of this or can we leave it as a future improvement?

[aprantl]

include/lldb/Target/StackFrameRecognizer.h

26

Would you mind adding doxygen comments to each of the new classes to explain what they are good for?

[jingham]

This is good. The addition of the "info" command will be helpful for people trying to debug their recognizers. It's okay to add multiple -s and -n's later - though the fact that you don't allow "apply to all frames" may make us want the ability to provide more than one option sooner rather than later...

Sorry for this thought coming late, but I worry a little bit about the fact that the class name is the recognizers identity, particularly for deleting. I might have a good recognizer class that I want to add to one library, then later in the session want to apply it to another library as well. The second addition will mean that the name now exists twice but with different shared libraries, and then since I only provide the name to "delete" I can't tell which one I've deleted.

It also makes the API's a little odd, since the name of the recognizer is important to the commands for handling it, but it isn't clear from the API's that I have to provide a unique name for them.

I think it would be better to have the RecognizerManager keep an ID for each recognizer, and have list print and delete take the index.

Also, it might be convenient to have "frame recognizer delete" with no arguments query "Do you want to delete all recognizers" and then delete them. That's the way "break delete" works so it's an accepted pattern in lldb. This could be done as a follow-on, however.

packages/Python/lldbsuite/test/functionalities/frame-recognizer/TestFrameRecognizer.py

55

Would you mind using:

lldbutil.run_break_set_by_symbol(self, "foo")

instead of this runCmd. The lldbutil routine will check that the breakpoint got set and error out here if it didn't. That will reduce the head-scratching if for some reason we fail to set the breakpoint and then the test falls over downstream.

92

Also here.

[kubamracek]

Adding class comments, adding IDs to recognizers.

[kubamracek]

Ping.

[jingham]

LGTM. Thanks for working on this!

include/lldb/API/SBVariablesOptions.h

public:
   ~SBVariablesOptions();
 
   bool IsValid() const;
 
   bool GetIncludeArguments() const;
 
   void SetIncludeArguments(bool);
 
+  bool GetIncludeRecognizedArguments() const;
+
+  void SetIncludeRecognizedArguments(bool);
+
   bool GetIncludeLocals() const;
 
   void SetIncludeLocals(bool);
 
   bool GetIncludeStatics() const;
 
   void SetIncludeStatics(bool);
 

include/lldb/Interpreter/OptionGroupVariable.h

public:
   Status SetOptionValue(uint32_t option_idx, llvm::StringRef option_value,
                         ExecutionContext *execution_context) override;
   Status SetOptionValue(uint32_t, const char *, ExecutionContext *) = delete;
 
   void OptionParsingStarting(ExecutionContext *execution_context) override;
 
   bool include_frame_options : 1,
       show_args : 1,    // Frame option only (include_frame_options == true)
+      show_recognized_args : 1,  // Frame option only (include_frame_options ==
+                                 // true)
       show_locals : 1,  // Frame option only (include_frame_options == true)
       show_globals : 1, // Frame option only (include_frame_options == true)
       use_regex : 1, show_scope : 1, show_decl : 1;
   OptionValueString summary;        // the name of a named summary
   OptionValueString summary_string; // a summary string
 
 private:
   DISALLOW_COPY_AND_ASSIGN(OptionGroupVariable);
 };
 
 } // namespace lldb_private
 
 #endif // liblldb_OptionGroupVariable_h_

include/lldb/Interpreter/ScriptInterpreter.h

public:
   }
 
   virtual StructuredData::GenericSP
   CreateScriptCommandObject(const char *class_name) {
     return StructuredData::GenericSP();
   }
 
   virtual StructuredData::GenericSP
+  CreateFrameRecognizer(const char *class_name) {
+    return StructuredData::GenericSP();
+  }
+
+  virtual lldb::ValueObjectListSP GetRecognizedArguments(
+      const StructuredData::ObjectSP &implementor,
+      lldb::StackFrameSP frame_sp) {
+    return lldb::ValueObjectListSP();
+  }
+
+  virtual StructuredData::GenericSP
   OSPlugin_CreatePluginObject(const char *class_name,
                               lldb::ProcessSP process_sp) {
     return StructuredData::GenericSP();
   }
 
   virtual StructuredData::DictionarySP
   OSPlugin_RegisterInfo(StructuredData::ObjectSP os_plugin_object_sp) {
     return StructuredData::DictionarySP();

include/lldb/Target/StackFrame.h

public:
   lldb::ProcessSP CalculateProcess() override;
 
   lldb::ThreadSP CalculateThread() override;
 
   lldb::StackFrameSP CalculateStackFrame() override;
 
   void CalculateExecutionContext(ExecutionContext &exe_ctx) override;
 
+  lldb::RecognizedStackFrameSP GetRecognizedFrame();
+
 protected:
   friend class StackFrameList;
 
   void SetSymbolContextScope(SymbolContextScope *symbol_scope);
 
   void UpdateCurrentFrameFromPreviousFrame(StackFrame &prev_frame);
 
   void UpdatePreviousFrameFromCurrentFrame(StackFrame &curr_frame);
private:
   uint32_t m_stop_id;
   bool m_stop_id_is_valid; // Does this frame have a stop_id?  Use it when
                            // referring to the m_frame_code_addr.
   bool m_is_history_frame;
   lldb::VariableListSP m_variable_list_sp;
   ValueObjectList m_variable_list_value_objects; // Value objects for each
                                                  // variable in
                                                  // m_variable_list_sp
+  lldb::RecognizedStackFrameSP m_recognized_frame_sp;
   StreamString m_disassembly;
   std::recursive_mutex m_mutex;
 
   DISALLOW_COPY_AND_ASSIGN(StackFrame);
 };
 
 } // namespace lldb_private
 
 #endif // liblldb_StackFrame_h_

include/lldb/Target/StackFrameRecognizer.h

+//===-- StackFrameRecognizer.h ----------------------------------*- C++ -*-===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef liblldb_StackFrameRecognizer_h_
+#define liblldb_StackFrameRecognizer_h_
+
+// C Includes
+// C++ Includes
+// Other libraries and framework includes
+// Project includes
+#include "lldb/Core/ValueObjectList.h"
+#include "lldb/Symbol/VariableList.h"
+#include "lldb/Utility/StructuredData.h"
+#include "lldb/lldb-private-forward.h"
+#include "lldb/lldb-public.h"
+
+namespace lldb_private {
+
+class RecognizedStackFrame
+    : std::enable_shared_from_this<RecognizedStackFrame> {
+public:
+  virtual lldb::ValueObjectListSP GetRecognizedArguments() {
+    return m_arguments;
+  }
+  virtual ~RecognizedStackFrame(){};
+
+protected:
+  lldb::ValueObjectListSP m_arguments;
+};
+
+class StackFrameRecognizer
+    : std::enable_shared_from_this<StackFrameRecognizer> {
+public:
+  virtual lldb::RecognizedStackFrameSP RecognizeFrame(
+      lldb::StackFrameSP frame) {
+    return lldb::RecognizedStackFrameSP();
+  };
+  virtual std::string GetName() {
+    return "";
+  }
+
+  virtual ~StackFrameRecognizer(){};
+};
+
+#ifndef LLDB_DISABLE_PYTHON
+
+class ScriptedStackFrameRecognizer : public StackFrameRecognizer {
+  lldb_private::ScriptInterpreter *m_interpreter;
+  lldb_private::StructuredData::ObjectSP m_python_object_sp;
+  std::string m_python_class;
+
+public:
+  ScriptedStackFrameRecognizer(lldb_private::ScriptInterpreter *interpreter,
+                               const char *pclass);
+  ~ScriptedStackFrameRecognizer() {}
+
+  std::string GetName() override {
+    return GetPythonClassName();
+  }
+
+  const char *GetPythonClassName() { return m_python_class.c_str(); }
+
+  lldb::RecognizedStackFrameSP RecognizeFrame(
+      lldb::StackFrameSP frame) override;
+
+private:
+  DISALLOW_COPY_AND_ASSIGN(ScriptedStackFrameRecognizer);
+};
+
+#endif
+
+class StackFrameRecognizerManager {
+public:
+  static void AddRecognizer(lldb::StackFrameRecognizerSP recognizer,
+                            ConstString &module, ConstString &symbol,
+                            bool first_instruction_only = true);
+
+  static void AddRecognizer(lldb::StackFrameRecognizerSP recognizer,
+                            lldb::RegularExpressionSP module,
+                            lldb::RegularExpressionSP symbol,
+                            bool first_instruction_only = true);
+
+  static void ForEach(
+      std::function<void(std::string recognizer_name, std::string module,
+                         std::string symbol, bool regexp)> const &callback);
+
+  static bool Delete(std::string recognizer_name);
+
+  static void RemoveAllRecognizers();
+
+  static lldb::RecognizedStackFrameSP RecognizeFrame(lldb::StackFrameSP frame);
+};
+
+} // namespace lldb_private
+
+#endif // liblldb_StackFrameRecognizer_h_

include/lldb/lldb-forward.h

 class ProcessModID;
 class ProcessInfo;
 class ProcessInstanceInfo;
 class ProcessInstanceInfoList;
 class ProcessInstanceInfoMatch;
 class ProcessLaunchInfo;
 class Property;
 struct PropertyDefinition;
+class RecognizedStackFrame;
 class RegisterCheckpoint;
 class RegisterContext;
 class RegisterLocation;
 class RegisterLocationList;
 class RegisterValue;
 class RegularExpression;
 class REPL;
 class Scalar;
 class ScriptInterpreter;
 class ScriptInterpreterLocker;
 struct ScriptSummaryFormat;
 class SearchFilter;
 class Section;
 class SectionImpl;
 class SectionList;
 class SectionLoadHistory;
 class SectionLoadList;
 class Settings;
 class SourceManager;
 class SourceManagerImpl;
 class StackFrame;
 class StackFrameImpl;
 class StackFrameList;
+class StackFrameRecognizer;
+class StackFrameRecognizerManager;
 class StackID;
 class StopInfo;
 class Stoppoint;
 class StoppointCallbackContext;
 class StoppointLocation;
 class Stream;
 template <unsigned N> class StreamBuffer;
 class StreamFile;

 typedef std::shared_ptr<lldb_private::Property> PropertySP;
 typedef std::shared_ptr<lldb_private::RegisterCheckpoint> RegisterCheckpointSP;
 typedef std::shared_ptr<lldb_private::RegisterContext> RegisterContextSP;
 typedef std::shared_ptr<lldb_private::RegularExpression> RegularExpressionSP;
 typedef std::shared_ptr<lldb_private::Queue> QueueSP;
 typedef std::weak_ptr<lldb_private::Queue> QueueWP;
 typedef std::shared_ptr<lldb_private::QueueItem> QueueItemSP;
 typedef std::shared_ptr<lldb_private::REPL> REPLSP;
+typedef std::shared_ptr<lldb_private::RecognizedStackFrame>
+    RecognizedStackFrameSP;
 typedef std::shared_ptr<lldb_private::ScriptSummaryFormat>
     ScriptSummaryFormatSP;
 typedef std::shared_ptr<lldb_private::ScriptInterpreter> ScriptInterpreterSP;
 typedef std::unique_ptr<lldb_private::ScriptInterpreter> ScriptInterpreterUP;
 typedef std::shared_ptr<lldb_private::Section> SectionSP;
 typedef std::unique_ptr<lldb_private::SectionList> SectionListUP;
 typedef std::weak_ptr<lldb_private::Section> SectionWP;
 typedef std::shared_ptr<lldb_private::SectionLoadList> SectionLoadListSP;
 typedef std::shared_ptr<lldb_private::SearchFilter> SearchFilterSP;
 typedef std::shared_ptr<lldb_private::Settings> SettingsSP;
 typedef std::unique_ptr<lldb_private::SourceManager> SourceManagerUP;
 typedef std::shared_ptr<lldb_private::StackFrame> StackFrameSP;
 typedef std::unique_ptr<lldb_private::StackFrame> StackFrameUP;
 typedef std::weak_ptr<lldb_private::StackFrame> StackFrameWP;
 typedef std::shared_ptr<lldb_private::StackFrameList> StackFrameListSP;
+typedef std::shared_ptr<lldb_private::StackFrameRecognizer>
+    StackFrameRecognizerSP;
 typedef std::shared_ptr<lldb_private::StopInfo> StopInfoSP;
 typedef std::shared_ptr<lldb_private::StoppointLocation> StoppointLocationSP;
 typedef std::shared_ptr<lldb_private::Stream> StreamSP;
 typedef std::weak_ptr<lldb_private::Stream> StreamWP;
 typedef std::shared_ptr<lldb_private::StreamFile> StreamFileSP;
 typedef std::shared_ptr<lldb_private::StringSummaryFormat>
     StringTypeSummaryImplSP;
 typedef std::unique_ptr<lldb_private::StructuredDataImpl> StructuredDataImplUP;

lldb.xcodeproj/project.pbxproj

/* Begin PBXBuildFile section */
     236124A51986B4E2004EFC37 /* Socket.cpp in Sources */ = {isa = PBXBuildFile; fileRef = 236124A31986B4E2004EFC37 /* Socket.cpp */; };
     26D7E45D13D5E30A007FD12B /* SocketAddress.cpp in Sources */ = {isa = PBXBuildFile; fileRef = 26D7E45C13D5E30A007FD12B /* SocketAddress.cpp */; };
     23CB15451D66DA9300EDDDE1 /* SocketAddressTest.cpp in Sources */ = {isa = PBXBuildFile; fileRef = 2321F9391BDD332400BA9A93 /* SocketAddressTest.cpp */; };
     23CB153B1D66DA9300EDDDE1 /* SocketTest.cpp in Sources */ = {isa = PBXBuildFile; fileRef = 2321F93A1BDD332400BA9A93 /* SocketTest.cpp */; };
     232CB61D191E00CD00EF39FC /* SoftwareBreakpoint.cpp in Sources */ = {isa = PBXBuildFile; fileRef = 232CB613191E00CC00EF39FC /* SoftwareBreakpoint.cpp */; };
     2689004C13353E0400698AC0 /* SourceManager.cpp in Sources */ = {isa = PBXBuildFile; fileRef = 26BC7E8F10F1B85900F91463 /* SourceManager.cpp */; };
     268900F313353E6F00698AC0 /* StackFrame.cpp in Sources */ = {isa = PBXBuildFile; fileRef = 26BC7F3810F1B90C00F91463 /* StackFrame.cpp */; };
     268900F413353E6F00698AC0 /* StackFrameList.cpp in Sources */ = {isa = PBXBuildFile; fileRef = 26BC7F3910F1B90C00F91463 /* StackFrameList.cpp */; };
+    8CF46A6220522A9800423DDF /* StackFrameRecognizer.cpp in Sources */ = {isa = PBXBuildFile; fileRef = 8CF46A6120522A9000423DDF /* StackFrameRecognizer.cpp */; };
     268900F513353E6F00698AC0 /* StackID.cpp in Sources */ = {isa = PBXBuildFile; fileRef = 26BC7F3A10F1B90C00F91463 /* StackID.cpp */; };
     2689004D13353E0400698AC0 /* State.cpp in Sources */ = {isa = PBXBuildFile; fileRef = 26BC7E9010F1B85900F91463 /* State.cpp */; };
     9A3D43ED1F3237F900EB767C /* StateTest.cpp in Sources */ = {isa = PBXBuildFile; fileRef = 9A3D43E21F3237D500EB767C /* StateTest.cpp */; };
     492DB7EB1EC662E200B9E9AF /* Status.cpp in Sources */ = {isa = PBXBuildFile; fileRef = 492DB7E81EC662D100B9E9AF /* Status.cpp */; };
     9A3D43D91F3151C400EB767C /* StatusTest.cpp in Sources */ = {isa = PBXBuildFile; fileRef = 9A3D43C61F3150D200EB767C /* StatusTest.cpp */; };
     268900F613353E6F00698AC0 /* StopInfo.cpp in Sources */ = {isa = PBXBuildFile; fileRef = 2615DB861208A9E40021781D /* StopInfo.cpp */; };
     268900B513353E5000698AC0 /* StopInfoMachException.cpp in Sources */ = {isa = PBXBuildFile; fileRef = 2615DBC81208B5FC0021781D /* StopInfoMachException.cpp */; };
     2689000B13353DB600698AC0 /* Stoppoint.cpp in Sources */ = {isa = PBXBuildFile; fileRef = 26BC7E1610F1B83100F91463 /* Stoppoint.cpp */; };

     232CB613191E00CC00EF39FC /* SoftwareBreakpoint.cpp */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; name = SoftwareBreakpoint.cpp; path = source/Host/common/SoftwareBreakpoint.cpp; sourceTree = "<group>"; };
     267A47F21B14115A0021A5BC /* SoftwareBreakpoint.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; name = SoftwareBreakpoint.h; path = include/lldb/Host/common/SoftwareBreakpoint.h; sourceTree = "<group>"; };
     26BC7E8F10F1B85900F91463 /* SourceManager.cpp */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; name = SourceManager.cpp; path = source/Core/SourceManager.cpp; sourceTree = "<group>"; };
     26BC7D7610F1B77400F91463 /* SourceManager.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = SourceManager.h; path = include/lldb/Core/SourceManager.h; sourceTree = "<group>"; };
     26BC7F3810F1B90C00F91463 /* StackFrame.cpp */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; name = StackFrame.cpp; path = source/Target/StackFrame.cpp; sourceTree = "<group>"; };
     26BC7DF510F1B81A00F91463 /* StackFrame.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = StackFrame.h; path = include/lldb/Target/StackFrame.h; sourceTree = "<group>"; };
     26BC7F3910F1B90C00F91463 /* StackFrameList.cpp */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; name = StackFrameList.cpp; path = source/Target/StackFrameList.cpp; sourceTree = "<group>"; };
     26BC7DF610F1B81A00F91463 /* StackFrameList.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = StackFrameList.h; path = include/lldb/Target/StackFrameList.h; sourceTree = "<group>"; };
+    8CF46A6120522A9000423DDF /* StackFrameRecognizer.cpp */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.cpp.cpp; name = StackFrameRecognizer.cpp; path = source/Target/StackFrameRecognizer.cpp; sourceTree = "<group>"; };
+    8CFDB67920467B390052B399 /* StackFrameRecognizer.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; name = StackFrameRecognizer.h; path = include/lldb/Target/StackFrameRecognizer.h; sourceTree = "<group>"; };
     26BC7F3A10F1B90C00F91463 /* StackID.cpp */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; name = StackID.cpp; path = source/Target/StackID.cpp; sourceTree = "<group>"; };
     26BC7DF710F1B81A00F91463 /* StackID.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = StackID.h; path = include/lldb/Target/StackID.h; sourceTree = "<group>"; };
     26BC7E9010F1B85900F91463 /* State.cpp */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; name = State.cpp; path = source/Core/State.cpp; sourceTree = "<group>"; };
     26BC7D7710F1B77400F91463 /* State.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = State.h; path = include/lldb/Core/State.h; sourceTree = "<group>"; };
     9A3D43E21F3237D500EB767C /* StateTest.cpp */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; path = StateTest.cpp; sourceTree = "<group>"; };
     492DB7E81EC662D100B9E9AF /* Status.cpp */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; name = Status.cpp; path = source/Utility/Status.cpp; sourceTree = "<group>"; };
     492DB7E61EC662B100B9E9AF /* Status.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = Status.h; path = include/lldb/Utility/Status.h; sourceTree = "<group>"; };
     9A3D43C61F3150D200EB767C /* StatusTest.cpp */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; path = StatusTest.cpp; sourceTree = "<group>"; };
26BC7DEF10F1B80200F91463 /* Target */ = {
         262173A018395D3800C52091 /* SectionLoadHistory.h */,
         262173A218395D4600C52091 /* SectionLoadHistory.cpp */,
         2618D78F1240115500F2B8FE /* SectionLoadList.h */,
         2618D7911240116900F2B8FE /* SectionLoadList.cpp */,
         26BC7DF510F1B81A00F91463 /* StackFrame.h */,
         26BC7F3810F1B90C00F91463 /* StackFrame.cpp */,
         26BC7DF610F1B81A00F91463 /* StackFrameList.h */,
         26BC7F3910F1B90C00F91463 /* StackFrameList.cpp */,
+        8CFDB67920467B390052B399 /* StackFrameRecognizer.h */,
+        8CF46A6120522A9000423DDF /* StackFrameRecognizer.cpp */,
         26BC7DF710F1B81A00F91463 /* StackID.h */,
         26BC7F3A10F1B90C00F91463 /* StackID.cpp */,
         2615DB841208A9C90021781D /* StopInfo.h */,
         2615DB861208A9E40021781D /* StopInfo.cpp */,
         238F2B9F1D2C835A001FF92A /* StructuredDataPlugin.h */,
         238F2B9D1D2C82D0001FF92A /* StructuredDataPlugin.cpp */,
         238F2BA01D2C835A001FF92A /* SystemRuntime.h */,
         AF81DEF91828A23F0042CF19 /* SystemRuntime.cpp */,
2689FFC613353D7A00698AC0 /* Sources */ = {
         268900EF13353E6F00698AC0 /* Platform.cpp in Sources */,
         268900F013353E6F00698AC0 /* Process.cpp in Sources */,
         26BC17AD18C7F4CB00D2196D /* RegisterContextPOSIXCore_mips64.cpp in Sources */,
         268900F113353E6F00698AC0 /* RegisterContext.cpp in Sources */,
         6D55BAED1A8CD0A800A70529 /* PlatformAndroid.cpp in Sources */,
         268900F213353E6F00698AC0 /* SectionLoadList.cpp in Sources */,
         268900F313353E6F00698AC0 /* StackFrame.cpp in Sources */,
         268900F413353E6F00698AC0 /* StackFrameList.cpp in Sources */,
+        8CF46A6220522A9800423DDF /* StackFrameRecognizer.cpp in Sources */,
         268900F513353E6F00698AC0 /* StackID.cpp in Sources */,
         268900F613353E6F00698AC0 /* StopInfo.cpp in Sources */,
         256CBDB41ADD0EFD00BC6CDC /* RegisterContextPOSIXCore_arm.cpp in Sources */,
         267F684F1CC02E270086832B /* RegisterContextPOSIXCore_s390x.cpp in Sources */,
         268900F713353E6F00698AC0 /* Target.cpp in Sources */,
         268900F813353E6F00698AC0 /* TargetList.cpp in Sources */,
         268900F913353E6F00698AC0 /* Thread.cpp in Sources */,
         268900FA13353E6F00698AC0 /* ThreadList.cpp in Sources */,

packages/Python/lldbsuite/test/functionalities/frame-recognizer/Makefile

+LEVEL = ../../make
+
+OBJC_SOURCES := main.m
+
+CFLAGS_EXTRAS += -g0 # No debug info.
+MAKE_DSYM := NO
+
+include $(LEVEL)/Makefile.rules
+
+LDFLAGS += -framework Foundation

packages/Python/lldbsuite/test/functionalities/frame-recognizer/TestFrameRecognizer.py

+# encoding: utf-8
+"""
+Test lldb's frame recognizers.
+"""
+
+import lldb
+from lldbsuite.test.decorators import *
+from lldbsuite.test.lldbtest import *
+from lldbsuite.test import lldbutil
+
+import recognizer
+
+class FrameRecognizerTestCase(TestBase):
+
+    mydir = TestBase.compute_mydir(__file__)
+    NO_DEBUG_INFO_TESTCASE = True
+
+    @skipUnlessDarwin
+    def test_frame_recognizer_1(self):
+        self.build()
+
+        target = self.dbg.CreateTarget(self.getBuildArtifact("a.out"))
+        self.assertTrue(target, VALID_TARGET)
+
+        self.runCmd("command script import " + os.path.join(self.getSourceDir(), "recognizer.py"))
+
+        self.expect("frame recognizer list",
+                    substrs=['no matching results found.'])
+
+        self.runCmd("frame recognizer add -l recognizer.MyFrameRecognizer -m a.out -n foo")
+
+        self.expect("frame recognizer list",
+                    substrs=['recognizer.MyFrameRecognizer: module a.out, function foo'])
+
+        self.runCmd("frame recognizer add -l recognizer.MyOtherFrameRecognizer -m a.out -n bar -x")
+
+        self.expect("frame recognizer list",
+                    substrs=['recognizer.MyFrameRecognizer: module a.out, function foo',
+                             'recognizer.MyOtherFrameRecognizer: module a.out, function bar (regexp)'
+                    ])
+
+        self.runCmd("frame recognizer delete -l recognizer.MyFrameRecognizer")
+
+        self.expect("frame recognizer list",
+                    substrs=['recognizer.MyOtherFrameRecognizer: module a.out, function bar (regexp)'])
+
+        self.runCmd("frame recognizer clear")
+
+        self.expect("frame recognizer list",
+                    substrs=['no matching results found.'])
+
+        self.runCmd("frame recognizer add -l recognizer.MyFrameRecognizer -m a.out -n foo")
+
+        self.runCmd("b foo")
+        self.runCmd("r")
+
+        self.expect("thread list", STOPPED_DUE_TO_BREAKPOINT,
+                    substrs=['stopped', 'stop reason = breakpoint'])
+
+        process = target.GetProcess()
+        thread = process.GetSelectedThread()
+        frame = thread.GetSelectedFrame()
+
+        self.assertEqual(frame.GetSymbol().GetName(), "foo")
+        self.assertFalse(frame.GetLineEntry().IsValid())
+
+        self.expect("frame variable",
+                    substrs=['(int) a = 42', '(int) b = 56'])
+
+        opts = lldb.SBVariablesOptions();
+        opts.SetIncludeRecognizedArguments(True);
+        variables = frame.GetVariables(opts);
+
+        self.assertEqual(variables.GetSize(), 2)
+        self.assertEqual(variables.GetValueAtIndex(0).name, "a")
+        self.assertEqual(variables.GetValueAtIndex(0).signed, 42)
+        self.assertEqual(variables.GetValueAtIndex(1).name, "b")
+        self.assertEqual(variables.GetValueAtIndex(1).signed, 56)
+
+        # FIXME: The following doesn't work yet, but should be fixed.
+        """
+        self.runCmd("b bar")
+        self.runCmd("c")
+
+        self.expect("thread list", STOPPED_DUE_TO_BREAKPOINT,
+                    substrs=['stopped', 'stop reason = breakpoint'])
+
+        self.expect("frame variable -t",
+                    substrs=['(int *) a = '])
+
+        self.expect("frame variable -t *a",
+                    substrs=['*a = 78'])
+        """

packages/Python/lldbsuite/test/functionalities/frame-recognizer/main.m

+//===-- main.m ------------------------------------------------*- ObjC -*-===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+#import <Foundation/Foundation.h>
+
+void foo(int a, int b)
+{
+    printf("%d %d\n", a, b);
+}
+
+void bar(int *ptr)
+{
+  printf("%d\n", *ptr);
+}
+
+int main (int argc, const char * argv[])
+{
+    foo(42, 56);
+    int i = 78;
+    bar(&i);
+    return 0;
+}

packages/Python/lldbsuite/test/functionalities/frame-recognizer/recognizer.py

+# encoding: utf-8
+
+import lldb
+
+class MyFrameRecognizer(object):
+    def get_recognized_arguments(self, frame):
+        if frame.name == "foo":
+            arg1 = frame.EvaluateExpression("$arg1").signed
+            arg2 = frame.EvaluateExpression("$arg2").signed
+            val1 = lldb.target.CreateValueFromExpression("a", "%d" % arg1)
+            val2 = lldb.target.CreateValueFromExpression("b", "%d" % arg2)
+            return [val1, val2]
+        elif frame.name == "bar":
+            arg1 = frame.EvaluateExpression("$arg1").signed
+            val1 = lldb.target.CreateValueFromExpression("a", "(int *)%d" % arg1)
+            return [val1]
+        return []
+
+class MyOtherFrameRecognizer(object):
+    def get_recognized_arguments(self, frame):
+        return []

scripts/Python/python-wrapper.swig

)
 
     if (result.IsAllocated())
         return result.release();
 
     Py_RETURN_NONE;
 }
 
 SWIGEXPORT void*
+LLDBSWIGPython_CreateFrameRecognizer
+(
+    const char *python_class_name,
+    const char *session_dictionary_name
+)
+{
+    using namespace lldb_private;
+
+    if (python_class_name == NULL || python_class_name[0] == '\0' || !session_dictionary_name)
+        Py_RETURN_NONE;
+
+    PyErr_Cleaner py_err_cleaner(true);
+
+    auto dict = PythonModule::MainModule().ResolveName<PythonDictionary>(session_dictionary_name);
+    auto pfunc = PythonObject::ResolveNameWithDictionary<PythonCallable>(python_class_name, dict);
+
+    if (!pfunc.IsAllocated())
+        Py_RETURN_NONE;
+
+    auto result = pfunc();
+
+    if (result.IsAllocated())
+        return result.release();
+
+    Py_RETURN_NONE;
+}
+
+SWIGEXPORT PyObject*
+LLDBSwigPython_GetRecognizedArguments
+(
+    PyObject *implementor,
+    const lldb::StackFrameSP& frame_sp
+)
+{
+    using namespace lldb_private;
+
+    static char callee_name[] = "get_recognized_arguments";
+
+    lldb::SBFrame frame_sb(frame_sp);
+    PyObject *arg = SBTypeToSWIGWrapper(frame_sb);
+
+    PyObject* result = PyObject_CallMethodObjArgs(implementor, PyString_FromString(callee_name), arg, NULL);
+    return result;
+}
+
+SWIGEXPORT void*
 LLDBSWIGPython_GetDynamicSetting (void* module, const char* setting, const lldb::TargetSP& target_sp)
 {
     using namespace lldb_private;
 
     if (!module || !setting)
         Py_RETURN_NONE;
 
     PyErr_Cleaner py_err_cleaner(true);

scripts/interface/SBVariablesOptions.i

public:
     bool
     IsValid () const;
     
     bool
     GetIncludeArguments ()  const;
     
     void
     SetIncludeArguments (bool);
-    
     bool
+    GetIncludeRecognizedArguments ()  const;
+
+    void
+    SetIncludeRecognizedArguments (bool);
+
+    bool
     GetIncludeLocals ()  const;
     
     void
     SetIncludeLocals (bool);
     
     bool
     GetIncludeStatics ()  const;
     

source/API/SBFrame.cpp

 #include "lldb/Symbol/Symbol.h"
 #include "lldb/Symbol/SymbolContext.h"
 #include "lldb/Symbol/Variable.h"
 #include "lldb/Symbol/VariableList.h"
 #include "lldb/Target/ExecutionContext.h"
 #include "lldb/Target/Process.h"
 #include "lldb/Target/RegisterContext.h"
 #include "lldb/Target/StackFrame.h"
+#include "lldb/Target/StackFrameRecognizer.h"
 #include "lldb/Target/StackID.h"
 #include "lldb/Target/Target.h"
 #include "lldb/Target/Thread.h"
 #include "lldb/Utility/ConstString.h"
 #include "lldb/Utility/Log.h"
 #include "lldb/Utility/Stream.h"
 
 #include "lldb/API/SBAddress.h"
SBValueList SBFrame::GetVariables(const lldb::SBVariablesOptions &options) {
   std::unique_lock<std::recursive_mutex> lock;
   ExecutionContext exe_ctx(m_opaque_sp.get(), lock);
 
   StackFrame *frame = nullptr;
   Target *target = exe_ctx.GetTargetPtr();
 
   const bool statics = options.GetIncludeStatics();
   const bool arguments = options.GetIncludeArguments();
+  const bool recognized_arguments = options.GetIncludeRecognizedArguments();
   const bool locals = options.GetIncludeLocals();
   const bool in_scope_only = options.GetInScopeOnly();
   const bool include_runtime_support_values =
       options.GetIncludeRuntimeSupportValues();
   const lldb::DynamicValueType use_dynamic = options.GetUseDynamic();
 
   if (log)
-    log->Printf("SBFrame::GetVariables (arguments=%i, locals=%i, statics=%i, "
-                "in_scope_only=%i runtime=%i dynamic=%i)",
-                arguments, locals, statics, in_scope_only,
-                include_runtime_support_values, use_dynamic);
+    log->Printf(
+        "SBFrame::GetVariables (arguments=%i, recognized_arguments=%i, "
+        "locals=%i, statics=%i, in_scope_only=%i runtime=%i dynamic=%i)",
+        arguments, recognized_arguments, locals, statics, in_scope_only,
 
   std::set<VariableSP> variable_set;
   Process *process = exe_ctx.GetProcessPtr();
   if (target && process) {
     Process::StopLocker stop_locker;
     if (stop_locker.TryLock(&process->GetRunLock())) {
       frame = exe_ctx.GetFramePtr();
       if (frame) {
if (stop_locker.TryLock(&process->GetRunLock())) {
                   SBValue value_sb;
                   value_sb.SetSP(valobj_sp, use_dynamic);
                   value_list.Append(value_sb);
                 }
               }
             }
           }
         }
+        if (recognized_arguments) {
+          auto recognized_frame = frame->GetRecognizedFrame();
+          if (recognized_frame) {
+            ValueObjectListSP recognized_arg_list =
+                recognized_frame->GetRecognizedArguments();
+            if (recognized_arg_list) {
+              for (size_t i = 0; i < recognized_arg_list->GetSize(); i++) {
+                SBValue value_sb;
+                value_sb.SetSP(recognized_arg_list->GetValueObjectAtIndex(i),
+                               use_dynamic);
+                value_list.Append(value_sb);
+              }
+            }
+          }
+        }
       } else {
         if (log)
           log->Printf("SBFrame::GetVariables () => error: could not "
                       "reconstruct frame object for this SBFrame.");
       }
     } else {
       if (log)
         log->Printf("SBFrame::GetVariables () => error: process is running");

source/API/SBVariablesOptions.cpp

 #include "lldb/API/SBVariablesOptions.h"
 
 using namespace lldb;
 using namespace lldb_private;
 
 class VariablesOptionsImpl {
 public:
   VariablesOptionsImpl()
-      : m_include_arguments(false), m_include_locals(false),
-        m_include_statics(false), m_in_scope_only(false),
-        m_include_runtime_support_values(false),
+      : m_include_arguments(false), m_include_recognized_arguments(false),
+        m_include_locals(false), m_include_statics(false),
+        m_in_scope_only(false), m_include_runtime_support_values(false),
         m_use_dynamic(lldb::eNoDynamicValues) {}
 
   VariablesOptionsImpl(const VariablesOptionsImpl &) = default;
 
   ~VariablesOptionsImpl() = default;
 
   VariablesOptionsImpl &operator=(const VariablesOptionsImpl &) = default;
 
   bool GetIncludeArguments() const { return m_include_arguments; }
 
   void SetIncludeArguments(bool b) { m_include_arguments = b; }
 
+  bool GetIncludeRecognizedArguments() const {
+    return m_include_recognized_arguments;
+  }
+
+  void SetIncludeRecognizedArguments(bool b) {
+    m_include_recognized_arguments = b;
+  }
+
   bool GetIncludeLocals() const { return m_include_locals; }
 
   void SetIncludeLocals(bool b) { m_include_locals = b; }
 
   bool GetIncludeStatics() const { return m_include_statics; }
 
   void SetIncludeStatics(bool b) { m_include_statics = b; }
 
public:
   }
 
   lldb::DynamicValueType GetUseDynamic() const { return m_use_dynamic; }
 
   void SetUseDynamic(lldb::DynamicValueType d) { m_use_dynamic = d; }
 
 private:
   bool m_include_arguments : 1;
+  bool m_include_recognized_arguments : 1;
   bool m_include_locals : 1;
   bool m_include_statics : 1;
   bool m_in_scope_only : 1;
   bool m_include_runtime_support_values : 1;
   lldb::DynamicValueType m_use_dynamic;
 };
 
 SBVariablesOptions::SBVariablesOptions()

 bool SBVariablesOptions::GetIncludeArguments() const {
   return m_opaque_ap->GetIncludeArguments();
 }
 
 void SBVariablesOptions::SetIncludeArguments(bool arguments) {
   m_opaque_ap->SetIncludeArguments(arguments);
 }
 
+bool SBVariablesOptions::GetIncludeRecognizedArguments() const {
+  return m_opaque_ap->GetIncludeRecognizedArguments();
+}
+
+void SBVariablesOptions::SetIncludeRecognizedArguments(bool arguments) {
+  m_opaque_ap->SetIncludeRecognizedArguments(arguments);
+}
+
 bool SBVariablesOptions::GetIncludeLocals() const {
   return m_opaque_ap->GetIncludeLocals();
 }
 
 void SBVariablesOptions::SetIncludeLocals(bool locals) {
   m_opaque_ap->SetIncludeLocals(locals);
 }
 

source/API/SystemInitializerFull.cpp

LLDBSwigPythonCallModuleInit(const char *python_module_name,
                              const char *session_dictionary_name,
                              lldb::DebuggerSP &debugger);
 
 extern "C" void *
 LLDBSWIGPythonCreateOSPlugin(const char *python_class_name,
                              const char *session_dictionary_name,
                              const lldb::ProcessSP &process_sp);
 
+extern "C" void *LLDBSWIGPython_CreateFrameRecognizer(
+    const char *python_class_name,
+    const char *session_dictionary_name);
+
+extern "C" void *LLDBSwigPython_GetRecognizedArguments(void *implementor,
+    const lldb::StackFrameSP& frame_sp);
+
 extern "C" bool LLDBSWIGPythonRunScriptKeywordProcess(
     const char *python_function_name, const char *session_dictionary_name,
     lldb::ProcessSP &process, std::string &output);
 
 extern "C" bool LLDBSWIGPythonRunScriptKeywordThread(
     const char *python_function_name, const char *session_dictionary_name,
     lldb::ThreadSP &thread, std::string &output);
 
ScriptInterpreterPython::InitializeInterpreter(
       LLDBSwigPython_CalculateNumChildren, LLDBSwigPython_GetChildAtIndex,
       LLDBSwigPython_GetIndexOfChildWithName,
       LLDBSWIGPython_CastPyObjectToSBValue,
       LLDBSWIGPython_GetValueObjectSPFromSBValue,
       LLDBSwigPython_UpdateSynthProviderInstance,
       LLDBSwigPython_MightHaveChildrenSynthProviderInstance,
       LLDBSwigPython_GetValueSynthProviderInstance, LLDBSwigPythonCallCommand,
       LLDBSwigPythonCallCommandObject, LLDBSwigPythonCallModuleInit,
-      LLDBSWIGPythonCreateOSPlugin, LLDBSWIGPythonRunScriptKeywordProcess,
+      LLDBSWIGPythonCreateOSPlugin, LLDBSWIGPython_CreateFrameRecognizer,
+      LLDBSwigPython_GetRecognizedArguments,
+      LLDBSWIGPythonRunScriptKeywordProcess,
       LLDBSWIGPythonRunScriptKeywordThread,
       LLDBSWIGPythonRunScriptKeywordTarget, LLDBSWIGPythonRunScriptKeywordFrame,
       LLDBSWIGPythonRunScriptKeywordValue, LLDBSWIGPython_GetDynamicSetting,
       LLDBSwigPythonCreateScriptedThreadPlan, LLDBSWIGPythonCallThreadPlan);
 #endif
 }
 
 void SystemInitializerFull::Terminate() {

source/Commands/CommandObjectFrame.cpp

 #include "lldb/Symbol/Function.h"
 #include "lldb/Symbol/ObjectFile.h"
 #include "lldb/Symbol/SymbolContext.h"
 #include "lldb/Symbol/Type.h"
 #include "lldb/Symbol/Variable.h"
 #include "lldb/Symbol/VariableList.h"
 #include "lldb/Target/Process.h"
 #include "lldb/Target/StackFrame.h"
+#include "lldb/Target/StackFrameRecognizer.h"
 #include "lldb/Target/StopInfo.h"
 #include "lldb/Target/Target.h"
 #include "lldb/Target/Thread.h"
 #include "lldb/Utility/Args.h"
 #include "lldb/Utility/LLDBAssert.h"
 #include "lldb/Utility/StreamString.h"
 #include "lldb/Utility/Timer.h"
 
if (variable_list) {
               }
             }
           }
         }
       }
       result.SetStatus(eReturnStatusSuccessFinishResult);
     }
 
+    if (m_option_variable.show_recognized_args) {
+      auto recognized_frame = frame->GetRecognizedFrame();
+      if (recognized_frame) {
+        ValueObjectListSP recognized_arg_list = recognized_frame->GetRecognizedArguments();
+        if (recognized_arg_list) {
+          for (size_t i = 0; i < recognized_arg_list->GetSize(); i++) {
+            valobj_sp = recognized_arg_list->GetValueObjectAtIndex(i);
+            
+            options.SetFormat(m_option_format.GetFormat());
+            options.SetVariableFormatDisplayLanguage(
+                valobj_sp->GetPreferredDisplayLanguage());
+            options.SetRootValueObjectName(valobj_sp->GetName().AsCString());
+            valobj_sp->Dump(result.GetOutputStream(), options);
+          }
+        }
+      }
+    }
+
     if (m_interpreter.TruncationWarningNecessary()) {
       result.GetOutputStream().Printf(m_interpreter.TruncationWarningText(),
                                       m_cmd_name.c_str());
       m_interpreter.TruncationWarningGiven();
     }
 
     // Increment statistics.
     bool res = result.Succeeded();
     Target *target = GetSelectedOrDummyTarget();
     if (res)
       target->IncrementStats(StatisticKind::FrameVarSuccess);
     else
       target->IncrementStats(StatisticKind::FrameVarFailure);
     return res;
   }
 
 protected:
   OptionGroupOptions m_option_group;
   OptionGroupVariable m_option_variable;
   OptionGroupFormat m_option_format;
   OptionGroupValueObjectDisplay m_varobj_options;
 };
 
+#pragma mark CommandObjectFrameRecognizer
+
+static OptionDefinition g_frame_recognizer_add_options[] = {
+    // clang-format off
+  { LLDB_OPT_SET_ALL, false, "module",        'm', OptionParser::eRequiredArgument, nullptr, nullptr, 0, eArgTypeName,        "Name of the module that this recognizer applies to." },
+  { LLDB_OPT_SET_ALL, false, "function",      'n', OptionParser::eRequiredArgument, nullptr, nullptr, 0, eArgTypeName,        "Name of the function that this recognizer applies to." },
+  { LLDB_OPT_SET_2,   false, "python-class",  'l', OptionParser::eRequiredArgument, nullptr, nullptr, 0, eArgTypePythonClass, "Give the name of a Python class to use for this frame recognizer." },
+  { LLDB_OPT_SET_ALL, false, "regex",         'x', OptionParser::eNoArgument,       nullptr, nullptr, 0, eArgTypeNone,        "Function name and module name are actually regular expressions." }
+    // clang-format on
+};
+
+class CommandObjectFrameRecognizerAdd : public CommandObjectParsed {
+private:
+  class CommandOptions : public Options {
+  public:
+    CommandOptions() : Options() {}
+    ~CommandOptions() override = default;
+
+    Status SetOptionValue(uint32_t option_idx, llvm::StringRef option_arg,
+                          ExecutionContext *execution_context) override {
+      Status error;
+      const int short_option = m_getopt_table[option_idx].val;
+
+      switch (short_option) {
+      case 'l':
+        m_class_name = std::string(option_arg);
+        break;
+      case 'm':
+        m_module = std::string(option_arg);
+        break;
+      case 'n':
+        m_function = std::string(option_arg);
+        break;
+      case 'x':
+        m_regex = true;
+        break;
+      default:
+        error.SetErrorStringWithFormat("unrecognized option '%c'",
+                                       short_option);
+        break;
+      }
+
+      return error;
+    }
+
+    void OptionParsingStarting(ExecutionContext *execution_context) override {
+      m_module = "";
+      m_function = "";
+      m_class_name = "";
+      m_regex = false;
+    }
+
+    llvm::ArrayRef<OptionDefinition> GetDefinitions() override {
+      return llvm::makeArrayRef(g_frame_recognizer_add_options);
+    }
+
+    // Instance variables to hold the values for command options.
+    std::string m_class_name;
+    std::string m_module;
+    std::string m_function;
+    bool m_regex;
+  };
+
+  CommandOptions m_options;
+
+  Options *GetOptions() override { return &m_options; }
+
+protected:
+  bool DoExecute(Args &command, CommandReturnObject &result) override;
+
+public:
+  CommandObjectFrameRecognizerAdd(CommandInterpreter &interpreter)
+      : CommandObjectParsed(interpreter, "frame recognizer add",
+                            "Add a new frame recognizer.", nullptr),
+        m_options() {
+    SetHelpLong(R"(
+Frame recognizers allow retrieving information about special frames based on
+ABI, arguments or other special properties of that frame, even without source
+code or debug info. Currently, they can extract function arguments that would
+otherwise be unaccesible.
+
+Adding a custom frame recognizer is possible by implementing a Python class
+and using the 'frame recognizer add' command. The Python class should have a
+'get_recognized_arguments' method and it will receive an argument of type
+lldb.SBFrame representing the current frame that we are trying to recognize.
+The method should return a (possibly empty) list of lldb.SBValue objects that
+represent the recognized arguments.
+
+An example of a recognizer that retrieves the file descriptor values from libc
+functions 'read', 'write' and 'close' follows:
+
+  class LibcFdRecognizer(object):
+    def get_recognized_arguments(self, frame):
+      if frame.name in ["read", "write", "close"]:
+        fd = frame.EvaluateExpression("$arg1").unsigned
+        value = lldb.target.CreateValueFromExpression("fd", "(int)%d" % fd)
+        return [value]
+      return []
+
+The file containing this implementation can be imported via 'command script
+import' and then we can register this recognizer with 'frame recognizer add'.
+It's important to restrict the recognizer to the libc library (which is
+libsystem_kernel.dylib on macOS):
+
+(lldb) command script import .../fd_recognizer.py
+(lldb) frame recognizer add -l fd_recognizer.LibcFdRecognizer -n read -m libsystem_kernel.dylib
+
+When the program is stopped at the beginning of the 'read' function in libc, we
+can view the recognizer arguments in 'frame variable':
+
+(lldb) b read
+(lldb) r
+Process 1234 stopped
+* thread #1, queue = 'com.apple.main-thread', stop reason = breakpoint 1.3
+    frame #0: 0x00007fff06013ca0 libsystem_kernel.dylib`read
+(lldb) frame variable
+(int) fd = 3
+
+    )");
+  }
+  ~CommandObjectFrameRecognizerAdd() override = default;
+};
+
+bool CommandObjectFrameRecognizerAdd::DoExecute(Args &command,
+                                                CommandReturnObject &result) {
+  if (m_options.m_class_name.empty()) {
+    result.AppendErrorWithFormat(
+        "%s needs a Python class name (-l argument).\n", m_cmd_name.c_str());
+    result.SetStatus(eReturnStatusFailed);
+    return false;
+  }
+
+  if (m_options.m_module.empty()) {
+    result.AppendErrorWithFormat("%s needs a module name (-m argument).\n",
+                                 m_cmd_name.c_str());
+    result.SetStatus(eReturnStatusFailed);
+    return false;
+  }
+
+  if (m_options.m_function.empty()) {
+    result.AppendErrorWithFormat("%s needs a function name (-n argument).\n",
+                                 m_cmd_name.c_str());
+    result.SetStatus(eReturnStatusFailed);
+    return false;
+  }
+
+  ScriptInterpreter *interpreter = m_interpreter.GetScriptInterpreter();
+
+  if (interpreter &&
+      !interpreter->CheckObjectExists(m_options.m_class_name.c_str())) {
+    result.AppendWarning(
+        "The provided class does not exist - please define it "
+        "before attempting to use this frame recognizer");
+  }
+
+  StackFrameRecognizerSP recognizer_sp =
+      StackFrameRecognizerSP(new ScriptedStackFrameRecognizer(
+          interpreter, m_options.m_class_name.c_str()));
+  if (m_options.m_regex) {
+    auto module =
+        RegularExpressionSP(new RegularExpression(m_options.m_module));
+    auto func =
+        RegularExpressionSP(new RegularExpression(m_options.m_function));
+    StackFrameRecognizerManager::AddRecognizer(recognizer_sp, module, func);
+  } else {
+    auto module = ConstString(m_options.m_module);
+    auto func = ConstString(m_options.m_function);
+    StackFrameRecognizerManager::AddRecognizer(recognizer_sp, module, func);
+  }
+
+  result.SetStatus(eReturnStatusSuccessFinishNoResult);
+  return result.Succeeded();
+}
+
+class CommandObjectFrameRecognizerClear : public CommandObjectParsed {
+public:
+  CommandObjectFrameRecognizerClear(CommandInterpreter &interpreter)
+      : CommandObjectParsed(interpreter, "frame recognizer clear",
+                           "Delete all frame recognizers.", nullptr) {}
+
+  ~CommandObjectFrameRecognizerClear() override = default;
+
+protected:
+  bool DoExecute(Args &command, CommandReturnObject &result) override {
+    StackFrameRecognizerManager::RemoveAllRecognizers();
+    result.SetStatus(eReturnStatusSuccessFinishResult);
+    return result.Succeeded();
+  }
+};
+
+static OptionDefinition g_frame_recognizer_delete_options[] = {
+    // clang-format off
+  { LLDB_OPT_SET_2,   false, "python-class",  'l', OptionParser::eRequiredArgument, nullptr, nullptr, 0, eArgTypePythonClass, "Name of a Python class of a frame recognizer." },
+    // clang-format on
+};
+
+class CommandObjectFrameRecognizerDelete : public CommandObjectParsed {
+private:
+  class CommandOptions : public Options {
+  public:
+    CommandOptions() : Options() {}
+    ~CommandOptions() override = default;
+
+    Status SetOptionValue(uint32_t option_idx, llvm::StringRef option_arg,
+                          ExecutionContext *execution_context) override {
+      Status error;
+      const int short_option = m_getopt_table[option_idx].val;
+
+      switch (short_option) {
+      case 'l':
+        m_class_name = std::string(option_arg);
+        break;
+      default:
+        error.SetErrorStringWithFormat("unrecognized option '%c'",
+                                       short_option);
+        break;
+      }
+
+      return error;
+    }
+
+    void OptionParsingStarting(ExecutionContext *execution_context) override {
+      m_class_name = "";
+    }
+
+    llvm::ArrayRef<OptionDefinition> GetDefinitions() override {
+      return llvm::makeArrayRef(g_frame_recognizer_delete_options);
+    }
+
+    // Instance variables to hold the values for command options.
+    std::string m_class_name;
+  };
+
+  CommandOptions m_options;
+
+  Options *GetOptions() override { return &m_options; }
+
+public:
+  CommandObjectFrameRecognizerDelete(CommandInterpreter &interpreter)
+      : CommandObjectParsed(interpreter, "frame recognizer delete",
+                           "Delete an existing frame recognizer.", nullptr) {}
+
+  ~CommandObjectFrameRecognizerDelete() override = default;
+
+protected:
+  bool DoExecute(Args &command, CommandReturnObject &result) override {
+    if (m_options.m_class_name.empty()) {
+      result.AppendErrorWithFormat(
+          "%s needs a Python class name (-l argument).\n", m_cmd_name.c_str());
+      result.SetStatus(eReturnStatusFailed);
+      return false;
+    }
+
+    if (StackFrameRecognizerManager::Delete(m_options.m_class_name)) {
+      result.SetStatus(eReturnStatusSuccessFinishNoResult);
+      return result.Succeeded();
+    } else {
+      result.GetOutputStream().PutCString("no matching results found.\n");
+      result.SetStatus(eReturnStatusFailed);
+      return false;
+    }
+  }
+};
+
+class CommandObjectFrameRecognizerList : public CommandObjectParsed {
+public:
+  CommandObjectFrameRecognizerList(CommandInterpreter &interpreter)
+      : CommandObjectParsed(interpreter, "frame recognizer list",
+                           "Show a list of active frame recognizers.",
+                           nullptr) {}
+
+  ~CommandObjectFrameRecognizerList() override = default;
+
+protected:
+ bool DoExecute(Args &command, CommandReturnObject &result) override {
+   bool any_printed = false;
+   StackFrameRecognizerManager::ForEach(
+       [&result, &any_printed](std::string name, std::string function,
+                               std::string symbol, bool regexp) {
+         if (name == "") name = "(internal)";
+         result.GetOutputStream().Printf(
+             "%s: module %s, function %s%s\n", name.c_str(), function.c_str(),
+             symbol.c_str(), regexp ? " (regexp)" : "");
+         any_printed = true;
+       });
+
+   if (any_printed)
+     result.SetStatus(eReturnStatusSuccessFinishResult);
+   else {
+     result.GetOutputStream().PutCString("no matching results found.\n");
+     result.SetStatus(eReturnStatusSuccessFinishNoResult);
+   }
+   return result.Succeeded();
+ }
+};
+
+class CommandObjectFrameRecognizer : public CommandObjectMultiword {
+public:
+  CommandObjectFrameRecognizer(CommandInterpreter &interpreter)
+      : CommandObjectMultiword(
+            interpreter, "frame recognizer",
+            "Commands for editing frame recognizers.",
+            "frame recognizer [<sub-command-options>] ") {
+    LoadSubCommand(
+        "add",
+        CommandObjectSP(new CommandObjectFrameRecognizerAdd(interpreter)));
+    LoadSubCommand(
+        "clear",
+        CommandObjectSP(new CommandObjectFrameRecognizerClear(interpreter)));
+    LoadSubCommand(
+        "delete",
+        CommandObjectSP(new CommandObjectFrameRecognizerDelete(interpreter)));
+    LoadSubCommand(
+        "list",
+        CommandObjectSP(new CommandObjectFrameRecognizerList(interpreter)));
+  }
+
+  ~CommandObjectFrameRecognizer() override = default;
+};
+
 #pragma mark CommandObjectMultiwordFrame
 
 //-------------------------------------------------------------------------
 // CommandObjectMultiwordFrame
 //-------------------------------------------------------------------------
 
 CommandObjectMultiwordFrame::CommandObjectMultiwordFrame(
     CommandInterpreter &interpreter)
     : CommandObjectMultiword(interpreter, "frame", "Commands for selecting and "
                                                    "examing the current "
                                                    "thread's stack frames.",
                              "frame <subcommand> [<subcommand-options>]") {
   LoadSubCommand("diagnose",
                  CommandObjectSP(new CommandObjectFrameDiagnose(interpreter)));
   LoadSubCommand("info",
                  CommandObjectSP(new CommandObjectFrameInfo(interpreter)));
   LoadSubCommand("select",
                  CommandObjectSP(new CommandObjectFrameSelect(interpreter)));
   LoadSubCommand("variable",
                  CommandObjectSP(new CommandObjectFrameVariable(interpreter)));
+#ifndef LLDB_DISABLE_PYTHON
+  LoadSubCommand(
+      "recognizer",
+      CommandObjectSP(new CommandObjectFrameRecognizer(interpreter)));
+#endif
 }
 
 CommandObjectMultiwordFrame::~CommandObjectMultiwordFrame() = default;

source/Interpreter/OptionGroupVariable.cpp

 using namespace lldb_private;
 
 // if you add any options here, remember to update the counters in
 // OptionGroupVariable::GetNumDefinitions()
 static OptionDefinition g_variable_options[] = {
     {LLDB_OPT_SET_1 | LLDB_OPT_SET_2, false, "no-args", 'a',
      OptionParser::eNoArgument, nullptr, nullptr, 0, eArgTypeNone,
      "Omit function arguments."},
+    {LLDB_OPT_SET_1 | LLDB_OPT_SET_2, false, "no-recognized-args", 't',
+     OptionParser::eNoArgument, nullptr, nullptr, 0, eArgTypeNone,
+     "Omit recognized function arguments."},
     {LLDB_OPT_SET_1 | LLDB_OPT_SET_2, false, "no-locals", 'l',
      OptionParser::eNoArgument, nullptr, nullptr, 0, eArgTypeNone,
      "Omit local variables."},
     {LLDB_OPT_SET_1 | LLDB_OPT_SET_2, false, "show-globals", 'g',
      OptionParser::eNoArgument, nullptr, nullptr, 0, eArgTypeNone,
      "Show the current frame source file global and static variables."},
     {LLDB_OPT_SET_1 | LLDB_OPT_SET_2, false, "show-declaration", 'c',
      OptionParser::eNoArgument, nullptr, nullptr, 0, eArgTypeNone,
case 'g':
     show_globals = true;
     break;
   case 'c':
     show_decl = true;
     break;
   case 's':
     show_scope = true;
     break;
+  case 't':
+    show_recognized_args = false;
+    break;
   case 'y':
     error = summary.SetCurrentValue(option_arg);
     break;
   case 'z':
     error = summary_string.SetCurrentValue(option_arg);
     break;
   default:
     error.SetErrorStringWithFormat("unrecognized short option '%c'",
                                    short_option);
     break;
   }
 
   return error;
 }
 
 void OptionGroupVariable::OptionParsingStarting(
     ExecutionContext *execution_context) {
   show_args = true;     // Frame option only
+  show_recognized_args = true; // Frame option only
   show_locals = true;   // Frame option only
   show_globals = false; // Frame option only
   show_decl = false;
   use_regex = false;
   show_scope = false;
   summary.Clear();
   summary_string.Clear();
 }

source/Plugins/ScriptInterpreter/Python/ScriptInterpreterPython.h

#endif
   typedef bool (*SWIGPythonCallThreadPlan)(void *implementor,
                                            const char *method_name,
                                            Event *event_sp, bool &got_error);
 
   typedef void *(*SWIGPythonCreateOSPlugin)(const char *python_class_name,
                                             const char *session_dictionary_name,
                                             const lldb::ProcessSP &process_sp);
 
+  typedef void *(*SWIGPythonCreateFrameRecognizer)(
+      const char *python_class_name, const char *session_dictionary_name);
+
+  typedef void *(*SWIGPythonGetRecognizedArguments)(
+      void *implementor, const lldb::StackFrameSP &frame_sp);
+
   typedef size_t (*SWIGPythonCalculateNumChildren)(void *implementor,
                                                    uint32_t max);
 
   typedef void *(*SWIGPythonGetChildAtIndex)(void *implementor, uint32_t idx);
 
   typedef int (*SWIGPythonGetIndexOfChildWithName)(void *implementor,
                                                    const char *child_name);
 
#endif
   bool ScriptedThreadPlanIsStale(StructuredData::ObjectSP implementor_sp,
                                  bool &script_error) override;
 
   lldb::StateType
   ScriptedThreadPlanGetRunState(StructuredData::ObjectSP implementor_sp,
                                 bool &script_error) override;
 
   StructuredData::GenericSP
+  CreateFrameRecognizer(const char *class_name) override;
+
+  lldb::ValueObjectListSP
+  GetRecognizedArguments(const StructuredData::ObjectSP &implementor,
+                         lldb::StackFrameSP frame_sp) override;
+
+  StructuredData::GenericSP
   OSPlugin_CreatePluginObject(const char *class_name,
                               lldb::ProcessSP process_sp) override;
 
   StructuredData::DictionarySP
   OSPlugin_RegisterInfo(StructuredData::ObjectSP os_plugin_object_sp) override;
 
   StructuredData::ArraySP
   OSPlugin_ThreadsInfo(StructuredData::ObjectSP os_plugin_object_sp) override;
static void InitializeInterpreter(
       SWIGPythonUpdateSynthProviderInstance swig_update_provider,
       SWIGPythonMightHaveChildrenSynthProviderInstance
           swig_mighthavechildren_provider,
       SWIGPythonGetValueSynthProviderInstance swig_getvalue_provider,
       SWIGPythonCallCommand swig_call_command,
       SWIGPythonCallCommandObject swig_call_command_object,
       SWIGPythonCallModuleInit swig_call_module_init,
       SWIGPythonCreateOSPlugin swig_create_os_plugin,
+      SWIGPythonCreateFrameRecognizer swig_create_frame_recognizer,
+      SWIGPythonGetRecognizedArguments swig_get_recognized_arguments,
       SWIGPythonScriptKeyword_Process swig_run_script_keyword_process,
       SWIGPythonScriptKeyword_Thread swig_run_script_keyword_thread,
       SWIGPythonScriptKeyword_Target swig_run_script_keyword_target,
       SWIGPythonScriptKeyword_Frame swig_run_script_keyword_frame,
       SWIGPythonScriptKeyword_Value swig_run_script_keyword_value,
       SWIGPython_GetDynamicSetting swig_plugin_get,
       SWIGPythonCreateScriptedThreadPlan swig_thread_plan_script,
       SWIGPythonCallThreadPlan swig_call_thread_plan);

source/Plugins/ScriptInterpreter/Python/ScriptInterpreterPython.cpp

 
 #include <stdio.h>
 #include <stdlib.h>
 
 #include <mutex>
 #include <string>
 
 #include "lldb/API/SBValue.h"
+#include "lldb/API/SBFrame.h"
 #include "lldb/Breakpoint/BreakpointLocation.h"
 #include "lldb/Breakpoint/StoppointCallbackContext.h"
 #include "lldb/Breakpoint/WatchpointOptions.h"
 #include "lldb/Core/Communication.h"
 #include "lldb/Core/Debugger.h"
 #include "lldb/Core/PluginManager.h"
 #include "lldb/Core/ValueObject.h"
 #include "lldb/DataFormatters/TypeSummary.h"

 static ScriptInterpreterPython::SWIGPythonCallCommand g_swig_call_command =
     nullptr;
 static ScriptInterpreterPython::SWIGPythonCallCommandObject
     g_swig_call_command_object = nullptr;
 static ScriptInterpreterPython::SWIGPythonCallModuleInit
     g_swig_call_module_init = nullptr;
 static ScriptInterpreterPython::SWIGPythonCreateOSPlugin
     g_swig_create_os_plugin = nullptr;
+static ScriptInterpreterPython::SWIGPythonCreateFrameRecognizer
+    g_swig_create_frame_recognizer = nullptr;
+static ScriptInterpreterPython::SWIGPythonGetRecognizedArguments
+    g_swig_get_recognized_arguments = nullptr;
 static ScriptInterpreterPython::SWIGPythonScriptKeyword_Process
     g_swig_run_script_keyword_process = nullptr;
 static ScriptInterpreterPython::SWIGPythonScriptKeyword_Thread
     g_swig_run_script_keyword_thread = nullptr;
 static ScriptInterpreterPython::SWIGPythonScriptKeyword_Target
     g_swig_run_script_keyword_target = nullptr;
 static ScriptInterpreterPython::SWIGPythonScriptKeyword_Frame
     g_swig_run_script_keyword_frame = nullptr;
if (!ExportFunctionDefinitionToInterpreter(auto_generated_class).Success())
     return false;
 
   // Store the name of the auto-generated class
 
   output.assign(auto_generated_class_name);
   return true;
 }
 
+StructuredData::GenericSP ScriptInterpreterPython::CreateFrameRecognizer(
+    const char *class_name) {
+  if (class_name == nullptr || class_name[0] == '\0')
+    return StructuredData::GenericSP();
+
+  void *ret_val;
+
+  {
+    Locker py_lock(this, Locker::AcquireLock | Locker::NoSTDIN,
+                   Locker::FreeLock);
+    ret_val =
+        g_swig_create_frame_recognizer(class_name, m_dictionary_name.c_str());
+  }
+
+  return StructuredData::GenericSP(new StructuredPythonObject(ret_val));
+}
+
+lldb::ValueObjectListSP ScriptInterpreterPython::GetRecognizedArguments(
+    const StructuredData::ObjectSP &os_plugin_object_sp,
+    lldb::StackFrameSP frame_sp) {
+  Locker py_lock(this, Locker::AcquireLock | Locker::NoSTDIN, Locker::FreeLock);
+
+  static char callee_name[] = "get_recognized_arguments";
+
+  if (!os_plugin_object_sp) return ValueObjectListSP();
+
+  StructuredData::Generic *generic = os_plugin_object_sp->GetAsGeneric();
+  if (!generic) return nullptr;
+
+  PythonObject implementor(PyRefType::Borrowed,
+                           (PyObject *)generic->GetValue());
+
+  if (!implementor.IsAllocated()) return ValueObjectListSP();
+
+  PythonObject py_return(
+      PyRefType::Owned,
+      (PyObject *)g_swig_get_recognized_arguments(implementor.get(), frame_sp));
+
+  // if it fails, print the error but otherwise go on
+  if (PyErr_Occurred()) {
+    PyErr_Print();
+    PyErr_Clear();
+  }
+  if (py_return.get()) {
+    PythonList result_list(PyRefType::Borrowed, py_return.get());
+    ValueObjectListSP result = ValueObjectListSP(new ValueObjectList());
+    for (int i = 0; i < result_list.GetSize(); i++) {
+      PyObject *item = result_list.GetItemAtIndex(i).get();
+      lldb::SBValue *sb_value_ptr =
+          (lldb::SBValue *)g_swig_cast_to_sbvalue(item);
+      if (sb_value_ptr->IsValid()) result->Append(sb_value_ptr->GetSP());
+    }
+    return result;
+  }
+  return ValueObjectListSP();
+}
+
 StructuredData::GenericSP ScriptInterpreterPython::OSPlugin_CreatePluginObject(
     const char *class_name, lldb::ProcessSP process_sp) {
   if (class_name == nullptr || class_name[0] == '\0')
     return StructuredData::GenericSP();
 
   if (!process_sp)
     return StructuredData::GenericSP();
 
void ScriptInterpreterPython::InitializeInterpreter(
     SWIGPythonUpdateSynthProviderInstance swig_update_provider,
     SWIGPythonMightHaveChildrenSynthProviderInstance
         swig_mighthavechildren_provider,
     SWIGPythonGetValueSynthProviderInstance swig_getvalue_provider,
     SWIGPythonCallCommand swig_call_command,
     SWIGPythonCallCommandObject swig_call_command_object,
     SWIGPythonCallModuleInit swig_call_module_init,
     SWIGPythonCreateOSPlugin swig_create_os_plugin,
+    SWIGPythonCreateFrameRecognizer swig_create_frame_recognizer,
+    SWIGPythonGetRecognizedArguments swig_get_recognized_arguments,
     SWIGPythonScriptKeyword_Process swig_run_script_keyword_process,
     SWIGPythonScriptKeyword_Thread swig_run_script_keyword_thread,
     SWIGPythonScriptKeyword_Target swig_run_script_keyword_target,
     SWIGPythonScriptKeyword_Frame swig_run_script_keyword_frame,
     SWIGPythonScriptKeyword_Value swig_run_script_keyword_value,
     SWIGPython_GetDynamicSetting swig_plugin_get,
     SWIGPythonCreateScriptedThreadPlan swig_thread_plan_script,
     SWIGPythonCallThreadPlan swig_call_thread_plan) {
void ScriptInterpreterPython::InitializeInterpreter(
   g_swig_get_valobj_sp_from_sbvalue = swig_get_valobj_sp_from_sbvalue;
   g_swig_update_provider = swig_update_provider;
   g_swig_mighthavechildren_provider = swig_mighthavechildren_provider;
   g_swig_getvalue_provider = swig_getvalue_provider;
   g_swig_call_command = swig_call_command;
   g_swig_call_command_object = swig_call_command_object;
   g_swig_call_module_init = swig_call_module_init;
   g_swig_create_os_plugin = swig_create_os_plugin;
+  g_swig_create_frame_recognizer = swig_create_frame_recognizer;
+  g_swig_get_recognized_arguments = swig_get_recognized_arguments;
   g_swig_run_script_keyword_process = swig_run_script_keyword_process;
   g_swig_run_script_keyword_thread = swig_run_script_keyword_thread;
   g_swig_run_script_keyword_target = swig_run_script_keyword_target;
   g_swig_run_script_keyword_frame = swig_run_script_keyword_frame;
   g_swig_run_script_keyword_value = swig_run_script_keyword_value;
   g_swig_plugin_get = swig_plugin_get;
   g_swig_thread_plan_script = swig_thread_plan_script;
   g_swig_call_thread_plan = swig_call_thread_plan;

source/Target/CMakeLists.txt

add_lldb_library(lldbTarget
   QueueItem.cpp
   QueueList.cpp
   RegisterContext.cpp
   RegisterNumber.cpp
   SectionLoadHistory.cpp
   SectionLoadList.cpp
   StackFrame.cpp
   StackFrameList.cpp
+  StackFrameRecognizer.cpp
   StackID.cpp
   StopInfo.cpp
   StructuredDataPlugin.cpp
   SystemRuntime.cpp
   Target.cpp
   TargetList.cpp
   Thread.cpp
   ThreadCollection.cpp

source/Target/StackFrame.cpp

 #include "lldb/Symbol/Symbol.h"
 #include "lldb/Symbol/SymbolContextScope.h"
 #include "lldb/Symbol/Type.h"
 #include "lldb/Symbol/VariableList.h"
 #include "lldb/Target/ABI.h"
 #include "lldb/Target/ExecutionContext.h"
 #include "lldb/Target/Process.h"
 #include "lldb/Target/RegisterContext.h"
+#include "lldb/Target/StackFrameRecognizer.h"
 #include "lldb/Target/Target.h"
 #include "lldb/Target/Thread.h"
 
 using namespace lldb;
 using namespace lldb_private;
 
 // The first bits in the flags are reserved for the SymbolContext::Scope bits
 // so we know if we have tried to look up information in our internal symbol
StackFrame::StackFrame(const ThreadSP &thread_sp, user_id_t frame_idx,
                        bool stop_id_is_valid, bool is_history_frame,
                        const SymbolContext *sc_ptr)
     : m_thread_wp(thread_sp), m_frame_index(frame_idx),
       m_concrete_frame_index(unwind_frame_index), m_reg_context_sp(),
       m_id(pc, cfa, nullptr), m_frame_code_addr(pc), m_sc(), m_flags(),
       m_frame_base(), m_frame_base_error(), m_cfa_is_valid(cfa_is_valid),
       m_stop_id(stop_id), m_stop_id_is_valid(stop_id_is_valid),
       m_is_history_frame(is_history_frame), m_variable_list_sp(),
-      m_variable_list_value_objects(), m_disassembly(), m_mutex() {
+      m_variable_list_value_objects(), m_recognized_frame_sp(), m_disassembly(),
+      m_mutex() {
   // If we don't have a CFA value, use the frame index for our StackID so that
   // recursive functions properly aren't confused with one another on a history
   // stack.
   if (m_is_history_frame && !m_cfa_is_valid) {
     m_id.SetCFA(m_frame_index);
   }
 
   if (sc_ptr != nullptr) {
     m_sc = *sc_ptr;
     m_flags.Set(m_sc.GetResolvedMask());
   }
 }
 
 StackFrame::StackFrame(const ThreadSP &thread_sp, user_id_t frame_idx,
                        user_id_t unwind_frame_index,
                        const RegisterContextSP &reg_context_sp, addr_t cfa,
                        addr_t pc, const SymbolContext *sc_ptr)
     : m_thread_wp(thread_sp), m_frame_index(frame_idx),
       m_concrete_frame_index(unwind_frame_index),
       m_reg_context_sp(reg_context_sp), m_id(pc, cfa, nullptr),
       m_frame_code_addr(pc), m_sc(), m_flags(), m_frame_base(),
       m_frame_base_error(), m_cfa_is_valid(true), m_stop_id(0),
       m_stop_id_is_valid(false), m_is_history_frame(false),
-      m_variable_list_sp(), m_variable_list_value_objects(), m_disassembly(),
-      m_mutex() {
+      m_variable_list_sp(), m_variable_list_value_objects(),
+      m_recognized_frame_sp(), m_disassembly(), m_mutex() {
   if (sc_ptr != nullptr) {
     m_sc = *sc_ptr;
     m_flags.Set(m_sc.GetResolvedMask());
   }
 
   if (reg_context_sp && !m_sc.target_sp) {
     m_sc.target_sp = reg_context_sp->CalculateTarget();
     if (m_sc.target_sp)
       m_flags.Set(eSymbolContextTarget);
   }
 }
 
 StackFrame::StackFrame(const ThreadSP &thread_sp, user_id_t frame_idx,
                        user_id_t unwind_frame_index,
                        const RegisterContextSP &reg_context_sp, addr_t cfa,
                        const Address &pc_addr, const SymbolContext *sc_ptr)
     : m_thread_wp(thread_sp), m_frame_index(frame_idx),
       m_concrete_frame_index(unwind_frame_index),
       m_reg_context_sp(reg_context_sp),
       m_id(pc_addr.GetLoadAddress(thread_sp->CalculateTarget().get()), cfa,
            nullptr),
       m_frame_code_addr(pc_addr), m_sc(), m_flags(), m_frame_base(),
       m_frame_base_error(), m_cfa_is_valid(true), m_stop_id(0),
       m_stop_id_is_valid(false), m_is_history_frame(false),
-      m_variable_list_sp(), m_variable_list_value_objects(), m_disassembly(),
-      m_mutex() {
+      m_variable_list_sp(), m_variable_list_value_objects(),
+      m_recognized_frame_sp(), m_disassembly(), m_mutex() {
   if (sc_ptr != nullptr) {
     m_sc = *sc_ptr;
     m_flags.Set(m_sc.GetResolvedMask());
   }
 
   if (!m_sc.target_sp && reg_context_sp) {
     m_sc.target_sp = reg_context_sp->CalculateTarget();
     if (m_sc.target_sp)
if (target) {
           }
         }
         break;
       }
     }
   }
   return true;
 }
+
+RecognizedStackFrameSP StackFrame::GetRecognizedFrame() {
+  if (!m_recognized_frame_sp) {
+    m_recognized_frame_sp =
+        StackFrameRecognizerManager::RecognizeFrame(CalculateStackFrame());
+  }
+  return m_recognized_frame_sp;
+}

source/Target/StackFrameRecognizer.cpp

+//===-- StackFrameRecognizer.cpp --------------------------------*- C++ -*-===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+// C Includes
+// C++ Includes
+#include <vector>
+// Other libraries and framework includes
+// Project includes
+#include "lldb/Core/Module.h"
+#include "lldb/Interpreter/ScriptInterpreter.h"
+#include "lldb/Symbol/Symbol.h"
+#include "lldb/Target/StackFrame.h"
+#include "lldb/Target/StackFrameRecognizer.h"
+#include "lldb/Utility/RegularExpression.h"
+
+using namespace lldb;
+using namespace lldb_private;
+
+class ScriptedRecognizedStackFrame : public RecognizedStackFrame {
+public:
+  ScriptedRecognizedStackFrame(ValueObjectListSP args) {
+    m_arguments = args;
+  }
+};
+
+ScriptedStackFrameRecognizer::ScriptedStackFrameRecognizer(
+    ScriptInterpreter *interpreter, const char *pclass)
+    : m_interpreter(interpreter), m_python_class(pclass) {
+  m_python_object_sp =
+      m_interpreter->CreateFrameRecognizer(m_python_class.c_str());
+}
+
+RecognizedStackFrameSP
+ScriptedStackFrameRecognizer::RecognizeFrame(lldb::StackFrameSP frame) {
+  if (!m_python_object_sp || !m_interpreter)
+    return RecognizedStackFrameSP();
+
+  ValueObjectListSP args =
+      m_interpreter->GetRecognizedArguments(m_python_object_sp, frame);
+
+  return RecognizedStackFrameSP(new ScriptedRecognizedStackFrame(args));
+}
+
+class StackFrameRecognizerManagerImpl {
+public:
+  void AddRecognizer(StackFrameRecognizerSP recognizer, ConstString &module,
+                     ConstString &symbol, bool first_instruction_only) {
+    m_recognizers.push_front({recognizer, false, module, RegularExpressionSP(),
+                              symbol, RegularExpressionSP(),
+                              first_instruction_only});
+  }
+
+  void AddRecognizer(StackFrameRecognizerSP recognizer,
+                     RegularExpressionSP module, RegularExpressionSP symbol,
+                     bool first_instruction_only) {
+    m_recognizers.push_front({recognizer, true, ConstString(), module,
+                              ConstString(), symbol, first_instruction_only});
+  }
+
+  void ForEach(
+      std::function<void(std::string recognizer_name, std::string module,
+                         std::string symbol, bool regexp)> const &callback) {
+    for (auto entry : m_recognizers) {
+      if (entry.is_regexp) {
+        callback(entry.recognizer->GetName(), entry.module_regexp->GetText(),
+                 entry.symbol_regexp->GetText(), true);
+      } else {
+        callback(entry.recognizer->GetName(), entry.module.GetCString(),
+                 entry.symbol.GetCString(), false);
+      }
+    }
+  }
+
+  bool Delete(std::string recognizer_name) {
+    size_t previous_size = m_recognizers.size();
+    m_recognizers.erase(
+        std::remove_if(m_recognizers.begin(), m_recognizers.end(),
+                       [recognizer_name](RegisteredEntry entry) {
+                         return entry.recognizer->GetName() == recognizer_name;
+                       }),
+        m_recognizers.end());
+    return previous_size != m_recognizers.size();
+  }
+
+  void RemoveAllRecognizers() {
+    m_recognizers.clear();
+  }
+
+  RecognizedStackFrameSP RecognizeFrame(StackFrameSP frame) {
+    const SymbolContext &symctx =
+        frame->GetSymbolContext(eSymbolContextModule | eSymbolContextFunction);
+    ConstString function_name = symctx.GetFunctionName();
+    ConstString module_name = symctx.module_sp->GetFileSpec().GetFilename();
+    Address start_addr = symctx.symbol->GetAddress();
+    Address current_addr = frame->GetFrameCodeAddress();
+
+    for (auto entry : m_recognizers) {
+      if (entry.module)
+        if (entry.module != module_name)
+          continue;
+
+      if (entry.module_regexp)
+        if (!entry.module_regexp->Execute(module_name.GetStringRef()))
+          continue;
+
+      if (entry.symbol)
+        if (entry.symbol != function_name)
+          continue;
+
+      if (entry.symbol_regexp)
+        if (!entry.symbol_regexp->Execute(function_name.GetStringRef()))
+          continue;
+
+      if (entry.first_instruction_only)
+        if (start_addr != current_addr)
+          continue;
+
+      auto recognized_frame = entry.recognizer->RecognizeFrame(frame);
+      if (recognized_frame)
+        return recognized_frame;
+    }
+    return RecognizedStackFrameSP();
+  }
+
+private:
+  struct RegisteredEntry {
+    StackFrameRecognizerSP recognizer;
+    bool is_regexp;
+    ConstString module;
+    RegularExpressionSP module_regexp;
+    ConstString symbol;
+    RegularExpressionSP symbol_regexp;
+    bool first_instruction_only;
+  };
+
+  std::deque<RegisteredEntry> m_recognizers;
+};
+
+StackFrameRecognizerManagerImpl &GetStackFrameRecognizerManagerImpl() {
+  static StackFrameRecognizerManagerImpl instance =
+      StackFrameRecognizerManagerImpl();
+  return instance;
+}
+
+void StackFrameRecognizerManager::AddRecognizer(
+    StackFrameRecognizerSP recognizer, ConstString &module, ConstString &symbol,
+    bool first_instruction_only) {
+  GetStackFrameRecognizerManagerImpl().AddRecognizer(recognizer, module, symbol,
+                                                     first_instruction_only);
+}
+
+void StackFrameRecognizerManager::AddRecognizer(
+    StackFrameRecognizerSP recognizer, RegularExpressionSP module,
+    RegularExpressionSP symbol, bool first_instruction_only) {
+  GetStackFrameRecognizerManagerImpl().AddRecognizer(recognizer, module, symbol,
+                                                     first_instruction_only);
+}
+
+void StackFrameRecognizerManager::ForEach(
+    std::function<void(std::string recognizer_name, std::string module,
+                       std::string symbol, bool regexp)> const &callback) {
+  GetStackFrameRecognizerManagerImpl().ForEach(callback);
+}
+
+bool StackFrameRecognizerManager::Delete(std::string recognizer_name) {
+  return GetStackFrameRecognizerManagerImpl().Delete(recognizer_name);
+}
+
+void StackFrameRecognizerManager::RemoveAllRecognizers() {
+  GetStackFrameRecognizerManagerImpl().RemoveAllRecognizers();
+}
+
+RecognizedStackFrameSP
+StackFrameRecognizerManager::RecognizeFrame(StackFrameSP frame) {
+  return GetStackFrameRecognizerManagerImpl().RecognizeFrame(frame);
+}

www/python-reference.html

if process:
                         disassemble_instructions (insts)
                     else:
                         <font color=green># See if we have a symbol in the symbol table for where we stopped</font>
                         symbol = frame.GetSymbol();
                         if symbol:
                             <font color=green># We do have a symbol, print some info for the symbol</font>
                             print symbol
 </tt></pre></code>
-                </div>
-                <div class="postfooter"></div>
+            </div>
+            <div class="postfooter"></div>
+        </div>
 
-                </div>
-  </div>
+        <div class="post">
+            <h1 class ="postheader">Writing LLDB frame recognizers in Python</h1>
+            <div class="postcontent">
+
+                <p>Frame recognizers allow retrieving information about special frames based on
+                ABI, arguments or other special properties of that frame, even without source
+                code or debug info. Currently, they can extract function arguments that would
+                otherwise be unaccesible.</p>
+
+                <p>Adding a custom frame recognizer is possible by implementing a Python class
+                and using the '<b>frame recognizer add</b>' command. The Python class should have a
+                '<b>get_recognized_arguments</b>' method and it will receive an argument of type
+                <b>lldb.SBFrame</b> representing the current frame that we are trying to recognize.
+                The method should return a (possibly empty) list of <b>lldb.SBValue</b> objects that
+                represent the recognized arguments.</p>
+
+                <p>An example of a recognizer that retrieves the file descriptor values from libc
+                functions '<b>read</b>', '<b>write</b>' and '<b>close</b>' follows:</p>
+
+<code><pre><tt>  class LibcFdRecognizer(object):
+    def get_recognized_arguments(self, frame):
+      if frame.name in ["read", "write", "close"]:
+        fd = frame.EvaluateExpression("$arg1").unsigned
+        value = lldb.target.CreateValueFromExpression("fd", "(int)%d" % fd)
+        return [value]
+      return []
+</tt></pre></code>
+
+                <p>The file containing this implementation can be imported via '<b>command script
+                import</b>' and then we can register this recognizer with '<b>frame recognizer add</b>'.
+                It's important to restrict the recognizer to the libc library (which is
+                libsystem_kernel.dylib on macOS):</p>
+
+<code><pre><tt>(lldb) <b>command script import .../fd_recognizer.py</b>
+(lldb) <b>frame recognizer add -l fd_recognizer.LibcFdRecognizer -n read -m libsystem_kernel.dylib</b>
+</tt></pre></code>
+
+                <p>When the program is stopped at the beginning of the '<b>read</b>' function in libc, we
+                can view the recognizer arguments in '<b>frame variable</b>':</p>
+
+<code><pre><tt>(lldb) <b>b read</b>
+(lldb) <b>r</b>
+Process 1234 stopped
+* thread #1, queue = 'com.apple.main-thread', stop reason = breakpoint 1.3
+    frame #0: 0x00007fff06013ca0 libsystem_kernel.dylib`read
+(lldb) <b>frame variable</b>
+(int) fd = 3
+</tt></pre></code>
+
+            </div>
+            <div class="postfooter"></div>
+        </div>
+
+    </div>
 </div>
 </body>
 </html>