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 24extern "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 59typedef @TARGET_PTR@ GDB_CORE_ADDR; 60 61/* Return status codes. */ 62 63enum gdb_status { 64 GDB_FAIL = 0, 65 GDB_SUCCESS = 1 66}; 67 68struct gdb_object; 69struct gdb_symtab; 70struct gdb_block; 71struct 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 76struct 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 85typedef 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 95typedef 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 114typedef 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 125typedef 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 133typedef 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 142typedef 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 150typedef 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 157struct 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 174struct 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 179typedef void (gdb_reg_value_free) (struct gdb_reg_value *); 180 181/* Denotes the value of a register. */ 182 183struct 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 223struct gdb_frame_id 224{ 225 GDB_CORE_ADDR code_address; 226 GDB_CORE_ADDR stack_address; 227}; 228 229/* Forward declaration. */ 230 231struct 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 246typedef 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 260typedef 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 268struct 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 280struct 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 290typedef 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 299typedef 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 306typedef 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 312typedef 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 320extern 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 328struct 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