lldb/docs/design/overview.rst

   1 Overview
   2 ========
   3
   4 LLDB is a large and complex codebase. This section will help you become more
   5 familiar with the pieces that make up LLDB and give a general overview of the
   6 general architecture.
   7
   8 LLDB has many code groupings that makeup the source base:
   9
  10 .. contents::
  11    :local:
  12
  13 API
  14 ---
  15
  16 The API folder contains the public interface to LLDB.
  17
  18 We are currently vending a C++ API. In order to be able to add methods to this
  19 API and allow people to link to our classes, we have certain rules that we must
  20 follow:
  21
  22 - Classes can't inherit from any other classes.
  23 - Classes can't contain virtual methods.
  24 - Classes should be compatible with script bridging utilities like swig.
  25 - Classes should be lightweight and be backed by a single member. Pointers (or
  26   shared pointers) are the preferred choice since they allow changing the
  27   contents of the backend without affecting the public object layout.
  28 - The interface should be as minimal as possible in order to give a complete
  29   API.
  30
  31 By adhering to these rules we should be able to continue to vend a C++ API, and
  32 make changes to the API as any additional methods added to these classes will
  33 just be a dynamic loader lookup and they won't affect the class layout (since
  34 they aren't virtual methods, and no members can be added to the class).
  35
  36 Breakpoint
  37 ----------
  38
  39 A collection of classes that implement our breakpoint classes. Breakpoints are
  40 resolved symbolically and always continue to resolve themselves as your program
  41 runs. Whether settings breakpoints by file and line, by symbol name, by symbol
  42 regular expression, or by address, breakpoints will keep trying to resolve new
  43 locations each time shared libraries are loaded. Breakpoints will of course
  44 unresolve themselves when shared libraries are unloaded. Breakpoints can also
  45 be scoped to be set only in a specific shared library. By default, breakpoints
  46 can be set in any shared library and will continue to attempt to be resolved
  47 with each shared library load.
  48
  49 Breakpoint options can be set on the breakpoint, or on the individual
  50 locations. This allows flexibility when dealing with breakpoints and allows us
  51 to do what the user wants.
  52
  53 Commands
  54 --------
  55
  56 The command source files represent objects that implement the functionality for
  57 all textual commands available in our command line interface.
  58
  59 Every command is backed by a ``lldb_private::CommandObject`` or
  60 ``lldb_private::CommandObjectMultiword`` object.
  61
  62 ``lldb_private::CommandObjectMultiword`` are commands that have subcommands and
  63 allow command line commands to be logically grouped into a hierarchy.
  64
  65 ``lldb_private::CommandObject`` command line commands are the objects that
  66 implement the functionality of the command. They can optionally define options
  67 for themselves, as well as group those options into logical groups that can go
  68 together. The help system is tied into these objects and can extract the syntax
  69 and option groupings to display appropriate help for each command.
  70
  71 Core
  72 ----
  73
  74 The Core source files contain basic functionality that is required in the
  75 debugger as well as the class representing the debugger itself (Debugger). A
  76 wide variety of classes are implemented:
  77
  78 - Address (section offset addressing)
  79 - AddressRange
  80 - Broadcaster / Event / Listener
  81 - Communication classes that use Connection objects
  82 - Mangled names
  83 - Source manager
  84 - Value objects
  85
  86 Dataformatters
  87 --------------
  88
  89 A collection of classes that implement the data formatters subsystem.
  90
  91 Data formatters provide a set of user-tweakable hooks in the ValueObjects world
  92 that allow to customize presentation aspects of variables. While users interact
  93 with formatters mostly through the type command, inside LLDB there are a few
  94 layers to the implementation: DataVisualization at the highest end of the
  95 spectrum, backed by classes implementing individual formatters, matching rules,
  96 etc.
  97
  98 For a general user-level introduction to data formatters, you can look here.
  99
 100 More details on the architecture are to be found here.
 101
 102 Expression
 103 ----------
 104
 105 Expression parsing files cover everything from evaluating DWARF expressions, to
 106 evaluating expressions using Clang.
 107
 108 The DWARF expression parser has been heavily modified to support type
 109 promotion, new opcodes needed for evaluating expressions with symbolic variable
 110 references (expression local variables, program variables), and other operators
 111 required by typical expressions such as assign, address of, float/double/long
 112 double floating point values, casting, and more. The DWARF expression parser
 113 uses a stack of lldb_private::Value objects. These objects know how to do the
 114 standard C type promotion, and allow for symbolic references to variables in
 115 the program and in the LLDB process (expression local and expression global
 116 variables).
 117
 118 The expression parser uses a full instance of the Clang compiler in order to
 119 accurately evaluate expressions. Hooks have been put into Clang so that the
 120 compiler knows to ask about identifiers it doesn't know about. Once expressions
 121 have be compiled into an AST, we can then traverse this AST and either generate
 122 a DWARF expression that contains simple opcodes that can be quickly
 123 re-evaluated each time an expression needs to be evaluated, or JIT'ed up into
 124 code that can be run on the process being debugged.
 125
 126 Host
 127 ----
 128
 129 LLDB tries to abstract itself from the host upon which it is currently running
 130 by providing a host abstraction layer. This layer includes functionality, whose
 131 implementation varies wildly from host to host.
 132
 133 Host functionality includes abstraction layers for:
 134
 135 - Information about the host system (triple, list of running processes, etc.)
 136 - Launching processes
 137 - Various OS primitives like pipes and sockets
 138
 139 It also includes the base classes of the NativeProcess/Thread hierarchy, which
 140 is used by lldb-server.
 141
 142 Interpreter
 143 -----------
 144
 145 The interpreter classes are the classes responsible for being the base classes
 146 needed for each command object, and is responsible for tracking and running
 147 command line commands.
 148
 149 Symbol
 150 ------
 151
 152 Symbol classes involve everything needed in order to parse object files and
 153 debug symbols. All the needed classes for compilation units (code and debug
 154 info for a source file), functions, lexical blocks within functions, inlined
 155 functions, types, declaration locations, and variables are in this section.
 156
 157 Target
 158 ------
 159
 160 Classes that are related to a debug target include:
 161
 162 - Target
 163 - Process
 164 - Thread
 165 - Stack frames
 166 - Stack frame registers
 167 - ABI for function calling in process being debugged
 168 - Execution context batons
 169
 170 Utility
 171 -------
 172
 173 This module contains the lowest layers of LLDB. A lot of these classes don't
 174 really have anything to do with debugging -- they are just there because the
 175 higher layers of the debugger use these classes to implement their
 176 functionality. Others are data structures used in many other parts of the
 177 debugger. Most of the functionality in this module could be useful in an
 178 application that is not a debugger; however, providing a general purpose C++
 179 library is an explicit non-goal of this module..
 180
 181 This module provides following functionality:
 182
 183 - Abstract path manipulation (FileSpec)
 184 - Architecture specification
 185 - Data buffers (DataBuffer, DataEncoder, DataExtractor)
 186 - Logging
 187 - Structured data manipulation (JSON)
 188 - Streams
 189 - Timers
 190
 191 For historic reasons, some of this functionality overlaps that which is
 192 provided by the LLVM support library.