python/lldbutils/README.txt

   1 lldb debugging functionality for Gecko
   2 ======================================
   3
   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.
   7
   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.
  13
  14
  15 Supported commands
  16 ------------------
  17
  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.
  20
  21
  22 * frametree EXPR, ft EXPR
  23   frametreelimited EXPR, ftl EXPR
  24
  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.
  29
  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} ink-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} ink-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} ink-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} ink-overflow=360,426,7980,1410 scr-overflow=480,480,7740,1236 <
  45             Block(body)(1)@0x11687ebb0 {480,480,0,1236} ink-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} ink-overflow=-120,-54,7980,1410 scr-overflow=0,0,7740,1236 <
  47                 nsTextControlFrame@0x11687f068 {0,66,7740,1170} ink-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} ink-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  ...
  53
  54
  55 * js
  56
  57   Dumps the current JS stack.
  58
  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]
  66
  67
  68 * prefcnt EXPR
  69
  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.
  74
  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
  85
  86
  87 * pstate EXPR
  88
  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*.
  91
  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
  98
  99
 100 * ptag EXPR
 101
 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.
 105
 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"
 114
 115
 116 Supported type summaries and synthetic children
 117 -----------------------------------------------
 118
 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.
 123
 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.
 126
 127
 128 * nsAString, nsACString,
 129   nsFixedString, nsFixedCString,
 130   nsAutoString, nsAutoCString
 131
 132   Strings have a type summary that shows the actual string.
 133
 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) $16 = u"-25px"
 138
 139   (lldb) p this
 140   (nsHTMLDocument *) $18 = 0x0000000115b56000
 141   (lldb) p mContentType
 142   (nsCString) $19 = {
 143     nsACString = "text/html"
 144   }
 145
 146 * nscolor
 147
 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.
 151
 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   }
 162
 163 * nsIAtom
 164
 165   Atoms have a type summary that shows the string value inside the atom.
 166
 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"
 171
 172 * nsTArray and friends
 173
 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.
 178
 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   }
 210
 211 * nsTextNode, nsTextFragment
 212
 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.
 216
 217   (lldb) p this
 218   (nsTextFrame *) $14 = 0x000000011811bb10
 219   (lldb) p mContent
 220   (nsTextNode *) $15 = 0x0000000118130110 "Search or enter address"
 221