GDB (xrefs)

/tmp/gdb-8.1/gdb/jit-reader.h
Go to the documentation of this file.
1 /* JIT declarations for GDB, the GNU Debugger.
2
3 Copyright (C) 2011-2018 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
gdb_line_mapping
Definition: jit-reader.h:76
gdb_reader_funcs::reader_version
int reader_version
Definition: jit-reader.h:331
gdb_block_open
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_symbol_callbacks::line_mapping_add
gdb_symtab_add_line_mapping * line_mapping_add
Definition: jit-reader.h:165
gdb_symtab::file_name
const char * file_name
Definition: jit.c:477
gdb_block::begin
CORE_ADDR begin
Definition: jit.c:455
gdb_symbol_callbacks::symtab_close
gdb_symtab_close * symtab_close
Definition: jit-reader.h:162
gdb_unwind_callbacks::reg_get
gdb_unwind_reg_get * reg_get
Definition: jit-reader.h:270
gdb_get_frame_id
struct gdb_frame_id() gdb_get_frame_id(struct gdb_reader_funcs *self, struct gdb_unwind_callbacks *c)
gdb_unwind_callbacks
Definition: jit-reader.h:268
gdb_symtab
Definition: jit.c:464
gdb_symtab_open
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_reader_funcs::destroy
gdb_destroy_reader * destroy
Definition: jit-reader.h:339
gdb_unwind_callbacks::target_read
gdb_target_read * target_read
Definition: jit-reader.h:272
gdb_reg_value::free
gdb_reg_value_free * free
Definition: jit-reader.h:208
gdb_reg_value_free
void() gdb_reg_value_free(struct gdb_reg_value *)
Definition: jit-reader.h:179
gdb_symbol_callbacks::object_open
gdb_object_open * object_open
Definition: jit-reader.h:159
gdb_reader_funcs::priv_data
void * priv_data
Definition: jit-reader.h:334
gdb_symbol_callbacks
Definition: jit-reader.h:157
gdb_read_debug_info
enum gdb_status() gdb_read_debug_info(struct gdb_reader_funcs *self, struct gdb_symbol_callbacks *cb, void *memory, long memory_sz)
gdb_symbol_callbacks::priv_data
void * priv_data
Definition: jit-reader.h:169
name
const char *const name
Definition: aarch64-tdep.c:76
gdb_reader_funcs::get_frame_id
gdb_get_frame_id * get_frame_id
Definition: jit-reader.h:338
gdb_symbol_callbacks::block_open
gdb_block_open * block_open
Definition: jit-reader.h:161
GDB_CORE_ADDR
unsigned long GDB_CORE_ADDR
Definition: jit-reader.h:59
gdb_reader_funcs::read
gdb_read_debug_info * read
Definition: jit-reader.h:336
gdb_init_reader
struct gdb_reader_funcs * gdb_init_reader(void)
gdb_line_mapping::line
int line
Definition: jit-reader.h:78
gdb_unwind_reg_set
void() gdb_unwind_reg_set(struct gdb_unwind_callbacks *cb, int regnum, struct gdb_reg_value *val)
Definition: jit-reader.h:260
GDB_FAIL
Definition: jit-reader.h:64
gdb_unwind_callbacks::reg_set
gdb_unwind_reg_set * reg_set
Definition: jit-reader.h:271
gdb_symtab_add_line_mapping
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_unwind_callbacks::priv_data
void * priv_data
Definition: jit-reader.h:275
gdb_symbol_callbacks::object_close
gdb_object_close * object_close
Definition: jit-reader.h:163
regnum
int regnum
Definition: aarch64-tdep.c:77
symtab
Definition: symtab.h:1291
gdb_symbol_callbacks::symtab_open
gdb_symtab_open * symtab_open
Definition: jit-reader.h:160
gdb_reader_funcs
Definition: jit-reader.h:328
value
Definition: value.c:169
gdb_status
gdb_status
Definition: jit-reader.h:63
gdb_destroy_reader
void() gdb_destroy_reader(struct gdb_reader_funcs *self)
Definition: jit-reader.h:312
gdb_frame_id
Definition: jit-reader.h:223
gdb_unwind_reg_get
struct gdb_reg_value *() gdb_unwind_reg_get(struct gdb_unwind_callbacks *cb, int regnum)
Definition: jit-reader.h:247
gdb_frame_id::stack_address
GDB_CORE_ADDR stack_address
Definition: jit-reader.h:226
gdb_reader_funcs::unwind
gdb_unwind_frame * unwind
Definition: jit-reader.h:337
gdb_reg_value::size
int size
Definition: jit-reader.h:188
gdb_symbol_callbacks::target_read
gdb_target_read * target_read
Definition: jit-reader.h:166
gdb_block::end
CORE_ADDR end
Definition: jit.c:455
gdb_object_open
struct gdb_object *() gdb_object_open(struct gdb_symbol_callbacks *cb)
Definition: jit-reader.h:85
gdb_unwind_frame
enum gdb_status() gdb_unwind_frame(struct gdb_reader_funcs *self, struct gdb_unwind_callbacks *cb)
gdb_reg_value::defined
int defined
Definition: jit-reader.h:193
gdb_block
Definition: jit.c:442
gdb_line_mapping::pc
GDB_CORE_ADDR pc
Definition: jit-reader.h:79
gdb_reg_value
Definition: jit-reader.h:183
GDB_SUCCESS
Definition: jit-reader.h:65
gdb_target_read
enum gdb_status() gdb_target_read(GDB_CORE_ADDR target_mem, void *gdb_buf, int len)
gdb_object
Definition: jit.c:483
gdb_symtab_close
void() gdb_symtab_close(struct gdb_symbol_callbacks *cb, struct gdb_symtab *symtab)
Definition: jit-reader.h:133
gdb_block::parent
struct gdb_block * parent
Definition: jit.c:447
gdb_object_close
void() gdb_object_close(struct gdb_symbol_callbacks *cb, struct gdb_object *obj)
Definition: jit-reader.h:142
gdb_frame_id::code_address
GDB_CORE_ADDR code_address
Definition: jit-reader.h:225