GCC Middle and Back End API Reference
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_attributesregister_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
Definition tree-ssa-pre.cc:242

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

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

◆ 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

◆ 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.