123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336 |
- /* Interface between gdb and its extension languages.
- Copyright (C) 2014-2022 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 EXTENSION_H
- #define EXTENSION_H
- #include "mi/mi-cmds.h" /* For PRINT_NO_VALUES, etc. */
- #include "gdbsupport/array-view.h"
- #include "gdbsupport/gdb_optional.h"
- struct breakpoint;
- struct command_line;
- struct frame_info;
- struct language_defn;
- struct objfile;
- struct extension_language_defn;
- struct type;
- struct ui_file;
- struct ui_out;
- struct value;
- struct value_print_options;
- /* A function to load and process a script file.
- The file has been opened and is ready to be read from the beginning.
- Any exceptions are not caught, and are passed to the caller. */
- typedef void script_sourcer_func (const struct extension_language_defn *,
- FILE *stream, const char *filename);
- /* A function to load and process a script for an objfile.
- The file has been opened and is ready to be read from the beginning.
- Any exceptions are not caught, and are passed to the caller. */
- typedef void objfile_script_sourcer_func
- (const struct extension_language_defn *,
- struct objfile *, FILE *stream, const char *filename);
- /* A function to execute a script for an objfile.
- Any exceptions are not caught, and are passed to the caller. */
- typedef void objfile_script_executor_func
- (const struct extension_language_defn *,
- struct objfile *, const char *name, const char *script);
- /* Enum of each extension(/scripting) language. */
- enum extension_language
- {
- EXT_LANG_NONE,
- EXT_LANG_GDB,
- EXT_LANG_PYTHON,
- EXT_LANG_GUILE
- };
- /* Extension language frame-filter status return values. */
- enum ext_lang_bt_status
- {
- /* Return when an error has occurred in processing frame filters,
- or when printing the stack. */
- EXT_LANG_BT_ERROR = -1,
- /* Return from internal routines to indicate that the function
- succeeded. */
- EXT_LANG_BT_OK = 1,
- /* Return when the frame filter process is complete, but there
- were no filter registered and enabled to process. */
- EXT_LANG_BT_NO_FILTERS = 2
- };
- /* Flags to pass to apply_extlang_frame_filter. */
- enum frame_filter_flag
- {
- /* Set this flag if frame level is to be printed. */
- PRINT_LEVEL = 1 << 0,
- /* Set this flag if frame information is to be printed. */
- PRINT_FRAME_INFO = 1 << 1,
- /* Set this flag if frame arguments are to be printed. */
- PRINT_ARGS = 1 << 2,
- /* Set this flag if frame locals are to be printed. */
- PRINT_LOCALS = 1 << 3,
- /* Set this flag if a "More frames" message is to be printed. */
- PRINT_MORE_FRAMES = 1 << 4,
- /* Set this flag if elided frames should not be printed. */
- PRINT_HIDE = 1 << 5,
- };
- DEF_ENUM_FLAGS_TYPE (enum frame_filter_flag, frame_filter_flags);
- /* A choice of the different frame argument printing strategies that
- can occur in different cases of frame filter instantiation. */
- enum ext_lang_frame_args
- {
- /* Print no values for arguments when invoked from the MI. */
- NO_VALUES = PRINT_NO_VALUES,
- MI_PRINT_ALL_VALUES = PRINT_ALL_VALUES,
- /* Print only simple values (what MI defines as "simple") for
- arguments when invoked from the MI. */
- MI_PRINT_SIMPLE_VALUES = PRINT_SIMPLE_VALUES,
- /* Print only scalar values for arguments when invoked from the CLI. */
- CLI_SCALAR_VALUES,
- /* Print all values for arguments when invoked from the CLI. */
- CLI_ALL_VALUES,
- /* Only indicate the presence of arguments when invoked from the CLI. */
- CLI_PRESENCE
- };
- /* The possible results of
- extension_language_ops.breakpoint_cond_says_stop. */
- enum ext_lang_bp_stop
- {
- /* No "stop" condition is set. */
- EXT_LANG_BP_STOP_UNSET,
- /* A "stop" condition is set, and it says "don't stop". */
- EXT_LANG_BP_STOP_NO,
- /* A "stop" condition is set, and it says "stop". */
- EXT_LANG_BP_STOP_YES
- };
- /* Table of type printers associated with the global typedef table. */
- struct ext_lang_type_printers
- {
- ext_lang_type_printers ();
- ~ext_lang_type_printers ();
- DISABLE_COPY_AND_ASSIGN (ext_lang_type_printers);
- /* Type-printers from Python. */
- void *py_type_printers = nullptr;
- };
- /* The return code for some API calls. */
- enum ext_lang_rc
- {
- /* The operation completed successfully. */
- EXT_LANG_RC_OK,
- /* The operation was not performed (e.g., no pretty-printer). */
- EXT_LANG_RC_NOP,
- /* There was an error (e.g., Python error while printing a value).
- When an error occurs no further extension languages are tried.
- This is to preserve existing behaviour, and because it's convenient
- for Python developers.
- Note: This is different than encountering a memory error trying to read
- a value for pretty-printing. Here we're referring to, e.g., programming
- errors that trigger an exception in the extension language. */
- EXT_LANG_RC_ERROR
- };
- /* A type which holds its extension language specific xmethod worker data. */
- struct xmethod_worker
- {
- xmethod_worker (const extension_language_defn *extlang)
- : m_extlang (extlang)
- {}
- virtual ~xmethod_worker () = default;
- /* Invoke the xmethod encapsulated in this worker and return the result.
- The method is invoked on OBJ with arguments in the ARGS array. */
- virtual value *invoke (value *obj, gdb::array_view<value *> args) = 0;
- /* Return the arg types of the xmethod encapsulated in this worker.
- The type of the 'this' object is returned as the first element of
- the vector. */
- std::vector<type *> get_arg_types ();
- /* Return the type of the result of the xmethod encapsulated in this worker.
- OBJECT and ARGS are the same as for invoke. */
- type *get_result_type (value *object, gdb::array_view<value *> args);
- private:
- /* Return the types of the arguments the method takes. The types
- are returned in TYPE_ARGS, one per argument. */
- virtual enum ext_lang_rc do_get_arg_types
- (std::vector<type *> *type_args) = 0;
- /* Fetch the type of the result of the method implemented by this
- worker. OBJECT and ARGS are the same as for the invoked method.
- The result type is stored in *RESULT_TYPE. */
- virtual enum ext_lang_rc do_get_result_type
- (struct value *obj, gdb::array_view<value *> args,
- struct type **result_type_ptr) = 0;
- /* The language the xmethod worker is implemented in. */
- const extension_language_defn *m_extlang;
- };
- typedef std::unique_ptr<xmethod_worker> xmethod_worker_up;
- /* The interface for gdb's own extension(/scripting) language. */
- extern const struct extension_language_defn extension_language_gdb;
- extern const struct extension_language_defn *get_ext_lang_defn
- (enum extension_language lang);
- extern const struct extension_language_defn *get_ext_lang_of_file
- (const char *file);
- extern int ext_lang_present_p (const struct extension_language_defn *);
- extern int ext_lang_initialized_p (const struct extension_language_defn *);
- extern void throw_ext_lang_unsupported
- (const struct extension_language_defn *);
- /* Accessors for "public" attributes of the extension language definition. */
- extern enum extension_language ext_lang_kind
- (const struct extension_language_defn *);
- extern const char *ext_lang_name (const struct extension_language_defn *);
- extern const char *ext_lang_capitalized_name
- (const struct extension_language_defn *);
- extern const char *ext_lang_suffix (const struct extension_language_defn *);
- extern const char *ext_lang_auto_load_suffix
- (const struct extension_language_defn *);
- extern script_sourcer_func *ext_lang_script_sourcer
- (const struct extension_language_defn *);
- extern objfile_script_sourcer_func *ext_lang_objfile_script_sourcer
- (const struct extension_language_defn *);
- extern objfile_script_executor_func *ext_lang_objfile_script_executor
- (const struct extension_language_defn *);
- /* Return true if auto-loading of EXTLANG scripts is enabled.
- False is returned if support for this language isn't compiled in. */
- extern bool ext_lang_auto_load_enabled (const struct extension_language_defn *);
- /* Wrappers for each extension language API function that iterate over all
- extension languages. */
- extern void ext_lang_initialization (void);
- extern void eval_ext_lang_from_control_command (struct command_line *cmd);
- extern void auto_load_ext_lang_scripts_for_objfile (struct objfile *);
- extern char *apply_ext_lang_type_printers (struct ext_lang_type_printers *,
- struct type *);
- extern int apply_ext_lang_val_pretty_printer
- (struct value *value, struct ui_file *stream, int recurse,
- const struct value_print_options *options,
- const struct language_defn *language);
- extern enum ext_lang_bt_status apply_ext_lang_frame_filter
- (struct frame_info *frame, frame_filter_flags flags,
- enum ext_lang_frame_args args_type,
- struct ui_out *out, int frame_low, int frame_high);
- extern void preserve_ext_lang_values (struct objfile *, htab_t copied_types);
- extern const struct extension_language_defn *get_breakpoint_cond_ext_lang
- (struct breakpoint *b, enum extension_language skip_lang);
- extern int breakpoint_ext_lang_cond_says_stop (struct breakpoint *);
- /* If a method with name METHOD_NAME is to be invoked on an object of type
- TYPE, then all extension languages are searched for implementations of
- methods with name METHOD_NAME. All matches found are appended to the WORKERS
- vector. */
- extern void get_matching_xmethod_workers
- (struct type *type, const char *method_name,
- std::vector<xmethod_worker_up> *workers);
- /* Try to colorize some source code. FILENAME is the name of the file
- holding the code. CONTENTS is the source code itself. This will
- either a colorized (using ANSI terminal escapes) version of the
- source code, or an empty value if colorizing could not be done. */
- extern gdb::optional<std::string> ext_lang_colorize
- (const std::string &filename, const std::string &contents);
- /* Try to colorize a single line of disassembler output, CONTENT for
- GDBARCH. This will return either a colorized (using ANSI terminal
- escapes) version of CONTENT, or an empty value if colorizing could not
- be done. */
- extern gdb::optional<std::string> ext_lang_colorize_disasm
- (const std::string &content, gdbarch *gdbarch);
- #if GDB_SELF_TEST
- namespace selftests {
- extern void (*hook_set_active_ext_lang) ();
- }
- #endif
- #endif /* EXTENSION_H */
|