Blame - www/varformats.html - fp2-dev/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]

616

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

Enrico Granata

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

[diff] [blame]

617

Enrico Granata

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

[diff] [blame]

618

Sometimes, a basic type's value actually represents

Enrico Granata

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

[diff] [blame]

619

several different values packed together in a bitfield.

Enrico Granata

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

[diff] [blame]

620

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

621

them. Hexadecimal display can help, but if the bits

Enrico Granata

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

[diff] [blame]

622

actually span nibble boundaries, the help is limited.

Enrico Granata

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

[diff] [blame]

623

Binary view would show it all without ambiguity, but is

624

often too detailed and hard to read for real-life

Enrico Granata

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

[diff] [blame]

625

scenarios.

626

627

To cope with the issue, LLDB supports native

Enrico Granata

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

[diff] [blame]

628

bitfield formatting in summary strings. If your

629

expression paths leads to a so-called scalar type

630

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

631

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

632

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

Enrico Granata

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

[diff] [blame]

633

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

634

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

635

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

636

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

Enrico Granata

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

[diff] [blame]

637

<code> (lldb) frame variable float_point

Enrico Granata

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

[diff] [blame]

638

(float) float_point = -3.14159 </code>

639

640

Enrico Granata

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

[diff] [blame]

641

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

Enrico Granata

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

[diff] [blame]

642

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

Enrico Granata

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

[diff] [blame]

643

float

644

</td>

Enrico Granata

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

[diff] [blame]

645

</table> </code>

Enrico Granata

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

[diff] [blame]

646

647

<code>

Enrico Granata

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

[diff] [blame]

648

(lldb) frame variable float_point

Enrico Granata

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

[diff] [blame]

649

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

650

0x00000080 Mantissa: 4788184

651

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

652

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

Enrico Granata

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

[diff] [blame]

653

extracting bitfields out of a float object.

654

Enrico Granata

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

[diff] [blame]

655

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

656

included, and the order of the indices is irrelevant.

Enrico Granata

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

[diff] [blame]

657

658

LLDB also allows to use a similar syntax to display

Enrico Granata

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

[diff] [blame]

659

array members inside a summary string. For instance, you

660

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

661

more compact notation than the default, and then just

662

delve into individual array members that prove

Enrico Granata

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

[diff] [blame]

663

interesting to your debugging task. You can tell

664

LLDB to format arrays in special ways, possibly

665

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

Enrico Granata

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

[diff] [blame]

666

e.g.

Enrico Granata

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

[diff] [blame]

667

<code> (lldb) frame variable sarray

Enrico Granata

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

[diff] [blame]

668

(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]

688

(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]

694

(lldb) frame variable sarray

Enrico Granata

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

[diff] [blame]

695

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

696

697

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

Enrico Granata

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

[diff] [blame]

698

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

Enrico Granata

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

[diff] [blame]

699

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

700

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

701

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

702

If you find some of those integers anomalous, you can

703

then inspect that one item in greater detail, without

704

the array format getting in the way:

Enrico Granata

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

[diff] [blame]

705

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

Enrico Granata

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

[diff] [blame]

706

(Simple) sarray[1] = {

Enrico Granata

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

[diff] [blame]

707

x = 4

708

y = 5

709

z = '\x06'

Enrico Granata

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

[diff] [blame]

710

}

711

</code>

712

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

713

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]

717

(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]

722

(lldb) frame variable sarray

Enrico Granata

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

[diff] [blame]

723

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

724

Enrico Granata

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

[diff] [blame]

725

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

726

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

727

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

728

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

729

higher and lower bounds.

Enrico Granata

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

[diff] [blame]

730

731

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

732

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

733

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

734

<ul>

735

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

736

omitting square brackets, as in:

737

738

Enrico Granata

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

[diff] [blame]

739

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

Enrico Granata

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

[diff] [blame]

740

</td>

741

<table>

Enrico Granata

de51233

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

[diff] [blame]

742

743

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

744

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

745

has ended.

746

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

747

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

748

749

750

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

751

(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]

756

<ul>

757

Enrico Granata

de51233

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

[diff] [blame]

758

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

Enrico Granata

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

[diff] [blame]

759

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

760

and <code>a</code> formats

761

work to print an array of a non-aggregate

762

type, even if square brackets are omitted.

763

764

Enrico Granata

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

[diff] [blame]

765

(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

771

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

772

773

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

774

specify the square brackets operator to get the expected output.

</div>

</div>

Enrico Granata

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

[diff] [blame]

780

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

Enrico Granata

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

[diff] [blame]

781

Enrico Granata

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

[diff] [blame]

782

783

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

784

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

785

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

786

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

Enrico Granata

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

[diff] [blame]

787

any kind of computation on the value of variables.

Enrico Granata

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

[diff] [blame]

788

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

789

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

790

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

791

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

792

793

<code>

Enrico Granata

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

[diff] [blame]

794

class Rectangle

Enrico Granata

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

[diff] [blame]

795

{

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]

800

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

Enrico Granata

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

[diff] [blame]

801

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

802

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

Enrico Granata

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

[diff] [blame]

803

Enrico Granata

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

[diff] [blame]

804

int GetHeight() { return height; }

805

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

811

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]

812

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

Enrico Granata

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

[diff] [blame]

813

814

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

815

class, as shown in this example:

(lldb) type summary add -P Rectangle

820

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

Enrico Granata

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

[diff] [blame]

821

def function (valobj,internal_dict):

Enrico Granata

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

[diff] [blame]

822

height_val = valobj.GetChildMemberWithName('height')

823

width_val = valobj.GetChildMemberWithName('width')

Enrico Granata

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

[diff] [blame]

824

height = height_val.GetValueAsUnsigned(0)

825

width = width_val.GetValueAsUnsigned(0)

Enrico Granata

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

[diff] [blame]

826

area = height*width

Enrico Granata

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

[diff] [blame]

827

perimeter = 2*(height + width)

828

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

Enrico Granata

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

[diff] [blame]

829

DONE

Enrico Granata

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

[diff] [blame]

830

(lldb) frame variable

Enrico Granata

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

[diff] [blame]

831

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

832

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

833

(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]

837

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

838

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

839

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

840

the LLDB <a href="docs.html">doxygen documentation</a> when it becomes available.

841

842

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

Enrico Granata

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

[diff] [blame]

843

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

Enrico Granata

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

[diff] [blame]

844

Enrico Granata

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

[diff] [blame]

845

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

846

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

Enrico Granata

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

[diff] [blame]

847

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

848

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

849

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

850

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

851

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

852

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

Enrico Granata

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

[diff] [blame]

853

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

854

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

Enrico Granata

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

[diff] [blame]

855

856

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]

857

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

Enrico Granata

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

[diff] [blame]

858

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

859

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

860

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

861

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]

862

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

Enrico Granata

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

[diff] [blame]

863

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]

864

865

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

866

to input a Python script as a summary:

867

868

<ul>

Enrico Granata

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

[diff] [blame]

869

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

870

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

Enrico Granata

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

[diff] [blame]

874

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

Enrico Granata

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

[diff] [blame]

875

int(valobj.GetChildMemberWithName('height').GetValue());width =

876

int(valobj.GetChildMemberWithName('width').GetValue());

877

return 'Area: ' + str(height*width)" Rectangle

878

</td>

879

</table>

880

<ul>

Enrico Granata

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

[diff] [blame]

881

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

882

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

883

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

Enrico Granata

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

[diff] [blame]

884

loaded it from a file, using the <code>script import</code> command. LLDB will not make any attempt at determining whether

885

the function is defined and syntactically correct, until you try to call it. Any errors will be shown at that stage, as if

886

you were executing your function inside the Python interactive interpreter itself.

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]

894

895

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

896

Enrico Granata

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

[diff] [blame]

897

As you noticed, in order to associate the custom

898

summary string to the array types, one must give the

899

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

900

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

901

902

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

903

[12]</code>, ...

904

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

905

treated as regular expressions instead of type names.

Enrico Granata

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

[diff] [blame]

906

This would let you rephrase the above example

907

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

Enrico Granata

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

[diff] [blame]

911

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

Enrico Granata

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

[diff] [blame]

912

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

</td>

<table>

<code>

Enrico Granata

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

[diff] [blame]

917

(lldb) frame variable sarray

Enrico Granata

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

[diff] [blame]

918

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

919

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

920

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

921

objects.

922

While this feature is mostly useful for arrays, you

923

could also use regular expressions to catch other type

924

sets grouped by name. However, as regular expression

925

matching is slower than normal name matching, LLDB will

926

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

927

when this fails, will it resort to regular expression

928

matching. Thus, if your type has a base class with a

929

cascading summary, this will be preferred over any

930

regular expression match for your type itself.

Enrico Granata

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

[diff] [blame]

931

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

932

the names of STL container classes, regardless of the template

933

arguments provided (e.g. <code>std::vector<T></code> for any

Enrico Granata

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

[diff] [blame]

934

type argument <code>T</code>). The regular expressions used for this are:

935

936

<ul>

937

<li><code>^(std::)?vector<.+>$</code> for <code>std::vector<T></code></li>

</ul>

As you can see, the actual template arguments are ignored by the regular expression.

Enrico Granata

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

[diff] [blame]

942

Enrico Granata

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

[diff] [blame]

943

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

944

compliant implementation.

Enrico Granata

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

[diff] [blame]

945

Enrico Granata

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

[diff] [blame]

946

</div>

947

</div>

Enrico Granata

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

[diff] [blame]

948

949

950

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

951

Enrico Granata

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

[diff] [blame]

952

For a given type, there may be different meaningful summary

Enrico Granata

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

[diff] [blame]

953

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

Enrico Granata

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

[diff] [blame]

954

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

955

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

Enrico Granata

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

[diff] [blame]

956

you can use named summaries.

957

Enrico Granata

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

[diff] [blame]

958

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

959

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]

960

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

961

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]

965

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

Enrico Granata

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

[diff] [blame]

966

</td>

967

<table>

Enrico Granata

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

[diff] [blame]

968

<code> (lldb) frame variable one

Enrico Granata

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

[diff] [blame]

969

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

Enrico Granata

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

[diff] [blame]

970

(lldb) frame variable one --summary NamedSummary

Enrico Granata

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

[diff] [blame]

971

(i_am_cool) one = x=3

972

</code>

973

Enrico Granata

f7a9b14

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

[diff] [blame]

974

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

975

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

976

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

977

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

978

summary name was the datatype that the summary is applied to

979

980

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

981

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

982

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

983

your program run again.

984

Enrico Granata

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

[diff] [blame]

</div>

</div>

Enrico Granata

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

[diff] [blame]

988

989

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

990

991

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

992

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

993

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

994

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

995

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

996

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

Enrico Granata

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

[diff] [blame]

997

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]

998

<code>

999

(lldb) frame variable numbers -T

Enrico Granata

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

[diff] [blame]

1000

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

1001

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

1002

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

Enrico Granata

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

[diff] [blame]

1003

(int *) _M_start = 0x00000001001008a0

1004

(int *) _M_finish = 0x00000001001008a8

1005

(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

1011

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

1012

What you would like to see is probably something like:

1013

<code>

1014

(lldb) frame variable numbers -T

Enrico Granata

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

[diff] [blame]

1015

(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.

1023

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

1024

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

1025

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

1026

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]

1027

(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]

1028

must be implemented by the Python class):

1029

<code>

1030

class SyntheticChildrenProvider:

Enrico Granata

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

[diff] [blame]

1031

def __init__(self, valobj, internal_dict):

Enrico Granata

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

[diff] [blame]

1032

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]

1033

def num_children(self):

Enrico Granata

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

[diff] [blame]

1034

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]

1035

def get_child_index(self,name):

Enrico Granata

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

[diff] [blame]

1036

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]

1037

def get_child_at_index(self,index):

Enrico Granata

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

[diff] [blame]

1038

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]

1039

def update(self):

Enrico Granata

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

[diff] [blame]

1040

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]

1041

def has_children(self):

1042

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]

1043

</code>

Enrico Granata

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

[diff] [blame]

1044

[1] This method is optional. Also, it may optionally choose to return a value (starting with LLDB 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]

1045

1046

[2] This method is optional, and LLDB will honor it starting with SVN rev166495. While implementing it in terms of <code>num_children</code> is acceptable, implementors are encouraged to look for optimized coding alternatives whenever reasonable. For an example, see the <code>std::list</code> providers shipping with LLDB.

Enrico Granata

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

[diff] [blame]

1047

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.

Enrico Granata

415bb57

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

[diff] [blame]

1048

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

1049

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]

1050

The design pattern consistently used in synthetic providers shipping with LLDB

1051

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

1052

to perform the actual initialization.

1053

1054

Enrico Granata

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

[diff] [blame]

1055

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

1056

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]

1057

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]

1058

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

1059

the provider class interactively while adding it.

1060

Enrico Granata

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

[diff] [blame]

1061

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]

1062

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

1063

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]

1067

(lldb) command script import ~/Foo_Tools.py

Enrico Granata

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

[diff] [blame]

1068

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

1069

</td>

1070

<table>

1071

<code> (lldb) frame variable a_foo

(Foo) a_foo = {

x = 1

y = "Hello world"

}

</code>

Enrico Granata

2013-02-20 02:27:07 +0000

[diff] [blame]

1078

LLDB has synthetic children providers for basic 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>. and for basic Cocoa containers (NSArray and NSDictionary).

Enrico Granata

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

[diff] [blame]

1079

Enrico Granata

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

[diff] [blame]

1080

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

1081

This symbol tells LLDB to refer expression paths to the

1082

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"

1087

</td>

Enrico Granata

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

[diff] [blame]

1088

</table>

Enrico Granata

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

[diff] [blame]

1089

<code> (lldb) frame variable numbers

1090

(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]

1097

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

1098

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

1099

can benefit from this behavior, as in:

1100

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

1101

(int) numbers[0] = 1

1102

(int) numbers[1] = 12

1103

</code>

1104

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

1105

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

1106

<code> (lldb) expression numbers[0]

1107

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

1108

error: Couldn't convert the expression to DWARF

1109

</code>

1110

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

1111

and the <code>expression</code> command ignores synthetic children when evaluating its arguments.

Enrico Granata

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

[diff] [blame]

1112

</div>

1113

</div>

Enrico Granata

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

[diff] [blame]

1114

1115

1116

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

1117

Enrico Granata

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

[diff] [blame]

1118

Filters are a solution to the display of complex classes.

1119

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

1120

necessary for the user to see.

1121

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

1122

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

1123

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

1124

Python code.

1125

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

1126

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

1127

1128

Enrico Granata

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

[diff] [blame]

1129

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

Enrico Granata

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

[diff] [blame]

1130

</td>

Enrico Granata

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

[diff] [blame]

1131

</table>

Enrico Granata

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

[diff] [blame]

1132

<code> (lldb) frame variable a_foobar

1133

(Foobar) a_foobar = {

1134

(int) B = 1

1135

(char) H = 'H'

1136

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

1137

}

1138

</code>

Enrico Granata

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

[diff] [blame]

</div>

</div>

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

1144

1145

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

Enrico Granata

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

[diff] [blame]

1146

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

1147

While this does not influence the ability of the runtime to send messages to them, it could make it impossible for LLDB

1148

to determine the actual formatters for that object, given its type-based algorithm.

Enrico Granata

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

[diff] [blame]

1149

The debugger, however, can dynamically discover the type of an Objective-C

1150

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

1151

to let LLDB do that, however, a special option to <code>frame variable</code> is

1152

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

1153

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

1154

<ul>

1155

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

1156

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

1157

code on the target is not required</li>

1158

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

1159

dynamic type discovery</li>

</ul>

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

1164

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

1165

for them. As an example:

(lldb) frame variable ns_string --dynamic-type no-run-target --show-types

1170

</td>

1171

</table>

Enrico Granata

1459660

2013-02-20 02:22:00 +0000

[diff] [blame]

1172

<code>(__NSCFString *) ns_string = 0x00000001001183d0 @"An NSString saying hello world"

Enrico Granata

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

[diff] [blame]

1173

</code>

1174

1175

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

1176

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

1177

As a final sidenote on this, LLDB is currently able to provide a summary string for <code>NSString</code>

1178

that shows the content of the string, without requiring you to run code on the target

Enrico Granata

5e536c4

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

[diff] [blame]

1179

process. This features requires you to enable the AppKit category (see below for details).

Enrico Granata

d627d4f

2013-02-20 02:27:07 +0000

[diff] [blame]

1180

The first implementation of this feature was a Python script (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]

1181

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]

1182

Enrico Granata

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

[diff] [blame]

</div>

</div>

Enrico Granata

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

[diff] [blame]

1186

1187

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

1188

1189

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

1190

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

1191

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

1192

or OS release.

Enrico Granata

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

[diff] [blame]

1193

By default, several categories are created in LLDB:

1194

<ul>

Enrico Granata

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

[diff] [blame]

1195

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

1196

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

1197

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

1198

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

1199

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

Enrico Granata

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

[diff] [blame]

1200

<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

1201

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

1202

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

1203

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

1204

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

Enrico Granata

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

[diff] [blame]

1205

</ul>

Enrico Granata

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

[diff] [blame]

1206

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

1207

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

1208

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

1209

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

1210

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]

1211

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

1212

The order in which categories are enabled or disabled

Enrico Granata

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

[diff] [blame]

1213

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]

1214

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>

1219

<li>AppKit</li>

1220

<li>CoreServices</li>

1221

<li>CoreGraphics</li>

1222

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

1227

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]

1228

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]

1229

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]

1230

replace them with your own if so you wish.

Enrico Granata

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

[diff] [blame]

1231

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

1232

exist, it is automatically created. For instance,

1233

1234

1235

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

1236

</td>

1237

</table>

1238

automatically creates a (disabled) category named newcategory.

1239

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

1240

1241

1242

(lldb) type category enable newcategory

1243

</td>

1244

</table>

1245

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

1246

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

1247

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

1248

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]

1252

Enrico Granata

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

[diff] [blame]

1253

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

Enrico Granata

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

[diff] [blame]

1254

1255

While the rules for finding an appropriate format for a

1256

type are relatively simple (just go through typedef

Enrico Granata

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

[diff] [blame]

1257

hierarchies), searching other formatters goes through

Enrico Granata

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

[diff] [blame]

1258

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

1259

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

1260

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

1261

the following:

Enrico Granata

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

[diff] [blame]

1262

<ul>

Enrico Granata

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

[diff] [blame]

1263

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

Enrico Granata

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

[diff] [blame]

1264

use it</li>

Enrico Granata

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

[diff] [blame]

1265

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

Enrico Granata

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

[diff] [blame]

1266

for the pointee type that does not skip pointers, use

1267

it</li>

1268

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

Enrico Granata

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

[diff] [blame]

1269

formatter for the referred type that does not skip

Enrico Granata

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

[diff] [blame]

1270

references, use it</li>

Enrico Granata

f2cb7f2

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

[diff] [blame]

1271

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

1272

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

1273

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]

1274

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

Enrico Granata

86e7c3e

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

[diff] [blame]

1275

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

1276

the compiler has not emitted enough information. If the

1277

required information to traverse typedef hierarchies is

1278

missing, type cascading will not work. The

1279

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

1280

part of the LLVM project, emits the correct debugging

Enrico Granata

f2cb7f2

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

[diff] [blame]

1281

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

1282

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

Enrico Granata

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

[diff] [blame]

1283

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

1284

looking for regular expressions instead of exact

1285

matches</li>

1286

</ul>

Enrico Granata

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

[diff] [blame]

1287

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

1288

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

1289

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

1290

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

1291

more enabled categories, the search has failed.

Enrico Granata

f2cb7f2

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

[diff] [blame]

1292

Warning: previous versions of LLDB defined cascading to mean

1293

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

1294

This feature has been removed since it significantly degrades performance.

1295

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

1296

you want the formatter to apply.

Enrico Granata

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

[diff] [blame]

1297

</div>

1298

</div>

Enrico Granata