gdb/jit-reader.in

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