gdb/doc/LRS

   1 What's LRS?
   2 ===========
   3
   4 LRS, or Live Range Splitting is an optimization technique which allows a user
   5 variable to reside in different locations during different parts of a function.
   6
   7 For example, a variable might reside in the stack for part of a function and
   8 in a register during a loop and in a different register during another loop.
   9
  10 Clearly, if a variable may reside in different locations, then the compiler
  11 must describe to the debugger where the variable resides for any given part
  12 of the function.
  13
  14 This document describes the debug format for encoding these extensions in
  15 stabs.
  16
  17 Since these extensions are gcc specific, these additional symbols and stabs
  18 can be disabled by the gcc command option -gstabs.
  19
  20
  21 GNU extensions for LRS under stabs:
  22 ===================================
  23
  24
  25 range symbols:
  26 -------------
  27
  28     A range symbol will be used to mark the beginning or end of a live range
  29     (the range which describes where a symbol is active, or live).
  30     These symbols will later be referenced in the stabs for debug purposes.
  31     For simplicity, we'll use the terms "range_start" and "range_end" to
  32     identify the range symbols which mark the beginning and end of a live
  33     range respectively.
  34
  35     Any text symbol which would normally appear in the symbol table (eg. a
  36     function name) can be used as range symbol.  If an address is needed to
  37     delimit a live range and does not match any of the values of symbols
  38     which would normally appear in the symbol table, a new symbol will be
  39     added to the table whose value is that address.
  40
  41     The three new symbol types described below have been added for this
  42     purpose.
  43
  44     For efficiency, the compiler should use existing symbols as range symbols
  45     whenever possible; this reduces the number of additional symbols which
  46     need to be added to the symbol table.
  47
  48
  49 New debug symbol type for defining ranges:
  50 ------------------------------------------
  51
  52     range_off - contains PC function offset for start/end of a live range.
  53                 Its location is relative to the function start and therefore
  54                 eliminates the need for additional relocation.
  55
  56     This symbol has a values in the text section, and does not have a name.
  57
  58             NOTE: the following may not be needed but are included here just
  59                 in case.
  60             range - contains PC value of beginning or end of a live range
  61                 (relocs required).
  62
  63             NOTE: the following will be required if we desire LRS debugging
  64                 to work with old style a.out stabs.
  65             range_abs - contains absolute PC value of start/end of a live
  66                 range.  The range_abs debug symbol is provided for
  67                 completeness, in case there is a need to describe addresses
  68                 in ROM, etc.
  69
  70
  71 Live range:
  72 -----------
  73
  74     The compiler and debugger view a variable with multiple homes as a primary
  75     symbol and aliases for that symbol.  The primary symbol describes the default
  76     home of the variable while aliases describe alternate homes for the variable.
  77
  78     A live range defines the interval of instructions beginning with
  79     range_start and ending at range_end-1, and is used to specify a range of
  80     instructions where an alias is active or "live".  So, the actual end of
  81     the range will be one less than the value of the range_end symbol.
  82
  83     Ranges do not have to be nested. Eg. Two ranges may intersect while
  84         each range contains subranges which are not in the other range.
  85
  86     There does not have to be a 1-1 mapping from range_start to
  87         range_end symbols.  Eg. Two range_starts can share the same
  88         range_end, while one symbol's range_start can be another symbol's
  89         range_end.
  90
  91     When a variable's storage class changes (eg. from stack to register, or
  92         from one register to another), a new symbol entry will be added to
  93         the symbol table with stabs describing the new type, and appropriate
  94         live ranges refering to the variable's initial symbol index.
  95
  96     For variables which are defined in the source but optimized away, a symbol
  97         should be emitted with the live range l(0,0).
  98
  99     Live ranges for aliases of a particular variable should always be disjoint.
 100         Overlapping ranges for aliases of the same variable will be treated as
 101         an error by the debugger, and the overlapping range will be ignored.
 102
 103     If no live range information is given, the live range will be assumed to
 104         span the symbol's entire lexical scope.
 105
 106
 107 New stabs string identifiers:
 108 -----------------------------
 109
 110   "id" in "#id" in the following section refers to a numeric value.
 111
 112   New stab syntax for live range:  l(<ref_from>,<ref_to>)
 113
 114     <ref_from> - "#id" where #id identifies the text symbol (range symbol) to
 115                 use as the start of live range (range_start).  The value for
 116                 the referenced text symbol is the starting address of the
 117                 live range.
 118
 119     <ref_to> - "#id" where #id identifies the text symbol (range symbol) to
 120                 use as the end of live range (range_end).  The value for
 121                 the referenced text symbol is ONE BYTE PAST the ending
 122                 address of the live range.
 123
 124
 125   New stab syntax for identifying symbols.
 126
 127     <def> - "#id="
 128
 129             Uses:
 130               <def><name>:<typedef1>...
 131                   When used in front of a symbol name, "#id=" defines a
 132                   unique reference number for this symbol.  The reference
 133                   number can be used later when defining aliases for this
 134                   symbol.
 135               <def>
 136                   When used as the entire stab string, "#id=" identifies this
 137                   nameless symbol as being the symbol for which "#id" refers to.
 138
 139
 140     <ref> - "#id" where "#id" refers to the symbol for which the string
 141                 "#id=" identifies.
 142             Uses:
 143               <ref>:<typedef2>;<liverange>;<liverange>...
 144                   Defines an alias for the symbol identified by the reference
 145                   number ID.
 146               l(<ref1>,<ref2>)
 147                   When used within a live range, "#id" refers to the text
 148                   symbol identified by "#id=" to use as the range symbol.
 149
 150     <liverange> - "l(<ref_from>,<ref_to>)" - specifies a live range for a
 151                 symbol.  Multiple "l" specifiers can be combined to represent
 152                 mutiple live ranges, separated by semicolons.
 153
 154
 155
 156
 157 Example:
 158 ========
 159
 160 Consider a program of the form:
 161
 162     void foo(){
 163       int a = ...;
 164       ...
 165       while (b--)
 166        c += a;
 167       ..
 168       d = a;
 169       ..
 170     }
 171
 172 Assume that "a" lives in the stack at offset -8, except for inside the loop where
 173 "a" resides in register "r5".
 174
 175 The way to describe this is to create a stab for the variable "a" which describes
 176 "a" as living in the stack and an alias for the variable "a" which describes it
 177 as living in register "r5" in the loop.
 178
 179 Let's assume that "#1" and "#2" are symbols which bound the area where "a" lives
 180 in a register.
 181
 182 The stabs to describe "a" and its alias would look like this:
 183
 184         .stabs "#3=a:1",128,0,8,-8
 185         .stabs "#3:r1;l(#1,#2)",64,0,0,5
 186
 187
 188
 189
 190 This design implies that the debugger will keep a chain of aliases for any
 191 given variable with aliases and that chain will be searched first to find
 192 out if an alias is active.  If no alias is active, then the debugger will
 193 assume that the main variable is active.
 194
 195