gdb/jit-reader.h - gdb

Data types defined

Macros defined

Source code

  1. /* JIT declarations for GDB, the GNU Debugger.

  3.    Copyright (C) 2011-2014 Free Software Foundation, Inc.

  5.    This file is part of GDB.

  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.

  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.

  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/>.  */

  20. #ifndef GDB_JIT_READER_H
  21. ‌#define GDB_JIT_READER_H

  23. #ifdef __cplusplus
  24. extern "C" {
  25. #endif

  27. /* Versioning information.  See gdb_reader_funcs.  */

  29. ‌#define GDB_READER_INTERFACE_VERSION 1

  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.  */

  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.   }

  46. #else

  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.   }

  55. #endif

  57. /* Represents an address on the target system.  */

  59. ‌typedef unsigned long GDB_CORE_ADDR;

  61. /* Return status codes.  */

  63. ‌enum gdb_status {
  64.   GDB_FAIL = 0,
  65.   GDB_SUCCESS = 1
  66. };

  68. struct gdb_object;
  69. struct gdb_symtab;
  70. struct gdb_block;
  71. struct gdb_symbol_callbacks;

  73. /* An array of these are used to represent a map from code addresses to line
  74.    numbers in the source file.  */

  76. ‌struct gdb_line_mapping
  77. {
  78.   int line;
  79.   GDB_CORE_ADDR pc;
  80. };

  82. /* Create a new GDB code object.  Each code object can have one or
  83.    more symbol tables, each representing a compiled source file.  */

  85. ‌typedef struct gdb_object *(gdb_object_open) (struct gdb_symbol_callbacks *cb);

  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.

  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.  */

  95. ‌typedef struct gdb_symtab *(gdb_symtab_open) (struct gdb_symbol_callbacks *cb,
  96.                                               struct gdb_object *obj,
  97.                                               const char *file_name);

  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.

  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.

  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.  */

  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);

  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.  */

  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);

  130. /* Close the symtab SYMTAB.  This signals to GDB that no more blocks
  131.    will be opened on this symtab.  */

  133. ‌typedef void (gdb_symtab_close) (struct gdb_symbol_callbacks *cb,
  134.                                  struct gdb_symtab *symtab);


  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.  */

  142. ‌typedef void (gdb_object_close) (struct gdb_symbol_callbacks *cb,
  143.                                  struct gdb_object *obj);

  145. /* Reads LEN bytes from TARGET_MEM in the target's virtual address
  146.    space into GDB_BUF.

  148.    Returns GDB_FAIL on failure, and GDB_SUCCESS on success.  */

  150. ‌typedef enum gdb_status (gdb_target_read) (GDB_CORE_ADDR target_mem,
  151.                                            void *gdb_buf, int len);

  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.  */

  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;

  165.   gdb_symtab_add_line_mapping *line_mapping_add;
  166.   gdb_target_read *target_read;

  168.   /* For internal use by GDB.  */
  169.   void *priv_data;
  170. };

  172. /* Forward declaration.  */

  174. struct gdb_reg_value;

  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.  */

  179. ‌typedef void (gdb_reg_value_free) (struct gdb_reg_value *);

  181. /* Denotes the value of a register.  */

  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;

  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;

  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.

  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.

  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;

  210.   /* The value of the register.  */
  211.   unsigned char value[1];
  212. };

  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.  */

  223. ‌struct gdb_frame_id
  224. {
  225.   GDB_CORE_ADDR code_address;
  226.   GDB_CORE_ADDR stack_address;
  227. };

  229. /* Forward declaration.  */

  231. struct gdb_unwind_callbacks;

  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.

  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.

  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.  */

  246. ‌typedef struct gdb_reg_value *(gdb_unwind_reg_get)
  247.                               (struct gdb_unwind_callbacks *cb, int regnum);

  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.

  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).

  257.    A register can also be "set" to an undefined value by setting the
  258.    defined in VAL to zero.  */

  260. ‌typedef void (gdb_unwind_reg_set) (struct gdb_unwind_callbacks *cb, int regnum,
  261.                                    struct gdb_reg_value *val);

  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.  */

  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;

  274.   /* For internal use by GDB.  */
  275.   void *priv_data;
  276. };

  278. /* Forward declaration.  */

  280. struct gdb_reader_funcs;

  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.

  288.    Return GDB_FAIL on failure and GDB_SUCCESS on success.  */

  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);

  294. /* Unwind the current frame, CB is the set of unwind callbacks that
  295.    are to be used to do this.

  297.    Return GDB_FAIL on failure and GDB_SUCCESS on success.  */

  299. ‌typedef enum gdb_status (gdb_unwind_frame) (struct gdb_reader_funcs *self,
  300.                                             struct gdb_unwind_callbacks *cb);

  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.  */

  306. ‌typedef struct gdb_frame_id (gdb_get_frame_id) (struct gdb_reader_funcs *self,
  307.                                                 struct gdb_unwind_callbacks *c);

  309. /* Called when a reader is being unloaded.  This function should also
  310.    free SELF, if required.  */

  312. ‌typedef void (gdb_destroy_reader) (struct gdb_reader_funcs *self);

  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).  */

  320. extern struct gdb_reader_funcs *gdb_init_reader (void);

  322. /* Pointer to the functions which implement the reader's
  323.    functionality.  The individual functions have been documented
  324.    above.

  326.    None of the fields are optional.  */

  328. ‌struct gdb_reader_funcs
  329. {
  330.   /* Must be set to GDB_READER_INTERFACE_VERSION.  */
  331.   int reader_version;

  333.   /* For use by the reader.  */
  334.   void *priv_data;

  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. };

  342. #ifdef __cplusplus
  343. } /* extern "C" */
  344. #endif

  346. #endif