1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/python/lldbutils/README.txt Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,221 @@
1.4 +lldb debugging functionality for Gecko
1.5 +======================================
1.6 +
1.7 +This directory contains a module, lldbutils, which is imported by the
1.8 +in-tree .lldbinit file. The lldbutil modules define some lldb commands
1.9 +that are handy for debugging Gecko.
1.10 +
1.11 +If you want to add a new command or Python-implemented type summary, either add
1.12 +it to one of the existing broad area Python files (such as lldbutils/layout.py
1.13 +for layout-related commands) or create a new file if none of the existing files
1.14 +is appropriate. If you add a new file, make sure you add it to __all__ in
1.15 +lldbutils/__init__.py.
1.16 +
1.17 +
1.18 +Supported commands
1.19 +------------------
1.20 +
1.21 +Most commands below that can take a pointer to an object also support being
1.22 +called with a smart pointer like nsRefPtr or nsCOMPtr.
1.23 +
1.24 +
1.25 +* frametree EXPR, ft EXPR
1.26 + frametreelimited EXPR, ftl EXPR
1.27 +
1.28 + Shows information about a frame tree. EXPR is an expression that
1.29 + is evaluated, and must be an nsIFrame*. frametree displays the
1.30 + entire frame tree that contains the given frame. frametreelimited
1.31 + displays a subtree of the frame tree rooted at the given frame.
1.32 +
1.33 + (lldb) p this
1.34 + (nsBlockFrame *) $4 = 0x000000011687fcb8
1.35 + (lldb) ftl this
1.36 + Block(div)(-1)@0x11687fcb8 {0,0,7380,690} [state=0002100000d04601] [content=0x11688c0c0] [sc=0x11687f990:-moz-scrolled-content]<
1.37 + 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 <
1.38 + Text(0)""@0x1168990c0 {60,510,0,0} [state=0001000020404000] [content=0x11687ca10] [sc=0x11687fd88:-moz-non-element,parent=0x11687eb00] [run=0x115115e80][0,0,T]
1.39 + >
1.40 + >
1.41 + (lldb) ft this
1.42 + Viewport(-1)@0x116017430 [view=0x115efe190] {0,0,60,60} [state=000b063000002623] [sc=0x1160170f8:-moz-viewport]<
1.43 + HTMLScroll(html)(-1)@0x1160180d0 {0,0,0,0} [state=000b020000000403] [content=0x115e4d640] [sc=0x116017768:-moz-viewport-scroll]<
1.44 + ...
1.45 + 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]<
1.46 + 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]<
1.47 + 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 <
1.48 + 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]<
1.49 + 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 <
1.50 + nsTextControlFrame@0x11687f068 {0,66,7740,1170} vis-overflow=-120,-120,7980,1410 scr-overflow=0,0,7740,1170 [state=0002000000004621] [content=0x115ca2c50] [sc=0x11687ea40]<
1.51 + HTMLScroll(div)(-1)@0x11687f6b0 {180,240,7380,690} [state=0002000000084409] [content=0x11688c0c0] [sc=0x11687eb00]<
1.52 + Block(div)(-1)@0x11687fcb8 {0,0,7380,690} [state=0002100000d04601] [content=0x11688c0c0] [sc=0x11687f990:-moz-scrolled-content]<
1.53 + 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 <
1.54 + Text(0)""@0x1168990c0 {60,510,0,0} [state=0001000020404000] [content=0x11687ca10] [sc=0x11687fd88:-moz-non-element,parent=0x11687eb00] [run=0x115115e80][0,0,T]
1.55 + ...
1.56 +
1.57 +
1.58 +* js
1.59 +
1.60 + Dumps the current JS stack.
1.61 +
1.62 + (lldb) js
1.63 + 0 anonymous(aForce = false) ["chrome://browser/content/browser.js":13414]
1.64 + this = [object Object]
1.65 + 1 updateAppearance() ["chrome://browser/content/browser.js":13326]
1.66 + this = [object Object]
1.67 + 2 handleEvent(aEvent = [object Event]) ["chrome://browser/content/tabbrowser.xml":3811]
1.68 + this = [object XULElement]
1.69 +
1.70 +
1.71 +* prefcnt EXPR
1.72 +
1.73 + Shows the refcount of a given object. EXPR is an expression that is
1.74 + evaluated, and can be either a pointer to or an actual refcounted
1.75 + object. The object can be a standard nsISupports-like refcounted
1.76 + object, a cycle-collected object or a mozilla::RefCounted<T> object.
1.77 +
1.78 + (lldb) p this
1.79 + (nsHTMLDocument *) $1 = 0x0000000116e9d800
1.80 + (lldb) prefcnt this
1.81 + 20
1.82 + (lldb) p mDocumentURI
1.83 + (nsCOMPtr<nsIURI>) $3 = {
1.84 + mRawPtr = 0x0000000117163e50
1.85 + }
1.86 + (lldb) prefcnt mDocumentURI
1.87 + 11
1.88 +
1.89 +
1.90 +* pstate EXPR
1.91 +
1.92 + Shows the frame state bits (using their symbolic names) of a given frame.
1.93 + EXPR is an expression that is evaluated, and must be an nsIFrame*.
1.94 +
1.95 + (lldb) p this
1.96 + (nsTextFrame *) $1 = 0x000000011f470b10
1.97 + (lldb) p/x mState
1.98 + (nsFrameState) $2 = 0x0000004080604000
1.99 + (lldb) pstate this
1.100 + TEXT_HAS_NONCOLLAPSED_CHARACTERS | TEXT_END_OF_LINE | TEXT_START_OF_LINE | NS_FRAME_PAINTED_THEBES | NS_FRAME_INDEPENDENT_SELECTION
1.101 +
1.102 +
1.103 +* ptag EXPR
1.104 +
1.105 + Shows the DOM tag name of a node. EXPR is an expression that is
1.106 + evaluated, and can be either an nsINode pointer or a concrete DOM
1.107 + object.
1.108 +
1.109 + (lldb) p this
1.110 + (nsHTMLDocument *) $0 = 0x0000000116e9d800
1.111 + (lldb) ptag this
1.112 + (PermanentAtomImpl *) $1 = 0x0000000110133ac0 u"#document"
1.113 + (lldb) p this->GetRootElement()
1.114 + (mozilla::dom::HTMLSharedElement *) $2 = 0x0000000118429780
1.115 + (lldb) ptag $2
1.116 + (PermanentAtomImpl *) $3 = 0x0000000110123b80 u"html"
1.117 +
1.118 +
1.119 +Supported type summaries and synthetic children
1.120 +-----------------------------------------------
1.121 +
1.122 +In lldb terminology, type summaries are rules for how to display a value
1.123 +when using the "expression" command (or its familiar-to-gdb-users "p" alias),
1.124 +and synthetic children are fake member variables or array elements also
1.125 +added by custom rules.
1.126 +
1.127 +For objects that do have synthetic children defined for them, like nsTArray,
1.128 +the "expr -R -- EXPR" command can be used to show its actual member variables.
1.129 +
1.130 +
1.131 +* nsAString, nsACString,
1.132 + nsFixedString, nsFixedCString,
1.133 + nsAutoString, nsAutoCString
1.134 +
1.135 + Strings have a type summary that shows the actual string.
1.136 +
1.137 + (lldb) frame info
1.138 + 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
1.139 + (lldb) p aPropValue
1.140 + (const nsAString_internal) $16 = u"-25px"
1.141 +
1.142 + (lldb) p this
1.143 + (nsHTMLDocument *) $18 = 0x0000000115b56000
1.144 + (lldb) p mContentType
1.145 + (nsCString) $19 = {
1.146 + nsACString_internal = "text/html"
1.147 + }
1.148 +
1.149 +* nscolor
1.150 +
1.151 + nscolors (32-bit RGBA colors) have a type summary that shows the color as
1.152 + one of the CSS 2.1 color keywords, a six digit hex color, an rgba() color,
1.153 + or the "transparent" keyword.
1.154 +
1.155 + (lldb) p this
1.156 + (nsTextFrame *) $0 = 0x00000001168245e0
1.157 + (lldb) p *this->StyleColor()
1.158 + (const nsStyleColor) $1 = {
1.159 + mColor = lime
1.160 + }
1.161 + (lldb) expr -R -- *this->StyleColor()
1.162 + (const nsStyleColor) $2 = {
1.163 + mColor = 4278255360
1.164 + }
1.165 +
1.166 +* nsIAtom
1.167 +
1.168 + Atoms have a type summary that shows the string value inside the atom.
1.169 +
1.170 + (lldb) frame info
1.171 + frame #0: 0x00000001028b8c49 XUL`mozilla::dom::Element::GetBoolAttr(this=0x0000000115ca1c50, aAttr=0x000000011012a640) const + 25 at Element.h:907
1.172 + (lldb) p aAttr
1.173 + (PermanentAtomImpl *) $1 = 0x000000011012a640 u"readonly"
1.174 +
1.175 +* nsTArray and friends
1.176 +
1.177 + nsTArrays and their auto and fallible varieties have synthetic children
1.178 + for their elements. This means when displaying them with "expr" (or "p"),
1.179 + they will be shown like regular arrays, rather than showing the mHdr and
1.180 + other fields.
1.181 +
1.182 + (lldb) frame info
1.183 + frame #0: 0x00000001043eb8a8 XUL`SVGTextFrame::DoGlyphPositioning(this=0x000000012f3f8778) + 248 at SVGTextFrame.cpp:4940
1.184 + (lldb) p charPositions
1.185 + (nsTArray<nsPoint>) $5 = {
1.186 + [0] = {
1.187 + mozilla::gfx::BasePoint<int, nsPoint> = {
1.188 + x = 0
1.189 + y = 816
1.190 + }
1.191 + }
1.192 + [1] = {
1.193 + mozilla::gfx::BasePoint<int, nsPoint> = {
1.194 + x = 426
1.195 + y = 816
1.196 + }
1.197 + }
1.198 + [2] = {
1.199 + mozilla::gfx::BasePoint<int, nsPoint> = {
1.200 + x = 906
1.201 + y = 816
1.202 + }
1.203 + }
1.204 + }
1.205 + (lldb) expr -R -- charPositions
1.206 + (nsTArray<nsPoint>) $4 = {
1.207 + nsTArray_Impl<nsPoint, nsTArrayInfallibleAllocator> = {
1.208 + nsTArray_base<nsTArrayInfallibleAllocator, nsTArray_CopyWithMemutils> = {
1.209 + mHdr = 0x000000012f3f1b80
1.210 + }
1.211 + }
1.212 + }
1.213 +
1.214 +* nsTextNode, nsTextFragment
1.215 +
1.216 + Text nodes have a type summary that shows the nsTextFragment in the
1.217 + nsTextNode, which itself has a type summary that shows the text
1.218 + content.
1.219 +
1.220 + (lldb) p this
1.221 + (nsTextFrame *) $14 = 0x000000011811bb10
1.222 + (lldb) p mContent
1.223 + (nsTextNode *) $15 = 0x0000000118130110 "Search or enter address"
1.224 +
