| 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 @TARGET_PTR@ 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 |