gdb/prologue-value.h

   1 /* Interface to prologue value handling for GDB.
   2    Copyright 2003, 2004, 2005, 2007, 2008, 2009, 2010, 2011
   3    Free Software Foundation, Inc.
   4
   5    This file is part of GDB.
   6
   7    This program is free software; you can redistribute it and/or modify
   8    it under the terms of the GNU General Public License as published by
   9    the Free Software Foundation; either version 3 of the License, or
  10    (at your option) any later version.
  11
  12    This program is distributed in the hope that it will be useful,
  13    but WITHOUT ANY WARRANTY; without even the implied warranty of
  14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15    GNU General Public License for more details.
  16
  17    You should have received a copy of the GNU General Public License
  18    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  19
  20 #ifndef PROLOGUE_VALUE_H
  21 #define PROLOGUE_VALUE_H
  22
  23 /* When we analyze a prologue, we're really doing 'abstract
  24    interpretation' or 'pseudo-evaluation': running the function's code
  25    in simulation, but using conservative approximations of the values
  26    it would have when it actually runs.  For example, if our function
  27    starts with the instruction:
  28
  29       addi r1, 42     # add 42 to r1
  30
  31    we don't know exactly what value will be in r1 after executing this
  32    instruction, but we do know it'll be 42 greater than its original
  33    value.
  34
  35    If we then see an instruction like:
  36
  37       addi r1, 22     # add 22 to r1
  38
  39    we still don't know what r1's value is, but again, we can say it is
  40    now 64 greater than its original value.
  41
  42    If the next instruction were:
  43
  44       mov r2, r1      # set r2 to r1's value
  45
  46    then we can say that r2's value is now the original value of r1
  47    plus 64.
  48
  49    It's common for prologues to save registers on the stack, so we'll
  50    need to track the values of stack frame slots, as well as the
  51    registers.  So after an instruction like this:
  52
  53       mov (fp+4), r2
  54
  55    then we'd know that the stack slot four bytes above the frame
  56    pointer holds the original value of r1 plus 64.
  57
  58    And so on.
  59
  60    Of course, this can only go so far before it gets unreasonable.  If
  61    we wanted to be able to say anything about the value of r1 after
  62    the instruction:
  63
  64       xor r1, r3      # exclusive-or r1 and r3, place result in r1
  65
  66    then things would get pretty complex.  But remember, we're just
  67    doing a conservative approximation; if exclusive-or instructions
  68    aren't relevant to prologues, we can just say r1's value is now
  69    'unknown'.  We can ignore things that are too complex, if that loss
  70    of information is acceptable for our application.
  71
  72    So when I say "conservative approximation" here, what I mean is an
  73    approximation that is either accurate, or marked "unknown", but
  74    never inaccurate.
  75
  76    Once you've reached the current PC, or an instruction that you
  77    don't know how to simulate, you stop.  Now you can examine the
  78    state of the registers and stack slots you've kept track of.
  79
  80    - To see how large your stack frame is, just check the value of the
  81      stack pointer register; if it's the original value of the SP
  82      minus a constant, then that constant is the stack frame's size.
  83      If the SP's value has been marked as 'unknown', then that means
  84      the prologue has done something too complex for us to track, and
  85      we don't know the frame size.
  86
  87    - To see where we've saved the previous frame's registers, we just
  88      search the values we've tracked --- stack slots, usually, but
  89      registers, too, if you want --- for something equal to the
  90      register's original value.  If the ABI suggests a standard place
  91      to save a given register, then we can check there first, but
  92      really, anything that will get us back the original value will
  93      probably work.
  94
  95    Sure, this takes some work.  But prologue analyzers aren't
  96    quick-and-simple pattern patching to recognize a few fixed prologue
  97    forms any more; they're big, hairy functions.  Along with inferior
  98    function calls, prologue analysis accounts for a substantial
  99    portion of the time needed to stabilize a GDB port.  So I think
 100    it's worthwhile to look for an approach that will be easier to
 101    understand and maintain.  In the approach used here:
 102
 103    - It's easier to see that the analyzer is correct: you just see
 104      whether the analyzer properly (albiet conservatively) simulates
 105      the effect of each instruction.
 106
 107    - It's easier to extend the analyzer: you can add support for new
 108      instructions, and know that you haven't broken anything that
 109      wasn't already broken before.
 110
 111    - It's orthogonal: to gather new information, you don't need to
 112      complicate the code for each instruction.  As long as your domain
 113      of conservative values is already detailed enough to tell you
 114      what you need, then all the existing instruction simulations are
 115      already gathering the right data for you.
 116
 117    A 'struct prologue_value' is a conservative approximation of the
 118    real value the register or stack slot will have.  */
 119
 120 struct prologue_value {
 121
 122   /* What sort of value is this?  This determines the interpretation
 123      of subsequent fields.  */
 124   enum {
 125
 126     /* We don't know anything about the value.  This is also used for
 127        values we could have kept track of, when doing so would have
 128        been too complex and we don't want to bother.  The bottom of
 129        our lattice.  */
 130     pvk_unknown,
 131
 132     /* A known constant.  K is its value.  */
 133     pvk_constant,
 134
 135     /* The value that register REG originally had *UPON ENTRY TO THE
 136        FUNCTION*, plus K.  If K is zero, this means, obviously, just
 137        the value REG had upon entry to the function.  REG is a GDB
 138        register number.  Before we start interpreting, we initialize
 139        every register R to { pvk_register, R, 0 }.  */
 140     pvk_register,
 141
 142   } kind;
 143
 144   /* The meanings of the following fields depend on 'kind'; see the
 145      comments for the specific 'kind' values.  */
 146   int reg;
 147   CORE_ADDR k;
 148 };
 149
 150 typedef struct prologue_value pv_t;
 151
 152
 153 /* Return the unknown prologue value --- { pvk_unknown, ?, ? }.  */
 154 pv_t pv_unknown (void);
 155
 156 /* Return the prologue value representing the constant K.  */
 157 pv_t pv_constant (CORE_ADDR k);
 158
 159 /* Return the prologue value representing the original value of
 160    register REG, plus the constant K.  */
 161 pv_t pv_register (int reg, CORE_ADDR k);
 162
 163
 164 /* Return conservative approximations of the results of the following
 165    operations.  */
 166 pv_t pv_add (pv_t a, pv_t b);               /* a + b */
 167 pv_t pv_add_constant (pv_t v, CORE_ADDR k); /* a + k */
 168 pv_t pv_subtract (pv_t a, pv_t b);          /* a - b */
 169 pv_t pv_logical_and (pv_t a, pv_t b);       /* a & b */
 170
 171
 172 /* Return non-zero iff A and B are identical expressions.
 173
 174    This is not the same as asking if the two values are equal; the
 175    result of such a comparison would have to be a pv_boolean, and
 176    asking whether two 'unknown' values were equal would give you
 177    pv_maybe.  Same for comparing, say, { pvk_register, R1, 0 } and {
 178    pvk_register, R2, 0}.
 179
 180    Instead, this function asks whether the two representations are the
 181    same.  */
 182 int pv_is_identical (pv_t a, pv_t b);
 183
 184
 185 /* Return non-zero if A is known to be a constant.  */
 186 int pv_is_constant (pv_t a);
 187
 188 /* Return non-zero if A is the original value of register number R
 189    plus some constant, zero otherwise.  */
 190 int pv_is_register (pv_t a, int r);
 191
 192
 193 /* Return non-zero if A is the original value of register R plus the
 194    constant K.  */
 195 int pv_is_register_k (pv_t a, int r, CORE_ADDR k);
 196
 197 /* A conservative boolean type, including "maybe", when we can't
 198    figure out whether something is true or not.  */
 199 enum pv_boolean {
 200   pv_maybe,
 201   pv_definite_yes,
 202   pv_definite_no,
 203 };
 204
 205
 206 /* Decide whether a reference to SIZE bytes at ADDR refers exactly to
 207    an element of an array.  The array starts at ARRAY_ADDR, and has
 208    ARRAY_LEN values of ELT_SIZE bytes each.  If ADDR definitely does
 209    refer to an array element, set *I to the index of the referenced
 210    element in the array, and return pv_definite_yes.  If it definitely
 211    doesn't, return pv_definite_no.  If we can't tell, return pv_maybe.
 212
 213    If the reference does touch the array, but doesn't fall exactly on
 214    an element boundary, or doesn't refer to the whole element, return
 215    pv_maybe.  */
 216 enum pv_boolean pv_is_array_ref (pv_t addr, CORE_ADDR size,
 217                                  pv_t array_addr, CORE_ADDR array_len,
 218                                  CORE_ADDR elt_size,
 219                                  int *i);
 220
 221
 222 /* A 'struct pv_area' keeps track of values stored in a particular
 223    region of memory.  */
 224 struct pv_area;
 225
 226 /* Create a new area, tracking stores relative to the original value
 227    of BASE_REG.  If BASE_REG is SP, then this effectively records the
 228    contents of the stack frame: the original value of the SP is the
 229    frame's CFA, or some constant offset from it.
 230
 231    Stores to constant addresses, unknown addresses, or to addresses
 232    relative to registers other than BASE_REG will trash this area; see
 233    pv_area_store_would_trash.
 234
 235    To check whether a pointer refers to this area, only the low
 236    ADDR_BIT bits will be compared.  */
 237 struct pv_area *make_pv_area (int base_reg, int addr_bit);
 238
 239 /* Free AREA.  */
 240 void free_pv_area (struct pv_area *area);
 241
 242
 243 /* Register a cleanup to free AREA.  */
 244 struct cleanup *make_cleanup_free_pv_area (struct pv_area *area);
 245
 246
 247 /* Store the SIZE-byte value VALUE at ADDR in AREA.
 248
 249    If ADDR is not relative to the same base register we used in
 250    creating AREA, then we can't tell which values here the stored
 251    value might overlap, and we'll have to mark everything as
 252    unknown.  */
 253 void pv_area_store (struct pv_area *area,
 254                     pv_t addr,
 255                     CORE_ADDR size,
 256                     pv_t value);
 257
 258 /* Return the SIZE-byte value at ADDR in AREA.  This may return
 259    pv_unknown ().  */
 260 pv_t pv_area_fetch (struct pv_area *area, pv_t addr, CORE_ADDR size);
 261
 262 /* Return true if storing to address ADDR in AREA would force us to
 263    mark the contents of the entire area as unknown.  This could happen
 264    if, say, ADDR is unknown, since we could be storing anywhere.  Or,
 265    it could happen if ADDR is relative to a different register than
 266    the other stores base register, since we don't know the relative
 267    values of the two registers.
 268
 269    If you've reached such a store, it may be better to simply stop the
 270    prologue analysis, and return the information you've gathered,
 271    instead of losing all that information, most of which is probably
 272    okay.  */
 273 int pv_area_store_would_trash (struct pv_area *area, pv_t addr);
 274
 275
 276 /* Search AREA for the original value of REGISTER.  If we can't find
 277    it, return zero; if we can find it, return a non-zero value, and if
 278    OFFSET_P is non-zero, set *OFFSET_P to the register's offset within
 279    AREA.  GDBARCH is the architecture of which REGISTER is a member.
 280
 281    In the worst case, this takes time proportional to the number of
 282    items stored in AREA.  If you plan to gather a lot of information
 283    about registers saved in AREA, consider calling pv_area_scan
 284    instead, and collecting all your information in one pass.  */
 285 int pv_area_find_reg (struct pv_area *area,
 286                       struct gdbarch *gdbarch,
 287                       int reg,
 288                       CORE_ADDR *offset_p);
 289
 290
 291 /* For every part of AREA whose value we know, apply FUNC to CLOSURE,
 292    the value's address, its size, and the value itself.  */
 293 void pv_area_scan (struct pv_area *area,
 294                    void (*func) (void *closure,
 295                                  pv_t addr,
 296                                  CORE_ADDR size,
 297                                  pv_t value),
 298                    void *closure);
 299
 300
 301 #endif /* PROLOGUE_VALUE_H */