This is an archive of the discontinued LLVM Phabricator instance.

Update lldb architecture docs
ClosedPublic

Authored by labath on Jun 30 2017, 3:07 AM.

Download Raw Diff

Details

Reviewers

zturner
jingham

Commits

rG11b16c811011: Update lldb architecture docs
rLLDB307072: Update lldb architecture docs
rL307072: 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.

Diff Detail

Build Status

Buildable 7843
Build 7843: arc lint + arc unit

Event Timeline

labath created this revision.Jun 30 2017, 3:07 AM

Thanks!

This revision is now accepted and ready to land.Jul 3 2017, 9:59 AM

Closed by commit rL307072: Update lldb architecture docs (authored by labath). · Explain WhyJul 4 2017, 5:30 AM

This revision was automatically updated to reflect the committed changes.

Revision Contents

Path

Size

www/

architecture.html

architecture/

index.html

133 lines

Diff 104835

www/architecture.html

This file was deleted.

Property	Old Value	New Value
File Mode	100755	null

	<!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>

www/architecture/index.html

Show First 20 Lines • Show All 113 Lines • ▼ Show 20 Lines	<div id="middle">
tied into these objects and can extract the syntax and		tied into these objects and can extract the syntax and
option groupings to display appropriate help for each		option groupings to display appropriate help for each
command.</p>		command.</p>
</div>		</div>
<div class="postfooter"></div>		<div class="postfooter"></div>
</div>		</div>
<a name="core"></a>		<a name="core"></a>
<div class="post">		<div class="post">
<h1 class ="postheader">Core</h1>		<h1 class ="postheader">Core</h1>
<div class="postcontent">		<div class="postcontent">
		<p>
<p>The Core source files contain basic functionality that		The Core source files contain basic functionality
is required in the debugger. A wide variety of classes		that is required in the debugger as well as the
are implemented:</p>		class represeting the debugger it self (Debugger). A
		wide variety of classes are implemented:
		</p>
<ul>		<ul>
<li>Address (section offset addressing)</li>		<li>Address (section offset addressing)</li>
<li>AddressRange</li>		<li>AddressRange</li>
<li>Architecture specification</li>		<li>Architecture specification</li>
<li>Broadcaster / Event / Listener </li>		<li>Broadcaster / Event / Listener </li>
<li>Communication classes that use Connection objects</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>Mangled names</li>
<li>Regular expressions</li>
<li>Source manager</li>		<li>Source manager</li>
<li>Streams</li>
<li>Value objects</li>		<li>Value objects</li>
</ul>		</ul>
</div>		</div>
<div class="postfooter"></div>		<div class="postfooter"></div>
</div>		</div>
<a name="dataformatters"></a>		<a name="dataformatters"></a>
<div class="post">		<div class="post">
<h1 class ="postheader">DataFormatters</h1>		<h1 class ="postheader">DataFormatters</h1>
<div class="postcontent">		<div class="postcontent">

<p>A collection of classes that implement the data formatters subsystem.</p>		<p>A collection of classes that implement the data formatters subsystem.</p>
<p>Data formatters provide a set of user-tweakable hooks in the ValueObjects world that allow		<p>Data formatters provide a set of user-tweakable hooks in the ValueObjects world that allow
Show All 34 Lines	<div id="middle">
that contains simple opcodes that can be quickly re-evaluated		that contains simple opcodes that can be quickly re-evaluated
each time an expression needs to be evaluated, or JIT'ed		each time an expression needs to be evaluated, or JIT'ed
up into code that can be run on the process being debugged.</p>		up into code that can be run on the process being debugged.</p>
</div>		</div>
<div class="postfooter"></div>		<div class="postfooter"></div>
</div>		</div>
<a name="host"></a>		<a name="host"></a>
<div class="post">		<div class="post">
<h1 class ="postheader">Host</h1>		<h1 class ="postheader">Host</h1>
<div class="postcontent">		<div class="postcontent">
		<p>
<p>LLDB tries to abstract itself from the host upon which		LLDB tries to abstract itself from the host upon which
it is currently running by providing a host abstraction		it is currently running by providing a host abstraction
layer. This layer involves everything from spawning, detaching,		layer. This layer includes functionality, whose
joining and killing native in-process threads, to getting		implementation varies wildly from host to host.
current information about the current host.</p>		</p>
<p>Host functionality includes abstraction layers for:</p>		<p>Host functionality includes abstraction layers for:</p>
<ul>		<ul>
<li>Mutexes</li>		<li>Information about the host system (triple, list of running processes, etc.)</li>
<li>Conditions</li>		<li>Launching processes</li>
<li>Timing functions</li>		<li>Various OS primitives like pipes and sockets</li>
<li>Thread functions</li>
<li>Host target triple</li>
<li>Host child process notifications</li>
<li>Host specific types</li>
</ul>		</ul>
		<p>
		It also includes the base classes of the
		NativeProcess/Thread hierarchy, which is used by
		lldb-server.
		</p>
</div>		</div>
<div class="postfooter"></div>		<div class="postfooter"></div>
</div>		</div>
<a name="interpreter"></a>		<a name="interpreter"></a>
<div class="post">		<div class="post">
<h1 class ="postheader">Interpreter</h1>		<h1 class ="postheader">Interpreter</h1>
<div class="postcontent">		<div class="postcontent">

<p>The interpreter classes are the classes responsible for		<p>The interpreter classes are the classes responsible for
being the base classes needed for each command object,		being the base classes needed for each command object,
Show All 30 Lines	<div id="middle">
<li>ABI for function calling in process being debugged</li>		<li>ABI for function calling in process being debugged</li>
<li>Execution context batons</li>		<li>Execution context batons</li>
</ul>		</ul>
</div>		</div>
<div class="postfooter"></div>		<div class="postfooter"></div>
</div>		</div>
<a name="utility"></a>		<a name="utility"></a>
<div class="post">		<div class="post">
<h1 class ="postheader">Utility</h1>		<h1 class ="postheader">Utility</h1>
<div class="postcontent">		<div class="postcontent">
		<p>
<p>Utility files should be as stand alone as possible and		This module contains the lowest layers of LLDB. A
available for LLDB, plug-ins or related		lot of these classes don't really have anything to
applications to use.</p>		do with debugging -- they are just there because the
<p>Files found in the Utility section include:</p>		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>		<ul>
<li>Pseudo-terminal support</li>		<li>Abstract path manipulation (FileSpec)</li>
<li>Register numbering for specific architectures.</li>		<li>Data buffers (DataBuffer, DataEncoder, DataExtractor)</li>
<li>String data extractors</li>		<li>Logging</li>
		<li>Structured data manipulation (JSON)</li>
		<li>Streams</li>
		<li>Timers</li>
		<li>etc.</li>
</ul>		</ul>
		<p>
		For historic reasons, some of this functionality
		overlaps that which is provided by the LLVM support
		library.
		</p>
</div>		</div>
<div class="postfooter"></div>		<div class="postfooter"></div>
</div>		</div>
</div>		</div>
</div>		</div>
</div>		</div>
</body>		</body>
</html>		</html>