gdb/ax.h

   1 /* Definitions for expressions designed to be executed on the agent
   2    Copyright 1998 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 PARAMS ((CORE_ADDR));
 143
 144 /* Free a agent expression.  */
 145 extern void free_agent_expr PARAMS ((struct agent_expr *));
 146
 147 /* Append a simple operator OP to EXPR.  */
 148 extern void ax_simple PARAMS ((struct agent_expr * EXPR, enum agent_op OP));
 149
 150 /* Append the floating-point prefix, for the next bytecode.  */
 151 #define ax_float(EXPR) (ax_simple ((EXPR), aop_float))
 152
 153 /* Append a sign-extension instruction to EXPR, to extend an N-bit value.  */
 154 extern void ax_ext PARAMS ((struct agent_expr * EXPR, int N));
 155
 156 /* Append a zero-extension instruction to EXPR, to extend an N-bit value.  */
 157 extern void ax_zero_ext PARAMS ((struct agent_expr * EXPR, int N));
 158
 159 /* Append a trace_quick instruction to EXPR, to record N bytes.  */
 160 extern void ax_trace_quick PARAMS ((struct agent_expr * EXPR, int N));
 161
 162 /* Append a goto op to EXPR.  OP is the actual op (must be aop_goto or
 163    aop_if_goto).  We assume we don't know the target offset yet,
 164    because it's probably a forward branch, so we leave space in EXPR
 165    for the target, and return the offset in EXPR of that space, so we
 166    can backpatch it once we do know the target offset.  Use ax_label
 167    to do the backpatching.  */
 168 extern int ax_goto PARAMS ((struct agent_expr * EXPR, enum agent_op OP));
 169
 170 /* Suppose a given call to ax_goto returns some value PATCH.  When you
 171    know the offset TARGET that goto should jump to, call
 172    ax_label (EXPR, PATCH, TARGET)
 173    to patch TARGET into the ax_goto instruction.  */
 174 extern void ax_label PARAMS ((struct agent_expr * EXPR, int patch, int target));
 175
 176 /* Assemble code to push a constant on the stack.  */
 177 extern void ax_const_l PARAMS ((struct agent_expr * EXPR, LONGEST l));
 178 extern void ax_const_d PARAMS ((struct agent_expr * EXPR, LONGEST d));
 179
 180 /* Assemble code to push the value of register number REG on the
 181    stack.  */
 182 extern void ax_reg PARAMS ((struct agent_expr * EXPR, int REG));
 183 \f
 184
 185 /* Functions for printing out expressions, and otherwise debugging
 186    things.  */
 187
 188 /* Disassemble the expression EXPR, writing to F.  */
 189 extern void ax_print PARAMS ((GDB_FILE * f, struct agent_expr * EXPR));
 190
 191 /* An entry in the opcode map.  */
 192 struct aop_map
 193   {
 194
 195     /* The name of the opcode.  Null means that this entry is not a
 196        valid opcode --- a hole in the opcode space.  */
 197     char *name;
 198
 199     /* All opcodes take no operands from the bytecode stream, or take
 200        unsigned integers of various sizes.  If this is a positive number
 201        n, then the opcode is followed by an n-byte operand, which should
 202        be printed as an unsigned integer.  If this is zero, then the
 203        opcode takes no operands from the bytecode stream.
 204
 205        If we get more complicated opcodes in the future, don't add other
 206        magic values of this; that's a crock.  Add an `enum encoding'
 207        field to this, or something like that.  */
 208     int op_size;
 209
 210     /* The size of the data operated upon, in bits, for bytecodes that
 211        care about that (ref and const).  Zero for all others.  */
 212     int data_size;
 213
 214     /* Number of stack elements consumed, and number produced.  */
 215     int consumed, produced;
 216   };
 217
 218 /* Map of the bytecodes, indexed by bytecode number.  */
 219 extern struct aop_map aop_map[];
 220
 221 /* Different kinds of flaws an agent expression might have, as
 222    detected by agent_reqs.  */
 223 enum agent_flaws
 224   {
 225     agent_flaw_none = 0,        /* code is good */
 226
 227     /* There is an invalid instruction in the stream.  */
 228     agent_flaw_bad_instruction,
 229
 230     /* There is an incomplete instruction at the end of the expression.  */
 231     agent_flaw_incomplete_instruction,
 232
 233     /* agent_reqs was unable to prove that every jump target is to a
 234        valid offset.  Valid offsets are within the bounds of the
 235        expression, and to a valid instruction boundary.  */
 236     agent_flaw_bad_jump,
 237
 238     /* agent_reqs was unable to prove to its satisfaction that, for each
 239        jump target location, the stack will have the same height whether
 240        that location is reached via a jump or by straight execution.  */
 241     agent_flaw_height_mismatch,
 242
 243     /* agent_reqs was unable to prove that every instruction following
 244        an unconditional jump was the target of some other jump.  */
 245     agent_flaw_hole
 246   };
 247
 248 /* Structure describing the requirements of a bytecode expression.  */
 249 struct agent_reqs
 250   {
 251
 252     /* If the following is not equal to agent_flaw_none, the rest of the
 253        information in this structure is suspect.  */
 254     enum agent_flaws flaw;
 255
 256     /* Number of elements left on stack at end; may be negative if expr
 257        only consumes elements.  */
 258     int final_height;
 259
 260     /* Maximum and minimum stack height, relative to initial height.  */
 261     int max_height, min_height;
 262
 263     /* Largest `ref' or `const' opcode used, in bits.  Zero means the
 264        expression has no such instructions.  */
 265     int max_data_size;
 266
 267     /* Bit vector of registers used.  Register R is used iff
 268
 269        reg_mask[R / 8] & (1 << (R % 8))
 270
 271        is non-zero.  Note!  You may not assume that this bitmask is long
 272        enough to hold bits for all the registers of the machine; the
 273        agent expression code has no idea how many registers the machine
 274        has.  However, the bitmask is reg_mask_len bytes long, so the
 275        valid register numbers run from 0 to reg_mask_len * 8 - 1.
 276
 277        We're assuming eight-bit bytes.  So sue me.
 278
 279        The caller should free reg_list when done.  */
 280     int reg_mask_len;
 281     unsigned char *reg_mask;
 282   };
 283
 284
 285 /* Given an agent expression AX, fill in an agent_reqs structure REQS
 286    describing it.  */
 287 extern void ax_reqs PARAMS ((struct agent_expr * ax,
 288                              struct agent_reqs * reqs));
 289
 290 #endif /* AGENTEXPR_H */