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> _______________________________________________ lldb-commits mailing list lldb-commits@lists.llvm.org http://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
