mirror of
https://sourceware.org/git/binutils-gdb.git
synced 2024-12-27 04:52:05 +08:00
213516ef31
This commit is the result of running the gdb/copyright.py script, which automated the update of the copyright year range for all source files managed by the GDB project to be updated to include year 2023.
347 lines
12 KiB
Plaintext
347 lines
12 KiB
Plaintext
/* JIT declarations for GDB, the GNU Debugger.
|
|
|
|
Copyright (C) 2011-2023 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 @TARGET_PTR@ 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
|