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