python/lldbutils/README.txt@b8a032363ba2
python/lldbutils/README.txt
Thu, 22 Jan 2015 13:21:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 22 Jan 2015 13:21:57 +0100
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
- permissions
- -rw-r--r--
Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6
1 lldb debugging functionality for Gecko
2 ======================================
4 This directory contains a module, lldbutils, which is imported by the
5 in-tree .lldbinit file. The lldbutil modules define some lldb commands
6 that are handy for debugging Gecko.
8 If you want to add a new command or Python-implemented type summary, either add
9 it to one of the existing broad area Python files (such as lldbutils/layout.py
10 for layout-related commands) or create a new file if none of the existing files
11 is appropriate. If you add a new file, make sure you add it to __all__ in
12 lldbutils/__init__.py.
15 Supported commands
16 ------------------
18 Most commands below that can take a pointer to an object also support being
19 called with a smart pointer like nsRefPtr or nsCOMPtr.
22 * frametree EXPR, ft EXPR
23 frametreelimited EXPR, ftl EXPR
25 Shows information about a frame tree. EXPR is an expression that
26 is evaluated, and must be an nsIFrame*. frametree displays the
27 entire frame tree that contains the given frame. frametreelimited
28 displays a subtree of the frame tree rooted at the given frame.
30 (lldb) p this
31 (nsBlockFrame *) $4 = 0x000000011687fcb8
32 (lldb) ftl this
33 Block(div)(-1)@0x11687fcb8 {0,0,7380,690} [state=0002100000d04601] [content=0x11688c0c0] [sc=0x11687f990:-moz-scrolled-content]<
34 line 0x116899130: count=1 state=inline,clean,prevmarginclean,not impacted,not wrapped,before:nobr,after:nobr[0x100] {60,0,0,690} vis-overflow=60,510,0,0 scr-overflow=60,510,0,0 <
35 Text(0)""@0x1168990c0 {60,510,0,0} [state=0001000020404000] [content=0x11687ca10] [sc=0x11687fd88:-moz-non-element,parent=0x11687eb00] [run=0x115115e80][0,0,T]
36 >
37 >
38 (lldb) ft this
39 Viewport(-1)@0x116017430 [view=0x115efe190] {0,0,60,60} [state=000b063000002623] [sc=0x1160170f8:-moz-viewport]<
40 HTMLScroll(html)(-1)@0x1160180d0 {0,0,0,0} [state=000b020000000403] [content=0x115e4d640] [sc=0x116017768:-moz-viewport-scroll]<
41 ...
42 Canvas(html)(-1)@0x116017e08 {0,0,60,60} vis-overflow=0,0,8340,2196 scr-overflow=0,0,8220,2196 [state=000b002000000601] [content=0x115e4d640] [sc=0x11687e0f8:-moz-scrolled-canvas]<
43 Block(html)(-1)@0x11687e578 {0,0,60,2196} vis-overflow=0,0,8340,2196 scr-overflow=0,0,8220,2196 [state=000b100000d00601] [content=0x115e4d640] [sc=0x11687e4b8,parent=0x0]<
44 line 0x11687ec48: count=1 state=block,clean,prevmarginclean,not impacted,not wrapped,before:nobr,after:nobr[0x48] bm=480 {480,480,0,1236} vis-overflow=360,426,7980,1410 scr-overflow=480,480,7740,1236 <
45 Block(body)(1)@0x11687ebb0 {480,480,0,1236} vis-overflow=-120,-54,7980,1410 scr-overflow=0,0,7740,1236 [state=000b120000100601] [content=0x115ed8980] [sc=0x11687e990]<
46 line 0x116899170: count=1 state=inline,clean,prevmarginclean,not impacted,not wrapped,before:nobr,after:nobr[0x0] {0,0,7740,1236} vis-overflow=-120,-54,7980,1410 scr-overflow=0,0,7740,1236 <
47 nsTextControlFrame@0x11687f068 {0,66,7740,1170} vis-overflow=-120,-120,7980,1410 scr-overflow=0,0,7740,1170 [state=0002000000004621] [content=0x115ca2c50] [sc=0x11687ea40]<
48 HTMLScroll(div)(-1)@0x11687f6b0 {180,240,7380,690} [state=0002000000084409] [content=0x11688c0c0] [sc=0x11687eb00]<
49 Block(div)(-1)@0x11687fcb8 {0,0,7380,690} [state=0002100000d04601] [content=0x11688c0c0] [sc=0x11687f990:-moz-scrolled-content]<
50 line 0x116899130: count=1 state=inline,clean,prevmarginclean,not impacted,not wrapped,before:nobr,after:nobr[0x100] {60,0,0,690} vis-overflow=60,510,0,0 scr-overflow=60,510,0,0 <
51 Text(0)""@0x1168990c0 {60,510,0,0} [state=0001000020404000] [content=0x11687ca10] [sc=0x11687fd88:-moz-non-element,parent=0x11687eb00] [run=0x115115e80][0,0,T]
52 ...
55 * js
57 Dumps the current JS stack.
59 (lldb) js
60 0 anonymous(aForce = false) ["chrome://browser/content/browser.js":13414]
61 this = [object Object]
62 1 updateAppearance() ["chrome://browser/content/browser.js":13326]
63 this = [object Object]
64 2 handleEvent(aEvent = [object Event]) ["chrome://browser/content/tabbrowser.xml":3811]
65 this = [object XULElement]
68 * prefcnt EXPR
70 Shows the refcount of a given object. EXPR is an expression that is
71 evaluated, and can be either a pointer to or an actual refcounted
72 object. The object can be a standard nsISupports-like refcounted
73 object, a cycle-collected object or a mozilla::RefCounted<T> object.
75 (lldb) p this
76 (nsHTMLDocument *) $1 = 0x0000000116e9d800
77 (lldb) prefcnt this
78 20
79 (lldb) p mDocumentURI
80 (nsCOMPtr<nsIURI>) $3 = {
81 mRawPtr = 0x0000000117163e50
82 }
83 (lldb) prefcnt mDocumentURI
84 11
87 * pstate EXPR
89 Shows the frame state bits (using their symbolic names) of a given frame.
90 EXPR is an expression that is evaluated, and must be an nsIFrame*.
92 (lldb) p this
93 (nsTextFrame *) $1 = 0x000000011f470b10
94 (lldb) p/x mState
95 (nsFrameState) $2 = 0x0000004080604000
96 (lldb) pstate this
97 TEXT_HAS_NONCOLLAPSED_CHARACTERS | TEXT_END_OF_LINE | TEXT_START_OF_LINE | NS_FRAME_PAINTED_THEBES | NS_FRAME_INDEPENDENT_SELECTION
100 * ptag EXPR
102 Shows the DOM tag name of a node. EXPR is an expression that is
103 evaluated, and can be either an nsINode pointer or a concrete DOM
104 object.
106 (lldb) p this
107 (nsHTMLDocument *) $0 = 0x0000000116e9d800
108 (lldb) ptag this
109 (PermanentAtomImpl *) $1 = 0x0000000110133ac0 u"#document"
110 (lldb) p this->GetRootElement()
111 (mozilla::dom::HTMLSharedElement *) $2 = 0x0000000118429780
112 (lldb) ptag $2
113 (PermanentAtomImpl *) $3 = 0x0000000110123b80 u"html"
116 Supported type summaries and synthetic children
117 -----------------------------------------------
119 In lldb terminology, type summaries are rules for how to display a value
120 when using the "expression" command (or its familiar-to-gdb-users "p" alias),
121 and synthetic children are fake member variables or array elements also
122 added by custom rules.
124 For objects that do have synthetic children defined for them, like nsTArray,
125 the "expr -R -- EXPR" command can be used to show its actual member variables.
128 * nsAString, nsACString,
129 nsFixedString, nsFixedCString,
130 nsAutoString, nsAutoCString
132 Strings have a type summary that shows the actual string.
134 (lldb) frame info
135 frame #0: 0x000000010400cfea XUL`nsCSSParser::ParseProperty(this=0x00007fff5fbf5248, aPropID=eCSSProperty_margin_top, aPropValue=0x00007fff5fbf53f8, aSheetURI=0x0000000115ae8c00, aBaseURI=0x0000000115ae8c00, aSheetPrincipal=0x000000010ff9e040, aDeclaration=0x00000001826fd580, aChanged=0x00007fff5fbf5247, aIsImportant=false, aIsSVGMode=false) + 74 at nsCSSParser.cpp:12851
136 (lldb) p aPropValue
137 (const nsAString_internal) $16 = u"-25px"
139 (lldb) p this
140 (nsHTMLDocument *) $18 = 0x0000000115b56000
141 (lldb) p mContentType
142 (nsCString) $19 = {
143 nsACString_internal = "text/html"
144 }
146 * nscolor
148 nscolors (32-bit RGBA colors) have a type summary that shows the color as
149 one of the CSS 2.1 color keywords, a six digit hex color, an rgba() color,
150 or the "transparent" keyword.
152 (lldb) p this
153 (nsTextFrame *) $0 = 0x00000001168245e0
154 (lldb) p *this->StyleColor()
155 (const nsStyleColor) $1 = {
156 mColor = lime
157 }
158 (lldb) expr -R -- *this->StyleColor()
159 (const nsStyleColor) $2 = {
160 mColor = 4278255360
161 }
163 * nsIAtom
165 Atoms have a type summary that shows the string value inside the atom.
167 (lldb) frame info
168 frame #0: 0x00000001028b8c49 XUL`mozilla::dom::Element::GetBoolAttr(this=0x0000000115ca1c50, aAttr=0x000000011012a640) const + 25 at Element.h:907
169 (lldb) p aAttr
170 (PermanentAtomImpl *) $1 = 0x000000011012a640 u"readonly"
172 * nsTArray and friends
174 nsTArrays and their auto and fallible varieties have synthetic children
175 for their elements. This means when displaying them with "expr" (or "p"),
176 they will be shown like regular arrays, rather than showing the mHdr and
177 other fields.
179 (lldb) frame info
180 frame #0: 0x00000001043eb8a8 XUL`SVGTextFrame::DoGlyphPositioning(this=0x000000012f3f8778) + 248 at SVGTextFrame.cpp:4940
181 (lldb) p charPositions
182 (nsTArray<nsPoint>) $5 = {
183 [0] = {
184 mozilla::gfx::BasePoint<int, nsPoint> = {
185 x = 0
186 y = 816
187 }
188 }
189 [1] = {
190 mozilla::gfx::BasePoint<int, nsPoint> = {
191 x = 426
192 y = 816
193 }
194 }
195 [2] = {
196 mozilla::gfx::BasePoint<int, nsPoint> = {
197 x = 906
198 y = 816
199 }
200 }
201 }
202 (lldb) expr -R -- charPositions
203 (nsTArray<nsPoint>) $4 = {
204 nsTArray_Impl<nsPoint, nsTArrayInfallibleAllocator> = {
205 nsTArray_base<nsTArrayInfallibleAllocator, nsTArray_CopyWithMemutils> = {
206 mHdr = 0x000000012f3f1b80
207 }
208 }
209 }
211 * nsTextNode, nsTextFragment
213 Text nodes have a type summary that shows the nsTextFragment in the
214 nsTextNode, which itself has a type summary that shows the text
215 content.
217 (lldb) p this
218 (nsTextFrame *) $14 = 0x000000011811bb10
219 (lldb) p mContent
220 (nsTextNode *) $15 = 0x0000000118130110 "Search or enter address"
