gdb/jit-reader.in

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