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