Blame - www/varformats.html - platform/external/lldb

2011-07-08 02:51:01 +0000

[diff] [blame]

</div>

</div>

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

613

<h1 class="postheader">Bitfields and array syntax</h1>

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

614

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

615

Sometimes, a basic type's value actually represents

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

616

several different values packed together in a bitfield.

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

617

With the classical view, there is no way to look at

618

them. Hexadecimal display can help, but if the bits

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

619

actually span nibble boundaries, the help is limited.

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

620

Binary view would show it all without ambiguity, but is

621

often too detailed and hard to read for real-life

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

622

scenarios.

623

624

To cope with the issue, LLDB supports native

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

625

bitfield formatting in summary strings. If your

626

expression paths leads to a so-called scalar type

627

(the usual int, float, char, double, short, long, long

628

long, double, long double and unsigned variants), you

629

can ask LLDB to only grab some bits out of the value and

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

630

display them in any format you like. If you only need one bit

631

you can use the <code>[</code>n<code>]</code>, just like

632

indexing an array. To extract multiple bits, you can use

633

a slice-like syntax: <code>[</code>n-m<code>]</code>, e.g.

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

634

<code> (lldb) frame variable float_point

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

635

(float) float_point = -3.14159 </code>

636

637

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

638

(lldb) type summary add --summary-string "Sign: ${var[31]%B}

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

639

Exponent: ${var[30-23]%x} Mantissa: ${var[0-22]%u}"

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

640

float

641

</td>

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

642

</table> </code>

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

643

644

<code>

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

645

(lldb) frame variable float_point

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

646

(float) float_point = -3.14159 Sign: true Exponent:

647

0x00000080 Mantissa: 4788184

648

</code> In this example, LLDB shows the internal

649

representation of a <code>float</code> variable by

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

650

extracting bitfields out of a float object.

651

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

652

When typing a range, the extremes n and m are always

653

included, and the order of the indices is irrelevant.

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

654

655

LLDB also allows to use a similar syntax to display

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

656

array members inside a summary string. For instance, you

657

may want to display all arrays of a given type using a

658

more compact notation than the default, and then just

659

delve into individual array members that prove

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

660

interesting to your debugging task. You can tell

661

LLDB to format arrays in special ways, possibly

662

independent of the way the array members' datatype is formatted.

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

663

e.g.

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

664

<code> (lldb) frame variable sarray

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

665

(Simple [3]) sarray = {

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

[0] = {

x = 1

y = 2

z = '\x03'

}

[1] = {

x = 4

y = 5

z = '\x06'

}

[2] = {

x = 7

y = 8

z = '\t'

}

} </code>

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

685

(lldb) type summary add --summary-string "${var[].x}" "Simple

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

[3]"

</td>

<table>

<code>

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

691

(lldb) frame variable sarray

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

692

(Simple [3]) sarray = [1,4,7] </code>

693

694

The <code>[]</code> symbol amounts to: if <code>var</code>

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

695

is an array and I know its size, apply this summary

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

696

string to every element of the array. Here, we are

697

asking LLDB to display <code>.x</code> for every

698

element of the array, and in fact this is what happens.

699

If you find some of those integers anomalous, you can

700

then inspect that one item in greater detail, without

701

the array format getting in the way:

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

702

<code> (lldb) frame variable sarray[1]

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

703

(Simple) sarray[1] = {

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

704

x = 4

705

y = 5

706

z = '\x06'

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

707

}

708

</code>

709

You can also ask LLDB to only print a subset of the

710

array range by using the same syntax used to extract bit

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

for bitfields:

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

714

(lldb) type summary add --summary-string "${var[1-2].x}" "Simple

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

[3]"

</td>

<table>

<code>

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

719

(lldb) frame variable sarray

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

720

(Simple [3]) sarray = [4,7] </code>

721

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

722

If you are dealing with a pointer that you know is an array, you can use this

723

syntax to display the elements contained in the pointed array instead of just

724

the pointer value. However, because pointers have no notion of their size, the

725

empty brackets <code>[]</code> operator does not work, and you must explicitly provide

726

higher and lower bounds.

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

727

728

In general, LLDB needs the square brackets operator <code>[]</code> in

729

order to handle arrays and pointers correctly, and for pointers it also

730

needs a range. However, a few special cases are defined to make your life easier:

731

<ul>

732

<li>you can print a 0-terminated string (C-string) using the %s format,

733

omitting square brackets, as in:

734

735

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

736

(lldb) type summary add --summary-string "${var%s}" "char *"

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

737

</td>

738

<table>

Enrico Granata

de51233

2011-08-24 01:49:09 +0000

[diff] [blame]

739

740

This syntax works for <code>char*</code> as well as for <code>char[]</code>

741

because LLDB can rely on the final <code>\0</code> terminator to know when the string

742

has ended.

743

LLDB has default summary strings for <code>char*</code> and <code>char[]</code> that use

744

this special case. On debugger startup, the following are defined automatically:

745

746

747

(lldb) type summary add --summary-string "${var%s}" "char *"

748

(lldb) type summary add --summary-string "${var%s}" -x "char \[[0-9]+]"

</td>

<table>

</li>

</ul>

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

753

<ul>

754

Enrico Granata

de51233

2011-08-24 01:49:09 +0000

[diff] [blame]

755

<li>any of the array formats (<code>int8_t[]</code>,

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

756

<code>float32{}</code>, ...), and the <code>y</code>, <code>Y</code>

757

and <code>a</code> formats

758

work to print an array of a non-aggregate

759

type, even if square brackets are omitted.

760

761

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

762

(lldb) type summary add --summary-string "${var%int32_t[]}" "int [10]"

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

</td>

<table>

</ul>

This feature, however, is not enabled for pointers because there is no

768

way for LLDB to detect the end of the pointed data.

769

770

This also does not work for other formats (e.g. <code>boolean</code>), and you must

771

specify the square brackets operator to get the expected output.

</div>

</div>

Enrico Granata

2011-07-19 02:34:21 +0000

[diff] [blame]

777

<h1 class="postheader">Python scripting</h1>

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

778

Enrico Granata

2011-07-19 02:34:21 +0000

[diff] [blame]

779

780

Most of the times, summary strings prove good enough for the job of summarizing

781

the contents of a variable. However, as soon as you need to do more than picking

782

some values and rearranging them for display, summary strings stop being an

783

effective tool. This is because summary strings lack the power to actually perform

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

784

any kind of computation on the value of variables.

Enrico Granata

2011-07-19 02:34:21 +0000

[diff] [blame]

785

To solve this issue, you can bind some Python scripting code as a summary for

786

your datatype, and that script has the ability to both extract children variables

787

as the summary strings do and to perform active computation on the extracted

788

values. As a small example, let's say we have a Rectangle class:

789

790

<code>

Enrico Granata

2011-09-08 00:50:01 +0000

[diff] [blame]

791

class Rectangle

Enrico Granata

2011-07-19 02:34:21 +0000

[diff] [blame]

792

{

Enrico Granata

2011-09-08 00:50:01 +0000

[diff] [blame]

private:

int height;

int width;

public:

Enrico Granata

2011-07-19 02:34:21 +0000

[diff] [blame]

797

Rectangle() : height(3), width(5) {}

Enrico Granata

2011-09-08 00:50:01 +0000

[diff] [blame]

798

Rectangle(int H) : height(H), width(H*2-1) {}

799

Rectangle(int H, int W) : height(H), width(W) {}

Enrico Granata

2011-07-19 02:34:21 +0000

[diff] [blame]

800

Enrico Granata

2011-09-08 00:50:01 +0000

[diff] [blame]

801

int GetHeight() { return height; }

802

int GetWidth() { return width; }

Enrico Granata

2011-07-19 02:34:21 +0000

[diff] [blame]

};

</code>

Summary strings are effective to reduce the screen real estate used by

808

the default viewing mode, but are not effective if we want to display the

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

809

area and perimeter of <code>Rectangle</code> objects

Enrico Granata

2011-07-19 02:34:21 +0000

[diff] [blame]

810

811

To obtain this, we can simply attach a small Python script to the <code>Rectangle</code>

812

class, as shown in this example:

(lldb) type summary add -P Rectangle

817

Enter your Python command(s). Type 'DONE' to end.

Enrico Granata

2012-08-08 02:06:30 +0000

[diff] [blame]

818

def function (valobj,internal_dict):

Enrico Granata

2011-07-19 02:34:21 +0000

[diff] [blame]

819

height_val = valobj.GetChildMemberWithName('height')

820

width_val = valobj.GetChildMemberWithName('width')

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

821

height = height_val.GetValueAsUnsigned(0)

822

width = width_val.GetValueAsUnsigned(0)

Enrico Granata

2011-07-19 02:34:21 +0000

[diff] [blame]

823

area = height*width

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

824

perimeter = 2*(height + width)

825

return 'Area: ' + str(area) + ', Perimeter: ' + str(perimeter)

Enrico Granata

2011-07-19 02:34:21 +0000

[diff] [blame]

826

DONE

Enrico Granata

2011-07-19 02:34:21 +0000

[diff] [blame]

827

(lldb) frame variable

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

828

(Rectangle) r1 = Area: 20, Perimeter: 18

829

(Rectangle) r2 = Area: 72, Perimeter: 36

830

(Rectangle) r3 = Area: 16, Perimeter: 16

Enrico Granata

2011-07-19 02:34:21 +0000

[diff] [blame]

</td>

</table>

Enrico Granata

2011-07-19 02:34:21 +0000

[diff] [blame]

834

In order to write effective summary scripts, you need to know the LLDB public

835

API, which is the way Python code can access the LLDB object model. For further

836

details on the API you should look at <a href="scripting.html">this page</a>, or at

Daniel Malea

5c94013

2013-07-19 17:33:02 +0000

[diff] [blame]

837

the LLDB <a href="docs.html">API reference documentation</a>.

Enrico Granata

2011-07-19 02:34:21 +0000

[diff] [blame]

838

839

As a brief introduction, your script is encapsulated into a function that is

Enrico Granata

2012-08-08 02:06:30 +0000

[diff] [blame]

840

passed two parameters: <code>valobj</code> and <code>internal_dict</code>.

Enrico Granata

2011-07-19 02:34:21 +0000

[diff] [blame]

841

Enrico Granata

2012-08-08 02:06:30 +0000

[diff] [blame]

842

<code>internal_dict</code> is an internal support parameter used by LLDB and you should

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

843

not touch it. <code>valobj</code> is the object encapsulating the actual

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

844

variable being displayed, and its type is <a href="http://llvm.org/svn/llvm-project/lldb/trunk/include/lldb/API/SBValue.h">SBValue</a>.

845

Out of the many possible operations on an SBValue, the basic one is retrieve the children objects

846

it contains (essentially, the fields of the object wrapped by it), by calling

847

<code>GetChildMemberWithName()</code>, passing it the child's name as a string.

848

If the variable has a value, you can ask for it, and return it as a string using <code>GetValue()</code>,

849

or as a signed/unsigned number using <code>GetValueAsSigned()</code>, <code>GetValueAsUnsigned()</code>.

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

850

It is also possible to retrieve an <a href="http://llvm.org/svn/llvm-project/lldb/trunk/include/lldb/API/SBData.h"><code>SBData</code></a> object by calling <code>GetData()</code> and then read

851

the object's contents out of the <code>SBData</code>.

Enrico Granata

2011-07-19 02:34:21 +0000

[diff] [blame]

852

853

If you need to delve into several levels of hierarchy, as you can do with summary

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

854

strings, you can use the method <code>GetValueForExpressionPath()</code>, passing it

Enrico Granata

2011-08-24 17:12:47 +0000

[diff] [blame]

855

an expression path just like those you could use for summary strings (one of the differences

856

is that dereferencing a pointer does not occur by prefixing the path with a <code>*</code>,

857

but by calling the <code>Dereference()</code> method on the returned SBValue).

858

If you need to access array slices, you cannot do that (yet) via this method call, and you must

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

859

use <code>GetChildAtIndex()</code> querying it for the array items one by one.

Enrico Granata

2011-08-24 17:12:47 +0000

[diff] [blame]

860

Also, handling custom formats is something you have to deal with on your own.

Enrico Granata

2011-07-19 02:34:21 +0000

[diff] [blame]

861

862

Other than interactively typing a Python script there are two other ways for you

863

to input a Python script as a summary:

864

865

<ul>

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

866

<li> using the --python-script option to <code>type summary add </code> and typing the script

Enrico Granata

2011-07-19 02:34:21 +0000

[diff] [blame]

867

code as an option argument; as in: </ul>

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

871

(lldb) type summary add --python-script "height =

Enrico Granata

2013-05-31 22:54:23 +0000

[diff] [blame]

872

valobj.GetChildMemberWithName('height').GetValueAsUnsigned(0);width =

873

valobj.GetChildMemberWithName('width').GetValueAsUnsigned(0);

874

return 'Area: %d' % (height*width)" Rectangle

Enrico Granata

2011-07-19 02:34:21 +0000

[diff] [blame]

875

</td>

876

</table>

877

<ul>

Enrico Granata

2011-08-24 17:12:47 +0000

[diff] [blame]

878

<li> using the <code>--python-function</code> (<code>-F</code>) option to <code>type summary add </code> and giving the name of a

Enrico Granata

2011-07-19 02:34:21 +0000

[diff] [blame]

879

Python function with the correct prototype. Most probably, you will define (or have

880

already defined) the function in the interactive interpreter, or somehow

Enrico Granata

2013-05-31 22:54:23 +0000

[diff] [blame]

881

loaded it from a file, using the <code>command script import</code> command. LLDB will emit a warning if it is unable to find the function you passed, but will still register the binding.

Enrico Granata

2011-07-19 02:34:21 +0000

[diff] [blame]

</ul>

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

</div>

</div>

Enrico Granata

2011-07-19 02:34:21 +0000

[diff] [blame]

889

890

<h1 class="postheader">Regular expression typenames</h1>

891

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

892

As you noticed, in order to associate the custom

893

summary string to the array types, one must give the

894

array size as part of the typename. This can long become

895

tiresome when using arrays of different sizes, <code>Simple

896

897

[3]</code>, <code>Simple [9]</code>, <code>Simple

898

[12]</code>, ...

899

If you use the <code>-x</code> option, type names are

900

treated as regular expressions instead of type names.

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

901

This would let you rephrase the above example

902

for arrays of type <code>Simple [3]</code> as:

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

906

(lldb) type summary add --summary-string "${var[].x}"

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

907

-x "Simple \[[0-9]+\]"

</td>

<table>

<code>

Enrico Granata

2013-05-31 22:54:23 +0000

[diff] [blame]

912

(lldb) frame variable

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

913

(Simple [3]) sarray = [1,4,7]

Enrico Granata

2013-05-31 22:54:23 +0000

[diff] [blame]

914

(Simple [2]) sother = [3,6]

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

915

</code> The above scenario works for <code>Simple [3]</code>

916

as well as for any other array of <code>Simple</code>

917

objects.

918

While this feature is mostly useful for arrays, you

919

could also use regular expressions to catch other type

920

sets grouped by name. However, as regular expression

921

matching is slower than normal name matching, LLDB will

922

first try to match by name in any way it can, and only

923

when this fails, will it resort to regular expression

Enrico Granata

2013-05-31 22:54:23 +0000

[diff] [blame]

924

matching.

Enrico Granata

2011-08-24 17:12:47 +0000

[diff] [blame]

925

One of the ways LLDB uses this feature internally, is to match

926

the names of STL container classes, regardless of the template

Enrico Granata

2013-05-31 22:54:23 +0000

[diff] [blame]

927

arguments provided. The details for this are found at <a href="http://llvm.org/svn/llvm-project/lldb/trunk/source/DataFormatters/FormatManager.cpp">FormatManager.cpp</a>

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

928

Enrico Granata

2011-08-24 17:12:47 +0000

[diff] [blame]

929

The regular expression language used by LLDB is the <a href="http://en.wikipedia.org/wiki/Regular_expression#POSIX_Extended_Regular_Expressions">POSIX extended language</a>, as defined by the <a href="http://pubs.opengroup.org/onlinepubs/7908799/xsh/regex.h.html">Single UNIX Specification</a>, of which Mac OS X is a

930

compliant implementation.

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

931

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

932

</div>

933

</div>

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

934

935

936

<h1 class="postheader">Named summaries</h1>

937

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

938

For a given type, there may be different meaningful summary

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

939

representations. However, currently, only one summary can be associated

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

940

to a type at each moment. If you need to temporarily override the association

941

for a variable, without changing the summary string for to its type,

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

942

you can use named summaries.

943

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

944

Named summaries work by attaching a name to a summary when creating

945

it. Then, when there is a need to attach the summary to a variable, the

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

946

<code>frame variable</code> command, supports a <code>--summary</code> option

947

that tells LLDB to use the named summary given instead of the default one.

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

951

(lldb) type summary add --summary-string "x=${var.integer}" --name NamedSummary

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

952

</td>

953

<table>

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

954

<code> (lldb) frame variable one

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

955

(i_am_cool) one = int = 3, float = 3.14159, char = 69

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

956

(lldb) frame variable one --summary NamedSummary

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

957

(i_am_cool) one = x=3

958

</code>

959

Enrico Granata

f7a9b14

2011-07-15 02:26:42 +0000

[diff] [blame]

960

When defining a named summmary, binding it to one or more types becomes optional.

961

Even if you bind the named summary to a type, and later change the summary string

962

for that type, the named summary will not be changed by that. You can delete

963

named summaries by using the <code>type summary delete</code> command, as if the

964

summary name was the datatype that the summary is applied to

965

966

A summary attached to a variable using the </code>--summary</code> option,

967

has the same semantics that a custom format attached using the <code>-f</code>

968

option has: it stays attached till you attach a new one, or till you let

969

your program run again.

970

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

</div>

</div>

Enrico Granata

2011-08-22 16:10:25 +0000

[diff] [blame]

974

975

<h1 class="postheader">Synthetic children</h1>

976

977

Summaries work well when one is able to navigate through an expression path.

978

In order for LLDB to do so, appropriate debugging information must be available.

979

Some types are opaque, i.e. no knowledge of their internals is provided.

980

When that's the case, expression paths do not work correctly.

981

In other cases, the internals are available to use in expression paths, but they

982

do not provide a user-friendly representation of the object's value.

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

983

For instance, consider an STL vector, as implemented by the <a href="http://gcc.gnu.org/onlinedocs/libstdc++/">GNU C++ Library</a>:

Enrico Granata

2011-08-22 16:10:25 +0000

[diff] [blame]

984

<code>

985

(lldb) frame variable numbers -T

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

986

(std::vector<int>) numbers = {

987

(std::_Vector_base<int, std::allocator<int> >) std::_Vector_base<int, std::allocator<int> > = {

988

(std::_Vector_base<int, std::allocator&tl;int> >::_Vector_impl) _M_impl = {

Enrico Granata

2011-08-22 16:10:25 +0000

[diff] [blame]

989

(int *) _M_start = 0x00000001001008a0

990

(int *) _M_finish = 0x00000001001008a8

991

(int *) _M_end_of_storage = 0x00000001001008a8

}

}

}

</code>

Here, you can see how the type is implemented, and you can write a summary for that implementation

997

but that is not going to help you infer what items are actually stored in the vector.

998

What you would like to see is probably something like:

999

<code>

1000

(lldb) frame variable numbers -T

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

1001

(std::vector<int>) numbers = {

Enrico Granata

2011-08-22 16:10:25 +0000

[diff] [blame]

(int) [0] = 1

(int) [1] = 12

(int) [2] = 123

(int) [3] = 1234

}

</code>

Synthetic children are a way to get that result.

1009

The feature is based upon the idea of providing a new set of children for a variable that replaces the ones

1010

available by default through the debug information. In the example, we can use synthetic children to provide

1011

the vector items as children for the std::vector object.

1012

In order to create synthetic children, you need to provide a Python class that adheres to a given interface

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

1013

(the word is italicized because <a href="http://en.wikipedia.org/wiki/Duck_typing">Python has no explicit notion of interface</a>, by that word we mean a given set of methods

Enrico Granata

2011-08-22 16:10:25 +0000

[diff] [blame]

1014

must be implemented by the Python class):

1015

<code>

1016

class SyntheticChildrenProvider:

Enrico Granata

2012-08-08 02:06:30 +0000

[diff] [blame]

1017

def __init__(self, valobj, internal_dict):

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

1018

this call should initialize the Python object using valobj as the variable to provide synthetic children for

Enrico Granata

2011-08-22 16:10:25 +0000

[diff] [blame]

1019

def num_children(self):

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

1020

this call should return the number of children that you want your object to have

Enrico Granata

2011-08-22 16:10:25 +0000

[diff] [blame]

1021

def get_child_index(self,name):

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

1022

this call should return the index of the synthetic child whose name is given as argument

Enrico Granata

2011-08-22 16:10:25 +0000

[diff] [blame]

1023

def get_child_at_index(self,index):

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

1024

this call should return a new LLDB SBValue object representing the child at the index given as argument

Enrico Granata

2011-08-22 16:10:25 +0000

[diff] [blame]

1025

def update(self):

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

1026

this call should be used to update the internal state of this Python object whenever the state of the variables in LLDB changes.[1]

Enrico Granata

251729e

2012-10-24 01:23:57 +0000

[diff] [blame]

1027

def has_children(self):

1028

this call should return True if this object might have children, and False if this object can be guaranteed not to have children.[2]

Enrico Granata

2011-08-22 16:10:25 +0000

[diff] [blame]

1029

</code>

Enrico Granata

2013-05-31 22:54:23 +0000

[diff] [blame]

1030

[1] This method is optional. Also, it may optionally choose to return a value (starting with SVN rev153061/LLDB-134). If it returns a value, and that value is <code>True</code>, LLDB will be allowed to cache the children and the children count it previously obtained, and will not return to the provider class to ask. If nothing, <code>None</code>, or anything other than <code>True</code> is returned, LLDB will discard the cached information and ask. Regardless, whenever necessary LLDB will call <code>update</code>.

Enrico Granata

251729e

2012-10-24 01:23:57 +0000

[diff] [blame]

1031

Enrico Granata

2013-05-31 22:54:23 +0000

[diff] [blame]

1032

[2] This method is optional (starting with SVN rev166495/LLDB-175). While implementing it in terms of <code>num_children</code> is acceptable, implementors are encouraged to look for optimized coding alternatives whenever reasonable.

1033

For examples of how synthetic children are created, you are encouraged to look at <a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/synthetic/">examples/synthetic</a> in the LLDB trunk. Please, be aware that the code in those files (except bitfield/)

1034

is legacy code and is not maintained.

Enrico Granata

415bb57

2012-03-17 02:04:20 +0000

[diff] [blame]

1035

You may especially want to begin looking at <a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/synthetic/bitfield">this example</a> to get

1036

a feel for this feature, as it is a very easy and well commented example.

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

1037

The design pattern consistently used in synthetic providers shipping with LLDB

1038

is to use the <code>__init__</code> to store the SBValue instance as a part of <code>self</code>. The <code>update</code> function is then used

1039

to perform the actual initialization.

1040

1041

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

1042

Once a synthetic children provider is written, one must load it into LLDB before it can be used.

1043

Currently, one can use the LLDB <code>script</code> command to type Python code interactively,

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

1044

or use the <code>command script import fileName </code> command to load Python code from a Python module

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

1045

(ordinary rules apply to importing modules this way). A third option is to type the code for

1046

the provider class interactively while adding it.

1047

Enrico Granata

2011-08-24 17:12:47 +0000

[diff] [blame]

1048

For example, let's pretend we have a class <code>Foo</code> for which a synthetic children provider class

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

1049

<code>Foo_Provider</code> is available, in a Python module contained in file <code>~/Foo_Tools.py</code>. The following interaction

Enrico Granata

2011-08-24 17:12:47 +0000

[diff] [blame]

1050

sets <code>Foo_Provider</code> as a synthetic children provider in LLDB:

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

1054

(lldb) command script import ~/Foo_Tools.py

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

1055

(lldb) type synthetic add Foo --python-class Foo_Tools.Foo_Provider

1056

</td>

1057

<table>

1058

<code> (lldb) frame variable a_foo

(Foo) a_foo = {

x = 1

y = "Hello world"

}

</code>

Enrico Granata

2013-05-31 22:54:23 +0000

[diff] [blame]

1065

LLDB has synthetic children providers for a core subset of STL classes, both in the version provided by <a href="http://gcc.gnu.org/libstdc++/">libstdcpp</a> and by <a href="http://libcxx.llvm.org/">libcxx</a>, as well as for several Foundation classes.

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

1066

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

1067

Synthetic children extend summary strings by enabling a new special variable: <code>${svar</code>.

1068

This symbol tells LLDB to refer expression paths to the

1069

synthetic children instead of the real ones. For instance,

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

(lldb) type summary add --expand -x "std::vector<" --summary-string "${svar%#} items"

1074

</td>

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

1075

</table>

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

1076

<code> (lldb) frame variable numbers

1077

(std::vector<int>) numbers = 4 items {

(int) [0] = 1

(int) [1] = 12

(int) [2] = 123

(int) [3] = 1234

}

</code>

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

1084

In some cases, if LLDB is unable to use the real object to get a child specified in an expression path, it will automatically refer to the

1085

synthetic children. While in summaries it is best to always use <code>${svar</code> to make your intentions clearer, interactive debugging

1086

can benefit from this behavior, as in:

1087

<code> (lldb) frame variable numbers[0] numbers[1]

1088

(int) numbers[0] = 1

1089

(int) numbers[1] = 12

1090

</code>

1091

Unlike many other visualization features, however, the access to synthetic children only works when using <code>frame variable</code>, and is

1092

not supported in <code>expression</code>:

1093

<code> (lldb) expression numbers[0]

1094

Error [IRForTarget]: Call to a function '_ZNSt33vector<int, std::allocator<int> >ixEm' that is not present in the target

1095

error: Couldn't convert the expression to DWARF

1096

</code>

1097

The reason for this is that classes might have an overloaded <code>operator []</code>, or other special provisions

Enrico Granata

2013-05-31 22:54:23 +0000

[diff] [blame]

1098

and the <code>expression</code> command chooses to ignore synthetic children in the interest of equivalency with code you asked to have compiled from source.

Enrico Granata

2011-08-22 16:10:25 +0000

[diff] [blame]

1099

</div>

1100

</div>

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

1101

1102

1103

<h1 class="postheader">Filters</h1>

1104

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

1105

Filters are a solution to the display of complex classes.

1106

At times, classes have many member variables but not all of these are actually

1107

necessary for the user to see.

1108

A filter will solve this issue by only letting the user see those member

1109

variables he cares about. Of course, the equivalent of a filter can be implemented easily

1110

using synthetic children, but a filter lets you get the job done without having to write

1111

Python code.

1112

For instance, if your class <code>Foobar</code> has member variables named <code>A</code> thru <code>Z</code>, but you only need to see

1113

the ones named <code>B</code>, <code>H</code> and <code>Q</code>, you can define a filter:

1114

1115

Enrico Granata

2011-08-24 17:12:47 +0000

[diff] [blame]

1116

(lldb) type filter add Foobar --child B --child H --child Q

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

1117

</td>

Enrico Granata

2011-08-24 04:53:31 +0000

[diff] [blame]

1118

</table>

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

1119

<code> (lldb) frame variable a_foobar

1120

(Foobar) a_foobar = {

1121

(int) B = 1

1122

(char) H = 'H'

1123

(std::string) Q = "Hello world"

1124

}

1125

</code>

Enrico Granata

2011-08-24 04:53:31 +0000

[diff] [blame]

</div>

</div>

<h1 class="postheader">Objective-C dynamic type discovery</h1>

1131

1132

When doing Objective-C development, you may notice that some of your variables

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

1133

come out as of type <code>id</code> (for instance, items extracted from <code>NSArray</code>).

Enrico Granata

2013-05-31 22:54:23 +0000

[diff] [blame]

1134

By default, LLDB will not show you the real type of the object. it can actually dynamically discover the type of an Objective-C

Enrico Granata

2011-08-24 04:53:31 +0000

[diff] [blame]

1135

variable, much like the runtime itself does when invoking a selector. In order

Enrico Granata

2013-05-31 22:54:23 +0000

[diff] [blame]

1136

to be shown the result of that discovery that, however, a special option to <code>frame variable</code> or <code>expression</code> is

1137

required: <code>--dynamic-type</code>.

Enrico Granata

2011-08-24 04:53:31 +0000

[diff] [blame]

1138

<code>--dynamic-type</code> can have one of three values:

1139

<ul>

1140

<li><code>no-dynamic-values</code>: the default, prevents dynamic type discovery</li>

1141

<li><code>no-run-target</code>: enables dynamic type discovery as long as running

1142

code on the target is not required</li>

1143

<li><code>run-target</code>: enables code execution on the target in order to perform

1144

dynamic type discovery</li>

</ul>

If you specify a value of either <code>no-run-target</code> or <code>run-target</code>,

1149

LLDB will detect the dynamic type of your variables and show the appropriate formatters

1150

for them. As an example:

Enrico Granata

2013-05-31 22:54:23 +0000

[diff] [blame]

1154

(lldb) expr @"Hello"

Enrico Granata

2011-08-24 04:53:31 +0000

[diff] [blame]

1155

</td>

1156

</table>

Enrico Granata

2013-05-31 22:54:23 +0000

[diff] [blame]

1157

<code>(NSString *) $0 = 0x00000001048000b0 @"Hello"

</code>

(lldb) expr -d no-run @"Hello"

1162

</td>

1163

</table>

1164

<code>(__NSCFString *) $1 = 0x00000001048000b0 @"Hello"

Enrico Granata

2011-08-24 04:53:31 +0000

[diff] [blame]

1165

</code>

1166

1167

Because LLDB uses a detection algorithm that does not need to invoke any functions

Enrico Granata

2013-05-31 22:54:23 +0000

[diff] [blame]

1168

on the target process, <code>no-run-target</code> is enough for this to work.

1169

As a side note, the summary for NSString shown in the example is built right into LLDB.

1170

It was initially implemented through Python (the code is still available for reference at <a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/summaries/cocoa/CFString.py">CFString.py</a>).

Enrico Granata

5e536c4

2013-02-20 02:24:20 +0000

[diff] [blame]

1171

However, this is out of sync with the current implementation of the NSString formatter (which is a C++ function compiled into the LLDB core).

Enrico Granata

2011-08-24 04:53:31 +0000

[diff] [blame]

1172

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

</div>

</div>

Enrico Granata

2011-08-24 01:32:46 +0000

[diff] [blame]

1176

1177

<h1 class="postheader">Categories</h1>

1178

1179

Categories are a way to group related formatters. For instance, LLDB itself groups

Enrico Granata

2013-05-31 22:54:23 +0000

[diff] [blame]

1180

the formatters for the libstdc++ types in a category named <code>gnu-libstdc++</code>.

Enrico Granata

2011-08-24 01:32:46 +0000

[diff] [blame]

1181

Basically, categories act like containers in which to store formatters for a same library

1182

or OS release.

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

1183

By default, several categories are created in LLDB:

1184

<ul>

Enrico Granata

2012-05-02 21:13:16 +0000

[diff] [blame]

1185

<li><code>default</code>: this is the category where every formatter ends up, unless another category is specified

1186

<li><code>objc</code>: formatters for basic and common Objective-C types that do not specifically depend on Mac OS X

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

1187

<li><code>gnu-libstdc++</code>: formatters for std::string, std::vector, std::list and std::map as implemented by libstdcpp

Enrico Granata

2012-05-02 21:13:16 +0000

[diff] [blame]

1188

<li><code>libcxx</code>: formatters for std::string, std::vector, std::list and std::map as implemented by <a href="http://libcxx.llvm.org/">libcxx</a>

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

1189

<li><code>system</code>: truly basic types for which a formatter is required

Enrico Granata

2012-05-02 21:13:16 +0000

[diff] [blame]

1190

<li><a href="https://developer.apple.com/library/mac/#documentation/Cocoa/Reference/Foundation/ObjC_classic/_index.html#//apple_ref/doc/uid/20001091"><code>AppKit</code></a>: Cocoa classes

1191

<li><a href="https://developer.apple.com/corefoundation/"><code>CoreFoundation</code></a>: CF classes

1192

<li><a href="https://developer.apple.com/library/mac/#documentation/CoreGraphics/Reference/CoreGraphicsConstantsRef/Reference/reference.html"><code>CoreGraphics</code></a>: CG classes

1193

<li><a href="http://developer.apple.com/library/mac/#documentation/Carbon/reference/CoreServicesReferenceCollection/_index.html"><code>CoreServices</code></a>: CS classes

1194

<li><code>VectorTypes</code>: compact display for several vector types

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

1195

</ul>

Enrico Granata

2011-08-24 01:32:46 +0000

[diff] [blame]

1196

If you want to use a custom category for your formatters, all the <code>type ... add</code> (except for <code>type format add</code>),

1197

provide a <code>--category</code> (<code>-w</code>) option, that names the category to add the formatter to.

1198

To delete the formatter, you then have to specify the correct category.

1199

Categories can be in one of two states: enabled and disabled. A category is initially disabled,

1200

and can be enabled using the <code>type category enable</code> command. To disable an enabled category,

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

1201

the command to use is <code>type category disable</code>.

1202

The order in which categories are enabled or disabled

Enrico Granata

2011-08-24 01:32:46 +0000

[diff] [blame]

1203

is significant, in that LLDB uses that order when looking for formatters. Therefore, when you enable a category, it becomes

Enrico Granata

2012-05-02 21:13:16 +0000

[diff] [blame]

1204

the second one to be searched (after <code>default</code>, which always stays on top of the list). The default categories are enabled in such a way that the search order is:

<ul>

<li>default</li>

<li>CoreFoundation</li>

1209

<li>AppKit</li>

1210

<li>CoreServices</li>

1211

<li>CoreGraphics</li>

1212

<li>gnu-libstdc++</li>

<li>libcxx</li>

<li>VectorTypes</li>

<li>system</li>

</ul>

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

1217

As said, <code>gnu-libstdc++</code> and <code>libcxx</code> contain formatters for C++ STL

Enrico Granata

2011-09-08 00:50:01 +0000

[diff] [blame]

1218

data types. <code>system</code> contains formatters for <code>char*</code> and <code>char[]</code>, which reflect the behavior

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

1219

of older versions of LLDB which had built-in formatters for these types. Because now these are formatters, you can even

Enrico Granata

2011-09-08 00:50:01 +0000

[diff] [blame]

1220

replace them with your own if so you wish.

Enrico Granata

2011-08-24 17:12:47 +0000

[diff] [blame]

1221

There is no special command to create a category. When you place a formatter in a category, if that category does not

1222

exist, it is automatically created. For instance,

1223

1224

1225

(lldb) type summary add Foobar --summary-string "a foobar" --category newcategory

1226

</td>

1227

</table>

1228

automatically creates a (disabled) category named newcategory.

1229

Another way to create a new (empty) category, is to enable it, as in:

1230

1231

1232

(lldb) type category enable newcategory

1233

</td>

1234

</table>

1235

However, in this case LLDB warns you that enabling an empty category has no effect. If you add formatters to the

1236

category after enabling it, they will be honored. But an empty category per se does not change the way any

1237

type is displayed. The reason the debugger warns you is that enabling an empty category might be a typo, and you

1238

effectively wanted to enable a similarly-named but not-empty category.

Enrico Granata

2011-08-24 01:32:46 +0000

[diff] [blame]

</div>

</div>

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

1242

Enrico Granata

2011-08-22 16:10:25 +0000

[diff] [blame]

1243

<h1 class="postheader">Finding formatters 101</h1>

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

1244

1245

While the rules for finding an appropriate format for a

1246

type are relatively simple (just go through typedef

Enrico Granata

2011-08-24 17:12:47 +0000

[diff] [blame]

1247

hierarchies), searching other formatters goes through

Enrico Granata

2011-08-24 01:32:46 +0000

[diff] [blame]

1248

a rather intricate set of rules. Namely, what happens is that LLDB

1249

starts looking in each enabled category, according to the order in which

1250

they were enabled (latest enabled first). In each category, LLDB does

1251

the following:

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

1252

<ul>

Enrico Granata

2011-08-22 16:10:25 +0000

[diff] [blame]

1253

<li>If there is a formatter for the type of the variable,

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

1254

use it</li>

Enrico Granata

2011-08-22 16:10:25 +0000

[diff] [blame]

1255

<li>If this object is a pointer, and there is a formatter

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

1256

for the pointee type that does not skip pointers, use

1257

it</li>

1258

<li>If this object is a reference, and there is a

Enrico Granata

2011-09-08 00:50:01 +0000

[diff] [blame]

1259

formatter for the referred type that does not skip

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

1260

references, use it</li>

Enrico Granata

f2cb7f2

2012-03-22 19:55:55 +0000

[diff] [blame]

1261

<li>If this object is an Objective-C class and dynamic types are enabled,

1262

look for a formatter for the dynamic type of the object. If dynamic types are disabled,

1263

or the search failed, look for a formatter for the declared type of the object</li>

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

1264

<li>If this object's type is a typedef, go through

Enrico Granata

86e7c3e

2011-07-12 22:56:10 +0000

[diff] [blame]

1265

typedef hierarchy (LLDB might not be able to do this if

1266

the compiler has not emitted enough information. If the

1267

required information to traverse typedef hierarchies is

1268

missing, type cascading will not work. The

1269

<a href="http://clang.llvm.org/">clang compiler</a>,

1270

part of the LLVM project, emits the correct debugging

Enrico Granata

f2cb7f2

2012-03-22 19:55:55 +0000

[diff] [blame]

1271

information for LLDB to cascade). If at any level of the hierarchy

1272

there is a valid formatter that can cascade, use it.</li>

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

1273

<li>If everything has failed, repeat the above search,

1274

looking for regular expressions instead of exact

1275

matches</li>

1276

</ul>

Enrico Granata

2011-08-24 01:32:46 +0000

[diff] [blame]

1277

If any of those attempts returned a valid formatter to be used,

1278

that one is used, and the search is terminated (without going to look

1279

in other categories). If nothing was found in the current category, the next

1280

enabled category is scanned according to the same algorithm. If there are no

1281

more enabled categories, the search has failed.

Enrico Granata

f2cb7f2

2012-03-22 19:55:55 +0000

[diff] [blame]

1282

Warning: previous versions of LLDB defined cascading to mean

1283

not only going through typedef chains, but also through inheritance chains.

1284

This feature has been removed since it significantly degrades performance.

1285

You need to set up your formatters for every type in inheritance chains to which

1286

you want the formatter to apply.

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

1287

</div>

1288

</div>

Enrico Granata