Home | History | Annotate | Download | only in gdb
      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 typedef unsigned long 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
    347