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)   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

)

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

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, get_plugin_base_name(), ggc_alloc(), 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(), and ggc_alloc().

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(), ggc_alloc(), 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, ggc_alloc(), plugin_callbacks, plugin_event_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(), ggc_alloc(), NULL, and plugin_name_args_tab.

Referenced by toplev::main().

for_each_plugin()

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

extern

Call CB with USER_DATA on each plugin.   

References for_each_plugin_closure::cb, for_each_plugin_cb(), ggc_alloc(), 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, ggc_alloc(), 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 ggc_alloc(), 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, ggc_alloc(), 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, ggc_alloc(), 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 error(), gcc_assert, ggc_alloc(), 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 ggc_alloc().

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, ggc_alloc(), 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, ggc_alloc(), 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, ggc_alloc(), 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, gcc_assert, ggc_alloc(), ggc_register_root_tab(), 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, ggc_alloc(), 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(), ggc_alloc(), 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.