From 99f0b8f9351889901fbe7fd16104543bd4c1bbf1 Mon Sep 17 00:00:00 2001 From: Enrico Granata Date: Wed, 17 Aug 2011 01:30:04 +0000 Subject: [PATCH] When defining a scripted command, it is possible to provide a docstring and that will be used as the help text for the command If no docstring is provided, a default help text is created LLDB will refuse to create scripted commands if the scripting language is anything but Python Some additional comments in AppleObjCRuntimeV2.cpp to describe the memory layout expected by the dynamic type lookup code llvm-svn: 137801 --- lldb/include/lldb/Interpreter/CommandObject.h | 3 ++ .../lldb/Interpreter/ScriptInterpreter.h | 6 +++ .../Interpreter/ScriptInterpreterPython.h | 3 ++ .../source/Commands/CommandObjectCommands.cpp | 17 +++++++ lldb/source/Interpreter/CommandObject.cpp | 6 +++ .../Interpreter/ScriptInterpreterPython.cpp | 24 +++++++++- .../AppleObjCRuntime/AppleObjCRuntimeV2.cpp | 48 ++++++++++++++++--- .../test/functionalities/alias/TestAliases.py | 4 ++ lldb/test/functionalities/alias/welcome.py | 4 ++ 9 files changed, 107 insertions(+), 8 deletions(-) diff --git a/lldb/include/lldb/Interpreter/CommandObject.h b/lldb/include/lldb/Interpreter/CommandObject.h index 525fc454eefc..f389ab875daf 100644 --- a/lldb/include/lldb/Interpreter/CommandObject.h +++ b/lldb/include/lldb/Interpreter/CommandObject.h @@ -111,6 +111,9 @@ public: void SetHelpLong (const char * str); + void + SetHelpLong (std::string str); + void SetSyntax (const char *str); diff --git a/lldb/include/lldb/Interpreter/ScriptInterpreter.h b/lldb/include/lldb/Interpreter/ScriptInterpreter.h index a2e620d6f611..4d494f732c9a 100644 --- a/lldb/include/lldb/Interpreter/ScriptInterpreter.h +++ b/lldb/include/lldb/Interpreter/ScriptInterpreter.h @@ -191,6 +191,12 @@ public: { return false; } + + virtual std::string + GetDocumentationForItem(const char* item) + { + return std::string(""); + } const char * GetScriptInterpreterPtyName (); diff --git a/lldb/include/lldb/Interpreter/ScriptInterpreterPython.h b/lldb/include/lldb/Interpreter/ScriptInterpreterPython.h index feb65eb98be1..8e5033b3c417 100644 --- a/lldb/include/lldb/Interpreter/ScriptInterpreterPython.h +++ b/lldb/include/lldb/Interpreter/ScriptInterpreterPython.h @@ -109,6 +109,9 @@ public: static std::string CallPythonScriptFunction (const char *python_function_name, lldb::ValueObjectSP valobj); + + virtual std::string + GetDocumentationForItem(const char* item); void CollectDataForBreakpointCommandCallback (BreakpointOptions *bp_options, diff --git a/lldb/source/Commands/CommandObjectCommands.cpp b/lldb/source/Commands/CommandObjectCommands.cpp index 6c12126d4f5e..d722d1d17e1a 100644 --- a/lldb/source/Commands/CommandObjectCommands.cpp +++ b/lldb/source/Commands/CommandObjectCommands.cpp @@ -24,6 +24,8 @@ #include "lldb/Interpreter/CommandObjectRegexCommand.h" #include "lldb/Interpreter/CommandReturnObject.h" #include "lldb/Interpreter/Options.h" +#include "lldb/Interpreter/ScriptInterpreter.h" +#include "lldb/Interpreter/ScriptInterpreterPython.h" using namespace lldb; using namespace lldb_private; @@ -1155,6 +1157,13 @@ public: NULL), m_function_name(funct) { + ScriptInterpreter* scripter = m_interpreter.GetScriptInterpreter(); + if (scripter) + { + std::string docstring = scripter->GetDocumentationForItem(funct.c_str()); + if (!docstring.empty()) + SetHelpLong(docstring); + } } virtual @@ -1427,6 +1436,14 @@ public: CommandReturnObject &result ) { + + if (m_interpreter.GetDebugger().GetScriptLanguage() != lldb::eScriptLanguagePython) + { + result.AppendError ("only scripting language supported for scripted commands is currently Python"); + result.SetStatus (eReturnStatusFailed); + return false; + } + size_t argc = args.GetArgumentCount(); if (argc != 1) diff --git a/lldb/source/Interpreter/CommandObject.cpp b/lldb/source/Interpreter/CommandObject.cpp index 635d9a588386..1607d8e11c28 100644 --- a/lldb/source/Interpreter/CommandObject.cpp +++ b/lldb/source/Interpreter/CommandObject.cpp @@ -128,6 +128,12 @@ CommandObject::SetHelpLong (const char *cstr) m_cmd_help_long = cstr; } +void +CommandObject::SetHelpLong (std::string str) +{ + m_cmd_help_long = str; +} + void CommandObject::SetSyntax (const char *cstr) { diff --git a/lldb/source/Interpreter/ScriptInterpreterPython.cpp b/lldb/source/Interpreter/ScriptInterpreterPython.cpp index 4db56d4ac230..e84cd6995497 100644 --- a/lldb/source/Interpreter/ScriptInterpreterPython.cpp +++ b/lldb/source/Interpreter/ScriptInterpreterPython.cpp @@ -763,13 +763,13 @@ ScriptInterpreterPython::ExecuteOneLineWithReturn (const char *in_string, case eCharPtr: // "char *" { const char format[3] = "s#"; - success = PyArg_Parse (py_return, format, (char **) &ret_value); + success = PyArg_Parse (py_return, format, (char **) ret_value); break; } case eCharStrOrNone: // char* or NULL if py_return == Py_None { const char format[3] = "z"; - success = PyArg_Parse (py_return, format, (char **) &ret_value); + success = PyArg_Parse (py_return, format, (char **) ret_value); break; } case eBool: @@ -1972,6 +1972,26 @@ ScriptInterpreterPython::RunScriptBasedCommand(const char* impl_function, } +// in Python, a special attribute __doc__ contains the docstring +// for an object (function, method, class, ...) if any is defined +// Otherwise, the attribute's value is None +std::string +ScriptInterpreterPython::GetDocumentationForItem(const char* item) +{ + std::string command(item); + command += ".__doc__"; + + char* result_ptr = NULL; // Python is going to point this to valid data if ExecuteOneLineWithReturn returns successfully + + if (ExecuteOneLineWithReturn (command.c_str(), + ScriptInterpreter::eCharStrOrNone, + &result_ptr) && result_ptr) + { + return std::string(result_ptr); + } + else + return std::string(""); +} void ScriptInterpreterPython::InitializeInterpreter (SWIGInitCallback python_swig_init_callback, diff --git a/lldb/source/Plugins/LanguageRuntime/ObjC/AppleObjCRuntime/AppleObjCRuntimeV2.cpp b/lldb/source/Plugins/LanguageRuntime/ObjC/AppleObjCRuntime/AppleObjCRuntimeV2.cpp index f80015f977b4..75a0a6a085ee 100644 --- a/lldb/source/Plugins/LanguageRuntime/ObjC/AppleObjCRuntime/AppleObjCRuntimeV2.cpp +++ b/lldb/source/Plugins/LanguageRuntime/ObjC/AppleObjCRuntime/AppleObjCRuntimeV2.cpp @@ -568,9 +568,9 @@ AppleObjCRuntimeV2::GetByteOffsetForIvar (ClangASTType &parent_ast_type, const c // tagged pointers are marked by having their least-significant bit // set. this makes them "invalid" as pointers because they violate -// the alignment requirements. this way, we can always know when -// we are dealing with a tagged pointer, and use the lookup approach -// that the runtime would +// the alignment requirements. of course, this detection algorithm +// is not accurate (it might become better by incorporating further +// knowledge about the internals of tagged pointers) bool AppleObjCRuntimeV2::IsTaggedPointer(lldb::addr_t ptr) { @@ -578,6 +578,9 @@ AppleObjCRuntimeV2::IsTaggedPointer(lldb::addr_t ptr) } +// this code relies on the assumption that an Objective-C object always starts +// with an ISA at offset 0. an ISA is effectively a pointer to an instance of +// struct class_t in the ObjCv2 runtime lldb_private::ObjCLanguageRuntime::ObjCISA AppleObjCRuntimeV2::GetISA(ValueObject& valobj) { @@ -587,8 +590,8 @@ AppleObjCRuntimeV2::GetISA(ValueObject& valobj) { // when using the expression parser, an additional layer of "frozen data" // can be created, which is basically a byte-exact copy of the data returned - // by the expression, but in host memory. because Python code might need to read - // into the object memory in non-obvious ways, we need to hand it the target version + // by the expression, but in host memory. because this code reads memory without + // taking the debug-info-provided object layout, we need to hand it the target version // of the expression output lldb::addr_t tgt_address = valobj.GetValueAsUnsigned(); ValueObjectSP target_object = ValueObjectConstResult::Create (valobj.GetExecutionContextScope(), @@ -647,9 +650,20 @@ AppleObjCRuntimeV2::GetActualTypeName(lldb_private::ObjCLanguageRuntime::ObjCISA uint8_t pointer_size = m_process->GetAddressByteSize(); Error error; + + /* + struct class_t *isa; + struct class_t *superclass; + Cache cache; + IMP *vtable; +--> uintptr_t data_NEVER_USE; + WARNING: this data_NEVER_USE pointer might one day contain flags in the least-significant bits + currently, rdar://problem/8955342 prevents the runtime from doing so + it presently is just a pointer to a class_rw_t + */ + lldb::addr_t rw_pointer = isa + (4 * pointer_size); //printf("rw_pointer: %llx\n", rw_pointer); - uint64_t data_pointer = m_process->ReadUnsignedIntegerFromMemory(rw_pointer, pointer_size, 0, @@ -657,6 +671,12 @@ AppleObjCRuntimeV2::GetActualTypeName(lldb_private::ObjCLanguageRuntime::ObjCISA if (error.Fail()) return ConstString("unknown"); + /* + uint32_t flags; + uint32_t version; + +--> const class_ro_t *ro; + */ data_pointer += 8; //printf("data_pointer: %llx\n", data_pointer); uint64_t ro_pointer = m_process->ReadUnsignedIntegerFromMemory(data_pointer, @@ -666,6 +686,18 @@ AppleObjCRuntimeV2::GetActualTypeName(lldb_private::ObjCLanguageRuntime::ObjCISA if (error.Fail()) return ConstString("unknown"); + /* + uint32_t flags; + uint32_t instanceStart; + uint32_t instanceSize; + #ifdef __LP64__ + uint32_t reserved; + #endif + + const uint8_t * ivarLayout; + +--> const char * name; + */ ro_pointer += 12; if (pointer_size == 8) ro_pointer += 4; @@ -722,6 +754,10 @@ AppleObjCRuntimeV2::GetParentClass(lldb_private::ObjCLanguageRuntime::ObjCISA is uint8_t pointer_size = m_process->GetAddressByteSize(); Error error; + /* + struct class_t *isa; +--> struct class_t *superclass; + */ lldb::addr_t parent_pointer = isa + pointer_size; //printf("rw_pointer: %llx\n", rw_pointer); diff --git a/lldb/test/functionalities/alias/TestAliases.py b/lldb/test/functionalities/alias/TestAliases.py index 4f43136f24d5..bfcafa38fac9 100644 --- a/lldb/test/functionalities/alias/TestAliases.py +++ b/lldb/test/functionalities/alias/TestAliases.py @@ -134,6 +134,10 @@ class AliasTestCase(TestBase): self.expect('welcome Enrico', substrs = ['Hello Enrico, welcome to LLDB']); + + self.expect("help welcome", + substrs = ['Just a docstring for welcome_impl', + 'A command that says hello to LLDB users']) self.runCmd("command script delete welcome"); diff --git a/lldb/test/functionalities/alias/welcome.py b/lldb/test/functionalities/alias/welcome.py index db90e89ee4e0..3b63c702327d 100644 --- a/lldb/test/functionalities/alias/welcome.py +++ b/lldb/test/functionalities/alias/welcome.py @@ -1,6 +1,10 @@ import sys def welcome_impl(debugger, args, result, dict): + """ + Just a docstring for welcome_impl + A command that says hello to LLDB users + """ result.Printf('Hello ' + args + ', welcome to LLDB'); return None;