diff options
Diffstat (limited to 'include/gdb/jit-reader.h')
| -rw-r--r-- | include/gdb/jit-reader.h | 346 |
1 files changed, 346 insertions, 0 deletions
diff --git a/include/gdb/jit-reader.h b/include/gdb/jit-reader.h new file mode 100644 index 0000000..7cff81a --- /dev/null +++ b/include/gdb/jit-reader.h @@ -0,0 +1,346 @@ +/* JIT declarations for GDB, the GNU Debugger. + + Copyright (C) 2011-2013 Free Software Foundation, Inc. + + This file is part of GDB. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see <http://www.gnu.org/licenses/>. */ + +#ifndef GDB_JIT_READER_H +#define GDB_JIT_READER_H + +#ifdef __cplusplus +extern "C" { +#endif + +/* Versioning information. See gdb_reader_funcs. */ + +#define GDB_READER_INTERFACE_VERSION 1 + +/* Readers must be released under a GPL compatible license. To + declare that the reader is indeed released under a GPL compatible + license, invoke the macro GDB_DECLARE_GPL_COMPATIBLE in a source + file. */ + +#ifdef __cplusplus +#define GDB_DECLARE_GPL_COMPATIBLE_READER \ + extern "C" { \ + extern int plugin_is_GPL_compatible (void); \ + extern int plugin_is_GPL_compatible (void) \ + { \ + return 0; \ + } \ + } + +#else + +#define GDB_DECLARE_GPL_COMPATIBLE_READER \ + extern int plugin_is_GPL_compatible (void); \ + extern int plugin_is_GPL_compatible (void) \ + { \ + return 0; \ + } + +#endif + +/* Represents an address on the target system. */ + +typedef unsigned long GDB_CORE_ADDR; + +/* Return status codes. */ + +enum gdb_status { + GDB_FAIL = 0, + GDB_SUCCESS = 1 +}; + +struct gdb_object; +struct gdb_symtab; +struct gdb_block; +struct gdb_symbol_callbacks; + +/* An array of these are used to represent a map from code addresses to line + numbers in the source file. */ + +struct gdb_line_mapping +{ + int line; + GDB_CORE_ADDR pc; +}; + +/* Create a new GDB code object. Each code object can have one or + more symbol tables, each representing a compiled source file. */ + +typedef struct gdb_object *(gdb_object_open) (struct gdb_symbol_callbacks *cb); + +/* The callback used to create new symbol table. CB is the + gdb_symbol_callbacks which the structure is part of. FILE_NAME is + an (optionally NULL) file name to associate with this new symbol + table. + + Returns a new instance to gdb_symtab that can later be passed to + gdb_block_new, gdb_symtab_add_line_mapping and gdb_symtab_close. */ + +typedef struct gdb_symtab *(gdb_symtab_open) (struct gdb_symbol_callbacks *cb, + struct gdb_object *obj, + const char *file_name); + +/* Creates a new block in a given symbol table. A symbol table is a + forest of blocks, each block representing an code address range and + a corresponding (optionally NULL) NAME. In case the block + corresponds to a function, the NAME passed should be the name of + the function. + + If the new block to be created is a child of (i.e. is nested in) + another block, the parent block can be passed in PARENT. SYMTAB is + the symbol table the new block is to belong in. BEGIN, END is the + code address range the block corresponds to. + + Returns a new instance of gdb_block, which, as of now, has no use. + Note that the gdb_block returned must not be freed by the + caller. */ + +typedef struct gdb_block *(gdb_block_open) (struct gdb_symbol_callbacks *cb, + struct gdb_symtab *symtab, + struct gdb_block *parent, + GDB_CORE_ADDR begin, + GDB_CORE_ADDR end, + const char *name); + +/* Adds a PC to line number mapping for the symbol table SYMTAB. + NLINES is the number of elements in LINES, each element + corresponding to one (PC, line) pair. */ + +typedef void (gdb_symtab_add_line_mapping) (struct gdb_symbol_callbacks *cb, + struct gdb_symtab *symtab, + int nlines, + struct gdb_line_mapping *lines); + +/* Close the symtab SYMTAB. This signals to GDB that no more blocks + will be opened on this symtab. */ + +typedef void (gdb_symtab_close) (struct gdb_symbol_callbacks *cb, + struct gdb_symtab *symtab); + + +/* Closes the gdb_object OBJ and adds the emitted information into + GDB's internal structures. Once this is done, the debug + information will be picked up and used; this will usually be the + last operation in gdb_read_debug_info. */ + +typedef void (gdb_object_close) (struct gdb_symbol_callbacks *cb, + struct gdb_object *obj); + +/* Reads LEN bytes from TARGET_MEM in the target's virtual address + space into GDB_BUF. + + Returns GDB_FAIL on failure, and GDB_SUCCESS on success. */ + +typedef enum gdb_status (gdb_target_read) (GDB_CORE_ADDR target_mem, + void *gdb_buf, int len); + +/* The list of callbacks that are passed to read. These callbacks are + to be used to construct the symbol table. The functions have been + described above. */ + +struct gdb_symbol_callbacks +{ + gdb_object_open *object_open; + gdb_symtab_open *symtab_open; + gdb_block_open *block_open; + gdb_symtab_close *symtab_close; + gdb_object_close *object_close; + + gdb_symtab_add_line_mapping *line_mapping_add; + gdb_target_read *target_read; + + /* For internal use by GDB. */ + void *priv_data; +}; + +/* Forward declaration. */ + +struct gdb_reg_value; + +/* A function of this type is used to free a gdb_reg_value. See the + comment on `free' in struct gdb_reg_value. */ + +typedef void (gdb_reg_value_free) (struct gdb_reg_value *); + +/* Denotes the value of a register. */ + +struct gdb_reg_value +{ + /* The size of the register in bytes. The reader need not set this + field. This will be set for (defined) register values being read + from GDB using reg_get. */ + int size; + + /* Set to non-zero if the value for the register is known. The + registers for which the reader does not call reg_set are also + assumed to be undefined */ + int defined; + + /* Since gdb_reg_value is a variable sized structure, it will + usually be allocated on the heap. This function is expected to + contain the corresponding "free" function. + + When a pointer to gdb_reg_value is being sent from GDB to the + reader (via gdb_unwind_reg_get), the reader is expected to call + this function (with the same gdb_reg_value as argument) once it + is done with the value. + + When the function sends the a gdb_reg_value to GDB (via + gdb_unwind_reg_set), it is expected to set this field to point to + an appropriate cleanup routine (or to NULL if no cleanup is + required). */ + gdb_reg_value_free *free; + + /* The value of the register. */ + unsigned char value[1]; +}; + +/* get_frame_id in gdb_reader_funcs is to return a gdb_frame_id + corresponding to the current frame. The registers corresponding to + the current frame can be read using reg_get. Calling get_frame_id + on a particular frame should return the same gdb_frame_id + throughout its lifetime (i.e. till before it gets unwound). One + way to do this is by having the CODE_ADDRESS point to the + function's first instruction and STACK_ADDRESS point to the value + of the stack pointer when entering the function. */ + +struct gdb_frame_id +{ + GDB_CORE_ADDR code_address; + GDB_CORE_ADDR stack_address; +}; + +/* Forward declaration. */ + +struct gdb_unwind_callbacks; + +/* Returns the value of a particular register in the current frame. + The current frame is the frame that needs to be unwound into the + outer (earlier) frame. + + CB is the struct gdb_unwind_callbacks * the callback belongs to. + REGNUM is the DWARF register number of the register that needs to + be unwound. + + Returns the gdb_reg_value corresponding to the register requested. + In case the value of the register has been optimized away or + otherwise unavailable, the defined flag in the returned + gdb_reg_value will be zero. */ + +typedef struct gdb_reg_value *(gdb_unwind_reg_get) + (struct gdb_unwind_callbacks *cb, int regnum); + +/* Sets the previous value of a particular register. REGNUM is the + (DWARF) register number whose value is to be set. VAL is the value + the register is to be set to. + + VAL is *not* copied, so the memory allocated to it cannot be + reused. Once GDB no longer needs the value, it is deallocated + using the FREE function (see gdb_reg_value). + + A register can also be "set" to an undefined value by setting the + defined in VAL to zero. */ + +typedef void (gdb_unwind_reg_set) (struct gdb_unwind_callbacks *cb, int regnum, + struct gdb_reg_value *val); + +/* This struct is passed to unwind in gdb_reader_funcs, and is to be + used to unwind the current frame (current being the frame whose + registers can be read using reg_get) into the earlier frame. The + functions have been described above. */ + +struct gdb_unwind_callbacks +{ + gdb_unwind_reg_get *reg_get; + gdb_unwind_reg_set *reg_set; + gdb_target_read *target_read; + + /* For internal use by GDB. */ + void *priv_data; +}; + +/* Forward declaration. */ + +struct gdb_reader_funcs; + +/* Parse the debug info off a block of memory, pointed to by MEMORY + (already copied to GDB's address space) and MEMORY_SZ bytes long. + The implementation has to use the functions in CB to actually emit + the parsed data into GDB. SELF is the same structure returned by + gdb_init_reader. + + Return GDB_FAIL on failure and GDB_SUCCESS on success. */ + +typedef enum gdb_status (gdb_read_debug_info) (struct gdb_reader_funcs *self, + struct gdb_symbol_callbacks *cb, + void *memory, long memory_sz); + +/* Unwind the current frame, CB is the set of unwind callbacks that + are to be used to do this. + + Return GDB_FAIL on failure and GDB_SUCCESS on success. */ + +typedef enum gdb_status (gdb_unwind_frame) (struct gdb_reader_funcs *self, + struct gdb_unwind_callbacks *cb); + +/* Return the frame ID corresponding to the current frame, using C to + read the current register values. See the comment on struct + gdb_frame_id. */ + +typedef struct gdb_frame_id (gdb_get_frame_id) (struct gdb_reader_funcs *self, + struct gdb_unwind_callbacks *c); + +/* Called when a reader is being unloaded. This function should also + free SELF, if required. */ + +typedef void (gdb_destroy_reader) (struct gdb_reader_funcs *self); + +/* Called when the reader is loaded. Must either return a properly + populated gdb_reader_funcs or NULL. The memory allocated for the + gdb_reader_funcs is to be managed by the reader itself (i.e. if it + is allocated from the heap, it must also be freed in + gdb_destroy_reader). */ + +extern struct gdb_reader_funcs *gdb_init_reader (void); + +/* Pointer to the functions which implement the reader's + functionality. The individual functions have been documented + above. + + None of the fields are optional. */ + +struct gdb_reader_funcs +{ + /* Must be set to GDB_READER_INTERFACE_VERSION. */ + int reader_version; + + /* For use by the reader. */ + void *priv_data; + + gdb_read_debug_info *read; + gdb_unwind_frame *unwind; + gdb_get_frame_id *get_frame_id; + gdb_destroy_reader *destroy; +}; + +#ifdef __cplusplus +} /* extern "C" */ +#endif + +#endif |