[Lldb-commits] [lldb] r307072 - Update lldb architecture docs
Pavel Labath via lldb-commits
lldb-commits at lists.llvm.org
Tue Jul 4 05:29:34 PDT 2017
Author: labath
Date: Tue Jul 4 05:29:34 2017
New Revision: 307072
URL: http://llvm.org/viewvc/llvm-project?rev=307072&view=rev
Log:
Update lldb architecture docs
Summary:
Due to recent refactors, the descriptions of various modules were wildly
out of date. With this patch, I am not trying to legislate anything,
I am merely documenting the current state of affairs.
I am also deleting one copy of the architecture docs. AFAIK, this one is
not referenced from the web page.
Reviewers: zturner, jingham
Subscribers: lldb-commits
Differential Revision: https://reviews.llvm.org/D34872
Removed:
lldb/trunk/www/architecture.html
Modified:
lldb/trunk/www/architecture/index.html
Removed: lldb/trunk/www/architecture.html
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/architecture.html?rev=307071&view=auto
==============================================================================
--- lldb/trunk/www/architecture.html (original)
+++ lldb/trunk/www/architecture.html (removed)
@@ -1,294 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
-<link href="style.css" rel="stylesheet" type="text/css" />
-<title>LLDB Architecture</title>
-</head>
-
-<body>
- <div class="www_title">
- The <strong>LLDB</strong> Debugger
- </div>
-
-<div id="container">
- <div id="content">
-
- <!--#include virtual="sidebar.incl"-->
-
- <div id="middle">
- <div class="post">
- <h1 class ="postheader">Architecture</h1>
- <div class="postcontent">
-
- <p>LLDB is a large and complex codebase. This section will help you become more familiar with
- the pieces that make up LLDB and give a general overview of the general architecture.</p>
- </div>
- <div class="postfooter"></div>
- </div>
- <div class="post">
- <h1 class ="postheader">Code Layout</h1>
- <div class="postcontent">
-
- <p>LLDB has many code groupings that makeup the source base:</p>
- <ul>
- <li><a href="#api">API</a></li>
- <li><a href="#breakpoint">Breakpoint</a></li>
- <li><a href="#commands">Commands</a></li>
- <li><a href="#core">Core</a></li>
- <li><a href="#dataformatters">DataFormatters</a></li>
- <li><a href="#expression">Expression</a></li>
- <li><a href="#host">Host</a></li>
- <li><a href="#interpreter">Interpreter</a></li>
- <li><a href="#symbol">Symbol</a></li>
- <li><a href="#targ">Target</a></li>
- <li><a href="#utility">Utility</a></li>
- </ul>
- </div>
- <div class="postfooter"></div>
- </div>
- <a name="api"></a>
- <div class="post">
- <h1 class ="postheader">API</h1>
- <div class="postcontent">
-
- <p>The API folder contains the public interface to LLDB.</p>
- <p>We are currently vending a C++ API. In order to be able to add
- methods to this API and allow people to link to our classes,
- we have certain rules that we must follow:</p>
- <ul>
- <li>Classes can't inherit from any other classes.</li>
- <li>Classes can't contain virtual methods.</li>
- <li>Classes should be compatible with script bridging utilities like <a href="http://www.swig.org/">swig</a>.</li>
- <li>Classes should be lightweight and be backed by a single member. Pointers (or shared pointers) are the preferred choice since they allow changing the contents of the backend without affecting the public object layout.</li>
- <li>The interface should be as minimal as possible in order to give a complete API.</li>
- </ul>
- <p>By adhering to these rules we should be able to continue to
- vend a C++ API, and make changes to the API as any additional
- methods added to these classes will just be a dynamic loader
- lookup and they won't affect the class layout (since they
- aren't virtual methods, and no members can be added to the
- class).</p>
- </div>
- <div class="postfooter"></div>
- </div>
- <a name="breakpoint"></a>
- <div class="post">
- <h1 class ="postheader">Breakpoint</h1>
- <div class="postcontent">
-
- <p>A collection of classes that implement our breakpoint classes.
- Breakpoints are resolved symbolically and always continue to
- resolve themselves as your program runs. Whether settings breakpoints
- by file and line, by symbol name, by symbol regular expression,
- or by address, breakpoints will keep trying to resolve new locations
- each time shared libraries are loaded. Breakpoints will of course
- unresolve themselves when shared libraries are unloaded. Breakpoints
- can also be scoped to be set only in a specific shared library. By
- default, breakpoints can be set in any shared library and will continue
- to attempt to be resolved with each shared library load.</p>
- <p>Breakpoint options can be set on the breakpoint,
- or on the individual locations. This allows flexibility when dealing
- with breakpoints and allows us to do what the user wants.</p>
- </div>
- <div class="postfooter"></div>
- </div>
- <a name="commands"></a>
- <div class="post">
- <h1 class ="postheader">Commands</h1>
- <div class="postcontent">
-
- <p>The command source files represent objects that implement
- the functionality for all textual commands available
- in our command line interface.</p>
- <p>Every command is backed by a <b>lldb_private::CommandObject</b>
- or <b>lldb_private::CommandObjectMultiword</b> object.</p>
- <p><b>lldb_private::CommandObjectMultiword</b> are commands that
- have subcommands and allow command line commands to be
- logically grouped into a hierarchy.</p>
- <p><b>lldb_private::CommandObject</b> command line commands
- are the objects that implement the functionality of the
- command. They can optionally define
- options for themselves, as well as group those options into
- logical groups that can go together. The help system is
- tied into these objects and can extract the syntax and
- option groupings to display appropriate help for each
- command.</p>
- </div>
- <div class="postfooter"></div>
- </div>
- <a name="core"></a>
- <div class="post">
- <h1 class ="postheader">Core</h1>
- <div class="postcontent">
-
- <p>The Core source files contain basic functionality that
- is required in the debugger. A wide variety of classes
- are implemented:</p>
-
- <ul>
- <li>Address (section offset addressing)</li>
- <li>AddressRange</li>
- <li>Architecture specification</li>
- <li>Broadcaster / Event / Listener </li>
- <li>Communication classes that use Connection objects</li>
- <li>Uniqued C strings</li>
- <li>Data extraction</li>
- <li>File specifications</li>
- <li>Mangled names</li>
- <li>Regular expressions</li>
- <li>Source manager</li>
- <li>Streams</li>
- <li>Value objects</li>
- </ul>
- </div>
- <div class="postfooter"></div>
- </div>
- <a name="dataformatters"></a>
- <div class="post">
- <h1 class ="postheader">DataFormatters</h1>
- <div class="postcontent">
-
- <p>A collection of classes that implement the data formatters subsystem.</p>
-
- <p>For a general user-level introduction to data formatters, you can look <a href="varformats.html">here</a>.
- <p>A 10,000 foot view of the data formatters is based upon the <code>DataVisualization</code> class.
- <code>DataVisualization</code> is the very high level entry point into the data formatters. It vends a stable interface in face of changing internals
- and is the recommended entry point for components of LLDB that need to ask questions of the data formatters.
- The main questions one can ask of <code>DataVisualization</code> are:
- <ul>
- <li>given a ValueObject, retrieve the formatters to be used for it</li>
- <li>given a type, retrieve the formatters to be used for it. This is not an "exact" question,
- i.e. one can retrieve a formatter from a type name which would not be used to then format ValueObjects of that type</li>
- <li>given a name, retrieve a category of that name, optionally creating it if needed - more generally, categories management</li>
- <li>given an identifier and a summary, store it as a named summary - more generally, named summary management</li>
- </ul>
-
- <p>For people actively maintaining the data formatters subsystem itself, however, the FormatManager class is the relevant point of entry.
- This class is subject to more frequent changes as the formatters evolve. Currently, it provides a thin caching layer on top of a list of categories
- that each export a group of formatters.
- </p>
- <p>From an end-user perspective, the "type" LLDB command is the point of access to the data formatters. A large group of generally-useful formatters
- is provided by default and loaded upon debugger startup.
- </div>
- <div class="postfooter"></div>
- </div>
- <a name="expression"></a>
- <div class="post">
- <h1 class ="postheader">Expression</h1>
- <div class="postcontent">
-
- <p>Expression parsing files cover everything from evaluating
- DWARF expressions, to evaluating expressions using
- Clang.</p>
- <p>The DWARF expression parser has been heavily modified to
- support type promotion, new opcodes needed for evaluating
- expressions with symbolic variable references (expression local variables,
- program variables), and other operators required by
- typical expressions such as assign, address of, float/double/long
- double floating point values, casting, and more. The
- DWARF expression parser uses a stack of lldb_private::Value
- objects. These objects know how to do the standard C type
- promotion, and allow for symbolic references to variables
- in the program and in the LLDB process (expression local
- and expression global variables).</p>
- <p>The expression parser uses a full instance of the Clang
- compiler in order to accurately evaluate expressions.
- Hooks have been put into Clang so that the compiler knows
- to ask about identifiers it doesn't know about. Once
- expressions have be compiled into an AST, we can then
- traverse this AST and either generate a DWARF expression
- that contains simple opcodes that can be quickly re-evaluated
- each time an expression needs to be evaluated, or JIT'ed
- up into code that can be run on the process being debugged.</p>
- </div>
- <div class="postfooter"></div>
- </div>
- <a name="host"></a>
- <div class="post">
- <h1 class ="postheader">Host</h1>
- <div class="postcontent">
-
- <p>LLDB tries to abstract itself from the host upon which
- it is currently running by providing a host abstraction
- layer. This layer involves everything from spawning, detaching,
- joining and killing native in-process threads, to getting
- current information about the current host.</p>
- <p>Host functionality includes abstraction layers for:</p>
- <ul>
- <li>Mutexes</li>
- <li>Conditions</li>
- <li>Timing functions</li>
- <li>Thread functions</li>
- <li>Host target triple</li>
- <li>Host child process notifications</li>
- <li>Host specific types</li>
- </ul>
- </div>
- <div class="postfooter"></div>
- </div>
- <a name="interpreter"></a>
- <div class="post">
- <h1 class ="postheader">Interpreter</h1>
- <div class="postcontent">
-
- <p>The interpreter classes are the classes responsible for
- being the base classes needed for each command object,
- and is responsible for tracking and running command line
- commands.</p>
- </div>
- <div class="postfooter"></div>
- </div>
- <a name="symbol"></a>
- <div class="post">
- <h1 class ="postheader">Symbol</h1>
- <div class="postcontent">
- <p>Symbol classes involve everything needed in order to parse
- object files and debug symbols. All the needed classes
- for compilation units (code and debug info for a source file),
- functions, lexical blocks within functions, inlined
- functions, types, declaration locations, and variables
- are in this section.</p>
- </div>
- <div class="postfooter"></div>
- </div>
- <a name="targ"></a>
- <div class="post">
- <h1 class ="postheader">Target</h1>
- <div class="postcontent">
-
- <p>Classes that are related to a debug target include:</p>
- <ul>
- <li>Target</li>
- <li>Process</li>
- <li>Thread</li>
- <li>Stack frames</li>
- <li>Stack frame registers</li>
- <li>ABI for function calling in process being debugged</li>
- <li>Execution context batons</li>
- </ul>
- </div>
- <div class="postfooter"></div>
- </div>
- <a name="utility"></a>
- <div class="post">
- <h1 class ="postheader">Utility</h1>
- <div class="postcontent">
-
- <p>Utility files should be as stand alone as possible and
- available for LLDB, plug-ins or related
- applications to use.</p>
- <p>Files found in the Utility section include:</p>
- <ul>
- <li>Pseudo-terminal support</li>
- <li>Register numbering for specific architectures.</li>
- <li>String data extractors</li>
- </ul>
- </div>
- <div class="postfooter"></div>
- </div>
- </div>
- </div>
-</div>
-</body>
-</html>
Modified: lldb/trunk/www/architecture/index.html
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/architecture/index.html?rev=307072&r1=307071&r2=307072&view=diff
==============================================================================
--- lldb/trunk/www/architecture/index.html (original)
+++ lldb/trunk/www/architecture/index.html Tue Jul 4 05:29:34 2017
@@ -119,30 +119,26 @@
</div>
<a name="core"></a>
<div class="post">
- <h1 class ="postheader">Core</h1>
- <div class="postcontent">
-
- <p>The Core source files contain basic functionality that
- is required in the debugger. A wide variety of classes
- are implemented:</p>
-
- <ul>
- <li>Address (section offset addressing)</li>
- <li>AddressRange</li>
- <li>Architecture specification</li>
- <li>Broadcaster / Event / Listener </li>
- <li>Communication classes that use Connection objects</li>
- <li>Uniqued C strings</li>
- <li>Data extraction</li>
- <li>File specifications</li>
- <li>Mangled names</li>
- <li>Regular expressions</li>
- <li>Source manager</li>
- <li>Streams</li>
- <li>Value objects</li>
- </ul>
- </div>
- <div class="postfooter"></div>
+ <h1 class ="postheader">Core</h1>
+ <div class="postcontent">
+ <p>
+ The Core source files contain basic functionality
+ that is required in the debugger as well as the
+ class represeting the debugger it self (Debugger). A
+ wide variety of classes are implemented:
+ </p>
+ <ul>
+ <li>Address (section offset addressing)</li>
+ <li>AddressRange</li>
+ <li>Architecture specification</li>
+ <li>Broadcaster / Event / Listener </li>
+ <li>Communication classes that use Connection objects</li>
+ <li>Mangled names</li>
+ <li>Source manager</li>
+ <li>Value objects</li>
+ </ul>
+ </div>
+ <div class="postfooter"></div>
</div>
<a name="dataformatters"></a>
<div class="post">
@@ -193,26 +189,27 @@
</div>
<a name="host"></a>
<div class="post">
- <h1 class ="postheader">Host</h1>
- <div class="postcontent">
-
- <p>LLDB tries to abstract itself from the host upon which
- it is currently running by providing a host abstraction
- layer. This layer involves everything from spawning, detaching,
- joining and killing native in-process threads, to getting
- current information about the current host.</p>
- <p>Host functionality includes abstraction layers for:</p>
- <ul>
- <li>Mutexes</li>
- <li>Conditions</li>
- <li>Timing functions</li>
- <li>Thread functions</li>
- <li>Host target triple</li>
- <li>Host child process notifications</li>
- <li>Host specific types</li>
- </ul>
- </div>
- <div class="postfooter"></div>
+ <h1 class ="postheader">Host</h1>
+ <div class="postcontent">
+ <p>
+ LLDB tries to abstract itself from the host upon which
+ it is currently running by providing a host abstraction
+ layer. This layer includes functionality, whose
+ implementation varies wildly from host to host.
+ </p>
+ <p>Host functionality includes abstraction layers for:</p>
+ <ul>
+ <li>Information about the host system (triple, list of running processes, etc.)</li>
+ <li>Launching processes</li>
+ <li>Various OS primitives like pipes and sockets</li>
+ </ul>
+ <p>
+ It also includes the base classes of the
+ NativeProcess/Thread hierarchy, which is used by
+ lldb-server.
+ </p>
+ </div>
+ <div class="postfooter"></div>
</div>
<a name="interpreter"></a>
<div class="post">
@@ -259,20 +256,40 @@
</div>
<a name="utility"></a>
<div class="post">
- <h1 class ="postheader">Utility</h1>
- <div class="postcontent">
-
- <p>Utility files should be as stand alone as possible and
- available for LLDB, plug-ins or related
- applications to use.</p>
- <p>Files found in the Utility section include:</p>
- <ul>
- <li>Pseudo-terminal support</li>
- <li>Register numbering for specific architectures.</li>
- <li>String data extractors</li>
- </ul>
- </div>
- <div class="postfooter"></div>
+ <h1 class ="postheader">Utility</h1>
+ <div class="postcontent">
+ <p>
+ This module contains the lowest layers of LLDB. A
+ lot of these classes don't really have anything to
+ do with debugging -- they are just there because the
+ higher layers of the debugger use these clasess
+ to implement their functionality. Others are data
+ structures used in many other parts of the debugger
+ (TraceOptions). Most of the functionality in this
+ module could be useful in an application that is
+ <strong>not</strong> a debugger; however, providing
+ a general purpose C++ library is an explicit
+ non-goal of this module.
+ </p>
+ <p>
+ This module provides following functionality:
+ </p>
+ <ul>
+ <li>Abstract path manipulation (FileSpec)</li>
+ <li>Data buffers (DataBuffer, DataEncoder, DataExtractor)</li>
+ <li>Logging</li>
+ <li>Structured data manipulation (JSON)</li>
+ <li>Streams</li>
+ <li>Timers</li>
+ <li>etc.</li>
+ </ul>
+ <p>
+ For historic reasons, some of this functionality
+ overlaps that which is provided by the LLVM support
+ library.
+ </p>
+ </div>
+ <div class="postfooter"></div>
</div>
</div>
</div>
More information about the lldb-commits
mailing list