plugin.h File Reference

#include "highlev-plugin-common.h"
#include "plugin.def"

Include dependency graph for plugin.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	plugin_argument
struct	plugin_info
struct	plugin_gcc_version
struct	plugin_name_args

Macros
#define	DEFEVENT(NAME)

Typedefs
typedef int(*	plugin_init_func) (struct plugin_name_args *plugin_info, struct plugin_gcc_version *version)
typedef void(*	plugin_callback_func) (void *gcc_data, void *user_data)

Enumerations
enum	plugin_event { PLUGIN_EVENT_FIRST_DYNAMIC }

Functions
bool	plugin_default_version_check (struct plugin_gcc_version *, struct plugin_gcc_version *)
int	plugin_init (struct plugin_name_args *plugin_info, struct plugin_gcc_version *version)
int	get_event_last (void)
int	get_named_event_id (const char *name, enum insert_option insert)
void	register_callback (const char *plugin_name, int event, plugin_callback_func callback, void *user_data)
int	unregister_callback (const char *plugin_name, int event)
const char *	default_plugin_dir_name (void)
void	add_new_plugin (const char *)
void	parse_plugin_arg_opt (const char *)
int	invoke_plugin_callbacks_full (int, void *)
void	initialize_plugins (void)
bool	plugins_active_p (void)
void	dump_active_plugins (FILE *)
void	debug_active_plugins (void)
void	warn_if_plugins (void)
void	print_plugins_versions (FILE *file, const char *indent)
void	print_plugins_help (FILE *file, const char *indent)
void	finalize_plugins (void)
void	for_each_plugin (void(*cb)(const plugin_name_args *, void *user_data), void *user_data)
int	invoke_plugin_callbacks (int event, void *gcc_data)
void	register_attribute (const struct attribute_spec *attr)
struct scoped_attributes *	register_scoped_attributes (const struct scoped_attribute_spec &, bool)

Variables
const char **	plugin_event_name
int	plugin_is_GPL_compatible
bool	flag_plugin_added

Macro Definition Documentation

DEFEVENT

#define DEFEVENT

(

NAME

)

Value:

NAME,

Typedef Documentation

plugin_callback_func

typedef void(* plugin_callback_func) (void *gcc_data, void *user_data)

Function type for a plugin callback routine.

GCC_DATA  - event-specific data provided by GCC
USER_DATA - plugin-specific data provided by the plugin   

plugin_init_func

typedef int(* plugin_init_func) (struct plugin_name_args *plugin_info, struct plugin_gcc_version *version)

Function type for the plugin initialization routine. Each plugin module
should define this as an externally-visible function with name
"plugin_init."

PLUGIN_INFO - plugin invocation information.
VERSION     - the plugin_gcc_version symbol of GCC.

Returns 0 if initialization finishes successfully.   

Enumeration Type Documentation

plugin_event

enum plugin_event

Header file for internal GCC plugin mechanism.
   Copyright (C) 2009-2024 Free Software Foundation, Inc.

This file is part of GCC.

GCC 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, or (at your option)
any later version.

GCC 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 GCC; see the file COPYING3.  If not see
<http://www.gnu.org/licenses/>.   

Event names.   

Enumerator

PLUGIN_EVENT_FIRST_DYNAMIC

This file contains the definitions for plugin events in GCC. Copyright (C) 2009-2024 Free Software Foundation, Inc. This file is part of GCC. GCC 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, or (at your option) any later version. GCC 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 GCC; see the file COPYING3. If not see <http://www.gnu.org/licenses/>. Called before parsing the body of a function. After finishing parsing a function. To hook into pass manager. After finishing parsing a type. After finishing parsing a declaration. Useful for summary processing. Allows to see low level AST in C and C++ frontends. Called before GCC exits. Information about the plugin. Called at start of GCC Garbage Collection. Extend the GGC marking. Called at end of GGC. Register an extra GGC root table. Called during attribute registration. Called before processing a translation unit. Called during pragma registration. Called before first pass from all_passes. Called after last pass from all_passes. Called before first ipa pass. Called after last ipa pass. Allows to override pass gate decision for current_pass. Called before executing a pass. Called before executing subpasses of a GIMPLE_PASS in execute_ipa_pass_list. Called after executing subpasses of a GIMPLE_PASS in execute_ipa_pass_list. Called when a pass is first instantiated. Called when a file is #include-d or given via the #line directive. this could happen many times. The event data is the included file path, as a const char* pointer. Called when -fanalyzer starts. The event data is an ana::plugin_analyzer_init_iface *. When adding a new hard-coded plugin event, don't forget to edit in file plugin.cc the functions register_callback and invoke_plugin_callbacks_full accordingly! After the hard-coded events above, plugins can dynamically allocate events at run time. PLUGIN_EVENT_FIRST_DYNAMIC only appears as last enum element.

Function Documentation

add_new_plugin()

void add_new_plugin ( const char * plugin_name )

extern

Create a plugin_name_args object for the given plugin and insert it
to the hash table. This function is called when
-fplugin=/path/to/NAME.so or -fplugin=NAME option is processed.   

References plugin_name_args::base_name, CONST_CAST, default_plugin_dir_name(), error(), fatal_error(), flag_plugin_added, plugin_name_args::full_name, get_plugin_base_name(), htab_hash_plugin(), htab_str_eq(), input_location, NULL, plugin_name_args_tab, and R_OK.

Referenced by handle_common_deferred_options().

debug_active_plugins()

void debug_active_plugins ( void )

extern

Dump active plugins to stderr.   

References dump_active_plugins().

default_plugin_dir_name()

const char * default_plugin_dir_name ( void )

extern

Retrieve the plugin directory name, as returned by the
-fprint-file-name=plugin argument to the gcc program, which is the
-iplugindir program argument to cc1.   

Retrieve the default plugin directory.  The gcc driver should have passed
it as -iplugindir <dir> to the cc1 program, and it is queriable through the
-print-file-name=plugin option to gcc.   

References fatal_error(), and input_location.

Referenced by add_new_plugin().

dump_active_plugins()

void dump_active_plugins ( FILE * file )

extern

Dump to FILE the names and associated events for all the active
plugins.   

References _, event_last, print_options::file, FMT_FOR_PLUGIN_EVENT, callback_info::next, plugin_callbacks, plugin_event_name, callback_info::plugin_name, and plugins_active_p().

Referenced by debug_active_plugins(), and warn_if_plugins().

finalize_plugins()

void finalize_plugins ( void )

extern

Free memory allocated by the plugin system.  

References finalize_one_plugin(), NULL, and plugin_name_args_tab.

Referenced by toplev::main().

for_each_plugin()

void for_each_plugin ( void(* cb )(const plugin_name_args *, void *user_data), void * user_data )

extern

Call CB with USER_DATA on each plugin.   

References for_each_plugin_closure::cb, for_each_plugin_cb(), plugin_name_args_tab, and for_each_plugin_closure::user_data.

get_event_last()

int get_event_last ( void )

extern

Called from the plugin's initialization code. Register a single callback.
  This function can be called multiple times.

  PLUGIN_NAME - display name for this plugin
  EVENT       - which event the callback is for
  CALLBACK    - the callback to be called at the event
  USER_DATA   - plugin-provided data.

Number of event ids / names registered so far.   

Return the current value of event_last, so that plugins which provide
additional functionality for events for the benefit of high-level plugins
know how many valid entries plugin_event_name holds.   

References event_last.

get_named_event_id()

int get_named_event_id	(	const char *	name,
		enum insert_option	insert )

Look up the event id for NAME.  If the name is not found, return -1
if INSERT is NO_INSERT.   

References event_horizon, event_last, event_tab, gcc_assert, i, insert(), NULL, plugin_callbacks, plugin_callbacks_init, plugin_event_name, and plugin_event_name_init.

initialize_plugins()

void initialize_plugins ( void )

extern

Main plugin initialization function.  Called from compile_file() in
toplev.cc.   

References NULL, plugin_name_args_tab, timevar_pop(), and timevar_push().

Referenced by toplev::main().

invoke_plugin_callbacks()

int invoke_plugin_callbacks ( int event, void * gcc_data )

inline

Called from inside GCC.  Invoke all plugin callbacks registered with
the specified event.
Return PLUGEVT_SUCCESS if at least one callback was called,
PLUGEVT_NO_CALLBACK if there was no callback.

EVENT    - the event identifier
GCC_DATA - event-specific data provided by the compiler   

References flag_plugin_added, invoke_plugin_callbacks_full(), and PLUGEVT_NO_CALLBACK.

Referenced by add_pass_instance(), compile_file(), do_compile(), execute_ipa_pass_list(), execute_one_pass(), cgraph_node::expand(), ggc_collect(), ggc_mark_roots(), init_attributes(), ipa_passes(), and toplev::main().

invoke_plugin_callbacks_full()

int invoke_plugin_callbacks_full ( int event, void * gcc_data )

extern

Invoke all plugin callbacks registered with the specified event,
called from invoke_plugin_callbacks().   

References event_last, callback_info::func, gcc_assert, callback_info::next, PLUGEVT_NO_CALLBACK, PLUGEVT_SUCCESS, plugin_callbacks, PLUGIN_EVENT_FIRST_DYNAMIC, timevar_pop(), timevar_push(), and callback_info::user_data.

Referenced by invoke_plugin_callbacks().

parse_plugin_arg_opt()

void parse_plugin_arg_opt ( const char * arg )

extern

Parse the -fplugin-arg-<name>-<key>[=<value>] option and create a
'plugin_argument' object for the parsed key-value pair. ARG is
the <name>-<key>[=<value>] part of the option.   

References plugin_name_args::argc, plugin_name_args::argv, error(), gcc_assert, plugin_argument::key, NULL, plugin_name_args_tab, and plugin_argument::value.

Referenced by handle_common_deferred_options().

plugin_default_version_check()

bool plugin_default_version_check ( struct plugin_gcc_version * gcc_version, struct plugin_gcc_version * plugin_version )

extern

The default version check. Compares every field in VERSION.  

References plugin_gcc_version::basever, plugin_gcc_version::configuration_arguments, plugin_gcc_version::datestamp, plugin_gcc_version::devphase, and plugin_gcc_version::revision.

plugin_init()

int plugin_init ( struct plugin_name_args * plugin_info, struct plugin_gcc_version * version )

extern

Declaration for "plugin_init" function so that it doesn't need to be
duplicated in every plugin.   

plugins_active_p()

bool plugins_active_p ( void )

extern

Return true if plugins have been loaded.   

References event_last, and plugin_callbacks.

Referenced by dump_active_plugins(), and warn_if_plugins().

print_plugins_help()

void print_plugins_help ( FILE * file, const char * indent )

extern

Print help for each plugin. The output goes to FILE and every line starts
with INDENT.  

References print_options::file, print_options::indent, plugin_name_args_tab, and print_help_one_plugin().

Referenced by toplev::main().

print_plugins_versions()

void print_plugins_versions ( FILE * file, const char * indent )

extern

Print the version of each plugin.  

References print_options::file, print_options::indent, plugin_name_args_tab, and print_version_one_plugin().

Referenced by print_version().

register_attribute()

void register_attribute ( const struct attribute_spec * attr )

extern

In attribs.cc.   

Insert a single ATTR into the attribute table.   

References find_attribute_namespace(), and register_scoped_attribute().

register_callback()

void register_callback ( const char * plugin_name, int event, plugin_callback_func callback, void * user_data )

extern

This is also called without a callback routine for the
PLUGIN_PASS_MANAGER_SETUP, PLUGIN_INFO and PLUGIN_REGISTER_GGC_ROOTS
pseudo-events, with a specific user_data.

Called from the plugin's initialization code. Register a single callback.
This function can be called multiple times.

PLUGIN_NAME - display name for this plugin
EVENT       - which event the callback is for
CALLBACK    - the callback to be called at the event
USER_DATA   - plugin-provided data    

References error(), event_last, callback_info::func, gcc_assert, ggc_register_root_tab(), callback_info::next, plugin_callbacks, PLUGIN_EVENT_FIRST_DYNAMIC, plugin_event_name, callback_info::plugin_name, register_pass(), register_plugin_info(), and callback_info::user_data.

register_scoped_attributes()

struct scoped_attributes * register_scoped_attributes ( const struct scoped_attribute_spec & , bool  )

extern

The default argument for the third parameter is given in attribs.h.   

unregister_callback()

int unregister_callback ( const char * plugin_name, int event )

extern

Remove a callback for EVENT which has been registered with for a plugin
PLUGIN_NAME.  Return PLUGEVT_SUCCESS if a matching callback was
found & removed, PLUGEVT_NO_CALLBACK if the event does not have a matching
callback, and PLUGEVT_NO_SUCH_EVENT if EVENT is invalid.   

References event_last, callback_info::next, PLUGEVT_NO_CALLBACK, PLUGEVT_NO_SUCH_EVENT, PLUGEVT_SUCCESS, plugin_callbacks, and callback_info::plugin_name.

warn_if_plugins()

void warn_if_plugins ( void )

extern

Give a warning if plugins are present, before an ICE message asking
to submit a bug report.   

References dump_active_plugins(), fnotice(), and plugins_active_p().

Referenced by internal_error_function().

Variable Documentation

flag_plugin_added

bool flag_plugin_added

extern

For invoke_plugin_callbacks(), see plugin.h.   

Referenced by add_new_plugin(), and invoke_plugin_callbacks().

plugin_event_name

const char** plugin_event_name

extern

All globals declared here have C linkage to reduce link compatibility
issues with implementation language choice and mangling.   

Referenced by dump_active_plugins(), get_named_event_id(), and register_callback().

plugin_is_GPL_compatible

int plugin_is_GPL_compatible

extern

In case the C++ compiler does name mangling for globals, declare
plugin_is_GPL_compatible extern "C" so that a later definition
in a plugin file will have this linkage.