gdb/ax.h

   1 /* Definitions for expressions designed to be executed on the agent
   2    Copyright 1998, 1999, 2000 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 2 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, write to the Free Software
  18    Foundation, Inc., 59 Temple Place - Suite 330,
  19    Boston, MA 02111-1307, USA.  */
  20
  21 #ifndef AGENTEXPR_H
  22 #define AGENTEXPR_H
  23
  24 /* It's sometimes useful to be able to debug programs that you can't
  25    really stop for more than a fraction of a second.  To this end, the
  26    user can specify a tracepoint (like a breakpoint, but you don't
  27    stop at it), and specify a bunch of expressions to record the
  28    values of when that tracepoint is reached.  As the program runs,
  29    GDB collects the values.  At any point (possibly while values are
  30    still being collected), the user can display the collected values.
  31
  32    This is used with remote debugging; we don't really support it on
  33    native configurations.
  34
  35    This means that expressions are being evaluated by the remote agent,
  36    which doesn't have any access to the symbol table information, and
  37    needs to be small and simple.
  38
  39    The agent_expr routines and datatypes are a bytecode language
  40    designed to be executed by the agent.  Agent expressions work in
  41    terms of fixed-width values, operators, memory references, and
  42    register references.  You can evaluate a agent expression just given
  43    a bunch of memory and register values to sniff at; you don't need
  44    any symbolic information like variable names, types, etc.
  45
  46    GDB translates source expressions, whose meaning depends on
  47    symbolic information, into agent bytecode expressions, whose meaning
  48    is independent of symbolic information.  This means the agent can
  49    evaluate them on the fly without reference to data only available
  50    to the host GDB.  */
  51 \f
  52
  53 /* Agent expression data structures.  */
  54
  55 /* The type of an element of the agent expression stack.
  56    The bytecode operation indicates which element we should access;
  57    the value itself has no typing information.  GDB generates all
  58    bytecode streams, so we don't have to worry about type errors.  */
  59
  60 union agent_val
  61   {
  62     LONGEST l;
  63     DOUBLEST d;
  64   };
  65
  66 /* A buffer containing a agent expression.  */
  67 struct agent_expr
  68   {
  69     unsigned char *buf;
  70     int len;                    /* number of characters used */
  71     int size;                   /* allocated size */
  72     CORE_ADDR scope;
  73   };
  74
  75
  76
  77
  78 /* The actual values of the various bytecode operations.
  79
  80    Other independent implementations of the agent bytecode engine will
  81    rely on the exact values of these enums, and may not be recompiled
  82    when we change this table.  The numeric values should remain fixed
  83    whenever possible.  Thus, we assign them values explicitly here (to
  84    allow gaps to form safely), and the disassembly table in
  85    agentexpr.h behaves like an opcode map.  If you want to see them
  86    grouped logically, see doc/agentexpr.texi.  */
  87
  88 enum agent_op
  89   {
  90     aop_float = 0x01,
  91     aop_add = 0x02,
  92     aop_sub = 0x03,
  93     aop_mul = 0x04,
  94     aop_div_signed = 0x05,
  95     aop_div_unsigned = 0x06,
  96     aop_rem_signed = 0x07,
  97     aop_rem_unsigned = 0x08,
  98     aop_lsh = 0x09,
  99     aop_rsh_signed = 0x0a,
 100     aop_rsh_unsigned = 0x0b,
 101     aop_trace = 0x0c,
 102     aop_trace_quick = 0x0d,
 103     aop_log_not = 0x0e,
 104     aop_bit_and = 0x0f,
 105     aop_bit_or = 0x10,
 106     aop_bit_xor = 0x11,
 107     aop_bit_not = 0x12,
 108     aop_equal = 0x13,
 109     aop_less_signed = 0x14,
 110     aop_less_unsigned = 0x15,
 111     aop_ext = 0x16,
 112     aop_ref8 = 0x17,
 113     aop_ref16 = 0x18,
 114     aop_ref32 = 0x19,
 115     aop_ref64 = 0x1a,
 116     aop_ref_float = 0x1b,
 117     aop_ref_double = 0x1c,
 118     aop_ref_long_double = 0x1d,
 119     aop_l_to_d = 0x1e,
 120     aop_d_to_l = 0x1f,
 121     aop_if_goto = 0x20,
 122     aop_goto = 0x21,
 123     aop_const8 = 0x22,
 124     aop_const16 = 0x23,
 125     aop_const32 = 0x24,
 126     aop_const64 = 0x25,
 127     aop_reg = 0x26,
 128     aop_end = 0x27,
 129     aop_dup = 0x28,
 130     aop_pop = 0x29,
 131     aop_zero_ext = 0x2a,
 132     aop_swap = 0x2b,
 133     aop_trace16 = 0x30,
 134     aop_last
 135   };
 136 \f
 137
 138
 139 /* Functions for building expressions.  */
 140
 141 /* Allocate a new, empty agent expression.  */
 142 extern struct agent_expr *new_agent_expr (CORE_ADDR);
 143
 144 /* Free a agent expression.  */
 145 extern void free_agent_expr (struct agent_expr *);
 146 extern struct cleanup *make_cleanup_free_agent_expr (struct agent_expr *);
 147
 148 /* Append a simple operator OP to EXPR.  */
 149 extern void ax_simple (struct agent_expr *EXPR, enum agent_op OP);
 150
 151 /* Append the floating-point prefix, for the next bytecode.  */
 152 #define ax_float(EXPR) (ax_simple ((EXPR), aop_float))
 153
 154 /* Append a sign-extension instruction to EXPR, to extend an N-bit value.  */
 155 extern void ax_ext (struct agent_expr *EXPR, int N);
 156
 157 /* Append a zero-extension instruction to EXPR, to extend an N-bit value.  */
 158 extern void ax_zero_ext (struct agent_expr *EXPR, int N);
 159
 160 /* Append a trace_quick instruction to EXPR, to record N bytes.  */
 161 extern void ax_trace_quick (struct agent_expr *EXPR, int N);
 162
 163 /* Append a goto op to EXPR.  OP is the actual op (must be aop_goto or
 164    aop_if_goto).  We assume we don't know the target offset yet,
 165    because it's probably a forward branch, so we leave space in EXPR
 166    for the target, and return the offset in EXPR of that space, so we
 167    can backpatch it once we do know the target offset.  Use ax_label
 168    to do the backpatching.  */
 169 extern int ax_goto (struct agent_expr *EXPR, enum agent_op OP);
 170
 171 /* Suppose a given call to ax_goto returns some value PATCH.  When you
 172    know the offset TARGET that goto should jump to, call
 173    ax_label (EXPR, PATCH, TARGET)
 174    to patch TARGET into the ax_goto instruction.  */
 175 extern void ax_label (struct agent_expr *EXPR, int patch, int target);
 176
 177 /* Assemble code to push a constant on the stack.  */
 178 extern void ax_const_l (struct agent_expr *EXPR, LONGEST l);
 179 extern void ax_const_d (struct agent_expr *EXPR, LONGEST d);
 180
 181 /* Assemble code to push the value of register number REG on the
 182    stack.  */
 183 extern void ax_reg (struct agent_expr *EXPR, int REG);
 184 \f
 185
 186 /* Functions for printing out expressions, and otherwise debugging
 187    things.  */
 188
 189 /* Disassemble the expression EXPR, writing to F.  */
 190 extern void ax_print (struct ui_file *f, struct agent_expr * EXPR);
 191
 192 /* An entry in the opcode map.  */
 193 struct aop_map
 194   {
 195
 196     /* The name of the opcode.  Null means that this entry is not a
 197        valid opcode --- a hole in the opcode space.  */
 198     char *name;
 199
 200     /* All opcodes take no operands from the bytecode stream, or take
 201        unsigned integers of various sizes.  If this is a positive number
 202        n, then the opcode is followed by an n-byte operand, which should
 203        be printed as an unsigned integer.  If this is zero, then the
 204        opcode takes no operands from the bytecode stream.
 205
 206        If we get more complicated opcodes in the future, don't add other
 207        magic values of this; that's a crock.  Add an `enum encoding'
 208        field to this, or something like that.  */
 209     int op_size;
 210
 211     /* The size of the data operated upon, in bits, for bytecodes that
 212        care about that (ref and const).  Zero for all others.  */
 213     int data_size;
 214
 215     /* Number of stack elements consumed, and number produced.  */
 216     int consumed, produced;
 217   };
 218
 219 /* Map of the bytecodes, indexed by bytecode number.  */
 220 extern struct aop_map aop_map[];
 221
 222 /* Different kinds of flaws an agent expression might have, as
 223    detected by agent_reqs.  */
 224 enum agent_flaws
 225   {
 226     agent_flaw_none = 0,        /* code is good */
 227
 228     /* There is an invalid instruction in the stream.  */
 229     agent_flaw_bad_instruction,
 230
 231     /* There is an incomplete instruction at the end of the expression.  */
 232     agent_flaw_incomplete_instruction,
 233
 234     /* agent_reqs was unable to prove that every jump target is to a
 235        valid offset.  Valid offsets are within the bounds of the
 236        expression, and to a valid instruction boundary.  */
 237     agent_flaw_bad_jump,
 238
 239     /* agent_reqs was unable to prove to its satisfaction that, for each
 240        jump target location, the stack will have the same height whether
 241        that location is reached via a jump or by straight execution.  */
 242     agent_flaw_height_mismatch,
 243
 244     /* agent_reqs was unable to prove that every instruction following
 245        an unconditional jump was the target of some other jump.  */
 246     agent_flaw_hole
 247   };
 248
 249 /* Structure describing the requirements of a bytecode expression.  */
 250 struct agent_reqs
 251   {
 252
 253     /* If the following is not equal to agent_flaw_none, the rest of the
 254        information in this structure is suspect.  */
 255     enum agent_flaws flaw;
 256
 257     /* Number of elements left on stack at end; may be negative if expr
 258        only consumes elements.  */
 259     int final_height;
 260
 261     /* Maximum and minimum stack height, relative to initial height.  */
 262     int max_height, min_height;
 263
 264     /* Largest `ref' or `const' opcode used, in bits.  Zero means the
 265        expression has no such instructions.  */
 266     int max_data_size;
 267
 268     /* Bit vector of registers used.  Register R is used iff
 269
 270        reg_mask[R / 8] & (1 << (R % 8))
 271
 272        is non-zero.  Note!  You may not assume that this bitmask is long
 273        enough to hold bits for all the registers of the machine; the
 274        agent expression code has no idea how many registers the machine
 275        has.  However, the bitmask is reg_mask_len bytes long, so the
 276        valid register numbers run from 0 to reg_mask_len * 8 - 1.
 277
 278        We're assuming eight-bit bytes.  So sue me.
 279
 280        The caller should free reg_list when done.  */
 281     int reg_mask_len;
 282     unsigned char *reg_mask;
 283   };
 284
 285
 286 /* Given an agent expression AX, fill in an agent_reqs structure REQS
 287    describing it.  */
 288 extern void ax_reqs (struct agent_expr *ax, struct agent_reqs *reqs);
 289
 290 #endif /* AGENTEXPR_H */