GDB (xrefs)
/tmp/gdb-7.10/gdb/jit-reader.h
Go to the documentation of this file.
1 /* JIT declarations for GDB, the GNU Debugger.
2 
3  Copyright (C) 2011-2015 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,
66 };
67 
68 struct gdb_object;
69 struct gdb_symtab;
70 struct gdb_block;
72 
73 /* An array of these are used to represent a map from code addresses to line
74  numbers in the source file. */
75 
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 
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 
158 {
164 
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 
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). */
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 
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 
269 {
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 
329 {
330  /* Must be set to GDB_READER_INTERFACE_VERSION. */
332 
333  /* For use by the reader. */
334  void *priv_data;
335 
340 };
341 
342 #ifdef __cplusplus
343 } /* extern "C" */
344 #endif
345 
346 #endif
gdb_symtab_add_line_mapping * line_mapping_add
Definition: jit-reader.h:165
struct gdb_reg_value *( gdb_unwind_reg_get)(struct gdb_unwind_callbacks *cb, int regnum)
Definition: jit-reader.h:247
gdb_symtab_close * symtab_close
Definition: jit-reader.h:162
gdb_unwind_reg_get * reg_get
Definition: jit-reader.h:270
struct gdb_frame_id() gdb_get_frame_id(struct gdb_reader_funcs *self, struct gdb_unwind_callbacks *c)
struct gdb_object *( gdb_object_open)(struct gdb_symbol_callbacks *cb)
Definition: jit-reader.h:85
struct gdb_symtab *( gdb_symtab_open)(struct gdb_symbol_callbacks *cb, struct gdb_object *obj, const char *file_name)
Definition: jit-reader.h:95
gdb_destroy_reader * destroy
Definition: jit-reader.h:339
gdb_target_read * target_read
Definition: jit-reader.h:272
gdb_reg_value_free * free
Definition: jit-reader.h:208
gdb_object_open * object_open
Definition: jit-reader.h:159
enum gdb_status() gdb_read_debug_info(struct gdb_reader_funcs *self, struct gdb_symbol_callbacks *cb, void *memory, long memory_sz)
gdb_get_frame_id * get_frame_id
Definition: jit-reader.h:338
gdb_block_open * block_open
Definition: jit-reader.h:161
unsigned long GDB_CORE_ADDR
Definition: jit-reader.h:59
gdb_read_debug_info * read
Definition: jit-reader.h:336
struct gdb_reader_funcs * gdb_init_reader(void)
gdb_unwind_reg_set * reg_set
Definition: jit-reader.h:271
void( gdb_symtab_add_line_mapping)(struct gdb_symbol_callbacks *cb, struct gdb_symtab *symtab, int nlines, struct gdb_line_mapping *lines)
Definition: jit-reader.h:125
gdb_object_close * object_close
Definition: jit-reader.h:163
void( gdb_object_close)(struct gdb_symbol_callbacks *cb, struct gdb_object *obj)
Definition: jit-reader.h:142
int regnum
Definition: aarch64-tdep.c:69
void( gdb_symtab_close)(struct gdb_symbol_callbacks *cb, struct gdb_symtab *symtab)
Definition: jit-reader.h:133
struct gdb_block *( gdb_block_open)(struct gdb_symbol_callbacks *cb, struct gdb_symtab *symtab, struct gdb_block *parent, GDB_CORE_ADDR begin, GDB_CORE_ADDR end, const char *name)
Definition: jit-reader.h:114
gdb_symtab_open * symtab_open
Definition: jit-reader.h:160
Definition: value.c:172
gdb_status
Definition: jit-reader.h:63
GDB_CORE_ADDR stack_address
Definition: jit-reader.h:226
gdb_unwind_frame * unwind
Definition: jit-reader.h:337
void( gdb_destroy_reader)(struct gdb_reader_funcs *self)
Definition: jit-reader.h:312
gdb_target_read * target_read
Definition: jit-reader.h:166
enum gdb_status() gdb_unwind_frame(struct gdb_reader_funcs *self, struct gdb_unwind_callbacks *cb)
Definition: jit.c:435
GDB_CORE_ADDR pc
Definition: jit-reader.h:79
void( gdb_reg_value_free)(struct gdb_reg_value *)
Definition: jit-reader.h:179
enum gdb_status() gdb_target_read(GDB_CORE_ADDR target_mem, void *gdb_buf, int len)
void( gdb_unwind_reg_set)(struct gdb_unwind_callbacks *cb, int regnum, struct gdb_reg_value *val)
Definition: jit-reader.h:260
GDB_CORE_ADDR code_address
Definition: jit-reader.h:225
const ULONGEST const LONGEST len
Definition: target.h:309