1/* JIT declarations for GDB, the GNU Debugger. 2 3 Copyright (C) 2011-2012 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 { \ 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 57typedef @TARGET_PTR@ GDB_CORE_ADDR; 58 59/* Return status codes. */ 60 61enum gdb_status { 62 GDB_FAIL = 0, 63 GDB_SUCCESS = 1 64}; 65 66struct gdb_object; 67struct gdb_symtab; 68struct gdb_block; 69struct 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 74struct 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 83typedef 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 93typedef 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 112typedef 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 123typedef 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 131typedef 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 140typedef 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 148typedef 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 155struct 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 172struct 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 177typedef void (gdb_reg_value_free) (struct gdb_reg_value *); 178 179/* Denotes the value of a register. */ 180 181struct 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 221struct gdb_frame_id 222{ 223 GDB_CORE_ADDR code_address; 224 GDB_CORE_ADDR stack_address; 225}; 226 227/* Forward declaration. */ 228 229struct 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 244typedef 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 258typedef 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 266struct 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 278struct 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 288typedef 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 297typedef 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 304typedef 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 310typedef 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 318extern 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 326struct 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 345