components/developer/gdb/Solaris/jit-reader.h

   1 /* JIT declarations for GDB, the GNU Debugger.
   2
   3    Copyright (C) 2011-2013 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 GDB_JIT_READER_H
  21 #define GDB_JIT_READER_H
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif
  26
  27 /* Versioning information.  See gdb_reader_funcs.  */
  28
  29 #define GDB_READER_INTERFACE_VERSION 1
  30
  31 /* Readers must be released under a GPL compatible license.  To
  32    declare that the reader is indeed released under a GPL compatible
  33    license, invoke the macro GDB_DECLARE_GPL_COMPATIBLE in a source
  34    file.  */
  35
  36 #ifdef __cplusplus
  37 #define GDB_DECLARE_GPL_COMPATIBLE_READER       \
  38   extern "C" {                                  \
  39   extern int plugin_is_GPL_compatible (void);   \
  40   extern int plugin_is_GPL_compatible (void)    \
  41   {                                             \
  42     return 0;                                   \
  43   }                                             \
  44   }
  45
  46 #else
  47
  48 #define GDB_DECLARE_GPL_COMPATIBLE_READER       \
  49   extern int plugin_is_GPL_compatible (void);   \
  50   extern int plugin_is_GPL_compatible (void)    \
  51   {                                             \
  52     return 0;                                   \
  53   }
  54
  55 #endif
  56
  57 /* Represents an address on the target system.  */
  58
  59 #if defined(_LP64) || defined (__amd64)
  60 typedef unsigned long GDB_CORE_ADDR;
  61 #else
  62 typedef unsigned long long GDB_CORE_ADDR;
  63 #endif
  64
  65 /* Return status codes.  */
  66
  67 enum gdb_status {
  68   GDB_FAIL = 0,
  69   GDB_SUCCESS = 1
  70 };
  71
  72 struct gdb_object;
  73 struct gdb_symtab;
  74 struct gdb_block;
  75 struct gdb_symbol_callbacks;
  76
  77 /* An array of these are used to represent a map from code addresses to line
  78    numbers in the source file.  */
  79
  80 struct gdb_line_mapping
  81 {
  82   int line;
  83   GDB_CORE_ADDR pc;
  84 };
  85
  86 /* Create a new GDB code object.  Each code object can have one or
  87    more symbol tables, each representing a compiled source file.  */
  88
  89 typedef struct gdb_object *(gdb_object_open) (struct gdb_symbol_callbacks *cb);
  90
  91 /* The callback used to create new symbol table.  CB is the
  92    gdb_symbol_callbacks which the structure is part of.  FILE_NAME is
  93    an (optionally NULL) file name to associate with this new symbol
  94    table.
  95
  96    Returns a new instance to gdb_symtab that can later be passed to
  97    gdb_block_new, gdb_symtab_add_line_mapping and gdb_symtab_close.  */
  98
  99 typedef struct gdb_symtab *(gdb_symtab_open) (struct gdb_symbol_callbacks *cb,
 100                                               struct gdb_object *obj,
 101                                               const char *file_name);
 102
 103 /* Creates a new block in a given symbol table.  A symbol table is a
 104    forest of blocks, each block representing an code address range and
 105    a corresponding (optionally NULL) NAME.  In case the block
 106    corresponds to a function, the NAME passed should be the name of
 107    the function.
 108
 109    If the new block to be created is a child of (i.e. is nested in)
 110    another block, the parent block can be passed in PARENT.  SYMTAB is
 111    the symbol table the new block is to belong in.  BEGIN, END is the
 112    code address range the block corresponds to.
 113
 114    Returns a new instance of gdb_block, which, as of now, has no use.
 115    Note that the gdb_block returned must not be freed by the
 116    caller.  */
 117
 118 typedef struct gdb_block *(gdb_block_open) (struct gdb_symbol_callbacks *cb,
 119                                             struct gdb_symtab *symtab,
 120                                             struct gdb_block *parent,
 121                                             GDB_CORE_ADDR begin,
 122                                             GDB_CORE_ADDR end,
 123                                             const char *name);
 124
 125 /* Adds a PC to line number mapping for the symbol table SYMTAB.
 126    NLINES is the number of elements in LINES, each element
 127    corresponding to one (PC, line) pair.  */
 128
 129 typedef void (gdb_symtab_add_line_mapping) (struct gdb_symbol_callbacks *cb,
 130                                             struct gdb_symtab *symtab,
 131                                             int nlines,
 132                                             struct gdb_line_mapping *lines);
 133
 134 /* Close the symtab SYMTAB.  This signals to GDB that no more blocks
 135    will be opened on this symtab.  */
 136
 137 typedef void (gdb_symtab_close) (struct gdb_symbol_callbacks *cb,
 138                                  struct gdb_symtab *symtab);
 139
 140
 141 /* Closes the gdb_object OBJ and adds the emitted information into
 142    GDB's internal structures.  Once this is done, the debug
 143    information will be picked up and used; this will usually be the
 144    last operation in gdb_read_debug_info.  */
 145
 146 typedef void (gdb_object_close) (struct gdb_symbol_callbacks *cb,
 147                                  struct gdb_object *obj);
 148
 149 /* Reads LEN bytes from TARGET_MEM in the target's virtual address
 150    space into GDB_BUF.
 151
 152    Returns GDB_FAIL on failure, and GDB_SUCCESS on success.  */
 153
 154 typedef enum gdb_status (gdb_target_read) (GDB_CORE_ADDR target_mem,
 155                                            void *gdb_buf, int len);
 156
 157 /* The list of callbacks that are passed to read.  These callbacks are
 158    to be used to construct the symbol table.  The functions have been
 159    described above.  */
 160
 161 struct gdb_symbol_callbacks
 162 {
 163   gdb_object_open *object_open;
 164   gdb_symtab_open *symtab_open;
 165   gdb_block_open *block_open;
 166   gdb_symtab_close *symtab_close;
 167   gdb_object_close *object_close;
 168
 169   gdb_symtab_add_line_mapping *line_mapping_add;
 170   gdb_target_read *target_read;
 171
 172   /* For internal use by GDB.  */
 173   void *priv_data;
 174 };
 175
 176 /* Forward declaration.  */
 177
 178 struct gdb_reg_value;
 179
 180 /* A function of this type is used to free a gdb_reg_value.  See the
 181    comment on `free' in struct gdb_reg_value.  */
 182
 183 typedef void (gdb_reg_value_free) (struct gdb_reg_value *);
 184
 185 /* Denotes the value of a register.  */
 186
 187 struct gdb_reg_value
 188 {
 189   /* The size of the register in bytes.  The reader need not set this
 190      field.  This will be set for (defined) register values being read
 191      from GDB using reg_get.  */
 192   int size;
 193
 194   /* Set to non-zero if the value for the register is known.  The
 195      registers for which the reader does not call reg_set are also
 196      assumed to be undefined */
 197   int defined;
 198
 199   /* Since gdb_reg_value is a variable sized structure, it will
 200      usually be allocated on the heap.  This function is expected to
 201      contain the corresponding "free" function.
 202
 203      When a pointer to gdb_reg_value is being sent from GDB to the
 204      reader (via gdb_unwind_reg_get), the reader is expected to call
 205      this function (with the same gdb_reg_value as argument) once it
 206      is done with the value.
 207
 208      When the function sends the a gdb_reg_value to GDB (via
 209      gdb_unwind_reg_set), it is expected to set this field to point to
 210      an appropriate cleanup routine (or to NULL if no cleanup is
 211      required).  */
 212   gdb_reg_value_free *free;
 213
 214   /* The value of the register.  */
 215   unsigned char value[1];
 216 };
 217
 218 /* get_frame_id in gdb_reader_funcs is to return a gdb_frame_id
 219    corresponding to the current frame.  The registers corresponding to
 220    the current frame can be read using reg_get.  Calling get_frame_id
 221    on a particular frame should return the same gdb_frame_id
 222    throughout its lifetime (i.e. till before it gets unwound).  One
 223    way to do this is by having the CODE_ADDRESS point to the
 224    function's first instruction and STACK_ADDRESS point to the value
 225    of the stack pointer when entering the function.  */
 226
 227 struct gdb_frame_id
 228 {
 229   GDB_CORE_ADDR code_address;
 230   GDB_CORE_ADDR stack_address;
 231 };
 232
 233 /* Forward declaration.  */
 234
 235 struct gdb_unwind_callbacks;
 236
 237 /* Returns the value of a particular register in the current frame.
 238    The current frame is the frame that needs to be unwound into the
 239    outer (earlier) frame.
 240
 241    CB is the struct gdb_unwind_callbacks * the callback belongs to.
 242    REGNUM is the DWARF register number of the register that needs to
 243    be unwound.
 244
 245    Returns the gdb_reg_value corresponding to the register requested.
 246    In case the value of the register has been optimized away or
 247    otherwise unavailable, the defined flag in the returned
 248    gdb_reg_value will be zero.  */
 249
 250 typedef struct gdb_reg_value *(gdb_unwind_reg_get)
 251                               (struct gdb_unwind_callbacks *cb, int regnum);
 252
 253 /* Sets the previous value of a particular register.  REGNUM is the
 254    (DWARF) register number whose value is to be set.  VAL is the value
 255    the register is to be set to.
 256
 257    VAL is *not* copied, so the memory allocated to it cannot be
 258    reused.  Once GDB no longer needs the value, it is deallocated
 259    using the FREE function (see gdb_reg_value).
 260
 261    A register can also be "set" to an undefined value by setting the
 262    defined in VAL to zero.  */
 263
 264 typedef void (gdb_unwind_reg_set) (struct gdb_unwind_callbacks *cb, int regnum,
 265                                    struct gdb_reg_value *val);
 266
 267 /* This struct is passed to unwind in gdb_reader_funcs, and is to be
 268    used to unwind the current frame (current being the frame whose
 269    registers can be read using reg_get) into the earlier frame.  The
 270    functions have been described above.  */
 271
 272 struct gdb_unwind_callbacks
 273 {
 274   gdb_unwind_reg_get *reg_get;
 275   gdb_unwind_reg_set *reg_set;
 276   gdb_target_read *target_read;
 277
 278   /* For internal use by GDB.  */
 279   void *priv_data;
 280 };
 281
 282 /* Forward declaration.  */
 283
 284 struct gdb_reader_funcs;
 285
 286 /* Parse the debug info off a block of memory, pointed to by MEMORY
 287    (already copied to GDB's address space) and MEMORY_SZ bytes long.
 288    The implementation has to use the functions in CB to actually emit
 289    the parsed data into GDB.  SELF is the same structure returned by
 290    gdb_init_reader.
 291
 292    Return GDB_FAIL on failure and GDB_SUCCESS on success.  */
 293
 294 typedef enum gdb_status (gdb_read_debug_info) (struct gdb_reader_funcs *self,
 295                                                struct gdb_symbol_callbacks *cb,
 296                                                void *memory, long memory_sz);
 297
 298 /* Unwind the current frame, CB is the set of unwind callbacks that
 299    are to be used to do this.
 300
 301    Return GDB_FAIL on failure and GDB_SUCCESS on success.  */
 302
 303 typedef enum gdb_status (gdb_unwind_frame) (struct gdb_reader_funcs *self,
 304                                             struct gdb_unwind_callbacks *cb);
 305
 306 /* Return the frame ID corresponding to the current frame, using C to
 307    read the current register values.  See the comment on struct
 308    gdb_frame_id.  */
 309
 310 typedef struct gdb_frame_id (gdb_get_frame_id) (struct gdb_reader_funcs *self,
 311                                                 struct gdb_unwind_callbacks *c);
 312
 313 /* Called when a reader is being unloaded.  This function should also
 314    free SELF, if required.  */
 315
 316 typedef void (gdb_destroy_reader) (struct gdb_reader_funcs *self);
 317
 318 /* Called when the reader is loaded.  Must either return a properly
 319    populated gdb_reader_funcs or NULL.  The memory allocated for the
 320    gdb_reader_funcs is to be managed by the reader itself (i.e. if it
 321    is allocated from the heap, it must also be freed in
 322    gdb_destroy_reader).  */
 323
 324 extern struct gdb_reader_funcs *gdb_init_reader (void);
 325
 326 /* Pointer to the functions which implement the reader's
 327    functionality.  The individual functions have been documented
 328    above.
 329
 330    None of the fields are optional.  */
 331
 332 struct gdb_reader_funcs
 333 {
 334   /* Must be set to GDB_READER_INTERFACE_VERSION.  */
 335   int reader_version;
 336
 337   /* For use by the reader.  */
 338   void *priv_data;
 339
 340   gdb_read_debug_info *read;
 341   gdb_unwind_frame *unwind;
 342   gdb_get_frame_id *get_frame_id;
 343   gdb_destroy_reader *destroy;
 344 };
 345
 346 #ifdef __cplusplus
 347 } /* extern "C" */
 348 #endif
 349
 350 #endif