diff options
Diffstat (limited to 'include/lldb/Expression')
| -rw-r--r-- | include/lldb/Expression/DWARFExpression.h | 81 | ||||
| -rw-r--r-- | include/lldb/Expression/Expression.h | 29 | ||||
| -rw-r--r-- | include/lldb/Expression/ExpressionParser.h | 16 | ||||
| -rw-r--r-- | include/lldb/Expression/ExpressionSourceCode.h | 5 | ||||
| -rw-r--r-- | include/lldb/Expression/ExpressionTypeSystemHelper.h | 6 | ||||
| -rw-r--r-- | include/lldb/Expression/ExpressionVariable.h | 24 | ||||
| -rw-r--r-- | include/lldb/Expression/FunctionCaller.h | 27 | ||||
| -rw-r--r-- | include/lldb/Expression/IRDynamicChecks.h | 33 | ||||
| -rw-r--r-- | include/lldb/Expression/IRExecutionUnit.h | 62 | ||||
| -rw-r--r-- | include/lldb/Expression/IRInterpreter.h | 8 | ||||
| -rw-r--r-- | include/lldb/Expression/IRMemoryMap.h | 22 | ||||
| -rw-r--r-- | include/lldb/Expression/LLVMUserExpression.h | 23 | ||||
| -rw-r--r-- | include/lldb/Expression/UserExpression.h | 27 | ||||
| -rw-r--r-- | include/lldb/Expression/UtilityFunction.h | 37 |
14 files changed, 193 insertions, 207 deletions
diff --git a/include/lldb/Expression/DWARFExpression.h b/include/lldb/Expression/DWARFExpression.h index c85aaa5c1f9a8..b4bd9697da58a 100644 --- a/include/lldb/Expression/DWARFExpression.h +++ b/include/lldb/Expression/DWARFExpression.h @@ -18,22 +18,22 @@ #include "lldb/lldb-private.h" #include <functional> -class DWARFCompileUnit; +class DWARFUnit; namespace lldb_private { //---------------------------------------------------------------------- -/// @class DWARFExpression DWARFExpression.h "lldb/Expression/DWARFExpression.h" -/// @brief Encapsulates a DWARF location expression and interprets it. +/// @class DWARFExpression DWARFExpression.h +/// "lldb/Expression/DWARFExpression.h" Encapsulates a DWARF location +/// expression and interprets it. /// /// DWARF location expressions are used in two ways by LLDB. The first -/// use is to find entities specified in the debug information, since -/// their locations are specified in precisely this language. The second -/// is to interpret expressions without having to run the target in cases -/// where the overhead from copying JIT-compiled code into the target is -/// too high or where the target cannot be run. This class encapsulates -/// a single DWARF location expression or a location list and interprets -/// it. +/// use is to find entities specified in the debug information, since their +/// locations are specified in precisely this language. The second is to +/// interpret expressions without having to run the target in cases where the +/// overhead from copying JIT-compiled code into the target is too high or +/// where the target cannot be run. This class encapsulates a single DWARF +/// location expression or a location list and interprets it. //---------------------------------------------------------------------- class DWARFExpression { public: @@ -46,7 +46,7 @@ public: //------------------------------------------------------------------ /// Constructor //------------------------------------------------------------------ - explicit DWARFExpression(DWARFCompileUnit *dwarf_cu); + explicit DWARFExpression(DWARFUnit *dwarf_cu); //------------------------------------------------------------------ /// Constructor @@ -62,7 +62,7 @@ public: /// The byte length of the location expression. //------------------------------------------------------------------ DWARFExpression(lldb::ModuleSP module, const DataExtractor &data, - DWARFCompileUnit *dwarf_cu, lldb::offset_t data_offset, + DWARFUnit *dwarf_cu, lldb::offset_t data_offset, lldb::offset_t data_length); //------------------------------------------------------------------ @@ -130,12 +130,12 @@ public: //------------------------------------------------------------------ /// If a location is not a location list, return true if the location - /// contains a DW_OP_addr () opcode in the stream that matches \a - /// file_addr. If file_addr is LLDB_INVALID_ADDRESS, the this - /// function will return true if the variable there is any DW_OP_addr - /// in a location that (yet still is NOT a location list). This helps - /// us detect if a variable is a global or static variable since - /// there is no other indication from DWARF debug info. + /// contains a DW_OP_addr () opcode in the stream that matches \a file_addr. + /// If file_addr is LLDB_INVALID_ADDRESS, the this function will return true + /// if the variable there is any DW_OP_addr in a location that (yet still is + /// NOT a location list). This helps us detect if a variable is a global or + /// static variable since there is no other indication from DWARF debug + /// info. /// /// @param[in] op_addr_idx /// The DW_OP_addr index to retrieve in case there is more than @@ -161,8 +161,8 @@ public: &link_address_callback); //------------------------------------------------------------------ - /// Make the expression parser read its location information from a - /// given data source. Does not change the offset and length + /// Make the expression parser read its location information from a given + /// data source. Does not change the offset and length /// /// @param[in] data /// A data extractor configured to read the DWARF location expression's @@ -171,8 +171,8 @@ public: void SetOpcodeData(const DataExtractor &data); //------------------------------------------------------------------ - /// Make the expression parser read its location information from a - /// given data source + /// Make the expression parser read its location information from a given + /// data source /// /// @param[in] module_sp /// The module that defines the DWARF expression. @@ -193,16 +193,15 @@ public: //------------------------------------------------------------------ /// Copy the DWARF location expression into a local buffer. /// - /// It is a good idea to copy the data so we don't keep the entire - /// object file worth of data around just for a few bytes of location - /// expression. LLDB typically will mmap the entire contents of debug - /// information files, and if we use SetOpcodeData, it will get a - /// shared reference to all of this data for the and cause the object - /// file to have to stay around. Even worse, a very very large ".a" - /// that contains one or more .o files could end up being referenced. - /// Location lists are typically small so even though we are copying - /// the data, it shouldn't amount to that much for the variables we - /// end up parsing. + /// It is a good idea to copy the data so we don't keep the entire object + /// file worth of data around just for a few bytes of location expression. + /// LLDB typically will mmap the entire contents of debug information files, + /// and if we use SetOpcodeData, it will get a shared reference to all of + /// this data for the and cause the object file to have to stay around. Even + /// worse, a very very large ".a" that contains one or more .o files could + /// end up being referenced. Location lists are typically small so even + /// though we are copying the data, it shouldn't amount to that much for the + /// variables we end up parsing. /// /// @param[in] module_sp /// The module that defines the DWARF expression. @@ -254,8 +253,8 @@ public: //------------------------------------------------------------------ /// Wrapper for the static evaluate function that accepts an - /// ExecutionContextScope instead of an ExecutionContext and uses - /// member variables to populate many operands + /// ExecutionContextScope instead of an ExecutionContext and uses member + /// variables to populate many operands //------------------------------------------------------------------ bool Evaluate(ExecutionContextScope *exe_scope, lldb::addr_t loclist_base_load_addr, @@ -263,8 +262,8 @@ public: Value &result, Status *error_ptr) const; //------------------------------------------------------------------ - /// Wrapper for the static evaluate function that uses member - /// variables to populate many operands + /// Wrapper for the static evaluate function that uses member variables to + /// populate many operands //------------------------------------------------------------------ bool Evaluate(ExecutionContext *exe_ctx, RegisterContext *reg_ctx, lldb::addr_t loclist_base_load_addr, @@ -332,7 +331,7 @@ public: //------------------------------------------------------------------ static bool Evaluate(ExecutionContext *exe_ctx, RegisterContext *reg_ctx, lldb::ModuleSP opcode_ctx, const DataExtractor &opcodes, - DWARFCompileUnit *dwarf_cu, const lldb::offset_t offset, + DWARFUnit *dwarf_cu, const lldb::offset_t offset, const lldb::offset_t length, const lldb::RegisterKind reg_set, const Value *initial_value_ptr, @@ -348,7 +347,7 @@ public: lldb::addr_t loclist_base_load_addr, lldb::addr_t address, ABI *abi); - static size_t LocationListSize(const DWARFCompileUnit *dwarf_cu, + static size_t LocationListSize(const DWARFUnit *dwarf_cu, const DataExtractor &debug_loc_data, lldb::offset_t offset); @@ -356,7 +355,7 @@ public: int address_size, int dwarf_ref_size, bool location_expression); - static void PrintDWARFLocationList(Stream &s, const DWARFCompileUnit *cu, + static void PrintDWARFLocationList(Stream &s, const DWARFUnit *cu, const DataExtractor &debug_loc_data, lldb::offset_t offset); @@ -389,7 +388,7 @@ protected: lldb::offset_t &offset, lldb::offset_t &len); static bool AddressRangeForLocationListEntry( - const DWARFCompileUnit *dwarf_cu, const DataExtractor &debug_loc_data, + const DWARFUnit *dwarf_cu, const DataExtractor &debug_loc_data, lldb::offset_t *offset_ptr, lldb::addr_t &low_pc, lldb::addr_t &high_pc); bool GetOpAndEndOffsets(StackFrame &frame, lldb::offset_t &op_offset, @@ -401,7 +400,7 @@ protected: lldb::ModuleWP m_module_wp; ///< Module which defined this expression. DataExtractor m_data; ///< A data extractor capable of reading opcode bytes - DWARFCompileUnit *m_dwarf_cu; ///< The DWARF compile unit this expression + DWARFUnit *m_dwarf_cu; ///< The DWARF compile unit this expression ///belongs to. It is used ///< to evaluate values indexing into the .debug_addr section (e.g. ///< DW_OP_GNU_addr_index, DW_OP_GNU_const_index) diff --git a/include/lldb/Expression/Expression.h b/include/lldb/Expression/Expression.h index 860444e9c2c2e..6b9363864722e 100644 --- a/include/lldb/Expression/Expression.h +++ b/include/lldb/Expression/Expression.h @@ -28,14 +28,14 @@ namespace lldb_private { class RecordingMemoryManager; //---------------------------------------------------------------------- -/// @class Expression Expression.h "lldb/Expression/Expression.h" -/// @brief Encapsulates a single expression for use in lldb +/// @class Expression Expression.h "lldb/Expression/Expression.h" Encapsulates +/// a single expression for use in lldb /// /// LLDB uses expressions for various purposes, notably to call functions -/// and as a backend for the expr command. Expression encapsulates -/// the objects needed to parse and interpret or JIT an expression. It -/// uses the expression parser appropriate to the language of the expression -/// to produce LLVM IR from the expression. +/// and as a backend for the expr command. Expression encapsulates the +/// objects needed to parse and interpret or JIT an expression. It uses the +/// expression parser appropriate to the language of the expression to produce +/// LLVM IR from the expression. //---------------------------------------------------------------------- class Expression { public: @@ -58,20 +58,19 @@ public: //------------------------------------------------------------------ /// Return the function name that should be used for executing the - /// expression. Text() should contain the definition of this - /// function. + /// expression. Text() should contain the definition of this function. //------------------------------------------------------------------ virtual const char *FunctionName() = 0; //------------------------------------------------------------------ - /// Return the language that should be used when parsing. To use - /// the default, return eLanguageTypeUnknown. + /// Return the language that should be used when parsing. To use the + /// default, return eLanguageTypeUnknown. //------------------------------------------------------------------ virtual lldb::LanguageType Language() { return lldb::eLanguageTypeUnknown; } //------------------------------------------------------------------ - /// Return the desired result type of the function, or - /// eResultTypeAny if indifferent. + /// Return the desired result type of the function, or eResultTypeAny if + /// indifferent. //------------------------------------------------------------------ virtual ResultType DesiredResultType() { return eResultTypeAny; } @@ -80,14 +79,12 @@ public: //------------------------------------------------------------------ //------------------------------------------------------------------ - /// Return true if validation code should be inserted into the - /// expression. + /// Return true if validation code should be inserted into the expression. //------------------------------------------------------------------ virtual bool NeedsValidation() = 0; //------------------------------------------------------------------ - /// Return true if external variables in the expression should be - /// resolved. + /// Return true if external variables in the expression should be resolved. //------------------------------------------------------------------ virtual bool NeedsVariableResolution() = 0; diff --git a/include/lldb/Expression/ExpressionParser.h b/include/lldb/Expression/ExpressionParser.h index a550d576f4376..66957926650a0 100644 --- a/include/lldb/Expression/ExpressionParser.h +++ b/include/lldb/Expression/ExpressionParser.h @@ -20,8 +20,8 @@ class IRExecutionUnit; //---------------------------------------------------------------------- /// @class ExpressionParser ExpressionParser.h -/// "lldb/Expression/ExpressionParser.h" -/// @brief Encapsulates an instance of a compiler that can parse expressions. +/// "lldb/Expression/ExpressionParser.h" Encapsulates an instance of a +/// compiler that can parse expressions. /// /// ExpressionParser is the base class for llvm based Expression parsers. //---------------------------------------------------------------------- @@ -50,8 +50,8 @@ public: virtual ~ExpressionParser(){}; //------------------------------------------------------------------ - /// Parse a single expression and convert it to IR using Clang. Don't - /// wrap the expression in anything at all. + /// Parse a single expression and convert it to IR using Clang. Don't wrap + /// the expression in anything at all. /// /// @param[in] diagnostic_manager /// The diagnostic manager in which to store the errors and warnings. @@ -64,8 +64,8 @@ public: //------------------------------------------------------------------ /// Try to use the FixIts in the diagnostic_manager to rewrite the - /// expression. If successful, the rewritten expression is stored - /// in the diagnostic_manager, get it out with GetFixedExpression. + /// expression. If successful, the rewritten expression is stored in the + /// diagnostic_manager, get it out with GetFixedExpression. /// /// @param[in] diagnostic_manager /// The diagnostic manager containing fixit's to apply. @@ -78,8 +78,8 @@ public: } //------------------------------------------------------------------ - /// Ready an already-parsed expression for execution, possibly - /// evaluating it statically. + /// Ready an already-parsed expression for execution, possibly evaluating it + /// statically. /// /// @param[out] func_addr /// The address to which the function has been written. diff --git a/include/lldb/Expression/ExpressionSourceCode.h b/include/lldb/Expression/ExpressionSourceCode.h index 02fc72aaf2515..b5a6187bf3c5f 100644 --- a/include/lldb/Expression/ExpressionSourceCode.h +++ b/include/lldb/Expression/ExpressionSourceCode.h @@ -40,9 +40,8 @@ public: bool static_method, ExecutionContext &exe_ctx) const; // Given a string returned by GetText, find the beginning and end of the body - // passed to CreateWrapped. - // Return true if the bounds could be found. This will also work on text with - // FixItHints applied. + // passed to CreateWrapped. Return true if the bounds could be found. This + // will also work on text with FixItHints applied. static bool GetOriginalBodyBounds(std::string transformed_text, lldb::LanguageType wrapping_language, size_t &start_loc, size_t &end_loc); diff --git a/include/lldb/Expression/ExpressionTypeSystemHelper.h b/include/lldb/Expression/ExpressionTypeSystemHelper.h index 20a5e67cf9b7f..ffcad54fb9f9b 100644 --- a/include/lldb/Expression/ExpressionTypeSystemHelper.h +++ b/include/lldb/Expression/ExpressionTypeSystemHelper.h @@ -18,11 +18,11 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class ExpressionTypeSystemHelper ExpressionTypeSystemHelper.h /// "lldb/Expression/ExpressionTypeSystemHelper.h" -/// @brief A helper object that the Expression can pass to its ExpressionParser +/// A helper object that the Expression can pass to its ExpressionParser /// to provide generic information that /// any type of expression will need to supply. It's only job is to support -/// dyn_cast so that the expression parser -/// can cast it back to the requisite specific type. +/// dyn_cast so that the expression parser can cast it back to the requisite +/// specific type. /// //---------------------------------------------------------------------- diff --git a/include/lldb/Expression/ExpressionVariable.h b/include/lldb/Expression/ExpressionVariable.h index c7570932c15ab..89b0500faf9cc 100644 --- a/include/lldb/Expression/ExpressionVariable.h +++ b/include/lldb/Expression/ExpressionVariable.h @@ -69,15 +69,12 @@ public: void SetName(const ConstString &name) { m_frozen_sp->SetName(name); } // this function is used to copy the address-of m_live_sp into m_frozen_sp - // this is necessary because the results of certain cast and - // pointer-arithmetic - // operations (such as those described in bugzilla issues 11588 and 11618) - // generate - // frozen objects that do not have a valid address-of, which can be - // troublesome when - // using synthetic children providers. Transferring the address-of the live - // object - // solves these issues and provides the expected user-level behavior + // this is necessary because the results of certain cast and pointer- + // arithmetic operations (such as those described in bugzilla issues 11588 + // and 11618) generate frozen objects that do not have a valid address-of, + // which can be troublesome when using synthetic children providers. + // Transferring the address-of the live object solves these issues and + // provides the expected user-level behavior void TransferAddress(bool force = false) { if (m_live_sp.get() == nullptr) return; @@ -129,7 +126,7 @@ public: //---------------------------------------------------------------------- /// @class ExpressionVariableList ExpressionVariable.h /// "lldb/Expression/ExpressionVariable.h" -/// @brief A list of variable references. +/// A list of variable references. /// /// This class stores variables internally, acting as the permanent store. //---------------------------------------------------------------------- @@ -242,7 +239,12 @@ public: lldb::ByteOrder byte_order, uint32_t addr_byte_size) = 0; - virtual ConstString GetNextPersistentVariableName() = 0; + /// Return a new persistent variable name with the specified prefix. + ConstString GetNextPersistentVariableName(Target &target, + llvm::StringRef prefix); + + virtual llvm::StringRef + GetPersistentVariablePrefix(bool is_error = false) const = 0; virtual void RemovePersistentVariable(lldb::ExpressionVariableSP variable) = 0; diff --git a/include/lldb/Expression/FunctionCaller.h b/include/lldb/Expression/FunctionCaller.h index 56305d5181bd5..c36263e342406 100644 --- a/include/lldb/Expression/FunctionCaller.h +++ b/include/lldb/Expression/FunctionCaller.h @@ -29,7 +29,7 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class FunctionCaller FunctionCaller.h "lldb/Expression/FunctionCaller.h" -/// @brief Encapsulates a function that can be called. +/// Encapsulates a function that can be called. /// /// A given FunctionCaller object can handle a single function signature. /// Once constructed, it can set up any number of concurrent calls to @@ -42,8 +42,8 @@ namespace lldb_private { /// struct with the written arguments. This method lets Clang handle the /// vagaries of function calling conventions. /// -/// The simplest use of the FunctionCaller is to construct it with a -/// function representative of the signature you want to use, then call +/// The simplest use of the FunctionCaller is to construct it with a function +/// representative of the signature you want to use, then call /// ExecuteFunction(ExecutionContext &, Stream &, Value &). /// /// If you need to reuse the arguments for several calls, you can call @@ -53,8 +53,8 @@ namespace lldb_private { /// If you need to call the function on the thread plan stack, you can also /// call InsertFunction() followed by GetThreadPlanToCallFunction(). /// -/// Any of the methods that take arg_addr_ptr or arg_addr_ref can be passed -/// a pointer set to LLDB_INVALID_ADDRESS and new structure will be allocated +/// Any of the methods that take arg_addr_ptr or arg_addr_ref can be passed a +/// pointer set to LLDB_INVALID_ADDRESS and new structure will be allocated /// and its address returned in that variable. /// /// Any of the methods that take arg_addr_ptr can be passed nullptr, and the @@ -170,8 +170,8 @@ public: DiagnosticManager &diagnostic_manager); //------------------------------------------------------------------ - /// Insert an argument struct with a non-default function address and - /// non-default argument values + /// Insert an argument struct with a non-default function address and non- + /// default argument values /// /// @param[in] exe_ctx /// The execution context to insert the function and its arguments @@ -308,28 +308,25 @@ public: //------------------------------------------------------------------ /// Return the function name that should be used for executing the - /// expression. Text() should contain the definition of this - /// function. + /// expression. Text() should contain the definition of this function. //------------------------------------------------------------------ const char *FunctionName() override { return m_wrapper_function_name.c_str(); } //------------------------------------------------------------------ - /// Return the object that the parser should use when registering - /// local variables. May be nullptr if the Expression doesn't care. + /// Return the object that the parser should use when registering local + /// variables. May be nullptr if the Expression doesn't care. //------------------------------------------------------------------ ExpressionVariableList *LocalVariables() { return nullptr; } //------------------------------------------------------------------ - /// Return true if validation code should be inserted into the - /// expression. + /// Return true if validation code should be inserted into the expression. //------------------------------------------------------------------ bool NeedsValidation() override { return false; } //------------------------------------------------------------------ - /// Return true if external variables in the expression should be - /// resolved. + /// Return true if external variables in the expression should be resolved. //------------------------------------------------------------------ bool NeedsVariableResolution() override { return false; } diff --git a/include/lldb/Expression/IRDynamicChecks.h b/include/lldb/Expression/IRDynamicChecks.h index b793a60585bb0..f31c03cfb9efa 100644 --- a/include/lldb/Expression/IRDynamicChecks.h +++ b/include/lldb/Expression/IRDynamicChecks.h @@ -33,17 +33,18 @@ class Stream; //---------------------------------------------------------------------- /// @class DynamicCheckerFunctions IRDynamicChecks.h -/// "lldb/Expression/IRDynamicChecks.h" -/// @brief Encapsulates dynamic check functions used by expressions. +/// "lldb/Expression/IRDynamicChecks.h" Encapsulates dynamic check functions +/// used by expressions. /// /// Each of the utility functions encapsulated in this class is responsible -/// for validating some data that an expression is about to use. Examples are: +/// for validating some data that an expression is about to use. Examples +/// are: /// -/// a = *b; // check that b is a valid pointer -/// [b init]; // check that b is a valid object to send "init" to +/// a = *b; // check that b is a valid pointer [b init]; // check that b +/// is a valid object to send "init" to /// -/// The class installs each checker function into the target process and -/// makes it available to IRDynamicChecks to use. +/// The class installs each checker function into the target process and makes +/// it available to IRDynamicChecks to use. //---------------------------------------------------------------------- class DynamicCheckerFunctions { public: @@ -58,8 +59,8 @@ public: ~DynamicCheckerFunctions(); //------------------------------------------------------------------ - /// Install the utility functions into a process. This binds the - /// instance of DynamicCheckerFunctions to that process. + /// Install the utility functions into a process. This binds the instance + /// of DynamicCheckerFunctions to that process. /// /// @param[in] diagnostic_manager /// A diagnostic manager to report errors to. @@ -81,16 +82,16 @@ public: }; //---------------------------------------------------------------------- -/// @class IRDynamicChecks IRDynamicChecks.h "lldb/Expression/IRDynamicChecks.h" -/// @brief Adds dynamic checks to a user-entered expression to reduce its -/// likelihood of crashing +/// @class IRDynamicChecks IRDynamicChecks.h +/// "lldb/Expression/IRDynamicChecks.h" Adds dynamic checks to a user-entered +/// expression to reduce its likelihood of crashing /// /// When an IR function is executed in the target process, it may cause -/// crashes or hangs by dereferencing NULL pointers, trying to call Objective-C -/// methods on objects that do not respond to them, and so forth. +/// crashes or hangs by dereferencing NULL pointers, trying to call +/// Objective-C methods on objects that do not respond to them, and so forth. /// -/// IRDynamicChecks adds calls to the functions in DynamicCheckerFunctions -/// to appropriate locations in an expression's IR. +/// IRDynamicChecks adds calls to the functions in DynamicCheckerFunctions to +/// appropriate locations in an expression's IR. //---------------------------------------------------------------------- class IRDynamicChecks : public llvm::ModulePass { public: diff --git a/include/lldb/Expression/IRExecutionUnit.h b/include/lldb/Expression/IRExecutionUnit.h index 703fcd152af41..e73f8956d9556 100644 --- a/include/lldb/Expression/IRExecutionUnit.h +++ b/include/lldb/Expression/IRExecutionUnit.h @@ -42,23 +42,23 @@ namespace lldb_private { class Status; //---------------------------------------------------------------------- -/// @class IRExecutionUnit IRExecutionUnit.h "lldb/Expression/IRExecutionUnit.h" -/// @brief Contains the IR and, optionally, JIT-compiled code for a module. +/// @class IRExecutionUnit IRExecutionUnit.h +/// "lldb/Expression/IRExecutionUnit.h" Contains the IR and, optionally, JIT- +/// compiled code for a module. /// -/// This class encapsulates the compiled version of an expression, in IR -/// form (for interpretation purposes) and in raw machine code form (for -/// execution in the target). +/// This class encapsulates the compiled version of an expression, in IR form +/// (for interpretation purposes) and in raw machine code form (for execution +/// in the target). /// -/// This object wraps an IR module that comes from the expression parser, -/// and knows how to use the JIT to make it into executable code. It can -/// then be used as input to the IR interpreter, or the address of the -/// executable code can be passed to a thread plan to run in the target. +/// This object wraps an IR module that comes from the expression parser, and +/// knows how to use the JIT to make it into executable code. It can then be +/// used as input to the IR interpreter, or the address of the executable code +/// can be passed to a thread plan to run in the target. /// /// This class creates a subclass of LLVM's SectionMemoryManager, because that -/// is -/// how the JIT emits code. Because LLDB needs to move JIT-compiled code -/// into the target process, the IRExecutionUnit knows how to copy the -/// emitted code into the target process. +/// is how the JIT emits code. Because LLDB needs to move JIT-compiled code +/// into the target process, the IRExecutionUnit knows how to copy the emitted +/// code into the target process. //---------------------------------------------------------------------- class IRExecutionUnit : public std::enable_shared_from_this<IRExecutionUnit>, public IRMemoryMap, @@ -90,9 +90,9 @@ public: lldb::addr_t &func_end); //------------------------------------------------------------------ - /// Accessors for IRForTarget and other clients that may want binary - /// data placed on their behalf. The binary data is owned by the - /// IRExecutionUnit unless the client explicitly chooses to free it. + /// Accessors for IRForTarget and other clients that may want binary data + /// placed on their behalf. The binary data is owned by the IRExecutionUnit + /// unless the client explicitly chooses to free it. //------------------------------------------------------------------ lldb::addr_t WriteNow(const uint8_t *bytes, size_t size, Status &error); @@ -123,7 +123,7 @@ public: //---------------------------------------------------------------------- /// @class JittedFunction IRExecutionUnit.h /// "lldb/Expression/IRExecutionUnit.h" - /// @brief Encapsulates a single function that has been generated by the JIT. + /// Encapsulates a single function that has been generated by the JIT. /// /// Functions that have been generated by the JIT are first resident in the /// local process, and then placed in the target process. JittedFunction @@ -182,9 +182,9 @@ public: private: //------------------------------------------------------------------ - /// Look up the object in m_address_map that contains a given address, - /// find where it was copied to, and return the remote address at the - /// same offset into the copied entity + /// Look up the object in m_address_map that contains a given address, find + /// where it was copied to, and return the remote address at the same offset + /// into the copied entity /// /// @param[in] local_address /// The address in the debugger. @@ -195,9 +195,9 @@ private: lldb::addr_t GetRemoteAddressForLocal(lldb::addr_t local_address); //------------------------------------------------------------------ - /// Look up the object in m_address_map that contains a given address, - /// find where it was copied to, and return its address range in the - /// target process + /// Look up the object in m_address_map that contains a given address, find + /// where it was copied to, and return its address range in the target + /// process /// /// @param[in] local_address /// The address in the debugger. @@ -272,8 +272,8 @@ private: ~MemoryManager() override; //------------------------------------------------------------------ - /// Allocate space for executable code, and add it to the - /// m_spaceBlocks map + /// Allocate space for executable code, and add it to the m_spaceBlocks + /// map /// /// @param[in] Size /// The size of the area. @@ -315,8 +315,8 @@ private: bool IsReadOnly) override; //------------------------------------------------------------------ - /// Called when object loading is complete and section page - /// permissions can be applied. Currently unimplemented for LLDB. + /// Called when object loading is complete and section page permissions + /// can be applied. Currently unimplemented for LLDB. /// /// @param[out] ErrMsg /// The error that prevented the page protection from succeeding. @@ -355,11 +355,11 @@ private: //---------------------------------------------------------------------- /// @class AllocationRecord IRExecutionUnit.h - /// "lldb/Expression/IRExecutionUnit.h" - /// @brief Encapsulates a single allocation request made by the JIT. + /// "lldb/Expression/IRExecutionUnit.h" Encapsulates a single allocation + /// request made by the JIT. /// - /// Allocations made by the JIT are first queued up and then applied in - /// bulk to the underlying process. + /// Allocations made by the JIT are first queued up and then applied in bulk + /// to the underlying process. //---------------------------------------------------------------------- enum class AllocationKind { Stub, Code, Data, Global, Bytes }; diff --git a/include/lldb/Expression/IRInterpreter.h b/include/lldb/Expression/IRInterpreter.h index 36e03c6fc4f61..2d87346b70663 100644 --- a/include/lldb/Expression/IRInterpreter.h +++ b/include/lldb/Expression/IRInterpreter.h @@ -29,12 +29,12 @@ class IRMemoryMap; //---------------------------------------------------------------------- /// @class IRInterpreter IRInterpreter.h "lldb/Expression/IRInterpreter.h" -/// @brief Attempt to interpret the function's code if it does not require +/// Attempt to interpret the function's code if it does not require /// running the target. /// -/// In some cases, the IR for an expression can be evaluated entirely -/// in the debugger, manipulating variables but not executing any code -/// in the target. The IRInterpreter attempts to do this. +/// In some cases, the IR for an expression can be evaluated entirely in the +/// debugger, manipulating variables but not executing any code in the target. +/// The IRInterpreter attempts to do this. //---------------------------------------------------------------------- class IRInterpreter { public: diff --git a/include/lldb/Expression/IRMemoryMap.h b/include/lldb/Expression/IRMemoryMap.h index abb5cd745053a..df8a03f4763f5 100644 --- a/include/lldb/Expression/IRMemoryMap.h +++ b/include/lldb/Expression/IRMemoryMap.h @@ -20,19 +20,19 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class IRMemoryMap IRMemoryMap.h "lldb/Expression/IRMemoryMap.h" -/// @brief Encapsulates memory that may exist in the process but must +/// Encapsulates memory that may exist in the process but must /// also be available in the host process. /// -/// This class encapsulates a group of memory objects that must be readable -/// or writable from the host process regardless of whether the process -/// exists. This allows the IR interpreter as well as JITted code to access -/// the same memory. All allocations made by this class are represented as -/// disjoint intervals. +/// This class encapsulates a group of memory objects that must be readable or +/// writable from the host process regardless of whether the process exists. +/// This allows the IR interpreter as well as JITted code to access the same +/// memory. All allocations made by this class are represented as disjoint +/// intervals. /// /// Point queries against this group of memory objects can be made by the -/// address in the tar at which they reside. If the inferior does not -/// exist, allocations still get made-up addresses. If an inferior appears -/// at some point, then those addresses need to be re-mapped. +/// address in the tar at which they reside. If the inferior does not exist, +/// allocations still get made-up addresses. If an inferior appears at some +/// point, then those addresses need to be re-mapped. //---------------------------------------------------------------------- class IRMemoryMap { public: @@ -83,8 +83,8 @@ public: lldb::TargetSP GetTarget() { return m_target_wp.lock(); } protected: - // This function should only be used if you know you are using the JIT. - // Any other cases should use GetBestExecutionContextScope(). + // This function should only be used if you know you are using the JIT. Any + // other cases should use GetBestExecutionContextScope(). lldb::ProcessWP &GetProcessWP() { return m_process_wp; } diff --git a/include/lldb/Expression/LLVMUserExpression.h b/include/lldb/Expression/LLVMUserExpression.h index 745d413e077be..a2f87e8a6e251 100644 --- a/include/lldb/Expression/LLVMUserExpression.h +++ b/include/lldb/Expression/LLVMUserExpression.h @@ -26,25 +26,24 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class LLVMUserExpression LLVMUserExpression.h -/// "lldb/Expression/LLVMUserExpression.h" -/// @brief Encapsulates a one-time expression for use in lldb. +/// "lldb/Expression/LLVMUserExpression.h" Encapsulates a one-time expression +/// for use in lldb. /// /// LLDB uses expressions for various purposes, notably to call functions -/// and as a backend for the expr command. LLVMUserExpression is a virtual base -/// class that encapsulates the objects needed to parse and JIT an expression. -/// The actual parsing part will be provided by the specific implementations -/// of LLVMUserExpression - which will be vended through the appropriate -/// TypeSystem. +/// and as a backend for the expr command. LLVMUserExpression is a virtual +/// base class that encapsulates the objects needed to parse and JIT an +/// expression. The actual parsing part will be provided by the specific +/// implementations of LLVMUserExpression - which will be vended through the +/// appropriate TypeSystem. //---------------------------------------------------------------------- class LLVMUserExpression : public UserExpression { public: // The IRPasses struct is filled in by a runtime after an expression is - // compiled and can be used to to run - // fixups/analysis passes as required. EarlyPasses are run on the generated - // module before lldb runs its own IR + // compiled and can be used to to run fixups/analysis passes as required. + // EarlyPasses are run on the generated module before lldb runs its own IR // fixups and inserts instrumentation code/pointer checks. LatePasses are run - // after the module has been processed by - // llvm, before the module is assembled and run in the ThreadPlan. + // after the module has been processed by llvm, before the module is + // assembled and run in the ThreadPlan. struct IRPasses { IRPasses() : EarlyPasses(nullptr), LatePasses(nullptr){}; std::shared_ptr<llvm::legacy::PassManager> EarlyPasses; diff --git a/include/lldb/Expression/UserExpression.h b/include/lldb/Expression/UserExpression.h index ced5cb2bf2b7d..96ca80c882e5e 100644 --- a/include/lldb/Expression/UserExpression.h +++ b/include/lldb/Expression/UserExpression.h @@ -30,7 +30,7 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class UserExpression UserExpression.h "lldb/Expression/UserExpression.h" -/// @brief Encapsulates a one-time expression for use in lldb. +/// Encapsulates a one-time expression for use in lldb. /// /// LLDB uses expressions for various purposes, notably to call functions /// and as a backend for the expr command. UserExpression is a virtual base @@ -103,8 +103,8 @@ public: bool MatchesContext(ExecutionContext &exe_ctx); //------------------------------------------------------------------ - /// Execute the parsed expression by callinng the derived class's - /// DoExecute method. + /// Execute the parsed expression by callinng the derived class's DoExecute + /// method. /// /// @param[in] diagnostic_manager /// A diagnostic manager to report errors to. @@ -177,32 +177,29 @@ public: //------------------------------------------------------------------ /// Return the function name that should be used for executing the - /// expression. Text() should contain the definition of this - /// function. + /// expression. Text() should contain the definition of this function. //------------------------------------------------------------------ const char *FunctionName() override { return "$__lldb_expr"; } //------------------------------------------------------------------ - /// Return the language that should be used when parsing. To use - /// the default, return eLanguageTypeUnknown. + /// Return the language that should be used when parsing. To use the + /// default, return eLanguageTypeUnknown. //------------------------------------------------------------------ lldb::LanguageType Language() override { return m_language; } //------------------------------------------------------------------ - /// Return the desired result type of the function, or - /// eResultTypeAny if indifferent. + /// Return the desired result type of the function, or eResultTypeAny if + /// indifferent. //------------------------------------------------------------------ ResultType DesiredResultType() override { return m_desired_type; } //------------------------------------------------------------------ - /// Return true if validation code should be inserted into the - /// expression. + /// Return true if validation code should be inserted into the expression. //------------------------------------------------------------------ bool NeedsValidation() override { return true; } //------------------------------------------------------------------ - /// Return true if external variables in the expression should be - /// resolved. + /// Return true if external variables in the expression should be resolved. //------------------------------------------------------------------ bool NeedsVariableResolution() override { return true; } @@ -216,8 +213,8 @@ public: virtual lldb::ModuleSP GetJITModule() { return lldb::ModuleSP(); } //------------------------------------------------------------------ - /// Evaluate one expression in the scratch context of the - /// target passed in the exe_ctx and return its result. + /// Evaluate one expression in the scratch context of the target passed in + /// the exe_ctx and return its result. /// /// @param[in] exe_ctx /// The execution context to use when evaluating the expression. diff --git a/include/lldb/Expression/UtilityFunction.h b/include/lldb/Expression/UtilityFunction.h index 9c54db35fa371..5d4bc8676b95b 100644 --- a/include/lldb/Expression/UtilityFunction.h +++ b/include/lldb/Expression/UtilityFunction.h @@ -25,13 +25,13 @@ namespace lldb_private { //---------------------------------------------------------------------- -/// @class UtilityFunction UtilityFunction.h "lldb/Expression/UtilityFunction.h" -/// @brief Encapsulates a bit of source code that provides a function that is -/// callable +/// @class UtilityFunction UtilityFunction.h +/// "lldb/Expression/UtilityFunction.h" Encapsulates a bit of source code that +/// provides a function that is callable /// /// LLDB uses expressions for various purposes, notably to call functions -/// and as a backend for the expr command. UtilityFunction encapsulates -/// a self-contained function meant to be used from other code. Utility +/// and as a backend for the expr command. UtilityFunction encapsulates a +/// self-contained function meant to be used from other code. Utility /// functions can perform error-checking for ClangUserExpressions, //---------------------------------------------------------------------- class UtilityFunction : public Expression { @@ -69,8 +69,7 @@ public: /// Check whether the given PC is inside the function /// /// Especially useful if the function dereferences nullptr to indicate a - /// failed - /// assert. + /// failed assert. /// /// @param[in] pc /// The program counter to check. @@ -80,8 +79,8 @@ public: /// false if not (or the function is not JIT compiled) //------------------------------------------------------------------ bool ContainsAddress(lldb::addr_t address) { - // nothing is both >= LLDB_INVALID_ADDRESS and < LLDB_INVALID_ADDRESS, - // so this always returns false if the function is not JIT compiled yet + // nothing is both >= LLDB_INVALID_ADDRESS and < LLDB_INVALID_ADDRESS, so + // this always returns false if the function is not JIT compiled yet return (address >= m_jit_start_addr && address < m_jit_end_addr); } @@ -93,33 +92,29 @@ public: //------------------------------------------------------------------ /// Return the function name that should be used for executing the - /// expression. Text() should contain the definition of this - /// function. + /// expression. Text() should contain the definition of this function. //------------------------------------------------------------------ const char *FunctionName() override { return m_function_name.c_str(); } //------------------------------------------------------------------ - /// Return the object that the parser should use when registering - /// local variables. May be nullptr if the Expression doesn't care. + /// Return the object that the parser should use when registering local + /// variables. May be nullptr if the Expression doesn't care. //------------------------------------------------------------------ ExpressionVariableList *LocalVariables() { return nullptr; } //------------------------------------------------------------------ - /// Return true if validation code should be inserted into the - /// expression. + /// Return true if validation code should be inserted into the expression. //------------------------------------------------------------------ bool NeedsValidation() override { return false; } //------------------------------------------------------------------ - /// Return true if external variables in the expression should be - /// resolved. + /// Return true if external variables in the expression should be resolved. //------------------------------------------------------------------ bool NeedsVariableResolution() override { return false; } - // This makes the function caller function. - // Pass in the ThreadSP if you have one available, compilation can end up - // calling code (e.g. to look up indirect - // functions) and we don't want this to wander onto another thread. + // This makes the function caller function. Pass in the ThreadSP if you have + // one available, compilation can end up calling code (e.g. to look up + // indirect functions) and we don't want this to wander onto another thread. FunctionCaller *MakeFunctionCaller(const CompilerType &return_type, const ValueList &arg_value_list, lldb::ThreadSP compilation_thread, |