gdb/prologue-value.h

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