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